0260bcd8e2
- 新版设计各域 SoT 按本轮实现同步：总体架构、模块设计、接口契约、数据模型、功能规格、文件设计与决策记录。 - 接口契约生成物重新导出（openapi 与前端客户端随契约一致）。 - 实现回顾与专项检查台账保留历史结论；本轮收尾发现另见 .agents.local 下的收尾报告与审查处置。
94 lines
8.4 KiB
Markdown
94 lines
8.4 KiB
Markdown
<!-- 导航元信息: {"内容描述": "元数据与结构演进", "使用场景": "设计、实现或评审对应主题", "使用要求": "与阅读指南的主题权威分工一致"} -->
|
||
# 元数据与结构演进
|
||
|
||
元数据是新版的共用能力。类型和内容字段是开放集；身份、归属、状态、授权、正式写入和已登记业务行为受代码合同保护。该选择的背景与取舍见[决策 0004](../决策/0004-保留元数据驱动的内容结构.md)。
|
||
|
||
## 五类职责
|
||
|
||
| 类别 | 定义维护者 | 实际执行者 |
|
||
|------|------------|------------|
|
||
| 类型、字段、结构版本 | S04 元数据 | 业务模块校验实例；前端渲染表单 |
|
||
| 字段可见、可编辑、检索、导出和 AI 用途声明 | S04 元数据 | 所属业务模块、B09 和导出模块裁剪 |
|
||
| 质量维度、规则和判据 | B06、B10 | 检查、修订和评测步骤 |
|
||
| 角色、模型、提示资源和工具策略 | S02 | 执行器和宿主适配 |
|
||
| 流程版本、节点和开放槽位 | 编排 | S02 执行已登记处理器 |
|
||
|
||
元数据定义结构，不提供任意 SQL、任意脚本或跨模块通用业务写接口。
|
||
|
||
## 结构对象
|
||
|
||
| 对象 | 必需内容 |
|
||
|------|----------|
|
||
| 类型登记 | type_id、中文名称、语义域、实例粒度、允许的实例族（用途→所属模块/生命周期）、状态 |
|
||
| 结构版本 | schema_id、schema_version、内容哈希、字段定义、父版本、发布状态 |
|
||
| 字段定义 | 稳定 field_id/key、名称、说明、类型、必填、枚举、嵌套或引用约束、用途策略 |
|
||
| 存储绑定 | native_column、extension_json 或 computed；native_column/computed 只引用代码允许的绑定身份 |
|
||
| 作品扩展版本 | work_id、基础版本、增加的字段、扩展版本和哈希 |
|
||
| 结构绑定 | 目标作品或实例、基础版本、扩展版本、effective_schema_hash |
|
||
| 投影 | 目标、用途、有效结构哈希、策略版本、授权与来源有效性指纹、允许字段和剔除原因 |
|
||
| 结构变更 | 旧新版本、兼容性分类、影响对象、转换要求及启用回执 |
|
||
|
||
同一类型可以支持多个已登记实例族，每个实例只属于一个业务维护者，由具名命令和任务用途确定，不能由模型自报 owner。结构引用只能指向已登记的固定版本，不隐式联网加载外部定义。
|
||
|
||
`实例粒度`可以是一个粒度或有限粒度列表，所属业务逐项校验真实目标。内置outline声明work与volume，fine_outline仍是chapter；scene的block在B01场景计划生命周期中对应scene节点，在B05仍按正文场景引用解释。节点归属由B01稳定外壳确定，多粒度声明不授予跨作品或跨生命周期写入权限。
|
||
|
||
稳定 field_id 与显示名分离。字段改名保留身份；别名只能由已审结构定义，禁止模型自行发明别名规避未知字段拒绝。引用字段声明目标类型、数量、作品范围及所需确认状态，值的所属模块解析和验证真实引用。
|
||
|
||
引用同时声明`关系用途`：默认“依据”参与版本依赖；“关联”用于同域目录导航，只核对真实身份、归属与确认状态，不递归成为生成依据。B01大纲的“近三章细纲”采用关联，细纲的sourceRef采用依据。解析模块按目标类型与实例族确定，不能按字符串或对象的JSON形状猜所属模块。历史固定版本可解释不等于当前用途可用；用作写作前置时，当前aiContext写作投影必须仍保留该规划结构要求的必需内容。
|
||
|
||
## 稳定骨架与动态内容
|
||
|
||
身份、作品归属、revision、来源引用、候选状态和审阅身份属于稳定骨架。书名等原生字段也可以具有元描述；物理列固定不等于没有动态表单。正文段落结构及任务执行外壳由专门协议定义，不允许作品扩展改写。
|
||
|
||
题材特有属性和沿用已有生命周期的新类型通过 Schema 配置。扩展的对象仍进入其所属模块的候选、审阅、确认和历史版本机制。新增存储生命周期、计算规则或外部副作用需要实现具名处理器，不能上传任意代码作为字段配置。
|
||
|
||
JSONB 只是动态值的载体。实例保存必须按指定有效结构运行时校验，不以 dict、任意 JSON 或前端校验代替合同。
|
||
|
||
## 定义来源与发布
|
||
|
||
代码仓保存内置结构的种子、版本转换和校验能力。PostgreSQL 保存已经发布的不可变结构版本、作品扩展及实际生效绑定。内置导入按种子身份与哈希幂等登记，不能覆盖作者扩展，也不能在启动时把工作树新文件直接激活。
|
||
|
||
基础接口提供类型/结构候选登记、按哈希发布、固定版本读取和兼容预览；作品扩展的作者动作与实例启用复用这些接口，须核对 S01 审阅凭据与 B01 作品归属。内部纯校验和事务参与机制通过不等于作者启用链已验证。
|
||
|
||
读取新建默认值可以选择当前基础版本；任务开始、实例写入和作者审阅必须固定确切版本。历史对象始终能按其原版本解释。结构重放的可读性与当前用途授权分别检查。
|
||
|
||
作品默认继承已绑定的基础版本，扩展只增不改，不删除或重定义基础字段。新增扩展字段可以允许或禁止本作品的具体用途，但不能放宽系统、来源和任务的上限。基础版本升级是显式变更；不能因为全局 active 指针变化，静默重新解释现有实例。
|
||
|
||
## 兼容性与升级
|
||
|
||
| 变更 | 处理 |
|
||
|------|------|
|
||
| 修改展示名或帮助说明 | 保留字段身份；更新投影版本，运行证据仍保留原定义 |
|
||
| 新增可选字段 | 发布新结构版本；明确升级范围，旧值保持原版本可读 |
|
||
| 新增必填字段 | 先识别受影响实例并补值或转换，不能凭空填造业务事实 |
|
||
| 更改类型、缩窄枚举、重解释引用 | 不兼容变更，产生转换方案与差异，经确认后切换 |
|
||
| 停用类型或字段 | 停止新的相应用途；保留旧值、历史读取及导出关系 |
|
||
| 收紧字段可见性或用途 | 当前读取立即执行收紧策略；旧快照不能恢复已撤回权限 |
|
||
|
||
结构版本、字段投影和数据 revision 分别校验。保存或采纳时，S01 对参与判断的结构绑定、策略和目标版本采用同一锁协议；不能在预检后留出结构切换竞争窗口。错误与恢复合同见[元数据投影与版本](../接口契约/元数据投影与版本.md)。
|
||
|
||
## 完整消费路径
|
||
|
||
作者登记或扩展类型 → 形成结构候选 → 校验兼容性与使用影响 → 作者启用指定版本 → 所属模块创建或编辑实例 → 同源结构渲染表单和模型输出合同 → 实例保存校验 → 上下文按用途裁剪 → 索引与导出保留字段身份 → 备份恢复保留结构与实例引用。
|
||
|
||
新增字段的验收必须贯通编辑、抽取、校验、读取、检索、导出及恢复。声明可检索只表示允许使用；索引建立、模型与切块版本由 B09 记录，不把尚未建立的索引显示为可用。
|
||
|
||
## 原结构资产承接
|
||
|
||
[内置类型承接表](内置类型承接表.md)逐项覆盖原设计的 23 个基础类型及当前独立 fine_outline 合同。这些资产的字段语义、用途限制、人物演变与来源都应承接；旧文件中的历史实例路径、租户列和样本门锚不成为新版约束。
|
||
|
||
旧 scene/Block 是叙事场景或小节粒度，不能机械等同新版段落。迁移保存旧 Block 到新场景、正文版本和段落的对应关系；章号转换为稳定章节身份时保留原展示序号。
|
||
|
||
## 元数据支撑验收
|
||
|
||
| 编号 | 可观察行为 |
|
||
|------|------------|
|
||
| M01 | 新增题材字段后，编辑、抽取、保存和读取使用同一结构，无作品分支代码 |
|
||
| M02 | 新增沿用已有生命周期的实体类型后可完整审阅、确认和引用，无固定 ENTITY_TYPES 拦截 |
|
||
| M03 | 扩展不能删除基础字段、改系统身份或提高模型工具权限 |
|
||
| M04 | 结构、投影或数据版本改变时，旧表单和旧候选不能继续提交 |
|
||
| M05 | 新增必填或更改字段类型必须处理历史实例，旧数据可以按旧版完整回读 |
|
||
| M06 | 隐藏字段在模型、检索和导出中分别遵守用途；允许展示不自动允许进入 AI |
|
||
| M07 | 备份恢复保留类型、结构、实例、来源及绑定关系，动态字段往返不丢失 |
|
||
| M08 | 启用、停用或结构切换与内容提交并发时，版本及权限判断仍在提交点成立 |
|