ljwx-health/docs/06-development/git-workflow.md

Git 分支策略与工作流

项目: LJWX-Health-Arch-V2.0 创建日期: 2026-01-18 适用范围: 架构升级项目期间 维护者: 技术负责人

---

📋 分支策略概览

LJWX Health 架构升级项目采用 Git Flow 变体策略，确保代码质量和发布流程的可控性。

分支结构

main (生产)
  │
  ├─ develop (开发主线)
  │    │
  │    ├─ feature/phase1-profile-scheduling (功能分支)
  │    ├─ feature/phase1-group-baseline (功能分支)
  │    ├─ feature/phase1-data-quality (功能分支)
  │    └─ ...
  │
  ├─ release/v2.0.0-rc1 (发布分支)
  │
  └─ hotfix/critical-bug-fix (热修复分支)

---

🌳 分支类型详解

1. main（主分支）

用途: 生产环境代码，始终保持可发布状态

保护规则:

• ❌ 禁止直接提交
• ✅ 仅允许从 release/* 或 hotfix/* 合并
• ✅ 必须通过 Pull Request
• ✅ 必须 Code Review
• ✅ 必须 CI 通过
• ✅ 必须项目经理批准

合并流程:

# 从 release 分支合并
git checkout main
git merge --no-ff release/v2.0.0-rc1
git tag -a v2.0.0 -m "Release v2.0.0: Phase 1 完成"
git push origin main --tags

---

2. develop（开发主线）

用途: 最新开发代码集成分支

保护规则:

• ❌ 禁止直接提交
• ✅ 仅允许从 feature/* 合并
• ✅ 必须通过 Pull Request
• ✅ 必须 Code Review
• ✅ 必须 CI 通过

合并流程:

# 合并功能分支
git checkout develop
git merge --no-ff feature/phase1-profile-scheduling
git push origin develop

---

3. feature/*（功能分支）

命名规范: feature/[phase]-[task-id]-[description]

示例:

• feature/phase1-profile-scheduling
• feature/phase1-group-baseline
• feature/phase2-risk-profile
• feature/phase3-ai-advisor

生命周期:

# 1. 创建功能分支
git checkout develop
git pull origin develop
git checkout -b feature/phase1-profile-scheduling

# 2. 开发过程
git add .
git commit -m "feat(profile): implement profile generation service"
git push origin feature/phase1-profile-scheduling

# 3. 保持同步
git fetch origin
git rebase origin/develop

# 4. 完成开发，创建 PR
# 在 GitHub/Gitea 创建 Pull Request: feature/xxx → develop

# 5. PR 合并后删除
git checkout develop
git pull origin develop
git branch -d feature/phase1-profile-scheduling
git push origin --delete feature/phase1-profile-scheduling

提交规范:

# 格式: <type>(<scope>): <subject>

# 类型 (type)
feat:     新功能
fix:      Bug 修复
refactor: 重构
test:     测试
docs:     文档
style:    代码格式
perf:     性能优化
chore:    构建/工具变更

# 范围 (scope)
profile   # 画像层
baseline  # 基线层
quality   # 数据质量
ai        # AI 相关
api       # API 接口
db        # 数据库
...

# 示例
git commit -m "feat(profile): add health profile scheduling task"
git commit -m "fix(baseline): correct department baseline calculation"
git commit -m "test(quality): add data quality service tests"

---

4. release/*（发布分支）

命名规范: release/v[major].[minor].[patch]-[tag]

示例:

• release/v2.0.0-rc1 (Phase 1 候选版本)
• release/v2.1.0-rc1 (Phase 2 候选版本)

创建时机: 每个 Phase 完成时

生命周期:

# 1. 从 develop 创建
git checkout develop
git pull origin develop
git checkout -b release/v2.0.0-rc1

# 2. 版本号更新
# 更新 pom.xml 版本号
mvn versions:set -DnewVersion=2.0.0
# 更新 package.json 版本号
npm version 2.0.0

# 3. 最后的 Bug 修复（仅修复，不加新功能）
git commit -m "fix(release): fix critical bugs for v2.0.0"

# 4. 合并到 main
git checkout main
git merge --no-ff release/v2.0.0-rc1
git tag -a v2.0.0 -m "Release v2.0.0: Phase 1 Complete"

# 5. 回合并到 develop
git checkout develop
git merge --no-ff release/v2.0.0-rc1

# 6. 推送
git push origin main develop --tags

# 7. 删除分支
git branch -d release/v2.0.0-rc1
git push origin --delete release/v2.0.0-rc1

---

5. hotfix/*（热修复分支）

命名规范: hotfix/[issue-id]-[description]

示例: hotfix/critical-profile-calculation-error

创建时机: 生产环境紧急 Bug

生命周期:

# 1. 从 main 创建
git checkout main
git pull origin main
git checkout -b hotfix/critical-profile-calculation-error

# 2. 修复 Bug
git commit -m "fix(profile): fix critical calculation error in profile service"

# 3. 合并到 main
git checkout main
git merge --no-ff hotfix/critical-profile-calculation-error
git tag -a v2.0.1 -m "Hotfix v2.0.1: Fix profile calculation"

# 4. 回合并到 develop
git checkout develop
git merge --no-ff hotfix/critical-profile-calculation-error

# 5. 推送
git push origin main develop --tags

# 6. 删除分支
git branch -d hotfix/critical-profile-calculation-error

---

📝 提交信息规范

Conventional Commits 规范

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

<body>

<footer>

Type 类型

Type	描述	示例
feat	新功能	feat(profile): add risk profile calculation
fix	Bug 修复	fix(baseline): correct baseline SQL query
refactor	重构	refactor(quality): extract validation logic
test	测试	test(profile): add profile service unit tests
docs	文档	docs(api): update profile API documentation
style	代码格式	style(profile): format code with prettier
perf	性能优化	perf(baseline): optimize baseline query
chore	构建/工具	chore(deps): upgrade spring boot to 3.2.1
ci	CI 配置	ci(github): add profile build workflow
revert	回退	revert: revert "feat(profile): xxx"

Scope 范围

根据五层架构划分：

Scope	描述	模块
state	状态层	数据采集、标准化
baseline	基线层	基线计算、群体统计
profile	画像层	风险、行为、社交画像
assessment	评估层	评分、风险评级
action	行动层	AI 建议、干预方案
quality	数据质量	质量评分、异常检测
api	API 接口	Controller、DTO
db	数据库	Schema、Migration
infra	基础设施	K8s、Docker、CI

提交示例

# 好的提交
git commit -m "feat(profile): implement health profile scheduling task

- Add generateUserHealthProfile() method to HealthBaselineScoreTasks
- Create HealthProfileService for profile generation
- Add UserHealthProfile entity and mapper
- Schedule daily execution at 03:00

Refs: T1.2.3"

# 坏的提交
git commit -m "update code"  # ❌ 不清晰
git commit -m "fix bug"      # ❌ 没有说明具体问题

---

🔄 Pull Request 流程

PR 创建清单

创建 PR 前确认：

• 代码已在本地测试
• 单元测试已编写且通过
• 代码已格式化
• 分支已 rebase 到最新 develop
• 提交信息符合规范
• 相关文档已更新

PR 模板

## 📋 变更类型

- [ ] 🎉 新功能 (feature)
- [ ] 🐛 Bug 修复 (fix)
- [ ] 🔨 重构 (refactor)
- [ ] 📝 文档 (docs)
- [ ] ✅ 测试 (test)

## 📝 变更描述

**任务 ID**: T1.2.3

**变更内容**:
- 实现画像生成调度任务
- 新增 `HealthProfileService`
- 新增 `UserHealthProfile` 实体

**相关文档**:
- [实施计划](docs/02-architecture/health-monitoring-implementation-plan.md#122-画像层调度任务-w2-3)

## ✅ 测试

- [x] 单元测试通过 (覆盖率 85%)
- [x] 集成测试通过
- [x] 手动测试通过

**测试用例**:
- 画像生成成功率 > 95%
- 调度任务按时执行

## 📸 截图/日志

（如有必要，添加截图或日志）

## 🔗 相关链接

- 任务: #123
- 文档: [链接]

## 👀 Reviewer

@tech-lead

Code Review 标准

Reviewer 检查清单:

• 功能正确性: 代码逻辑正确，满足需求
• 代码质量: 遵循编码规范，可读性好
• 性能: 无明显性能问题
• 安全性: 无 SQL 注入、XSS 等安全漏洞
• 测试覆盖: 单元测试覆盖率 > 80%
• 文档: 复杂逻辑有注释，API 有文档
• 向后兼容: 不破坏现有功能

Review 评论规范:

# 建议格式
[级别] 类别: 具体问题

级别:
- 🔴 Blocker: 必须修改才能合并
- 🟡 Major: 建议修改
- 🟢 Minor: 可选改进
- 💡 Nit: 小建议

示例:
🔴 Security: 此处存在 SQL 注入风险，建议使用参数化查询
🟡 Performance: 此处可使用批量查询优化性能
💡 Style: 建议将此方法提取为独立函数

---

🚀 常见工作流场景

场景 1: 开始 Phase 1 Task 1.2.3 开发

# 1. 更新 develop
git checkout develop
git pull origin develop

# 2. 创建功能分支
git checkout -b feature/phase1-profile-scheduling

# 3. 开发
# ... 编写代码 ...

# 4. 提交
git add .
git commit -m "feat(profile): implement profile scheduling task"

# 5. 推送
git push origin feature/phase1-profile-scheduling

# 6. 创建 PR (在 GitHub/Gitea UI)
# feature/phase1-profile-scheduling → develop

场景 2: 功能分支落后 develop，需要同步

# 方法 1: Rebase (推荐，保持线性历史)
git checkout feature/phase1-profile-scheduling
git fetch origin
git rebase origin/develop

# 如有冲突
git status  # 查看冲突文件
# 手动解决冲突
git add .
git rebase --continue

git push origin feature/phase1-profile-scheduling --force-with-lease

# 方法 2: Merge (保留分支历史)
git checkout feature/phase1-profile-scheduling
git merge origin/develop
git push origin feature/phase1-profile-scheduling

场景 3: Phase 1 完成，准备发布

# 1. 创建 release 分支
git checkout develop
git pull origin develop
git checkout -b release/v2.0.0-rc1

# 2. 更新版本号
cd ljwx-boot
mvn versions:set -DnewVersion=2.0.0
git commit -am "chore(release): bump version to 2.0.0"

# 3. UAT 测试期间修复 Bug
git commit -m "fix(release): fix minor bugs found in UAT"

# 4. 合并到 main
git checkout main
git merge --no-ff release/v2.0.0-rc1
git tag -a v2.0.0 -m "Release v2.0.0: Phase 1 Complete"

# 5. 回合并到 develop
git checkout develop
git merge --no-ff release/v2.0.0-rc1

# 6. 推送
git push origin main develop --tags

场景 4: 生产环境紧急 Bug

# 1. 从 main 创建 hotfix
git checkout main
git pull origin main
git checkout -b hotfix/critical-profile-error

# 2. 修复
git commit -m "fix(profile): fix critical calculation error"

# 3. 合并到 main
git checkout main
git merge --no-ff hotfix/critical-profile-error
git tag -a v2.0.1 -m "Hotfix v2.0.1"

# 4. 回合并到 develop
git checkout develop
git merge --no-ff hotfix/critical-profile-error

# 5. 推送
git push origin main develop --tags

# 6. 部署到生产
./scripts/deploy-k3s-with-ingress.sh

---

🛡️ 分支保护规则（GitHub/Gitea 配置）

main 分支

Branch Protection Rules:
  - Require pull request reviews before merging
    - Required approving reviews: 2
    - Dismiss stale pull request approvals when new commits are pushed
  - Require status checks to pass before merging
    - unit-tests
    - integration-tests
    - sonarqube-scan
  - Require branches to be up to date before merging
  - Require conversation resolution before merging
  - Include administrators
  - Restrict who can push to matching branches
    - Only: Project Managers, Tech Leads

develop 分支

Branch Protection Rules:
  - Require pull request reviews before merging
    - Required approving reviews: 1
  - Require status checks to pass before merging
    - unit-tests
    - integration-tests
  - Require branches to be up to date before merging
  - Do not allow bypassing the above settings

---

📊 分支生命周期示意图

时间线: W1 ──────── W6 ──────── W14 ──────── W24 ──────── W28 ────────>
        │           │           │            │           │
main    ●───────────●v2.0.0─────●v2.1.0──────●v2.2.0─────●v2.3.0
        │           │           │            │           │
develop ●───┬───┬───●───┬───┬───●───┬────┬───●───┬───────●
            │   │       │   │       │    │       │
feature/*   ●───┘   ●───┘   ●───────┘    ●───────┘
            P1-1    P1-2    P2-1         P3-1

---

🔍 故障排查

问题 1: Push 被拒绝

# 错误
! [rejected]        feature/xxx -> feature/xxx (non-fast-forward)

# 原因: 远程分支有新提交
# 解决:
git pull --rebase origin feature/xxx
git push origin feature/xxx

问题 2: Rebase 冲突

# 停在冲突处
CONFLICT (content): Merge conflict in file.java

# 解决步骤:
1. 打开冲突文件，手动解决冲突
2. git add file.java
3. git rebase --continue

# 如果想放弃 rebase
git rebase --abort

问题 3: 误提交到错误分支

# 场景: 在 develop 上直接提交了
git log  # 查看最后一次提交 commit-hash

# 方法 1: Cherry-pick 到正确分支
git checkout -b feature/correct-branch
git cherry-pick commit-hash
git checkout develop
git reset --hard HEAD~1

# 方法 2: 使用 reflog 恢复
git reflog
git reset --hard HEAD@{n}

---

📚 参考资源

• Git Flow 原理
• Conventional Commits
• 实施计划
• 进度跟踪

---

文档版本: v1.0 最后更新: 2026-01-18 维护者: 技术负责人