0260bcd8e2
- 新版设计各域 SoT 按本轮实现同步：总体架构、模块设计、接口契约、数据模型、功能规格、文件设计与决策记录。 - 接口契约生成物重新导出（openapi 与前端客户端随契约一致）。 - 实现回顾与专项检查台账保留历史结论；本轮收尾发现另见 .agents.local 下的收尾报告与审查处置。
68 lines
4.0 KiB
Markdown
68 lines
4.0 KiB
Markdown
<!-- 导航元信息: {"内容描述": "S04 元数据", "使用场景": "设计、实现或评审对应主题", "使用要求": "与阅读指南的主题权威分工一致"} -->
|
||
# S04 元数据
|
||
|
||
## 职责与对象
|
||
|
||
类型和结构定义、版本、扩展与投影，不拥有业务实例值。
|
||
|
||
实例归属以[总体架构](../总体架构.md)为准；结构、状态和公开外壳分别引用数据模型与接口契约。
|
||
|
||
## 公开接口
|
||
|
||
| 用例 | 输入责任 | 输出与后果 |
|
||
|------|----------|------------|
|
||
| register_type | 类型身份、粒度和已登记生命周期族 | 类型候选 |
|
||
| publish_schema | 字段结构及兼容检查 | 不可变结构版本 |
|
||
| compose_schema | 基础和作品扩展的明确版本 | 有效结构与哈希 |
|
||
| validate_value | 有效结构、用途和候选值 | 结构问题与引用校验需求 |
|
||
| project_fields | 结构、用途和受控授权摘要 | 允许字段与剔除原因 |
|
||
| activate_binding | 被审结构、预期绑定和影响处理 | 结构绑定回执 |
|
||
|
||
所有接口在本模块的接口.py 暴露。输入输出类型由同一公开表面导出，外部不导入私有模型或 SQL。
|
||
|
||
## 内部职责
|
||
|
||
| 文件 | 职责 |
|
||
|------|------|
|
||
| 接口.py | 元数据公开用例和可导入合同 |
|
||
| 模型.py | 元数据稳定对象、外壳及内部状态 |
|
||
| 存储.py | 元数据所属记录的 SQL 与版本读写 |
|
||
| 类型登记.py | 类型、粒度、业务归属和生命周期族 |
|
||
| 结构版本.py | 不可变结构发布、启用及固定读取 |
|
||
| 扩展合成.py | 基础结构和只增不改的作品扩展 |
|
||
| 字段校验.py | 类型、必填、枚举、嵌套和引用结构 |
|
||
| 字段投影.py | 展示、编辑、检索、导出和 AI 用途 |
|
||
| 变更影响.py | 兼容分类、受影响实例及升级要求 |
|
||
| 内置导入.py | 内置种子幂等登记，保护已存在绑定和扩展 |
|
||
|
||
完整路径及运行模板见[目标文件清单](../项目目录与文件职责.md)。逐文件意图、边界与目标见[文件合同](../文件设计/后端-S04-元数据.md)。
|
||
|
||
## 实现约束
|
||
|
||
- 保留基础字段、开放内容字段和同生命周期新类型；系统身份与原生绑定由代码登记。
|
||
- 基础版本与作品扩展合成可重复，不能随 active 指针变化重新解释历史数据。
|
||
- 结构校验与真实引用校验分工，后者由实例所属模块执行。
|
||
- 内置种子是发布输入；PG 保存生效版本，启动不覆盖作者扩展。
|
||
- 字段消费与结构/策略变更经同一类型级事务锁排序：消费持共享咨询锁，变更持排他咨询锁并保护实际更新行。评测账号只拥有元数据读取权限，不能为消费锁授予表写权限；多个类型按统一顺序保护，锁不跨模型网络调用。
|
||
|
||
## 协作与失败
|
||
|
||
业务模块和 B09 消费；前端通过 owner 投影得到结构和值；结构变更使用 S01 保护。
|
||
|
||
不兼容变更返回转换要求；结构、投影和实例版本不同步时拒绝；未知处理器和越权字段拒绝。
|
||
|
||
## 验收行为
|
||
|
||
- M01 新字段贯通。
|
||
- M02 新类型贯通。
|
||
- M03 扩展不能绕过保护。
|
||
- M04—M08 版本、用途、迁移与并发。
|
||
|
||
验收入口和替换条件见[迁移与验收](../迁移与验收.md)；这些条目是目标行为，不是已通过测试的声明。
|
||
|
||
## 当前公开范围
|
||
|
||
当前接入只开放登记候选、发布结构版本、兼容检查，以及业务owner对既有绑定的读写。发布v2不会自动升级固定绑定v1的实例。已有对象在线升级、作品扩展发布及在线策略更新单独立项，本期不提供公共启用工作流；既有低层API保留内部兼容。当前projection_version和类型锁协议保持不变；未来升级需独立转换、审阅、当前绑定CAS和恢复验收。
|
||
|
||
已发布种子的字段说明也参与结构内容哈希。`power_system`、`narrative_state` v1中的历史尾注是冻结说明，不是当前开发待办；本期保留原YAML字节。说明修订须发布新结构版本，既有实例是否升级另按在线升级项目处理，不以清理注释名义重写同版本身份。
|