Files
persionalBrand/docs/adr/0017-runtime-content-contract.md
T

3.1 KiB

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.<key> workspace.templateData.<key>
页面表达 brand.config.visualPresentation.<page>.<key> workspace.brand.visualPresentation.<page>.<key>
业务详情 offering.config.<key> workspace.offerings[].presentation.<key>
业务详情正文 offering.config.details.<key> workspace.offerings[].presentation.details.<key>
信任内容标准列 trust.title/summary/content workspace.trustItems[].title/summary/content
信任内容扩展 trust.config.<key> workspace.trustItems[].config.<key>
咨询字段 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 别名。