魂镜契约文档
1. 定位
本目录是跨服务、跨部署和跨版本稳定工程语言的事实源,承载稳定英文标识、ID、状态分类、Schema、事件、错误和协议。领域中文词义以 docs/domain/ 为准,产品承诺以 docs/product/ 为准,当前实现由 docs/operations/implementation-governance.md 规定的能力矩阵确认。
2. 当前文档
| 文档 | 内容 |
|---|---|
| 契约词汇与实现值集 | 稳定英文标识、ID 前缀、枚举、事件、错误码、状态分类和兼容性规则 |
| 身份可移植协议 | 魂籍、命台迁移、备份恢复与单命台交接 |
当前实现仍以 Pydantic Schema、OpenAPI 输出和前端类型承载部分机器契约;这些是待归位的实现事实,不与本目录并列成为第二套命名事实源。后续逐步在本目录补齐版本化 OpenAPI/JSON Schema、事件 Schema 和协议测试向量;未完成评审的目标态值不得在说明文档中先行虚构。
3. 事实源规则
flowchart LR
P[产品与领域语义] --> C[contracts 稳定契约]
C --> I[四服务实现]
I --> M[能力矩阵与验证证据]
M -.发现偏差.-> C
- 产品/领域决定“是什么、为什么”;契约决定“跨边界如何稳定表达”;实现不得反向把临时字段升级为正式领域定义。
- 一项契约先在本目录登记和评审,再进入代码、数据库、API、事件、配置与 UI。
- 下游引用契约,不复制完整枚举表。
- 破坏性变更必须新版本并给出兼容、迁移和回退安排。
- 文档示例是说明,不因出现示例值而自动成为完整枚举。
4. 变更要求
契约变更至少记录:语义、稳定英文标识、所属边界、兼容性、数据迁移、隐私/安全影响、生产者、消费者、测试与回退。身份、命台、授权、审计和区域驻留相关契约必须经过安全与恢复路径复核。