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 列表;不拆旧正文来猜测条目。缺少结构化数据时可显示原有正文,但不能用样例遮挡用户编辑。原型中的证书、经营年限和统计只在品牌管理员确认后填写。
+13
View File
@@ -22,6 +22,11 @@
## 模板与配置包
- 模板声明必须真正驱动安装和升级,不能只增加类型而保留 Controller 硬编码;
- 每个页面上的品牌事实、信任资料、业务详情和可编辑文案都必须来自 Runtime 数据,并在同一页面声明对应 Admin editor binding;`pnpm validate:templates` 的逐页 renderer / editor 契约测试通过后才能判定模板完成;
- 每种模板信任内容必须声明实际展示页面,逐页测试要同时验证“声明的类型有 renderer 消费”和“renderer 使用的类型已声明”;
- 新模板必须由 package-discovered 测试自动纳入,不得只给现有模板写专用断言;
- 信任内容类型必须在 manifest 声明 `title`、`summary`、`content` 对应的 Admin 字段标签;API 按当前品牌 manifest 校验类型,不能在 DTO 中固定模板类型枚举;
- 模板数据存储与发布映射遵循 `docs/template-data-flow.md`,信任内容和咨询表单分别使用 `TrustContent` 与 `InquiryForm`;
- 安装必须保存版本和配置快照;
- 升级必须有预览、显式确认和“不覆盖用户内容”的规则;
- 回滚必须明确是恢复配置基线还是删除新增数据,并在接口文案和测试中保持一致;
@@ -43,3 +48,11 @@
- 运行 Admin production build;
- 运行 `pnpm format:check` 和 `git diff --check`;
- 做一次变更范围 Code Review,确认没有“已实现但未测试”的 endpoint 或 UI 操作。
## 固定视觉区域与旧数据验收
- 必填视觉区域不由任意记录数量决定布局;缺少实际展示字段或重复公开记录必须阻止发布;
- 结构化内容完整性由 manifest 声明判定,后台和发布端共用规则;隐藏字段不能仍被要求必填;
- 对照原型检查子卡数量、内容层次和文字换行,源码匹配不视为视觉验收;
- 使用当前数据库通过发布 API 驱动最终生成页面,验证日程、配送、流程和咨询字段;
- 数据迁移必须备份、限定品牌、保留历史提交和旧发布快照,并验证重复执行不产生重复内容。
+17
View File
@@ -0,0 +1,17 @@
# Runtime Content Matrix
本表是字段审查的固定入口。任何新增模板字段必须同时补充 binding、存储、Runtime path、编辑页面和最终 renderer。
| 内容类别 | Admin 来源 | 数据库来源 | API Runtime | 小程序消费 | 当前状态 |
| ------------------------------ | --------------------- | ---------------------------------------- | ------------------------------------------------------- | -------------------------- | ---------------------------------------------------------- |
| 品牌名称、定位、简介、联系信息 | 品牌资料 | `BrandProfile` columns | `workspace.brand` | 各模板 brand component | 已收敛,旧 config 仅兼容 |
| 模板自定义品牌字段 | 模板页面编辑器 | `BrandProfile.config.templateData` | `workspace.templateData` | 模板页面读取 | 已有 contract,需继续禁止未声明 key |
| 页面标题和按钮文案 | 模板页面编辑器 | `BrandProfile.config.visualPresentation` | `workspace.brand.visualPresentation` | 页面 presentation props | 已有 contract |
| 业务摘要 | 业务提供项表单 | `Offering.summary` | `workspace.offerings[].summary` | 列表和首页 | 已收敛 |
| 业务详情正文 | 模板详情字段 | `Offering.config.details.background` | `workspace.offerings[].presentation.details.background` | 详情页 | 已收敛,禁止重复 description 入口 |
| 业务图片、分类、关键词 | 模板详情字段 | `Offering.config` | `workspace.offerings[].presentation` | 详情/列表页 | 已有映射测试 |
| 信任内容标题、摘要、正文 | 信任内容编辑器 | `TrustContent.title/summary/content` | `workspace.trustItems[]` | 首页、资料页及出摊区块标题 | 已修正 trustItems 传参,隐藏字段不消费 |
| 信任内容扩展 | 模板声明 configFields | `TrustContent.config` | `workspace.trustItems[].config` | 模板组件 | 已验证编辑、发布、页面数据及必填规则 |
| 咨询表单字段 | 工作台表单编辑器 | `InquiryForm.fieldsSnapshot` | `workspace.inquiryForms[].fields` | inquiry form | 已验证实际数据库表单与生成页面,餐饮类型网格和双列布局保留 |
餐饮出摊服务的日程、配送和流程正文均使用结构化 `configFields`,不再读取隐藏的摘要和正文。`maxPublishedItems: 1` 由该模板为三个固定区域声明,Admin 和发布检查同时提示重复公开记录。每周主卡内两张日程小卡、配送双列和流程标题/说明列表均由模板布局固定,不由数据库记录数量推断。
+54
View File
@@ -0,0 +1,54 @@
# Template Data Flow
This document records where template-controlled content is stored and how it reaches the Mini Program. Template packages define presentation and editor declarations; database rows are the source of truth for each brand's edited content.
## Storage And Runtime Mapping
| Content | Template declaration | Brand-scoped storage | Admin editor | Published runtime |
| -------------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Brand identity and contact facts | `admin.sections` bindings such as `brand.config.founder`; platform identity fields are shared | `BrandProfile` columns and `BrandProfile.config` JSON | Brand profile and page configuration | Brand data is copied into `BrandRelease.snapshot`; public workspace merges the brand config into `RuntimeWorkspace.brand` |
| Page copy and presentation | `admin.sections` with exact page binding | `BrandProfile.config.visualPresentation` and related config objects | Template-driven page editor | Public workspace exposes the saved config; Mini Program renderers consume the matching page fields |
| Offerings and details | Offering-target `admin.sections` | `Offering` columns and `Offering.config` JSON | Services editor | Release snapshot offerings are normalized by public workspace; disabled offerings are filtered |
| Trust content | `trustContentTypes`, including page destinations and Admin labels for `title`, `summary`, and `content` | Brand-scoped `TrustContent` rows | Trust content editor; form labels/options come from the selected template manifest | Only published rows are copied to public runtime; template pages render declared types |
| Inquiry forms | The template package provides an explicit sample form name and sample fields | Brand-scoped `InquiryForm.fieldsSnapshot`; submissions keep their own snapshots | Workspace form editor; explicit sample import creates a form only when no enabled form exists | Release snapshot forms are normalized into `RuntimeWorkspace.inquiryForms` |
| Template and visual selection | Package manifest and visual template manifest | `BrandTemplateInstallation` snapshot plus `BrandProfile.templateKey/config.visualTemplateKey` | Workspace/template selection | Release snapshot pins package and visual manifest versions |
## Food Schedule Example
The food template declares the schedule type for the `home` and `service` pages. Its Admin fields map directly to existing database columns:
- `adminFields.title` edits `TrustContent.title`.
- `adminFields.summary` edits the primary weekday schedule in `TrustContent.summary`.
- `adminFields.content` edits the weekend and supplementary schedule in `TrustContent.content`.
- The public workspace returns those values as a `RuntimeTrustItem`; the home and service page renderers read `item.summary` and `item.content`.
No schedule-specific Prisma migration is needed. Different templates can choose different field labels while retaining the shared trust-content storage contract.
The Admin editor lists the selected template's declared trust types and uses their `adminFields` labels, help, and placeholders. In the food workspace, the service page links directly to the trust-content editor, so the schedule is configured under **内容管理 → 信任内容 → 出摊安排**. Saving changes the brand's draft content; the Mini Program sees the new values after the next publication.
## Inquiry Field Runtime Mapping
- Explicit sample import copies package-declared fields into `InquiryForm.fieldsSnapshot` only when the brand has no enabled inquiry form. It does not overwrite an existing form.
- The public workspace projects the persisted form into Runtime field types. `phone` becomes Mini Program `tel`, and `multi-select` becomes the supported `checkbox` control.
- The Mini Program renders checkbox options and submits the selected values as an array. The stored Admin/API field type remains `multi-select`.
## Template-Specific Shallow Data
Templates may declare a small set of customer-specific `templateFields`. Their values are stored under `BrandProfile.config.templateData`, edited by the same manifest-driven Admin editor, copied into the publication snapshot, and exposed as `RuntimeWorkspace.templateData`. The contract intentionally supports shallow scalar fields and one-level lists; it is not an arbitrary JSON editor. Undeclared keys are filtered from the public Runtime response.
## Shared Platform Data
The visual template packages and their manifests are package-discovered. Brand-specific copy, trust content, offerings, and inquiry forms are persisted per brand and included in publication snapshots. The platform's `BrandTemplateDefinition` taxonomy (`personal`, `food`, and `doors`) remains a shared product-level catalog used for template selection and brand categorization; it is not the source of visual package content or sample data. Adding a visual package does not require adding its sample records to Prisma seed data.
## Template Completion Checks
- `pnpm validate:templates` discovers every `packages/template-*` package and checks same-page Admin bindings, trust type declarations, sample trust type declarations, and trust Admin field labels.
- API integration tests cover trust authorization, writes to the persisted summary/content columns, and rejection of types absent from the brand's selected template manifest.
- `pnpm template:check` also compiles templates and validates Mini Program fixture output.
- Package-discovered contract tests compare each declared trust type against Mini Program page renderers and require Admin labels for the persisted `TrustContent` columns.
## Boundaries
- `template.json.sampleContent` is an import fixture, not live brand content. It is copied into brand rows only after an explicit Admin import.
- Active customer inquiry forms are persisted separately from `BrandFieldDefinition`; the public Mini Program receives `InquiryForm.fieldsSnapshot`. Importing sample fields creates a form only when no enabled form exists and never replaces administrator-authored forms.
- Layout, icons, and template-specific visual composition remain package code. Brand facts and business claims shown in those layouts must come from brand-scoped runtime data.