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

7.7 KiB

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.