patbond-doc/docs/development/iterations/iteration-2/08-git-workflow-plan.md

08 M2 Git 与 CI 工作流规划

• 执行人：Git Workflow Master
• 日期：2026-09-07
• 范围：第二迭代（M2 宠物健康档案）开工前的三仓状态核查、分支/提交策略、CI 扩展与防泄漏规划。本报告只核查与规划，未改动任何代码、工作流或 mkdocs.yml。

---

1. 三仓当前状态核查（2026-09-07 实测）

仓库	分支	相对 origin	工作区	stash	最新提交 CI 状态
patbond-api	dev	同步（fetch 后确认）	干净	无	success（0d81c38，CI / backend-test，run 6）
patbond-flutter	dev	同步	干净	无	success（3f8388e，CI / flutter-gates，run 11）
patbond-doc	main	同步	干净	无	success（5537f92，CI / docs-build）

CI 状态经 Gitea commit status API 逐仓核实，非转述。

未提交内容清单：无。 第一迭代「三仓改动长期未 commit」的教训在收官阶段已彻底闭环——包括上次报告中留给用户自决的 patbond-flutter README.md 也已入库。唯一例外是本报告文件本身（写入 patbond-doc 后为未跟踪状态），按第 3 节波次规则随下一波提交。

两处非阻塞的历史遗留（可选清理，待拍板）：

• patbond-api 本地 master 分支（ff876bc）的上游 origin/master 已在远端删除（branch -vv 显示「丢失」）。本地分支可删：git branch -D master（确认无独有提交后执行；ff876bc 是初始 README 提交，早已被 dev 包含的话可安全删除，删前用 git merge-base --is-ancestor ff876bc dev 核实）。
• patbond-flutter 本地 main（030b11f）与远端 origin/main 均落后于 dev。dev 是事实集成分支，main 处于闲置态。M2 不动它；若未来引入「main = 可发布」语义（见 2.3），届时再统一处理。

2. M2 分支与提交策略

2.1 现状评估

第一迭代的 trunk-based 小步直推 dev（doc 直推 main）配合本地门禁运转良好：历史线性、无合并冲突、每个提交自带验收证据。但当时 CI 尚未上线，「门禁不绿不提交」全靠自觉；现在三仓 CI 已在 push 时执行同一套门禁，且三个 ci.yml 均已配置 pull_request: 触发器——PR 合入前门禁是零成本就绪的，只差用不用。

2.2 推荐方案（待拍板）：trunk-based 为主 + 高风险改动走 PR

两人 + AI 辅助的协作模式下，日常改动走 PR 的评审收益低、流程开销高，不推荐全面切换。推荐分层：

• 日常改动（单波次内可完成、不动 schema、不动跨仓契约）：继续小步直推 dev（doc 直推 main）。CI 在 push 后兜底，红了立即修——两人团队里一个红提交的传播面可控。
• 高风险改动强制走短命分支 + Gitea PR，合入前 CI 必须绿。触发条件（满足其一）：
  1. 新增/变更 Flyway 迁移（M2 的宠物健康档案必然新增 V3__*.sql，首当其冲）；
  2. 跨仓契约变更（openapi.yaml 的破坏性修改）;
  3. 依赖升级、大规模重构；
  4. 两人同时改同一仓库的并行期。
• 分支命名沿用规范：feat/<主题>、fix/<主题>（如 feat/pet-health-schema），合入后即删，不留长期分叉。
• 个人分支整理历史用 git push --force-with-lease；共享分支（dev/main）依旧禁止 force push、禁止改写已推送历史。

选择理由：这是对现行 git-workflow.md 第 9 行「何时开 feature 分支」条款的最小延伸——把「破坏性风险」具体化为可判定的清单，并利用已就绪的 PR 触发器让 CI 在合入前把关，而不是引入一套全新流程。

配套（可选，待拍板）：在 Gitea 仓库设置中为 dev/main 开启分支保护，勾选「合并前需状态检查通过」并选中 CI 上下文。两人团队可以不开（靠约定），开了则规则由平台强制执行，AI 辅助开发场景下多一道机械防线。

2.3 暂不引入的东西

• 不引入 Git Flow / develop-release 双轨——没有版本化发布压力，dev 单集成分支足够。
• 不引入 main 发布分支语义——等 M3 有部署目标后再议。

3. M2 提交节奏规范

3.1 波次即提交（第一迭代教训的制度化）

• 每个波次收尾时，三仓凡有改动必须 commit 并 push，push 后确认 CI 绿，才算波次闭环。 波次报告中记录各仓提交哈希与 CI 结论（沿用第一迭代收官报告的做法）。
• 波次中途允许多次小提交（鼓励），但不允许波次结束时仍有未提交改动过夜。
• AI 会话结束前，执行者对三仓各跑一次 git status，把结果写进波次报告——「工作区干净」要有出处。

3.2 提交信息：沿用现行约定，不引入新格式

git-workflow.md 已固化的「feat/fix/refactor/docs/test/chore 前缀 + 中文主题 + 正文验收证据 + ADR 引用」在第一迭代全程执行良好（近 20 个提交无一例外），M2 原样沿用，不引入英文 conventional commits 或 scope 括号语法——现行格式已具备 conventional commits 的全部实用价值（可 grep、可归类、可回溯），改格式只会割裂历史。

M2 补充一条：涉及契约的提交，正文注明对应的 openapi.yaml 版本或 doc 仓提交哈希（见 3.3）。

3.3 契约先行时的三仓提交顺序

M2 采用契约先行，顺序固定为：

1. patbond-doc 先行：docs/api/openapi.yaml 的契约变更单独成提交（docs: 宠物健康档案 API 契约（M2 波次 N）），push 且 docs-build 绿。契约提交不与其他文档改动混杂，保证可独立引用与回退。
2. patbond-api 跟进：实现 + 测试成一或多个提交，正文引用 doc 仓契约提交哈希，push 且 backend-test 绿。
3. patbond-flutter 收尾：对接实现，正文同样引用契约哈希，push 且 flutter-gates 绿。

契约中途返工时，doc 仓允许在同波次内追加修订提交（契约未被下游消费前不算破坏性变更）；一旦 api/flutter 已按某版契约合入，再改即视为破坏性修改，走 2.2 的 PR 通道。

4. CI 扩展规划

4.1 现状修正：任务假设的两问已被第一迭代末的事实回答

核查发现三仓 CI 均已上线且全绿，任务中「flutter 是否接入 CI」「doc 是否加 --strict 门禁」不再是开放问题：

• patbond-flutter CI 已上线并验证可行（run 11 success）。零外部 action 约束下 Flutter SDK 进容器的方案已在 ci.yml 中落地：从 flutter-io.cn 镜像 curl 下载 Flutter 3.44.6 的 tar.xz，解压到挂载的 gitea_toolcache 卷（runner container.options 配置 -v gitea_toolcache:/opt/hostedtoolcache），首跑下载约 900MB，后续 run 复用缓存秒级就绪；pub 走 pub.flutter-io.cn。门禁为 format/analyze/test 三命令，与本地一致。
• patbond-doc 的 mkdocs build --strict 门禁已上线（apt 装 mkdocs，规避 PEP 668；docs-build success）。
• patbond-api CI 全绿（82 测试，约 3m18s），Testcontainers 经 docker.sock 挂载正常工作。

4.2 M2 的 CI 增量（按优先级，均为规划，实施时再改文件）

1. 无必做项。 三条流水线覆盖了全部本地门禁，M2 开工不被 CI 阻塞。
2. 可选——Flutter 版本升级流程注明：toolcache 以 flutter-3.44.6 目录名区分版本，升级 SDK 时改 ci.yml 中 FLUTTER_VERSION 即自动触发新版本下载，旧目录需手动清理卷（写入 ci-runner-setup.md 的常见问题即可，M2 内低优先）。
3. 可选——api CI 增加 M2 迁移的守护：./mvnw clean test 已覆盖 Flyway 迁移执行（Testcontainers 起真库跑迁移），无需新增步骤；只需坚持「已推送迁移不可变」规则。
4. 明确不做：flutter build apk 冒烟（耗时大、M2 无发布需求）、覆盖率门槛（先积累基线再谈阈值）。

5. 敏感信息防泄漏（轻量方案规划，待拍板后实施）

现状：三仓 .git/hooks 均只有样例，无任何自动检查；卫生完全靠 git-workflow.md 约定 + 提交前人工核对。api 仓敏感配置已按 *.sample 模式管理（真实 application.yml 在 gitignore 中）。AI 辅助开发下，机械防线值得补上。零外部 action 约束下推荐两层，均为纯 shell + grep，无任何外部依赖：

5.1 第一层：入库的共享 pre-commit 脚本（推荐先做）

• 各仓新增 scripts/hooks/pre-commit（入库，可评审、可演进），检查 git diff --cached 的暂存内容：
  • 文件名黑名单：拦截 application.yml（非 .sample）、.env、*.pem、*.p12、*.jks、key.properties 等入暂存区；
  • 内容模式：对暂存 diff 的新增行 grep 常见凭据特征——BEGIN (RSA |EC )?PRIVATE KEY、password:/secret: 后跟非占位值（排除 changeme、your-*、<placeholder> 等样例值）、长 base64/hex token 形态；
  • 命中即拒绝提交并打印命中行号（不打印命中内容全文，避免终端留痕）。
• 启用方式为一次性 git config core.hooksPath scripts/hooks（每仓每机各执行一次，写入各仓 README）。hook 可被 --no-verify 绕过——这是特性不是缺陷：误报时有出口，且第二层兜底。

5.2 第二层：CI 侧兜底 grep（各仓 ci.yml 加一个 step）

• checkout 后加一个纯 shell step，对整棵工作树跑同一套文件名/内容模式检查（复用 5.1 的脚本，保证两层规则同源），命中则 fail。零外部 action，新增耗时秒级。
• 与 pre-commit 的分工：hook 拦「即将提交的」，CI 拦「已经提交的」（含 --no-verify 绕过和历史遗漏的新暴露）。CI 只查工作树而不扫全历史——扫历史属一次性审计，若做一次即可，不进流水线。

5.3 不推荐

• gitleaks/trufflehog 等外部工具：与零外部依赖约束冲突（需拉二进制或镜像），且对本项目的敏感面（一个 application.yml + 未来的第三方 key）而言是牛刀。
• 提交后自动改写历史清除泄漏：一旦真泄漏，正确动作是立即轮换凭据，再考虑历史清理——写入规范备忘即可。

6. 待拍板事项汇总

#	事项	推荐	见
1	M2 分支策略：trunk-based 为主 + 高风险改动（Flyway 迁移/契约破坏性变更/依赖升级/并行期）强制短命分支 + PR	采纳	2.2
2	Gitea dev/main 分支保护 + 状态检查强制	可选，倾向开启	2.2
3	提交信息格式沿用现行中文约定，不切换英文 conventional commits	沿用	3.2
4	契约先行三仓提交顺序：doc → api → flutter，契约提交独立成提交并被下游引用	采纳	3.3
5	防泄漏两层方案（共享 pre-commit 脚本 + CI 兜底 grep）	采纳，M2 第一波实施	5
6	patbond-api 本地孤儿 master 分支清理	顺手做	1

采纳后需要落实的文件改动（本报告未执行）：各仓 scripts/hooks/pre-commit 与 ci.yml 的兜底 step、git-workflow.md 增补 2.2/3.1/3.3 条款、本报告挂入 mkdocs 导航。