聚合事实文档模板（实现快照）

落地路径：docs/design/aggregates/{agg}/facts.md。 唯一长期维护的一份，来源是代码，不是设计文档；每次实施完成后覆盖更新。

1. 这份文档是什么

1.1 定位

四份文档里唯一的「快照」。三份契约（语义 / 写设计 / 投影读设计）回答「这次答应了什么」，本份回答「现在实际是什么」。

文档	性质	份数	结束方式
本次需求语义	契约	每需求一份	验收后归档
聚合写设计	契约	每需求一份	实施后归档
投影读设计	契约	每需求一份	实施后归档
聚合事实（本份）	快照	1 份	永不归档

1.2 更新机制

项	约定
触发	每次实施完成
输入	代码（主）+ 写设计 §10.6 回填（偏离）
方式	覆盖更新，不追加历史版本；历史看变更记录
读者	下一次需求从这里读当前态，而不是从旧设计文档读
维护人	实施者；未更新则下次迭代不得开始

1.3 与语义文档的分工

内容	语义文档	事实文档
属性有哪些	应该有	实际有哪些
规则是什么	应该怎么约束	实际挂了几条、什么条件下生效
消息码	业务表述	实际常量值
状态	业务状态机	实际枚举 code
不一致	—	在本份 §4 显性记录

不写什么：不写设计理由、不写未来计划（缺口只记现状）、不写「应该」。

2. 依据

项	内容
最后核对日期	YYYY-MM-DD
核对人
代码基线	分支 / 提交
最近一次实施来源	changes/archive/{需求}/{agg}/aggregate-design.md（归档契约）

3. 实际结构

3.1 聚合根字段

字段	类型	实际列	备注（JSON 列 / 生成列 / 未持久化）

3.2 子实体

实体	表	主键	差量策略

无子实体时写一行「无」。

3.3 枚举实际 code

枚举	code	名称	备注（预留 / 未使用）

3.4 表与索引

表	主键	索引	特殊列（version / 软删 / 审计）

表结构可能有两个来源：DDL 脚本与 Mapper XML。两者不一致时以实际库为准（SHOW CREATE TABLE），并在本表标注差异与待确认。

3.5 操作码

常量	code	描述	是否参与规则校验

3.6 消息码

常量	code	描述	挂载规则

3.7 领域事件

事件类	事实	载荷字段	构造方式	订阅方

3.8 规则实际挂载

#	语义编号	消息码	组	激活条件	判定基准	读取字段

组：A 全局 / B 准入 / C 状态前置。判定基准写「变更前 old」或「变更后」。

4. 未消除问题

只记还没修的问题，修掉就删行。完整比对（本次需求 vs 当前事实）写在对应需求的语义文档里，不在这里展开。

#	问题	影响	来源	计划

只记现状，不写方案细节；不收录属于「语义没写清」的事项（那类留给语义文档）。

规则：同一问题停留超过两个迭代，必须在评审上定去留（修 / 接受 / 写进语义）。

5. 变更记录

日期	来源设计文档	变更点	核对人

5.1 怎么生成

本份完全从代码推导，不依赖语义文档：

步	读什么	产出	是否需要判断
1	聚合根与子实体	§3.1 / §3.2	否
2	枚举类	§3.3	否
3	DDL 与 Mapper 对照	§3.4	是（两者不一致时以实际库为准）
4	操作注册表 / 规则注册表	§3.5 / §3.6	是（注册表之外的方法要对照才能发现）
5	事件类与订阅登记	§3.7	否
6	规则容器 addRule 的 lambda	§3.8	是（读 old 还是当前态只能读 lambda 体）
7	代码 vs 当前已知问题	§4 摘要	是（哪些算问题、是否已修）

第 3、4、6 步都含判断：第 6 步直接决定能不能发现「规则读错基准」这类问题，不能只看 addRule 签名就填表。