smart
67837df8d0
- 新增全套考试卷、评估卷、参考答案与考试培训包模板 - 修正slidev培训课件：调整模块标题、链路图缩放，替换工单示例为通用业务对象 - 修正课堂红线表述为证据红线，将小组作业调整为个人作业要求 - 新增权限、状态流转、审计日志、看板指标四类可复用业务规则块 - 整理AI工程技能交付包，迁移旧资产至客户专属交付包并统一术语 - 新增考试输出模板与TRAE使用记录文档
163 lines
6.6 KiB
Markdown
163 lines
6.6 KiB
Markdown
# 模块 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 看起来完整而填写未发生的验证。
|
|
-->
|