# Sanguo VeighNa 开发指南

## 一、开发工作流

### 1.1 功能开发流程

```bash
# 1. 从 develop 创建功能分支
git checkout develop
git pull origin develop
git checkout -b feature/your-feature-name

# 2. 开发并提交
git add .
git commit -m "feat: 添加CTP接口网关"

# 3. 推送到远程
git push origin feature/your-feature-name

# 4. 在 Gitea 创建 Pull Request 到 develop
# 5. 代码审查通过后合并
```

### 1.2 热修复流程

```bash
# 1. 从 master 创建修复分支
git checkout master
git pull origin master
git checkout -b hotfix/critical-bug-fix

# 2. 修复并提交
git add .
git commit -m "fix: 修复订单撤单bug"

# 3. 推送并创建 PR 到 master
git push origin hotfix/critical-bug-fix

# 4. 合并后同步到 develop
```

### 1.3 发布流程

```bash
# 1. 从 develop 创建发布分支
git checkout develop
git pull origin develop
git checkout -b release/v1.0.0

# 2. 更新版本号和 CHANGELOG
# 3. 合并到 master
git checkout master
git merge release/v1.0.0

# 4. 打标签
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

# 5. 同步回 develop
git checkout develop
git merge release/v1.0.0
```

---

## 二、提交信息规范

使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范：

```
<类型>[可选 范围]: <描述>

[可选 正文]

[可选 脚注]
```

### 类型说明

| 类型 | 说明 | 示例 |
|-----|------|------|
| `feat` | 新功能 | `feat: 添加沪深300行情接口` |
| `fix` | 修复bug | `fix: 修复K线数据时间戳错误` |
| `docs` | 文档更新 | `docs: 更新API文档` |
| `style` | 代码格式 | `style: 统一代码缩进` |
| `refactor` | 重构 | `refactor: 重构事件引擎` |
| `perf` | 性能优化 | `perf: 优化历史数据查询` |
| `test` | 测试 | `test: 添加订单模块测试` |
| `chore` | 构建/工具 | `chore: 更新依赖版本` |

### 范围说明

| 范围 | 说明 |
|-----|------|
| `gateway` | 交易接口 |
| `strategy` | 策略模块 |
| `data` | 数据模块 |
| `ui` | 用户界面 |
| `alpha` | AI量化模块 |
| `common` | 公共模块 |

### 示例

```bash
# 简单提交
git commit -m "feat: 添加CTP接口网关"

# 带范围的提交
git commit -m "fix(gateway): 修复订单撤单超时问题"

# 带说明的提交
git commit -m "feat(strategy): 添加网格交易策略

- 支持多合约网格
- 支持动态网格调整
- 添加风险控制功能

Closes #123"
```

---

## 三、代码审查流程

### 3.1 Pull Request 模板

在 Gitea 设置 PR 模板（`.github/pull_request_template.md`）：

```markdown
## 变更说明
<!-- 简要描述此 PR 的内容 -->

## 变更类型
- [ ] feat: 新功能
- [ ] fix: 修复bug
- [ ] docs: 文档更新
- [ ] refactor: 重构
- [ ] 其他: _____

## 相关 Issue
Closes #

## 测试说明
<!-- 说明如何测试此次变更 -->

## 检查清单
- [ ] 代码遵循项目规范
- [ ] 已添加必要的测试
- [ ] 文档已更新
- [ ] 通过所有测试
```

### 3.2 审查要点

1. **代码质量**
   - 遵循 PEP 8 规范
   - 类型注解完整
   - 文档字符串完整

2. **功能正确性**
   - 逻辑正确
   - 边界条件处理
   - 异常处理完善

3. **性能考虑**
   - 避免不必要的计算
   - 合理使用缓存
   - 注意内存使用

4. **安全性**
   - 输入验证
   - 权限检查
   - 敏感信息保护

---

## 四、测试策略

### 4.1 测试目录结构

```
tests/
├── unit/              # 单元测试
│   ├── test_gateway/
│   ├── test_strategy/
│   └── test_data/
├── integration/       # 集成测试
│   ├── test_trading_flow/
│   └── test_data_pipeline/
└── fixtures/          # 测试数据
```

### 4.2 测试运行

```bash
# 运行所有测试
pytest

# 运行特定测试
pytest tests/unit/test_gateway/

# 带覆盖率报告
pytest --cov=sanguo_trader --cov-report=html
```

---

## 五、版本管理

### 5.1 版本号格式

遵循 [Semantic Versioning](https://semver.org/)：

```
MAJOR.MINOR.PATCH

例：1.2.3
- MAJOR: 不兼容的API变更
- MINOR: 向后兼容的功能新增
- PATCH: 向后兼容的问题修复
```

### 5.2 版本发布检查清单

- [ ] 更新版本号（`__init__.py`）
- [ ] 更新 CHANGELOG.md
- [ ] 运行完整测试套件
- [ ] 更新文档
- [ ] 创建 Git 标签
- [ ] 推送到 Gitea
- [ ] 通知团队成员

---

## 六、持续集成（可选）

### 6.1 Gitea Actions 配置

创建 `.gitea/workflows/test.yml`：

```yaml
name: Tests

on:
  push:
    branches: [ master, develop ]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - name: Install dependencies
        run: |
          pip install -r requirements/base.txt
          pip install pytest pytest-cov
      - name: Run tests
        run: pytest --cov=sanguo_trader
```

---

## 七、成果物管理

### 7.1 发布管理

在 Gitea 中创建 Release：

1. 进入项目的 "Releases" 页面
2. 点击 "New Release"
3. 填写版本号和发布说明
4. 上传附件（可选）

### 7.2 文档管理

- API 文档: 使用 Sphinx 生成
- 用户手册: 存放在 `docs/user/`
- 开发文档: 存放在 `docs/development/`
- 更新日志: `CHANGELOG.md`

---

## 八、协作规范

### 8.1 任务分配

使用 Gitea Issues 跟踪任务：

- 标签：`feature`、`bug`、`enhancement`、`documentation`
- 里程碑：按版本规划
- 负责人：明确任务负责人

### 8.2 日常协作

1. 每日从 `develop` 拉取最新代码
2. 保持功能分支小而专注
3. 及时提交和推送代码
4. 及时响应 PR 审查意见
5. 合并后删除已完成的分支

---

## 九、故障排查

### 9.1 常见问题

**问题：合并冲突**
```bash
# 获取最新代码
git fetch origin

# 重新基于 develop
git rebase origin/develop

# 解决冲突后
git add .
git rebase --continue
```

**问题：提交错误**
```bash
# 修改最后一次提交
git commit --amend

# 撤销提交（保留改动）
git reset --soft HEAD~1
```

---

## 十、相关资源

- [VeighNa 官方文档](https://www.vnpy.com/docs)
- [VeighNa GitHub](https://github.com/vnpy/vnpy)
- [Conventional Commits](https://www.conventionalcommits.org/)
- [Semantic Versioning](https://semver.org/)