祝融说。

37.1 五大关键决策点：需求分析、架构设计、修复任务、集成验收、部署

项目背景：以下是一次老系统迁移项目的教学重组复盘——情节基于真实迁移项目的典型决策片段重组而成，具体数字（文件数、文档行数、差距项数等）为演示量级，不对应某一次具体项目记录。

• 后端：Java + Spring Boot，432 个源文件；
• 前端：Vue 3，4 个前端应用（管理端、机构端、考试员端、小程序）；
• 数据库：MySQL；
• 部署：Docker + GitHub Actions；
• 场景：基于旧生产系统的界面和功能，重建新系统；
• 挑战：旧系统有 3248 行的功能描述文档，需要逐字段对照，确保新系统不遗漏任何功能。

这个案例和其他章节不同：前几章学的是"在理想情况下应该怎么做"，这一章看的是"在贴近真实的约束下如何取舍"。两者有差距——而这个差距才是最有价值的部分。

关键决策点一：需求分析——到底用什么技能。

面对"老系统迁移"这个场景，你可能会想：用 Requirements 技能做需求分析。但落到项目实践中，这个决策面临一个选择：用 Requirements 从零分析需求，还是用 Legacy Recon 从老系统还原需求？

• 选择 Requirements 的理由：方法论完整，从 Event Storming 开始逐层推导出需求文档，适合"从零开始"的项目；
• 选择 Legacy Recon 的理由：老系统已经存在，所有功能都已在运行中。与其"重新分析"，不如"逐字段对照"——把老系统已有的功能拆解出来，对照新系统的实现，找出差距。

最终选择了 Legacy Recon。因为老系统有 3248 行的功能描述文档，加上完整的界面快照——这些信息比"重新分析"更准确、更完整。Requirements 需要业务人员参与讨论，而 Legacy Recon 只需要对照已有的实现。

这个决策的核心逻辑：当已有信息比"重新分析"更可靠时，优先使用已有信息。老系统已经上线运行，它的功能描述是对真实需求的精确映射——比任何"分析"都准确。

关键决策点二：架构设计——要不要从头设计。

差距报告出来后，团队面临第二个关键决策：是重新设计架构，还是在现有架构中补充功能？

• 选择重新设计架构的理由：老系统的架构可能有问题，重建时正好可以优化；
• 选择在现有架构中补充的理由：新系统已经上线运行，架构经过验证是稳定的。重新设计会引入不确定性和风险。

最终选择了在现有架构中补充。原因是：差距报告中的 49 项差距，全是"功能遗漏"而非"架构问题"。没有架构性问题，就不需要动架构。

这个决策的核心逻辑：架构设计的价值在于解决问题，而不是为了设计而设计。如果问题不在架构层面，就不要动架构。

关键决策点三：修复任务——要不要用 Workflow。

49 项差距排好优先级后，第三个关键决策：修复任务应该用 Workflow 自动执行，还是用 Coach 手动引导？

• 选择 Workflow 的理由：49 项差距中大部分是"补充遗漏功能"——需求明确、技术方案清晰，符合 Workflow 的适用条件；
• 选择 Coach 的理由：部分修复任务涉及多个模块的联动修改，需要多次确认和调整。

最终混合使用：对"需求明确、单模块修改"的修复任务使用 Workflow 的 auto 模式；对"涉及多个模块、需要确认"的复杂修复任务使用 Coach 手动引导。

过程中的一次重要教训：一个涉及前后端联动的修复任务，用 Workflow 的 auto 模式执行后，验收发现前端和后端的接口约定不一致——因为 Workflow 在单个里程碑中只检查了该模块的正确性，没有检查跨模块的接口一致性。这个问题的根源不是 Workflow 本身，而是"验收标准中没有包含跨模块检查"。之后在验收标准中增加了"跨模块接口一致性检查"，问题没有再出现。

关键决策点四：集成验收——修复优先级怎么排。

所有修复任务独立验收通过后，集成验收时发现了两个问题。第四个关键决策：如何安排修复优先级？

• 选择"全部修复再上线"的理由：问题虽小，但都是"不一致"，累积起来会降低系统质量；
• 选择"关键问题修复后上线，非关键问题后续迭代"的理由：两个问题都不影响核心业务流程（学员注册 → 考试 → 发证），可以上线后逐步修复。

最终选择了折中方案：区分"阻塞性"和"非阻塞性"问题。缓存刷新问题是阻塞性的——影响用户看到最新数据，必须上线前修复。日期格式问题是非阻塞性的——不影响功能，计划在下一个迭代中修复。

这个决策的核心逻辑：不是所有问题都需要在同一个版本中修复。区分"必须修"和"可以等"的能力，是经验带来的判断力。

关键决策点五：部署——自动化到什么程度。

第五个关键决策：部署流程应该全自动化，还是半自动化？

• 选择全自动化的理由：Docker + GitHub Actions 已配置好，可以完整 CI/CD；
• 选择半自动化的理由：项目涉及 4 个前端应用 + 1 个后端应用 + 2 个数据库 + 1 个缓存，全自动化可能导致"自动化了但没人敢用"。

最终选择了半自动化：自动构建 + 手动部署。GitHub Actions 自动完成构建和测试，但部署到生产环境需要手动执行一个 deploy.sh 脚本（支持 IP:端口模式 HTTP 访问、域名模式 Caddy 自动 HTTPS）。

这个决策的核心逻辑：自动化的目的是降低风险，不是增加风险。如果全自动化让你觉得"不可控"，那就留一个人工确认的环节。随着项目稳定运行，可以逐步增加自动化程度。

37.2 Legacy Recon 的"逐字段对照"方法

执行过程：Legacy Recon（老系统还原）专门处理"老系统 → 新系统"的迁移场景。

• 第一步：建立待办清单。将 7 大业务模块拆分为独立的审计任务；
• 第二步：并行审计。每个模块由独立的子代理审计，逐字段/逐功能对照老系统和新系统的实现。审计方法：前端代码检查界面实现、后端代码检查接口实现、数据库 schema 检查数据模型、整理差距（已有/缺失/部分实现）；
• 第三步：产出差距报告。按"地基优先"排序，高中低全纳入分层。

产出示例（差距报告）：

- 高优先级：15 项（影响核心流程）
- 中优先级：23 项（影响用户体验）
- 低优先级：11 项（优化类）
- 第三方依赖标注：5 项（需要外部凭证，延后）

一个典型修复任务的执行过程——任务：补充机构端的学员批量导入功能：

• 下发指令（含需求、技术约束、验收标准——使用现有 Excel 解析工具、输入验证规则与单个添加一致、导入结果页面展示成功/失败列表）；
• 编码：AI 自动完成文件上传、Excel 解析、数据验证、批量写入；
• 验收：功能检查（导入正常、字段验证正确）、架构检查（没有修改核心代码、数据模型一致）、安全检查（上传文件类型验证、SQL 注入防护）→ 结论 PASS → 提交。

进度管理（进度账本 job.progress.md）：

# 老系统功能补齐 — 进度账本
## 已完成
- [x] 机构端·学员批量导入（2026-07-13）
- [x] 机构端·资质变更记录（2026-07-13）
- [x] 管理端·考试员分配（2026-07-14）
- ...
## 进行中
- [ ] 机构端·财务报表导出
## 待办
- [ ] 管理端·数据统计看板
- [ ] 考试员端·评分功能

37.3 哪些技能用到了、哪些没有用到、为什么

用到的技能：

没有用到的技能及原因：

【复盘】经验的价值：知道什么时候不该用什么技能

关键经验：

1. 老系统迁移的关键是"逐字段对照"：不要依赖文档描述，要逐字段对比老系统和新系统的实际实现；
2. 并行审计提高效率：7 大业务模块并行审计，在本案例的规模下明显快于串行（快 3-4 倍为该案例的演示量级）；
3. 按优先级执行：地基优先（数据模型、核心接口），再用户可见功能，最后优化类；
4. 进度账本保持透明：追加式进度账本让所有人随时了解项目状态。

本案例展示了项目实践中最重要的能力：在多个选项之间做出选择，并为每个选择给出理由。五个关键决策点——需求分析用 Legacy Recon 而不是 Requirements、架构设计在现有架构中补充而不是重新设计、修复任务混合使用 Workflow 和 Coach、集成验收区分阻塞性和非阻塞性问题、部署选择半自动化而不是全自动——每一个决策都不是"理论最优"，而是"在当时的约束条件下最合适"。

这就是经验的价值：知道什么时候该用什么技能，更重要的是，知道什么时候不该用什么技能。