🏠 主目录 | ⬅️ 上一章 (Ch.08) | ➡️ 下一章 (Ch.10) | 🌐 English

Ch.09 先建立基线，再逐步改造旧系统

问题：无测试的旧系统难以判断改动是否破坏现有行为。

本章实践：先画依赖图并补关键路径测试，再按小范围提交重构。

在独立开发或承接存量项目时，最让人胆战心惊的莫过于接手前人留下、毫无文档且零单测覆盖的“屎山”工程。任何微小的改动，都可能引爆隐藏在深处的连环地雷。

面对这类遗留系统，千万不要冲动推倒重写。先读清入口、依赖和关键行为，再用可重复的测试保护现有功能；模型上下文大小不能代替逐步验证。

---

理解方式：在高速公路上给飞驰的老卡车换轮胎

重构正在跑着的遗留老系统，就像这样一种高危操作：

【莽撞全面重写】 ──> ❌ “这台老卡车太破了，我要在路边重新手搓一台新车！”
                     （结果新车造了 6 个月没造出来，业务早断粮饿死了。）
【渐进式微创解耦】──> ✅ 老卡车继续在高速上拉货（核心业务不中断）：
                     1. 先拿无人机拍底盘（让 AI 扫描全仓生成拓扑地图）；
                     2. 装上安全防侧翻支架（为关键接口编写基准行为快照）；
                     3. 每次只拆卸一颗生锈的螺丝，换好测跑没问题再动下一颗。

Codex 就是带毫米级激光仪的特种维修臂，只要你给它戴上测试护栏，它就能精准切下坏疽而不伤及健康肌肉。

---

动手实践：先完成这 3 步

接手一个陌生混乱仓库的第一天，按这 3 步稳健破局：

1. 步骤一：让 AI 输出全仓拓扑地图（只读探索）
   在终端运行只读沙盒分析，生成 Mermaid 依赖图：

   codex exec --sandbox read-only "分析项目整体架构与数据库模型，在 docs/topology.md 中输出 Mermaid 依赖图"

2. 步骤二：为要修改的接口拍一张“行为快照”（录制基准）
   要求 Codex：“不要动 src/api/ 的业务代码，只为现有接口补齐 3 个成功与失败的单元测试”。
3. 步骤三：单点切除并用测试断言守门
   下发微创重构 Specs，要求：“每次仅抽离一个函数，且修改后自动执行 npm test，测试必须全绿”。

---

9.1 第一步：全景逆向，建立代码拓扑图

接手混乱项目的首要任务是画出全景地图。利用 GPT-5.6 Terra 的长上下文扫描能力直接逆向出 Mermaid 实体关系图（ERD）与路由拓扑：

# 🎯 Goal
分析当前项目的数据库配置与路由层，生成核心表结构外键关联的 Mermaid ERD 图。

# 🛑 Constraints
- 只分析 prisma/schema.prisma 或 src/db/models/。
- 排除临时缓存表与第三方集成日志表。

# 🧪 Validation Specs
- 在 docs/database_topology.md 中输出语法正确的 Mermaid 渲染图。

Codex 几秒钟即可梳理出核心实体之间的多对多与级联关联，效率远胜人肉翻代码。

---

9.2 第二步：安全红线，编写行为基准测试

重构遗留代码的绝对铁律是：动手术前，必须先拉起生命体征监护仪（基准测试）。

# 🎯 Goal
为 src/pages/api/checkout.ts 接口编写基准单元测试，捕获当前真实的入参与返回快照。

# 🛑 Constraints
- 严禁修改 src/pages/api/checkout.ts 本身的任何逻辑代码。
- 使用本地 Jest / Vitest 执行测试套件。

# 🧪 Validation Specs
- 覆盖三种核心分支：正常结算、库存告罄报错、未认证拦截。
- 确保基准测试在当前旧代码上 100% 通过。

---

9.3 第三步：微创手术，实施渐进式解耦

1. 拆解胖控制器 (Fat Controllers)

将混杂在几百行单文件里的鉴权、打折、库存扣减逐个剔除为纯函数：

# 🎯 Goal
将 src/pages/api/checkout.ts 中的“折扣计算逻辑”抽离为独立服务 src/services/discountService.ts。

# 🛑 Constraints
- 外部 API 接口的 Request / Response JSON 格式必须保持严格向下兼容。
- 严禁影响 checkout.ts 的其他核心逻辑分支。

# 🧪 Validation Specs
- 运行 npm run test，确保之前编写的结算基准快照测试 100% 全绿通过。
- 运行 npm run lint 无任何类型错误。

2. 局部验证与安全回滚

要求 Codex 在每次小范围修改后运行验证命令。若测试失败，先查看差异；确认文件中没有需要保留的人工改动后，再恢复该文件：

git diff -- src/pages/api/checkout.ts
git restore -- src/pages/api/checkout.ts

---

🛡️ 翻车自救与避坑速查表

常见踩坑现象	致命原因	排查与处理
一句话让 AI “重构整个项目”，导致系统彻底瘫痪	步子迈太大，AI 在大规模文件修改中出现幻觉与类型断裂	严格约束重构粒度，每次 Prompt 仅允许改动 1 个特定服务或函数
重构后旧功能莫名其妙丢失或报错	缺少重构前的行为基准快照测试	坚持“测试先行”，在修改前必须先让 AI 针对旧代码写出 100% 通过的基准单测
AI 在重构中擅自把底层框架给升级了	约束中未锁死 package.json	在 AGENTS.md 与 Constraints 中强调：“严禁变更 package.json 内的任何依赖版本”

---

🏠 主目录 | ⬅️ 上一章 (Ch.08) | ➡️ 下一章 (Ch.10) | 🌐 English