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

55 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
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.