test-backend/.claude/git.md

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             ← 备份不是分支

---

日常操作

开始一个新任务

# 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

# 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 禁止操作

# ❌ 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 必须包含

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

## 关联任务
禅道 #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 有描述和测试说明