# 实现治理

## 1. 目标状态与实现状态分离

目标文档说明产品、领域、架构和契约应当是什么；实现状态说明当前代码和运营能力已经验证到哪里。设计完成、Schema 占位、静态原型、代码存在、测试通过和生产可用是不同证据等级，不得混写。

```mermaid
flowchart LR
    T[目标状态<br/>产品/领域/架构/契约] --> P[实现计划]
    P --> C[代码与配置]
    C --> V[验证证据]
    V --> M[能力矩阵实现状态]
    M -.差距与反馈.-> P
```

- 目标事实源：`docs/product/` → `docs/domain/` → `docs/architecture/` 与 `docs/contracts/`。
- 实现事实源：[能力矩阵](capability-matrix.md)及其链接的代码、自动测试、演练和[发布证据台账](release-evidence.md)。
- 目标文档不得因当前没实现而降格；实现文档不得把未来设计标成已实现。

## 2. 能力矩阵

每项能力按“用户可验证的纵向闭环”建行，而不是按目录、类或接口数量建行。矩阵至少包含：

| 字段 | 规则 |
| --- | --- |
| 能力与里程碑 | 对应 P0/P1/P2 或 1.0 发布门 |
| 目标契约 | 链接产品、领域、架构、协议和 Schema |
| 服务归属 | 灵台、神识、乾坤、琉璃镜；跨服务须列生产者/消费者 |
| 实现状态 | 使用受控状态集；具体值集须在契约评审后确定 |
| 适用档位/区域 | 轻量、标准、官方云及地区能力差异 |
| 验证证据 | 自动测试、端到端场景、演练、监控或人工验收链接 |
| 安全与数据 | 权限、驻留、删除、审计、恢复和禁域证据 |
| 已知限制 | 降级、规模、单机/多实例限制和未覆盖风险 |
| 责任与复核 | 责任角色、最近验证时间；不在文档虚构具体个人 |

## 3. 状态判定规则

- 没有运行证据的能力不能标为完成。
- 只有数据结构/API/局部页面时必须标注局部实现，不能等同用户闭环。
- Mock、静态设计稿和演示数据不能证明生产能力。
- 单元测试证明局部逻辑；跨服务能力还需契约测试与端到端证据。
- 涉及身份、迁移、删除、安全动作和灾备的能力必须有失败路径与演练证据。
- 仅在一个部署档位或区域验证的能力不得泛化为全球可用。
- 证据过期、依赖改变或 SLO 退化时，状态必须下调或标记待复核。

## 4. 契约先行

现有代码归位和新功能开发都遵循：确认产品/领域语义 → 登记稳定契约 → 明确服务边界 → 实现 → 契约/安全/恢复测试 → 更新能力矩阵。未确定的枚举、ID 前缀、事件和错误码不得由实现临时创造后直接固化。

## 5. 变更评审

每项显著变更应回答：是否改变人物连续性、命台唯一性、镜域驻留、四服务边界、用户授权、数据删除、审计链、SLO/RPO/RTO或自托管兼容性。触及这些不变量时必须同步目标契约、迁移/回退方案和发布门证据。

## 6. 文档维护

能力落地后更新矩阵而非篡改目标文档；目标决策改变时先更新上游事实源，再同步契约与实现计划。旧实现状态迁移期间可作为历史证据读取，但不能与新矩阵并列成为两个事实源。