Files
persionalBrand/docs/template-data-flow.md
T

56 lines
7.7 KiB
Markdown

# 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
餐饮模板的日程在 service 页展示,使用 TrustContent.config 的浅层字段:
- title 编辑日程区块标题。
- weekdayLabel、weekdayTag、weekdayDetail、weekdayHours 编辑工作日卡片。
- weekendLabel、weekendTag、weekendDetail、weekendHours 编辑周末卡片。
- status 编辑日程状态。summary 和 content 已在该类型声明中隐藏,不参与日程渲染。
- 配送范围与流程分别使用 coverage 和 process 类型的配置字段,不能把摘要或正文作为第二套结构化数据入口。
编辑器区域列表和 renderer 的 slot 均优先使用带结构化配置的记录。页面点选传递真实 recordId;没有记录时提供内容管理入口。保存只影响品牌草稿,发布后公开 Runtime 才更新。模板样例仍属于包,不作为数据库注册目录。
详情页中的业务记录只提供选择预览;公共标题和按钮文案通过品牌配置区域编辑,影响全部详情页,不复制到每条业务记录。
## 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.