Dao 里程碑交付工作流
文档名称：Dao Milestone Delivery Workflow 版本：v1.0 创建日期：2026-03-14 文档性质：Dao 工程里程碑执行规范 适用范围：当前仓库后续的阶段里程碑规划、任务拆解、详细设计、开发、自测、记录与提交
一、这份文档解决什么问题
这份文档用于统一后续里程碑的推进方式。
从这一版开始，当前仓库的开发不再采用“想到什么做什么”的推进方式，而采用一条固定闭环：
里程碑规划 -> 任务拆解 -> 业务流程梳理 -> 详细设计 -> 开发 -> 自测 -> 修复 -> 记录沉淀 -> 子任务提交 -> 下一子任务
直到完成当前里程碑，再补齐一篇里程碑开发笔记，最后由你统一完成 Dao Commit squash 提交。
二、总原则：按 Dao 的方式推进开发
后续开发统一遵循下面四条原则：
2.1 先认出，再行动
先看清当前里程碑真正要解决的问题，再开始设计和编码。
这意味着我们不能直接跳到实现，而要先回答：
- 这一轮真正的目标是什么
- 当前断点在哪里
- 业务流转卡在哪个环节
- 哪些是本轮必须解决的核心问题
- 哪些属于后续里程碑，不在本轮展开
2.2 先清边界，再谈复用
详细设计优先解决边界，而不是优先抽象。
每一轮都先明确：
- 业务边界
- 模块边界
- 输入输出边界
- 状态流转边界
- 页面、服务、数据、文档之间的协同边界
2.3 每个子任务都要形成可回溯闭环
一个子任务不以“代码写完”为完成标准，而以“可说明、可验证、可回看”为完成标准。
每个子任务完成时，都应同时留下：
- 目标
- 方案
- 关键决策
- 自测结果
- 变更记录
2.4 不把问题带进下一个阶段
自测未通过，不进入下一个子任务。
必须遵循：
开发 -> 自测 -> 修复 -> 再自测 -> 通过
只有当前子任务通过，才能继续下一个子任务。
三、里程碑推进的标准阶段
每一个里程碑统一拆成六个阶段。
阶段一：里程碑规划
目标：明确本轮为什么做、做到哪里算完成。
这一阶段需要产出：
- 里程碑背景
- 里程碑目标
- 里程碑范围
- 不在本轮范围内的内容
- 风险点
- 验收标准
这一阶段结束时，我们应能回答：
- 这一轮的核心命题是什么
- 为什么这件事值得作为一个独立里程碑
- 完成后系统状态会发生什么变化
阶段二：任务拆解
目标：把里程碑拆成可执行、可验证的子任务。
任务拆解必须满足：
- 子任务之间有清晰顺序
- 每个子任务都有单独完成标准
- 每个子任务都可以独立提交
- 每个子任务都能单独自测
推荐拆解顺序：
- 目标与现状梳理
- 业务流程梳理
- 详细设计
- 开发实现
- 接口或页面接入
- 自测与复盘
阶段三：业务流程梳理
目标：先跑通“业务上怎么运转”，再做实现。
这一阶段至少要明确：
- 角色是谁
- 输入是什么
- 关键动作有哪些
- 状态如何流转
- 输出是什么
- 异常路径如何处理
建议统一产出这几类内容：
- 主流程
- 分支流程
- 异常流程
- 状态流转表
- 模块协作关系
如果业务流程没有梳理清楚，不进入详细设计。
阶段四：详细设计
目标：在写代码之前先做结构设计。
详细设计至少覆盖：
- 模块划分
- 数据结构
- 状态流转
- 接口契约
- 页面交互
- 错误处理
- 可测试点
- 对现有代码的影响范围
详细设计要明确回答：
- 哪些文件新增
- 哪些文件修改
- 每一类改动为什么这样设计
- 是否影响既有能力
- 本轮怎么验证
阶段五：开发与自测
目标：按子任务逐个实现，并在每一步内完成闭环。
每个子任务的固定流程如下：
- 实现代码
- 更新相关文档
- 进行自测
- 自测失败则继续修复
- 重新自测直到通过
- 将过程记录到本轮开发记录文档
- 按 Dao Commit 方式提交当前子任务
这一阶段有一个硬规则：
没有自测通过，不进入下一个子任务。
阶段六：里程碑收口
目标：完成整轮沉淀，而不是只停留在功能完成。
里程碑完成后必须补齐：
- 一篇里程碑开发笔记
- 当前里程碑开发记录更新
- 当前里程碑结果与遗留问题说明
- 下一里程碑建议入口
最后再由你统一进行 Dao Commit squash 提交。
四、每个里程碑必须具备的文档资产
参考当前仓库已经形成的结构，后续每个里程碑统一保留以下文档：
4.1 任务拆解文档
用于定义：
- 为什么做这一轮
- 这一轮拆成哪些任务
- 每个任务的顺序和完成标准
建议命名：
XX-Mn任务拆解-<主题>.md
4.2 详细设计文档
用于定义：
- 业务流程
- 结构方案
- 模块边界
- 关键决策
- 自测方案
建议命名：
XX-Mn详细设计-<主题>.md
4.3 开发记录文档
用于复盘：
- 这轮做了什么
- 为什么这样做
- 遇到了什么问题
- 如何解决
- 如何验证
建议命名：
XX-开发记录-<主题>.md
4.4 里程碑开发笔记
用于站在里程碑层总结：
- 本轮的阶段目标
- 关键路径
- 过程中的重要判断
- 最终结果
- 对下一轮的启发
建议命名：
XX-技术博客-<主题>.md 或 XX-里程碑开发笔记-<主题>.md
五、子任务级执行规范
每一个子任务，都按相同模板推进。
5.1 子任务启动前
先明确四件事：
- 这个子任务解决什么问题
- 依赖前置任务是否已完成
- 影响范围有哪些
- 自测方式是什么
5.2 子任务开发中
开发过程中同步记录：
- 当前改动点
- 当前设计决策
- 当前风险
- 当前遗留问题
不等里程碑结束再回忆。
5.3 子任务完成时
必须同时满足：
- 代码完成
- 文档同步
- 自测通过
- 开发记录已更新
- 已形成 Dao Commit 子任务提交
六、自测规范
后续自测统一按“由近到远”的方式做。
6.1 第一层：静态检查
- 文档链接是否正确
- 路径引用是否正确
- 命名是否一致
- 配置是否可解析
6.2 第二层：局部验证
- 当前模块功能是否工作正常
- 关键状态流转是否符合设计
- 当前子任务是否引入回归问题
6.3 第三层：集成验证
- 与上下游模块协作是否正常
- 页面、接口、数据、文档是否一致
- 导航、入口、站点生成是否完整
6.4 第四层：失败回修
如果任意一层不通过，则立即回到实现阶段修复，直到重新通过。
标准闭环如下：
实现 -> 自测 -> 失败 -> 修复 -> 复测 -> 通过
七、开发记录应该记什么
从这一版起，开发记录不只记“做了什么”，还要记“为什么这么做”。
每轮开发记录至少包含：
7.1 背景
- 本轮为什么开始
- 它承接哪一个前置里程碑
7.2 目标
- 本轮要解决的核心问题
- 完成后的系统变化
7.3 关键决策
- 为什么选这个方案
- 为什么不选另一个方案
- 本轮边界是怎么确定的
7.4 过程
- 实际推进顺序
- 遇到的阻塞点
- 调整了哪些设计
7.5 自测
- 如何测
- 哪些点测过
- 测试失败过哪些地方
- 最终如何修复
7.6 结果
- 已完成内容
- 未完成内容
- 对下一轮的建议
八、Dao Commit 在子任务层的执行规则
后续提交统一遵循：
- 一个子任务，一个独立 Dao Commit
- commit 只提交当前子任务闭环，不混入其他改动
- commit message 先描述系统状态变化，再描述动作
- 需要沉淀经验时，正文补充“踩坑记录”与
#沉淀
执行方式统一如下：
8.1 子任务提交时机
当且仅当以下条件全部满足时提交：
- 当前子任务开发完成
- 当前子任务自测通过
- 当前文档已同步
- 当前开发记录已更新
8.2 子任务提交内容
至少包含：
- 代码改动
- 文档改动
- 开发记录更新
8.3 里程碑结束后的提交方式
里程碑内的每个子任务由我逐个完成 Dao Commit。
当前里程碑全部完成后：
- 我补齐里程碑开发笔记
- 我向你汇报里程碑完成情况
- 由你执行最终 Dao Commit squash 提交
九、推荐的执行顺序
后续每一个里程碑，默认按下面顺序推进：
- 先写里程碑任务拆解
- 再补业务流程和详细设计
- 然后按子任务逐个开发
- 每完成一个子任务，立即自测并修复
- 每完成一个子任务，立即更新开发记录并提交
- 子任务完成后进入下一个子任务
- 里程碑完成后补开发笔记
- 汇报结果，由你做最终 squash
十、从现在开始的协作约定
从现在开始，我会按下面方式和你协作：
- 先规划当前里程碑，不直接跳开发
- 先拆任务，不把大目标直接压进一个提交里
- 先梳理业务流程，再做详细设计
- 每个子任务都带自测闭环
- 每个子任务都同步更新里程碑文档
- 每个子任务都用 Dao Commit 独立提交
- 每个里程碑结束都补一篇开发笔记
- 最终由你统一做 Dao Commit squash
十一、当前建议
下一步最合理的动作不是直接开发，而是先确定：
- 当前要推进的是哪一个里程碑
- 本轮里程碑的主题是什么
- 本轮里程碑放在哪个模块目录下
确定后，我就会立即按这份工作流开始：
里程碑规划 -> 任务拆解 -> 业务流程 -> 详细设计 -> 子任务开发闭环