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

44 lines
3.1 KiB
Markdown

# 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 别名。