# 05 — Git 协作规则

> **适用**：所有 AI 和人工开发任务。分支怎么拉、什么时候合、冲突怎么处理。

---

## 分支模型

```
master ──────────────────────────────────────────→ 生产
  │
  └── test ──────────────────────────────────────→ 测试主线
  └── dev ──────────────────────────────────────→ 开发主线
        │
        ├── feature/任务编号-简短描述              → 新功能
        ├── bugfix/任务编号-简短描述               → Bug修复
        └── hotfix/任务编号-简短描述  (从 master 拉) → 紧急修复
```

### 什么时候从哪拉

| 场景 | 从哪拉 | 合回哪 |
|------|--------|--------|
| 新功能 | `dev` | `dev` |
| Bug 修复 | `dev` | `dev` |
| 紧急线上修复 | `master` | `master` + `dev`（两边都要合） |

### 分支命名

```
feature/2688-用户批量导入        ← 禅道任务号 + 功能描述
bugfix/2690-任务列表分页错误
hotfix/2691-登录验证码绕过

禁止：
feature/xxx                     ← 没任务号
zhangsan-test                   ← 没意义
dev-backup-20260603             ← 备份不是分支
```

---

## 日常操作

### 开始一个新任务

```bash
# 1. 切到 dev，拉最新
git checkout dev
git pull origin dev

# 2. 从 dev 拉分支
git checkout -b feature/任务号-功能描述

# 3. 开发...

# 4. 定期提交（不要攒到最后一次性交）
git add .
git commit -m "feat: xxx"

# 5. 推送到远程（每天至少推一次，防止本地丢失）
git push origin feature/任务号-功能描述
```

### 合并回 dev

```bash
# 1. 确保本地 dev 最新
git checkout dev
git pull origin dev

# 2. 切回自己的分支，rebase dev（让历史干净）
git checkout feature/任务号-功能描述
git rebase dev

# 如果有冲突：
#   - 逐个文件解决冲突
#   - git add <解决的文件>
#   - git rebase --continue
#   - 直到完成

# 3. 推 rebase 后的分支（需要 --force-with-lease，不是 --force）
git push --force-with-lease origin feature/任务号-功能描述

# 4. 到 Git 平台提 PR/MR 到 dev
# PR 标题：feat: 用户管理增加批量导入
# PR 描述：改了什么、怎么测试
```

### 冲突处理

```
1. git status 看哪些文件冲突
2. 打开冲突文件，找到 <<<<<<< ======= >>>>>>> 标记
3. 逐行确认保留哪边的代码
4. 删掉标记符号
5. git add <文件>
6. git rebase --continue 或 git merge --continue
7. 编译验证
```

**常见错误**：看到冲突整块接受一边，把别人的代码覆盖了。必须逐行看。

---

## AI 开发特殊规则

### AI 提交必须标注

```
feat: 用户管理增加批量导入 [AI: Claude Code]

- 新增 UserBatchImportController
- 新增 UserImportService
- 新增 import_batch 表
- 前端增加导入按钮和上传弹窗
```

**为什么**：review 时知道这是 AI 写的，检查更仔细（尤其是边界条件和安全性）。

### AI 解决冲突

AI 遇到冲突时，不能自己决定保留哪边。必须：
1. 列出冲突内容和两边来源
2. 让人类决定
3. 人类确认后再继续

### AI 禁止操作

```bash
# ❌ AI 绝对禁止
git push --force origin dev          # 强制推共享分支
git push --force origin master       # 同上
git reset --hard HEAD~10 && git push -f   # 回退远程历史
git commit --amend && git push -f    # 修改已推送的 commit
```

---

## Commit 格式

```
<type>: <简短描述> [来源标注]

类型：
  feat:     新功能
  fix:      Bug 修复
  refactor: 重构（不改功能）
  style:    格式调整
  docs:     文档
  test:     测试
  chore:    构建/依赖/工具

来源标注（AI 写的必须加）：
  [AI: Claude Code]
  [AI: Kimi]
  [AI: Codex]

正确示例：
  feat: 用户管理增加批量导入 [AI: Claude Code]
  fix: 任务列表分页总数计算错误
  refactor: 提取公共校验逻辑到 BaseService
  chore: 升级 Spring Boot 到 3.5.6

禁止示例：
  update                    ← 无意义
  fix bug                   ← 不知道修的哪个 bug
  修改                      ← 中文且无具体内容
  WIP / temp / test         ← 临时提交应该 squash 掉
```

---

## PR / MR 规范

### PR 必须包含

```markdown
## 改了什么
简要描述改动内容

## 关联任务
禅道 #2688 / 需求文档链接

## 测试方式
- [ ] 本地编译通过
- [ ] 接口测试通过
- [ ] 前端页面正常

## 契约变更
- [ ] 无接口变更
- [ ] 有接口变更 → 已更新 contract/ 目录 → 已通知前端
```

### Review 规则

- 至少一人 approve 才能合
- AI 生成的代码必须至少一人 review
- 改动超过 500 行 → 拆分 PR

---

## .gitignore 必备

```
# Java
target/
*.class
*.jar
*.war

# IDE
.idea/
*.iml
.vscode/
.settings/
.project
.classpath

# 前端
node_modules/
dist/
.env.local

# 系统
.DS_Store
Thumbs.db

# 敏感信息
*.pem
*.key
application-prod.yml  （如果有密码）
```

---

## 检查表

- [ ] 分支从正确的源头拉（功能/Bug → dev，紧急 → master）
- [ ] 分支名包含任务号
- [ ] commit message 有意义
- [ ] AI 提交标注了来源
- [ ] push 前 rebase 了 dev
- [ ] 没用 `--force` 推共享分支
- [ ] 冲突逐行解决，没整块覆盖
- [ ] PR 有描述和测试说明