fix: 收敛模板编辑发布契约并还原餐饮页面视觉

This commit is contained in:
que01 committed 2026-10-08 13:36:59 +08:00
1 parent 20bcb43534
commit f4061a24bd
102 files changed
+4510 -870

No files matched your search

+43
View File
@@ -0,0 +1,43 @@
# 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 别名。
+31
View File
@@ -0,0 +1,31 @@
# 0018 模板视觉槽位与内容发布校验
## Context
餐饮原型的固定日程、配送双列和流程列表被错误地转换为任意 TrustContent 记录循环。旧正文、摘要和 config 并存,后台与小程序选择的记录不同。隔离数据库 seed 测试通过,开发数据库和发布快照仍缺字段。
## Decision
- 先确认原型区块、子卡、行和按钮,再声明浅层字段。布局只使用结构化字段,不拆分正文推断布局。
- 餐饮三个固定区域声明 `maxPublishedItems: 1`,每个区域只能有一条公开记录;草稿和旧记录可以保留。其他模板的列表内容可以声明自己的数量限制,未声明时允许多条。发布检查阻止重复公开记录或缺少实际展示字段。
- `hideStandardFields` 明确当前模板不使用的标准列。Admin、共享内容完整性判定和发布校验消费同一声明;隐藏正文不再作为完整性门槛。
- 公开记录投影保留稳定 `id`,视觉步骤列表生成明确索引 key,避免编辑和重排时出现节点复用错误。
- 可编辑状态、标签、步骤说明和页脚文案均由 manifest 声明,业务承诺不得硬编码在 renderer。
- 咨询问题来自已发布 InquiryForm,模板样例只在显式导入或限定开发 fixture 时复制。历史提交快照不改变。
- 完成必须覆盖当前数据库、发布 API、最终生成文件和页面数据。静态源码检查和独立 seed 测试不能代替实际数据迁移。
## Alternatives
保留正文拆分兼容会继续产生双数据源。为餐饮新建专用表会把示例行业侵入平台模型。采用浅层 TrustContent.config 与模板声明即可保持可替换模板边界。
## Consequences
旧记录可以作为草稿查看和恢复,但不能同时公开到同一必填视觉区域。后台列表展示实际 config 内容预览。发布失败明确引导用户完善对应区块。
## Migration Plan
`apps/api/scripts/migrate-food-template-content.ts` 只处理开发餐饮品牌,执行前备份,事务内迁移,保留旧记录为草稿,并创建新发布版本。命令默认 dry run,`--apply` 执行;成功标记后再次执行不写数据。生产客户必须另行制定品牌内容迁移映射,不能批量导入演示承诺。
## 主理人视觉约束
整理主理人页内容不得改为通用正文卡。以 OwnerView 原型为基准保留 208 px 写真封面、渐变身份区、三列资质图标小卡、案例简称/说明/结果标签及回复承诺圆点/强调色。新增槽位使用浅层 config 列表;不拆旧正文来猜测条目。缺少结构化数据时可显示原有正文,但不能用样例遮挡用户编辑。原型中的证书、经营年限和统计只在品牌管理员确认后填写。