# 规范-版本控制与分支策略

> **位置**: `docs/开发规范/规范-版本控制与分支策略.md`
> **版本**: v1.0
> **日期**: 2026-07-08
> **关联**: AGENTS.md

---

## 1. Git 分支模型

```
main                → 生产环境，永远可部署，禁止直接推送
  └── develop       → 开发集成，每日自动构建
        ├── feature/战斗系统重构   → 功能分支，完成后 PR 到 develop
        ├── feature/新增拍卖系统   → 功能分支
        └── hotfix/修复充值漏洞    → 热修分支，从 main 切出
```

### 1.1 分支规则

| 分支 | 来源 | 合并目标 | 命名格式 |
|------|------|----------|----------|
| `main` | — | — | 保护分支 |
| `develop` | `main` | — | 保护分支 |
| `feature/xxx` | `develop` | `develop` | `feature/功能简述` |
| `hotfix/xxx` | `main` | `main` + `develop` | `hotfix/问题简述` |
| `release/vX.Y.Z` | `develop` | `main` + `develop` | `release/v版本号` |

### 1.2 强制规则

- ❌ **禁止直接向 `main` 推送代码**
- ✅ 所有合并必须通过 **Pull Request (PR)**
- ✅ PR 必须至少 **1 人审查通过** 才能合并
- ✅ PR 必须通过 **CI 检查**（编译 + 单元测试 + lint）
- ✅ 合并前必须 **rebase 到目标分支最新**（避免 merge commit 污染历史）

---

## 2. Commit 规范（已在 AGENTS.md 定义，此处补充）

```
<type>(<scope>): <subject>

<body>

Fixes #123
```

### 2.1 Commit 类型

| 类型 | 用途 | 示例 |
|------|------|------|
| `feat` | 新增功能 | `feat(client): 新增闭关系统界面` |
| `fix` | 修复 bug | `fix(server): 修复能量恢复计算溢出` |
| `docs` | 文档修改 | `docs(GDD-02): 修正能量恢复系数` |
| `refactor` | 重构 | `refactor(client): 重构 GameManager 为单例模式` |
| `perf` | 性能优化 | `perf(server): 优化战斗结算并发` |
| `test` | 测试 | `test(client): 新增 EnergySystem 单元测试` |
| `chore` | 杂项 | `chore: 更新 docker-compose 配置` |
| `security` | 安全修复 | `security(server): 修复 SQL 注入漏洞` |

### 2.2 Commit 正文要求

- 说明「为什么」做这次修改，而不仅是「做了什么」
- 如果修改影响外部行为，说明影响范围和迁移步骤
- 引用相关的决策编号（如 `同步 ✅158`）

---

## 3. 代码审查清单

审查者必须在 PR 中确认：

```
□ 代码与 GDD/PRD 对齐
□ 无废弃术语（体力/经验值/破界等）
□ 决策引用格式正确（本地决策带前缀）
□ 无魔法数字（常量已提取并注释来源）
□ 新功能有对应测试
□ 无敏感信息硬编码
□ 数据库变更有 migration 脚本
□ 数据模型变更有迁移函数
```

---

## 4. 版本号规则

采用语义化版本 `v主.次.修订`：

| 版本变化 | 触发条件 | 示例 |
|----------|----------|------|
| 主版本 +1 | 重大架构变更/不兼容协议修改 | v1 → v2 |
| 次版本 +1 | 新功能发布 | v1.2 → v1.3 |
| 修订 +1 | Bug 修复/热更 | v1.2.3 → v1.2.4 |

- 版本号在 `package.json`（client）和 `server/main.go`（server）中同步
- 每次发版必须打 git tag：`git tag -a v1.2.3 -m "版本说明"`

---

## 5. 版本记录

- **v1.0**（2026-07-08）: 初始版本，覆盖分支模型、commit 规范、审查清单、版本号规则
