# 0017 统一内容 Runtime Contract ## Context 模板字段目前同时经过 manifest、Prisma JSON、API projection 和 Mini Program 组件。历史兼容字段使同一业务语义存在多个入口,例如 Offering 的通用 `description` 与模板详情 `config.details.background`。仅检查某一层会允许“可编辑但不展示”的字段继续进入系统。 ## Decision 每个公开字段必须有一个规范 binding 和一个规范 Runtime path。binding 是持久化编辑路径,Runtime path 是 `RuntimeWorkspace` / 组件 props 的稳定路径。模板 manifest 负责声明业务字段和编辑文案,平台 contract 负责校验 binding、Runtime path 和页面归属;projection 只输出规范 Runtime path。 规范路径: | 数据 | 规范编辑路径 | 规范 Runtime 路径 | | -------------- | ---------------------------------------------- | -------------------------------------------------- | | 品牌事实 | `brand.*` | `workspace.brand.*` | | 模板品牌字段 | `brand.config.templateData.` | `workspace.templateData.` | | 页面表达 | `brand.config.visualPresentation..` | `workspace.brand.visualPresentation..` | | 业务详情 | `offering.config.` | `workspace.offerings[].presentation.` | | 业务详情正文 | `offering.config.details.` | `workspace.offerings[].presentation.details.` | | 信任内容标准列 | `trust.title/summary/content` | `workspace.trustItems[].title/summary/content` | | 信任内容扩展 | `trust.config.` | `workspace.trustItems[].config.` | | 咨询字段 | `inquiry.fieldsSnapshot` | `workspace.inquiryForms[].fields` | 历史别名只允许在 projection 或导入迁移处读取,不得新增 Admin binding,也不得作为组件协议。组件 props 必须直接使用 Runtime path 对应的对象,页面不能自行重新解释数据库字段。 ## Alternatives - 继续使用字段命名约定:实现快,但无法阻止别名和页面错配。 - 为每个模板独立写 DTO:隔离性好,但会复制平台数据事实并增加升级成本。 - 允许任意 JSON 编辑:灵活但无法做页面可见性和发布校验。 ## Consequences - 新模板必须声明字段到 Runtime 的完整路径,并通过 package-discovered contract tests。 - 兼容字段不会立即删除,先停止新增使用,再按发布版本迁移。 - 需要增加发布后测试,验证 Admin 修改值最终出现在 public workspace 和页面输入数据中。 ## Migration Plan 1. 为现有 manifest 补齐并验证规范 Runtime path。 2. 将 API projection 抽为共享 contract mapper,收敛别名处理。 3. 将 Admin 和 Mini Program props 改为消费规范路径。 4. 为每类字段增加发布后集成测试,完成后再评估删除旧 JSON 别名。