# 模块 3：AI 变更的 Git 协作与合并控制

<div class="mt-6 text-sm">

TRAE 可以加快修改，但不能绕开 Git 的可追溯、可审查和可回退要求。

AI 参与的改动越多，越要让分支、提交和合并边界保持清楚。

</div>

<div class="grid grid-cols-4 gap-3 mt-8 text-sm">
<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">分支范围</div>
<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">提交粒度</div>
<div class="p-3 rounded-xl bg-amber-500/10 border border-amber-500/30">冲突处理</div>
<div class="p-3 rounded-xl bg-red-500/10 border border-red-500/30">合并控制</div>
</div>

<!--
逐字稿：AI 可以帮助生成修改，但不能绕过 Git 带来的工程边界。分支、提交和合并控制让每次业务变更都能被理解、审查和回退。AI 参与得越多，越需要这些边界来隔离无关改动和错误假设。

Git 记录的不是操作痕迹，而是可被理解和恢复的业务变更。AI 参与越多，越需要用分支和提交来维持清晰边界。
-->

---

# 分支和提交要服务于审查

<div class="mt-5 text-xs">

| 做法 | 为什么重要 | 公务用车案例 |
|---|---|---|
| 一个分支只解决一个问题 | diff 容易审查和回退 | 取消原因保护不混入无关重构 |
| 一个提交对应一个可验证动作 | 可定位问题和选择性回退 | 参数保护与对应测试保持一致 |
| 提交前排除无关文件 | 噪声不会掩盖业务风险 | 构建生成物不应混入业务变更 |
| 描述真实变更与验证情况 | 后续定位有证据 | 提交信息和 PR 只写有依据的验证 |

</div>

<!--
逐字稿：分支和提交不是为了制造更多操作步骤，而是为了服务审查和恢复。一个分支解决一个问题，一个提交对应一个可验证动作，无关文件不混入业务变更。这样出现问题时，团队能定位影响，也能有针对性地回退。

公务用车案例的改动范围只包含 Service 参数保护及对应测试。构建生成物和无关格式调整没有纳入提交，这比把所有变动都塞进一个“fix”提交更适合 review 和回退。
-->

---

# 合并前的四道检查

<div class="mt-5 text-xs">

| 检查点 | 要确认什么 | 当前案例的检查问题 |
|---|---|---|
| 范围 | diff 是否只包含已说明的改动 | 是否只有 Service 校验和相应测试？ |
| 证据 | PR 是否如实标记测试、风险和未确认项 | 是否把 API 或浏览器验证误写为已通过？ |
| 冲突 | 是否理解双方业务意图 | 是否保留“写入前校验”的顺序？ |
| 回退 | 是否知道回退哪个提交、是否涉及数据补偿 | 代码改动可以选择性回退；集成数据仍需另行核对 |

</div>

<!--
逐字稿：合并前先检查四件事：范围是否收敛、测试和风险是否如实、冲突是否理解双方业务意图、回退点是否明确。任何一项说不清，都不应急于合并。TRAE 可以帮助解释 diff 和冲突，但保留哪段逻辑仍由规则与代码证据决定。

这四项中任何一项不清楚，都不应该急于合并。对冲突不确定时，TRAE 可以解释两段逻辑的差异，但保留哪段必须由业务约束和代码证据决定。
-->

---

# 用 TRAE 审查变更范围

<div class="mt-5 text-xs">

```md
请检查以下 git diff 是否符合本次变更范围。

目标：取消派车必须由后端拒绝空白取消原因。
允许修改：Dispatch Service 的参数保护和对应的聚焦测试。
禁止修改：SQL、权限、菜单、前端页面、派车/行程状态协议、无关格式。
证据：实际 Maven 定向测试结果；API 和浏览器验证尚未执行。

请输出：直接相关改动、可能无关或风险较高改动、
合并前必须补充的验证、回退点。
```

</div>

<!--
逐字稿：这是一份用于审查变更范围的任务上下文契约，不是让 AI 重新定义业务需求。输入中要写清目标、允许范围、禁止范围和实际验证证据。AI 的输出应识别直接相关改动、可疑改动、合并前缺口和回退点，不能凭空补齐未完成的集成验证。

这份任务上下文契约审查的是范围，不是重新判断业务需求。输入要把允许和禁止范围写清，尤其要提供实际证据，防止模型凭空认定集成验证已完成。
-->

---

# Git 历史也是工程接口

<div class="grid grid-cols-4 gap-3 mt-8 text-sm">
<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">看得懂<br><span class="text-xs op-70">目标与范围一致</span></div>
<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">审得动<br><span class="text-xs op-70">每次改动足够聚焦</span></div>
<div class="p-3 rounded-xl bg-amber-500/10 border border-amber-500/30">退得回<br><span class="text-xs op-70">影响与恢复路径清楚</span></div>
<div class="p-3 rounded-xl bg-red-500/10 border border-red-500/30">查得到<br><span class="text-xs op-70">结论能对应 diff 与证据</span></div>
</div>

<div class="mt-7 text-sm text-center op-75">
AI 可以生成改动，Git 负责把改动保留为可理解、可审查的工程历史。
</div>

<!--
逐字稿：Git 历史本身也是工程接口。后续维护者应当从提交和 diff 中看懂目标和范围，评审者应能审查每次聚焦改动，出现异常时也能知道退回哪里。AI 生成的是候选变更，Git 保留下来的是可理解、可验证的工程历史。

本案例的真实分支只包含 Service 参数保护及对应的聚焦测试。它说明规则保护已经落在后端最终边界，但单测通过仍不足以得出“接口、数据库、浏览器链路可发布”的结论。
-->