3.1 KiB
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
- 为现有 manifest 补齐并验证规范 Runtime path。
- 将 API projection 抽为共享 contract mapper,收敛别名处理。
- 将 Admin 和 Mini Program props 改为消费规范路径。
- 为每类字段增加发布后集成测试,完成后再评估删除旧 JSON 别名。