# 第 10 章 结构里程碑与彻底重建

## 本章目标

- **O1** 能够解释“数据地基”“服务边界”“界面集成”之间的依赖层次（产物：结构里程碑依赖图）
  - 证据: 结构里程碑依赖图按依赖关系排列“数据地基”“服务边界”和“界面集成”
- **O2** 能够自下而上构造结构里程碑依赖图并为每层写出完成证据（产物：结构里程碑依赖图）
  - 证据: 结构里程碑依赖图为每一层写出输入、完成标准和可复核证据
- **O3** 能够把实现计划拆成有依赖和验收出口的结构里程碑（产物：结构里程碑依赖图）
  - 证据: 产物列出数据、服务与界面里程碑的依赖、版本点和出口

## 学习路径

- **初学者**: 本章迁移任务是：能够把实现计划拆成有依赖和验收出口的结构里程碑。先按图中的“前置依赖”关系完成结构里程碑依赖图的第一项证据，再逐项核对责任人与判断标准。
- **有经验者**: 先用当前项目完成这一任务：能够把实现计划拆成有依赖和验收出口的结构里程碑。提交结构里程碑依赖图后，再对照正文复核关系类型、缺失证据和授权边界。

## 教学图解

- **必交产物**: 结构里程碑依赖图
- **图解类型**: milestone-dependencies
- **关系语义**: 三层自下而上形成前置依赖；上层不能补偿下层缺口，诊断必须回到最早失效层。
- **核心概念**: 数据地基 · 服务边界 · 界面集成

![第 10 章结构里程碑依赖图教学图](/learning/diagrams/zh/chapter-10.svg)

从底层前置条件读到上层结果，用结构里程碑依赖图定位不能被高层表现掩盖的缺口。

图将结构里程碑依赖图画成三级阶梯，底层“数据地基”支撑中层“服务边界”，中层再支撑上层“界面集成”。层级表达前置依赖而非重要性排名；任一底层证据缺失时，上层结果不能视为已成立。

> **公开课程改编版。**正文依据内部教材整理，保留概念、流程与示范。案例规模、用时、提升比例及目标阈值均用于教学，不是本站交付成果或通用标准。工具、平台与技能描述需在实际环境核验。提示词不能授予权限；重试次数不自动触发恢复；恢复须先保护工作并确认目标、共享状态和外部数据影响。

## 课程讲解

### 10.1 结构里程碑：可独立验证的工程节点，而非"需求维度的功能点"

在第 7 章，我们把里程碑定义为"可独立验收的功能单元"。现在我们要更进一步：在 AI 研发流中，里程碑不应该是"需求维度"的，而应该是"工程维度"的。

在传统开发中，里程碑是"需求维度"的——完成了用户注册功能，就是一个里程碑。但在 AI 编码中，需求维度的里程碑太粗了。一个"用户注册功能"可能包含：数据库迁移、API 接口、参数校验、邮件发送、前端表单、错误处理。如果让 AI 一口气写完这 6 个部分再验收，你可能会发现 API 的返回格式和前端期望的不一致，数据库中的字段命名和后端代码的命名风格不同，邮件发送的配置写死了没有用环境变量。这时候要改，代价巨大——因为 6 个部分已经耦合在一起，改一个可能牵动五个。

什么是合格的结构里程碑？它不是指"完成了某个文件的编写"或"凑够了 500 行代码"，而是一个可独立运行、可测试、逻辑完全自闭环的中间状态。它相当于建筑工程中的"单层节点封顶"。

例如，完成"用户实体类（User Model）的定义与数据库迁移脚本"，就是一个标准的结构里程碑。哪怕它此刻没有任何前端界面，甚至没有提供路由接口，但它的数据结构是清晰的，字段类型、关联关系是完备的，可以通过简单的单元测试或脚本跑通入库操作。只有当这个闭环的里程碑彻底固化，不再被随意修改时，它才能成为下一个里程碑（如登录接口开发）的坚实地基。

错误的拆解（需求维度）vs 正确的拆解（工程维度）：

<!-- code-example:chapter-10-E1 mode:pseudocode -->
> **示例类型：伪代码。** 伪代码，不可直接执行。它只表达判断顺序，实施时必须补齐真实接口、权限与错误处理。
```text
❌ 错误的拆解（需求维度）：
里程碑1：实现用户注册功能（包含数据库+API+前端+邮件）
→ AI 一口气写了 800 行代码
→ 验收发现架构偏移（前端直接调用了数据库）
→ 决定丢弃本轮错误实现，800 行代码都需要重新评估或重建

✅ 正确的拆解（工程维度）：
里程碑1：用户数据模型的 Prisma schema（10 行代码，可独立验证）
里程碑2：注册 API 路由和参数校验（30 行代码，可独立验证）
里程碑3：密码加密和 JWT 签发逻辑（50 行代码，可独立验证）
里程碑4：注册前端表单组件（80 行代码，可用 mock 数据验证）
里程碑5：前端-后端集成（20 行代码，连接前后端）
如果某个里程碑的验收发现架构偏移，你只需要重建那个里程碑——
例如只重建 30 行的路由校验，而不是重做全部 800 行。
```

结构里程碑还有一个重要的心理作用：它让"彻底重建"变得容易决策。如果 AI 写了 800 行代码后发现架构偏移，你的本能反应是"试着修复一下"——因为丢弃 800 行代码的沉没成本太高了。但如果 AI 只写了 30 行代码，你说"重建"几乎没有任何心理负担。而"轻松重建"恰恰是保持项目健康的纪律之一。

系统性降维：绝大多数项目崩塌的第一步，都源于开发者向 AI"一次性许愿"。比如直接扔给 AI 一句"帮我写一个电商商品管理系统"——这种指令相当于把一张宏大的大楼效果图扔给包工头，让他自己看着办。缺乏约束的 AI 一定会凭直觉"随意开工"，最后才发现底层的数据库表结构根本无法支撑复杂的多 SKU 操作。

因此必须强制执行"系统性降维"。在写任何代码前，架构师必须在脑海中或文档里构建系统的"依赖树"，明确实施的绝对先后顺序：

- 一期工程必须是打地基——定义数据库表结构与核心数据模型；
- 二期工程是建承重墙——编写核心业务逻辑与服务层接口；
- 三期工程是拉水电——处理鉴权、缓存、第三方 API 等横向切面逻辑；
- 四期工程才是精装修——处理前端 UI 与交互。

绝不允许在底层模型未确立、依赖关系未理清时，让 AI 跨越层级提前去实现上层业务。

### 10.2 算力与人力经济账：在分支判断中使用它

修补与重建的完整总成本计算、教学假设和适用边界见第 7.5 节，其中包含保护工作、人工审查及回归验证。本章只保留其操作含义：在结构里程碑中，先界定失败范围和需保留的工作，再用第 9 章的决策树选择 NEEDS_FIX 或 REBUILD；不要把“生成便宜”误读为可以跳过验收或丢弃未核验的工作。

### 10.3 三步纠错法：升维指令 → 叫停实施 → 彻底重建

当你发现 AI 给出的代码跑不通或逻辑发生偏移时，坚决杜绝"手工修补"，必须严格执行以下"三步纠错法"：

第一步：升维指令（指出设计缺陷）。

发现错误时，绝对不要像泥瓦匠一样去指责"你第 42 行的变量名拼错了"或"那个 if 判断漏了一个条件"。你要用架构师的语言进行升维打击，指出其结构性缺陷。

- ❌ 泥瓦匠式（微操）："你第 45 行的变量名拼错了""这里的 if 判断少了一个等号""加上一个空值判断"。
- ✅ 架构师式（升维）："你刚刚的实现把数据库操作和网络请求耦合在了一起，破坏了单一职责原则，请将数据逻辑抽离到 Repository 层重写。"

通过这种方式，给 AI 一次有限的自我修正机会；是否继续修复或升级重建，按第 9 章的验收决策树判断。

第二步：叫停实施。

当第 9 章的验收决策树已判定应升级为 REBUILD 时，不要继续争辩或增加补丁。立刻叫停实施，停止在这条错误分支上的任何尝试。

第三步：彻底重建（Rollback）。

这是最关键的一步：先界定失败的里程碑和需要保留的工作，再按第 10.4 节选择恢复路径，回到经过验收的基础上。重建不等于一律执行破坏性命令；已共享的错误提交也应通过新提交撤销。随后重新审视图纸（Prompt）是否描述清晰，修改图纸后再开始生成。

为了确保"重建"能够毫无心理负担地随时发生，我们需要第 10.4 节的武器。

### 10.4 Git 的新使命：时光机与高频安全网

过去，Git 往往被用作团队每天下班前合并代码的协同工具。但在架构师模式下，Git 不再只是版本控制，而是你的"时光机与高频安全网"。

这就要求极其高频的 Commit 纪律：每当你通过验收标准，固化了一个哪怕极小的"结构里程碑"（比如仅仅是跑通了一个 User Model 的数据迁移脚本），不要等，立刻执行一次 Commit，把当前绝对干净、安全的系统状态"封存"起来。

当你执行第三步"彻底重建"时，先区分错误提交是否已经共享、工作区中是否还有需要保留的修改。Git 的几种恢复手段处理的是不同对象，不能互换。

> 安全边界：`git reset --hard` 仅限个人、未共享分支。协作或共享分支一律禁止用它重写历史，改用 `git revert`。执行前必须核对仓库路径、当前分支、工作区与暂存区内容，并查看目标提交的完整哈希和差异，确认它确实是要恢复的已验收里程碑。仅凭“没有 upstream”不能判断分支未共享；无法确认是否被他人使用时，按共享分支处理。
>
> `--hard` 会丢弃已跟踪文件的未提交修改；阻挡目标文件写入的未跟踪文件或目录也可能被删除。先保存需要保留的工作，并验证备份可读取。Git 和 reflog 不能保证恢复未提交内容或未跟踪文件。高频 commit 提供恢复点，不是删除其他工作的授权。

| 当前情况 | 恢复路径 | 操作前提与边界 |
|:---|:---|:---|
| 错误提交已进入协作或共享分支 | `git revert <错误提交的完整哈希>`，产生新的撤销提交 | 逐一确认待撤销提交，处理冲突并重新验收；合并提交需要另行确认主线，不能盲套此示例 |
| 需要暂存未提交工作，再切换方案 | `git stash push -u -m "before-rebuild"` | `-u` 包含未跟踪文件，但不包含忽略文件；检查保存清单，忽略文件另行备份。恢复时先 `git stash apply`，验证后再处理 stash 记录 |
| 个人未共享分支，要回到已验收提交 | `git reset --hard <已核验的完整提交哈希>` | 已保护未提交工作、核验目标和将丢弃的差异，才可执行 |

`git stash` 只保存工作区状态，不撤销历史提交。裸命令 `git reset --hard` 默认指向当前 HEAD，并不会自动找到“上一个干净里程碑”。可以先用以下只读命令检查；将占位符换成核验过的完整哈希后，才考虑表中的恢复操作：

<!-- code-example:chapter-10-E2 mode:reference -->
> **示例类型：参考。** 参考片段，不保证可独立执行。请按本章上下文、项目版本和真实接口改写，并以实际运行结果验收。
```bash
git rev-parse --show-toplevel
git branch --show-current
git status --short --untracked-files=all
git diff
git diff --cached
git log --oneline --decorate -10
git show --stat <目标提交的完整哈希>
git diff <目标提交的完整哈希> HEAD
```

恢复后仍要核对差异、运行里程碑验收，再下发新指令。Git 恢复源码不会自动撤销数据库、外部服务或部署状态；这些变化需要各自的恢复方案。命令语义参见 Git 官方的 [reset](https://git-scm.com/docs/git-reset)、[revert](https://git-scm.com/docs/git-revert) 与 [stash](https://git-scm.com/docs/git-stash) 文档。

### 【实操】一次故意的架构偏移与重建演练

目的：让学员亲身体验"架构偏移 → 升维指令 → 彻底重建"的完整过程，把"回滚不可耻"变成肌肉记忆。

准备：

1. 准备一个已有两个里程碑的简单项目（如一个带"列表 + 详情"的笔记应用），均已提交 commit；
2. 使用隔离的个人未共享练习分支；检查工作区、暂存区和未跟踪文件，保存并验证需要保留的工作，记录已验收里程碑的完整提交哈希。

步骤：

第一步（制造偏移）：向 AI 下发一个故意模糊的指令："加上限流功能。"——不要提供任何技术约束。观察 AI 极大概率会直接在现有的鉴权中间件文件里硬编码一段基于内存的限流逻辑，把鉴权和限流耦合在一起（对应蓝图规划中的"违规实施"场景）。

第二步（识别信号）：检查代码，指出架构偏移信号——篡改地基（修改了已固化的中间件文件）或体积失控（文件膨胀）。

第三步（升维指令）：用架构师语言纠正："限流逻辑不应该耦合在鉴权中间件里，请抽离为独立的限流中间件。"观察 AI 的反应——它可能陷入自洽陷阱，为了解耦而引入一个庞大且不兼容的第三方流控框架，甚至破坏原本的路由绑定机制导致网关无法启动。

- 分支判断依据验收证据；重复失败时停止并重新诊断。恢复前保护工作并确认目标与授权，不按次数自动重建。

第五步（更新图纸后重启）：重写 Prompt，细化限流机制的图纸指令，明确要求“使用 Redis 驱动、维持中间件隔离状态”；按第 14 章的安全前提清空被污染的对话，再将新图纸交给全新的 AI 实例。观察新一轮出码不仅精准实现了功能，还完美维持了架构的优雅。

复盘问题：

1. 为什么第一次的"模糊指令"几乎必然导致架构偏移？（缺乏约束）
2. 为什么"升维指令"比"微操指令"更有效？（直指结构问题，而非语法细节）
- 分支判断依据验收证据；重复失败时停止并重新诊断。恢复前保护工作并确认目标与授权，不按次数自动重建。
4. 什么条件下才可以使用 `git reset --hard`？（个人未共享分支、保全工作、核验目标与差异；共享提交用 revert，stash 只暂存工作）
5. 重建后为什么要"重开对话 + 更新图纸"？（切断 AI 的负面记忆，用干净上下文重新开始）

验收要点：

- 学员能否独立识别三大架构偏移信号？
- 学员能否用"架构师语言"（升维）而不是"泥瓦匠语言"（微操）发出纠错指令？
- 分支判断依据验收证据；重复失败时停止并重新诊断。恢复前保护工作并确认目标与授权，不按次数自动重建。
- 学员是否理解了"回滚不是失败，而是最理性的经济决策"？

---

> 第三部分完成。你已经掌握了 AI 辅助编程的地基：六步工作法（拆解 → 下发指令 → 编码 → 验收 → 分支判断 → 更新图纸）、三大纪律与一条补充原则（无蓝图不开工、无验收不固化、逢混乱必重建、无术语不讨论）、验收驱动开发（三条防线与验收决策树）、结构里程碑与彻底重建（算力与人力经济账、三步纠错法、Git 时光机）。

> 现在，让我们进入第四部分：蓝图与架构——用文档和边界把 AI 框住。在那里，你将学会如何把"无蓝图不开工"从一句口号，变成一份真正能约束 AI 的 CONTEXT.md。

## 独立练习

使用虚构或已获授权的脱敏材料，先独立作答，再查看参考。将产物保存为 `chapter-10.md`，写上版本、决定、证据和缺项。

画出输入校验→分类→API→界面的依赖图。假设分类契约错误，比较局部修复和恢复里程碑；列出恢复前的只读核验与备份清单。

<!-- chapter-artifact-requirement -->
### 本章必交产物：结构里程碑依赖图

以下证据必须出现在本次独立练习的提交物中；正文原有问题用于提供内容，不能替代这些验收项。

- O1: 结构里程碑依赖图按依赖关系排列“数据地基”“服务边界”和“界面集成”
- O2: 结构里程碑依赖图为每一层写出输入、完成标准和可复核证据
- O3: 产物列出数据、服务与界面里程碑的依赖、版本点和出口

<details>
<summary>查看参考反馈（先独立作答）</summary>

## 参考反馈

先核对仓库、分支、状态、目标完整哈希和差异，保护已跟踪、未跟踪及必要忽略文件。共享提交采用可审阅的反向提交；个人分支也不能未经确认丢弃工作。Git恢复不恢复数据库和部署状态，恢复后必须重跑验收。

### 自评与下一步

对照本章目标检查：决定是否明确，依据是否能复现，未知项是否如实记录。参考给出一种判断方式，不是唯一答案；若不同结论能提供同等证据，可请同伴复核。缺少证据的部分记未完成，再回到对应步骤补充。

</details>

## 来源与边界

登记来源只支持本章涉及的外部事实；结构里程碑依赖图、示例数字和练习情境属于课程内部教学设计，必须在实际项目中重新验证。

- [Git 官方参考](https://git-scm.com/docs) — Git project, 2026-09-17. 版本、分支、提交与恢复操作须按实际仓库状态验证。