④ 判决名单(accepted.md)
三份契约之外的唯一长期产物。它不记录代码状态,只记录人的判决。 当前实际形态一律以代码为准:每轮按
design-doc-template§5.0 的勘察清单现读,不缓存、不落文档。
1. 定位
四份产物中唯一不随代码腐化的一份:
| 文档 | 性质 | 回答什么 | 结束方式 |
|---|---|---|---|
| ① 本次需求语义 | 契约 | 这次它应该是什么 | 验收后归档 |
| ② 聚合写设计 | 契约 | 这次怎么实现 | 实施后归档 |
| ③ 投影读设计 | 契约 | 这次怎么查 | 与 ② 同批归档 |
| ④ 判决名单(本份) | 名单 | 哪些事已经定了 | 只增不改、永不归档 |
- 「现在实际是什么」不在四份文档里,看代码。
- ④ 不承接任何代码状态(字段、表、索引、操作码、消息码、事件、规则挂载一律不写)。
2. 为什么只留「判决」
判据:记录「状态」的东西一定会过期,记录「决定」的东西不会。
| 内容 | 会腐化吗 | 归宿 |
|---|---|---|
| 字段 / 表 / 索引 / 操作码 / 消息码 / 事件 / 规则挂载 | 会(代码一变就错) | 删。每轮按勘察清单现读代码 |
| 未消除的代码缺陷 | 会(修掉就失效) | 删。进 issue / TODO,阻断级当场修 |
| 已接受的现状、已移交语义的事项 | 不会(人的决定) | 留在本份 |
一份会腐化的现状文档,用之前必须核验;核验手段就是读代码,读完它已无价值。所以不存。
3. 落盘与命名
docs/design/aggregates/{agg}/accepted.md——聚合级,一个聚合一份,跨需求累积。
与契约目录的关系:契约按需求归档(changes/archive/{需求}/),④ 在 aggregates/ 下不动。
4. 固定 3 节
| # | 章节 | 记什么 | 每行必带 |
|---|---|---|---|
| 1 | 已接受的现状 | 明知不理想但决定不改的(如 version 用 BIGINT) | 日期 / 事项 / 判决 |
| 2 | 已移交语义文档 | 属于「语义没写清」而非代码缺陷的缺口 | 日期 / 事项 / 移交去向 |
| 3 | 待修登记(过渡区) | 已知代码缺陷,尚未修 | 日期 / 问题 / 级别 / 去向 |
第 3 节是过渡区:代码缺陷本应进 issue tracker 或 TODO 注释;暂存于此只为不丢信息,引入 issue 机制后整节迁出。
5. 写法约束
- 只增不改:判决失效不删行,追加一行「作废(YYYY-MM-DD,原因)」。
- 不写状态:不写字段清单、不写表结构、不写「当前实现了什么」。
- 不写设计:技术形态归 ②③;本份只写「决定了什么」。
- 单文件 20 行内:超出说明判决记录过度,应回到语义或设计文档。
- 每轮归档前检查:有新判决则追加;没有则不写「无新增」(本份不是日志)。
6. 空骨架
markdown
# {agg} · 已定判决
> 只记「人的决定」,不记代码状态。代码状态每轮现读,不做缓存。
## 1. 已接受的现状
| 日期 | 事项 | 判决 |
| --- | --- | --- |
## 2. 已移交语义文档
| 日期 | 事项 | 移交去向 |
| --- | --- | --- |
## 3. 待修登记(过渡区)
| 日期 | 问题 | 级别 | 去向(issue / 修复轮) |
| --- | --- | --- | --- |7. 被读于
ddd-design-doc(第 0 步读判决、第 9 步追加判决)、ddd-aggregate-extend(避免重复讨论旧账)、ddd-aggregate-create(迭代场景)。