# 模块 2：标准 PR 说明与 AI 使用记录

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

PR 是团队协作里最稳定的交付节点。

如果 TRAE 参与了需求拆解、代码修改、测试和 Review，PR 说明里就要能看见这些证据。

</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-purple-500/10 border border-purple-500/30">风险与 AI 记录</div>
</div>

<!--
逐字稿：PR 是代码进入协作和评审的稳定节点。这里要保留的是与本次变更有关的事实、证据和风险，而不是完整的 AI 对话。评审者应当能快速看清为什么改、改了什么、验证到哪里，以及还有哪些边界没有确认。

PR 中需要留下的是与变更有关的事实、证据和风险，而不是完整聊天记录。reviewer 应能快速回答：为什么改、改了什么、测了什么、还有什么没有确认。
-->

---

# PR 模板

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

```md
## 需求背景
<为什么做，本次解决什么>

## 实现说明
<改了哪些模块、接口、页面、规则>

## 测试结果
- [ ] 单元测试：
- [ ] 接口验证：
- [ ] 浏览器验证：
- [ ] 手工验收：

## 风险点
<权限、状态、审计、异常、兼容性、数据范围>

## AI 使用记录
<TRAE 协助了哪些步骤，哪些建议被采纳，哪些被人工否决>

## 关联资产
<使用了哪些 rules、任务上下文契约、skills、checklists>
```

</div>

<!--
逐字稿：这份模板按评审者的阅读顺序组织。测试没有执行就明确标记为未执行，不能用含糊表述填补验证空白。AI 使用记录也只保留影响实现或判断的建议，以及人工采纳或否决的理由。

模板按 reviewer 的阅读顺序组织。未执行的测试必须如实填“未执行”，不能用模糊描述掩盖测试缺口。AI 使用记录只保留影响决策的建议和人工取舍。
-->

---

# PR 说明示例

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

```md
## 需求背景
取消已派车任务时，后端必须拒绝空白取消原因。

## 实现说明
- `OfficialVehicleDispatchServiceImpl.cancel` 在状态写入前加入 `Assert.hasText`。
- 新增全空白取消原因的 Service 单元测试。
- 未改前端必填、权限、审计、SQL、派车和行程逻辑。

## 测试结果
- [x] 单元测试：覆盖空白取消原因的拒绝行为。
- [ ] 接口、数据库、浏览器和审计验证：按实际执行情况记录。

## 风险点
统一异常映射、非空正常取消路径和外部调用方需要单独确认。
```

</div>

<!--
逐字稿：示例的价值在于它只陈述已经有依据支持的内容。它明确改动放在 Service 的写入前校验，也明确哪些相邻范围没有修改。接口、浏览器和审计验证尚未执行，就必须如实保留为待验证项。

这段示例只记录已有证据支持的变更与测试结果。未执行的接口或浏览器验证必须如实标记，不能为了让 PR 看起来完整而写成通过。
-->

---

# TRAE 生成 PR 说明的任务上下文契约

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

```md
请基于以下材料生成标准 PR 说明：任务背景、
main 与当前分支的 git diff、实际测试结果、Review 结论、
使用过的 rules、任务上下文契约、skills。

输出必须包含：需求背景、实现说明、测试结果、风险点、
AI 使用记录、关联资产。

要求：不要编造测试结果；没有证据的测试项标记“未执行”；
风险必须具体到模块或文件；不要将训练约束写成客户既有需求。
```

</div>

<!--
逐字稿：让 TRAE 起草 PR 说明时，最关键的输入不是一句需求，而是实际 diff、实际测试结果和已有 Review 结论。输出结构要固定，尤其要求未执行项如实标记、风险具体到模块或文件。生成后的每一条事实仍由提交者核对和负责。

这里最关键的是输入必须包含实际 diff 和实际命令结果。TRAE 生成后，提交者仍要对每个事实负责，尤其要检查它有没有擅自补全测试结果或客户业务结论。
-->

---

# AI 使用记录表

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

| 环节 | TRAE 做了什么 | 人工判断 | 沉淀内容 |
|---|---|---|---|
| 代码理解 | 定位前端必填、取消 API、权限、审计和 Service | 用源码逐条核对 | 影响分析任务上下文契约 |
| 方案选择 | 建议 Service 作为最终保护边界 | 因状态变更和车辆释放都在此处而采纳 | 状态变更 Rule |
| 测试设计 | 提出空白输入与正常取消回归点 | 仅将实际执行的空白单测标为通过 | 测试安全网 |
| 交付说明 | 整理最小 diff、风险和待确认项 | 删除任何无证据的“已验证”表述 | PR 模板 |

</div>

<!--
逐字稿：AI 使用记录的目的不是统计工具使用次数，而是复盘人机分工。代码理解、方案选择、测试设计和交付说明中，哪些建议被源码或测试支持，哪些被人工否决，都应该留下可复核的理由。反复出现的人工修正，才是以后沉淀 Rule、任务上下文契约或检查清单的依据。

记录 AI 使用不是为了统计对话，而是为了看清它在哪些环节有用、哪些结论仍需人工取证。反复出现的人工修正，才值得升级为 Rule、任务上下文契约或检查清单。
-->

---

# AI 使用记录不是聊天记录

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

| 应保留 | 不必保留 |
|---|---|
| 影响实现或验证结论的 AI 建议 | 完整对话逐字稿 |
| 人工采纳或否决建议的理由 | 与本次改动无关的探索 |
| 关联的 Rule、任务上下文契约、Skill 或检查单 | 无法复查的笼统评价 |
| 未解决风险和待确认边界 | 把推断包装成已验证结论 |

</div>

<div class="mt-6 p-3 rounded-xl bg-blue-500/10 border border-blue-500/30 text-sm">
好的 PR 说明，让评审者看到工程结论，而不是看到一段 AI 对话。
</div>

<!--
逐字稿：AI 使用记录不等于聊天记录。应当保留影响设计、实现或验证结论的建议，保留人工取舍的原因，保留关联资产和未解决风险。与本次改动无关的探索以及无法复核的评价，不会帮助后续评审，也不应成为工程记录的一部分。

本案例中的变更范围、Maven 记录和影响分析都可以回到对应的源码与执行材料核对。关键是不能为了让 PR 看起来完整而填写未发生的验证。
-->