smart
67837df8d0
- 新增全套考试卷、评估卷、参考答案与考试培训包模板 - 修正slidev培训课件：调整模块标题、链路图缩放，替换工单示例为通用业务对象 - 修正课堂红线表述为证据红线，将小组作业调整为个人作业要求 - 新增权限、状态流转、审计日志、看板指标四类可复用业务规则块 - 整理AI工程技能交付包，迁移旧资产至客户专属交付包并统一术语 - 新增考试输出模板与TRAE使用记录文档
180 lines
9.2 KiB
Markdown
180 lines
9.2 KiB
Markdown
# 模块 7：AI 改动的可演进性审查
|
|
|
|
<div class="mt-6 text-sm">
|
|
|
|
业务行为通过验证，只说明本次任务得到了正确结果。
|
|
|
|
可演进性关心的是下一次规则变化时，能否找到唯一入口、控制影响范围、替换依赖并准确定位回归。
|
|
|
|
</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>
|
|
|
|
<!--
|
|
逐字稿：业务行为通过验证，只能说明本次任务得到了正确结果。可演进性继续追问下一次规则变化时，我们能否快速找到入口、控制影响范围、替换依赖并定位回归。它不重复业务正确性审查，而是降低下一次修改的成本和风险。
|
|
|
|
本模块不重新审查权限、状态、审计等业务正确性，而是检查代码在后续变化中的定位成本和修改风险。
|
|
-->
|
|
|
|
---
|
|
|
|
# 四类会放大后续修改成本的风险
|
|
|
|
<div class="mt-5 text-xs">
|
|
|
|
| 风险 | 典型表现 | 更好的处理 |
|
|
|---|---|---|
|
|
| 修改入口分散 | 一个业务变化要在多个页面、接口或服务中同步修改 | 明确唯一的规则入口和调用边界 |
|
|
| 平行规则 | 同一校验在多个位置各自维护一份 | 让关键规则只有一个权威实现 |
|
|
| 隐藏依赖 | 逻辑依赖环境、全局状态或外部服务却不可见 | 把依赖显式注入、记录或隔离 |
|
|
| 回归难定位 | 失败只能靠全项目搜索和猜测 | 保留可观察结果、场景夹具与最小影响范围 |
|
|
|
|
</div>
|
|
|
|
<!--
|
|
逐字稿：可演进性并不等于过度抽象。真正需要避免的是规则入口分散、同一约束维护多份副本、依赖隐藏在环境或全局状态中，以及失败后只能靠全局搜索猜测原因。更好的实现让关键规则有权威位置，让依赖和回归场景能够被看见和定位。
|
|
|
|
这里的关注点不是要求抽象越多越好，而是让下一次变化能从清晰入口开始，而不是在多个副本和隐含依赖中猜测。
|
|
-->
|
|
|
|
---
|
|
|
|
# 从“本次通过”到“下次可改”
|
|
|
|
<div class="mt-5 text-xs">
|
|
|
|
| 本次交付已确认 | 可演进性还要确认 |
|
|
|---|---|
|
|
| 当前行为符合预期 | 下一次规则变化从哪里修改最清楚 |
|
|
| 本次 diff 已通过构建与测试 | 影响范围能否被调用关系和夹具限制 |
|
|
| 新逻辑放进了可运行的位置 | 关键规则是否有唯一权威位置 |
|
|
| 用例覆盖当前结果 | 失败时能否回到具体场景和依赖定位 |
|
|
|
|
</div>
|
|
|
|
<div class="mt-6 p-3 rounded-xl bg-amber-500/10 border border-amber-500/30 text-sm">
|
|
可演进的改动，不是为未来过度设计，而是不给下一次变化留下多份解释。
|
|
</div>
|
|
|
|
<!--
|
|
逐字稿：功能验证与可演进性是互补关系。前者证明当前行为符合预期，后者保证未来发生规则变化时，不需要在多个位置修改同一含义，也不会难以缩小回归范围。可演进的改动不是提前设计所有未来，而是不给下一次变化留下多份解释。
|
|
|
|
功能验证和可演进性互补。前者证明当前结果，后者降低未来修改与回归的定位成本。
|
|
-->
|
|
|
|
---
|
|
|
|
# 可演进性审查的四个问题
|
|
|
|
<div class="grid grid-cols-2 gap-4 mt-8 text-sm">
|
|
<div class="p-4 rounded-xl bg-blue-500/10 border border-blue-500/30">规则变化时，第一处应修改哪里？</div>
|
|
<div class="p-4 rounded-xl bg-emerald-500/10 border border-emerald-500/30">关键约束是否只有一个权威实现？</div>
|
|
<div class="p-4 rounded-xl bg-amber-500/10 border border-amber-500/30">外部依赖能否替换、观察或明确失败？</div>
|
|
<div class="p-4 rounded-xl bg-red-500/10 border border-red-500/30">回归能否缩小到具体场景、diff 与依赖？</div>
|
|
</div>
|
|
|
|
<div class="mt-7 text-sm text-center op-75">
|
|
审查的目标，是让 AI 生成的改动成为下一次可靠修改的起点。
|
|
</div>
|
|
|
|
<!--
|
|
逐字稿：这四个问题可以作为审查 AI 改动的最小检查框架。规则变化时第一处改哪里，关键约束是否有唯一权威位置，外部依赖能否替换或观察，回归能否缩小到具体场景。能够回答这些问题，AI 生成的改动才不只是一次性交付，而会成为下一次可靠修改的起点。
|
|
|
|
这四个问题将可维护性从泛泛的代码质量讨论，收敛到规则入口、权威位置、依赖边界和回归定位四项工程能力。
|
|
-->
|
|
|
|
---
|
|
|
|
# 公务用车案例：规则入口与状态写入相邻
|
|
|
|
<div class="mt-5 text-xs">
|
|
|
|
| 已读取的实现事实 | 对后续修改的意义 |
|
|
|---|---|
|
|
| `OfficialVehicleDispatchServiceImpl.cancel` 首行使用 `Assert.hasText` 校验取消原因 | 取消原因规则有明确的后端最终保护入口 |
|
|
| 同一方法随后读取派车单、校验 `DISPATCHED` 状态、写入取消状态与原因，并释放车辆 | 规则与其保护的状态写入相邻，影响范围容易阅读 |
|
|
| `OfficialVehicleDispatchServiceImplTest` 直接传入全空白原因并断言异常 | 规则变化可以从同一测试文件开始定位回归 |
|
|
|
|
</div>
|
|
|
|
<div class="mt-6 p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30 text-sm">
|
|
下一次调整“取消原因”规则时，应先从 Service 与这项聚焦测试开始；不应在页面、Controller 和 Service 中维护多份独立规则。
|
|
</div>
|
|
|
|
<!--
|
|
逐字稿：可维护性必须回到实际代码。当前公务用车案例中，取消原因的后端保护在 OfficialVehicleDispatchServiceImpl 的 cancel 方法首行，紧邻后续的状态校验、取消状态写入和车辆释放。对应的单元测试直接传入全空白原因并断言异常。
|
|
|
|
因此下一次调整取消原因规则，第一处应查看 Service 和同一测试文件。页面提示和 Controller 参数接收可以改善体验或协议，但不应成为与 Service 平行、各自演化的业务规则副本。
|
|
-->
|
|
|
|
---
|
|
|
|
# 案例结论：已获得的可维护性证据
|
|
|
|
<div class="grid grid-cols-2 gap-4 mt-6 text-xs">
|
|
|
|
<div>
|
|
|
|
<div class="font-bold text-emerald-500 mb-3">已经由源码与测试支持</div>
|
|
|
|
| 证据 | 可形成的结论 |
|
|
|---|---|
|
|
| 本次训练分支仅改动 Service 参数保护和对应测试 | 改动范围聚焦，未混入页面、SQL 或状态协议调整 |
|
|
| 空白原因在读取派车单与写状态前被拒绝 | 无效输入不会进入后续状态变更路径 |
|
|
| 定向 Maven 测试记录为成功 | 该 Service 场景具备可重复的回归起点 |
|
|
|
|
</div>
|
|
|
|
<div>
|
|
|
|
<div class="font-bold text-amber-500 mb-3">尚不能由现有材料证明</div>
|
|
|
|
| 缺少的证据 | 不能写成的结论 |
|
|
|---|---|
|
|
| 取消接口的 HTTP / 统一异常验证 | 前端会收到何种错误码和提示 |
|
|
| 非空正常取消的集成验证 | 派车、车辆状态与审计已完整回归 |
|
|
| 浏览器与数据库观察记录 | 页面交互和持久化链路已通过 |
|
|
|
|
</div>
|
|
|
|
</div>
|
|
|
|
<div class="mt-6 p-3 rounded-xl bg-blue-500/10 border border-blue-500/30 text-sm">
|
|
可维护性审查也要按证据说话：明确规则入口与回归起点，不把局部验证扩大成全链路结论。
|
|
</div>
|
|
|
|
<!--
|
|
逐字稿：这一页把可维护性判断和证据边界放在一起。本次分支的实际改动集中在 Service 参数保护和对应测试，空白原因会在读取派车单与状态写入前被拒绝，定向 Maven 测试也已成功。这些是已经成立的结论。
|
|
|
|
但现有材料没有执行取消接口的 HTTP 异常映射、非空正常取消的集成路径、浏览器或数据库观察，因此不能把这一条 Service 测试扩大成全链路已通过。工程上的克制，正是维护成本可控的基础。
|
|
-->
|
|
|
|
---
|
|
|
|
# 何时需要重构，何时保持聚焦？
|
|
|
|
<div class="mt-5 text-xs">
|
|
|
|
| 观察到的证据 | 适合的处理 | 不应做的事 |
|
|
|---|---|---|
|
|
| 当前只新增一条取消原因非空规则，且规则入口就在状态变更方法中 | 保持 Service 中的最小改动，并维护同一聚焦测试 | 为单一校验新建没有复用对象的抽象层 |
|
|
| 后续出现多个取消入口且重复表达同一规则 | 先核对全部调用方、状态效果与测试，再评估抽取唯一规则入口 | 未确认重复语义就机械合并代码 |
|
|
| 发现外部调用方、异常协议或审计要求会影响规则 | 补齐接口与集成证据，再调整边界 | 用猜测替代兼容性和回归验证 |
|
|
|
|
</div>
|
|
|
|
<div class="mt-6 p-3 rounded-xl bg-amber-500/10 border border-amber-500/30 text-sm">
|
|
可演进性不是预先堆叠抽象，而是让每次重构都有明确的重复、耦合或回归证据。
|
|
</div>
|
|
|
|
<!--
|
|
逐字稿：当前案例的证据只支持一个小而清晰的 Service 改动和对应测试，不支持为了形式上的可维护性额外建立抽象。只有当后续确实出现多个取消入口、重复规则，或者外部调用和异常协议带来新的边界时，才需要用调用关系和回归证据评估重构。
|
|
|
|
这也是审查 AI 改动的重要原则：AI 很容易提出结构优化候选，但是否重构应由重复语义、耦合关系和可验证的回归风险决定，而不是由代码看起来是否“更抽象”决定。
|
|
-->
|