docs: 固化模板管理与分发交付计划

This commit is contained in:
que01 committed 2026-10-16 13:13:12 +08:00
1 parent 3989fbd39e
commit 1918dae36b
4 files changed
+704 -15

No files matched your search

@@ -0,0 +1,120 @@
# 0029 模板管理、导入与分发边界
## 背景
平台已经有行业模板、视觉模板包、Runtime Workspace、样例导入和 Taro 构建的部分实现,但这些能力还没有形成从本地模板包到线上安装和小程序发布的统一生命周期。之前出现过以下类型的故障:
- 新模板代码在本地分支存在,但线上没有对应数据库内容或可选择的品牌;
- 模板 manifest、package metadata、生成注册表和部署包的版本可能不一致;
- 模板预览、品牌草稿、发布快照和微信代码上传被当成同一个状态;
- sample 只在一次性 seed 或脚本中出现,无法支持独立预览、显式导入和后续升级;
- 构建包缺少 apps/taro 或 production dependency,上传阶段才发现 miniprogram-ci 不可用;
- 构建任务日志并发写入导致状态回退、永久轮询和重启后无法恢复;
- 静态 doctor 或 mock 成功被误认为真实模板交付完成。
如果继续按单模板修补,模板数量增加后会重复出现版本漂移、权限遗漏、数据污染、构建串品牌和失败不可恢复的问题。需要一个单独的模板管理页面、可验证的包契约、明确的安装边界和可复验的端到端门禁。
## 决策
### 1. 以模板管理交付计划作为唯一任务入口
使用[模板管理与分发交付计划](../template-management-delivery-plan.md)统筹目标、阶段、证据、风险和进度。运行时进度、模板注册表和后续实现文档必须链接到该入口,不能各自维护一套互相冲突的完成状态。
这是一项目标架构决策,尚未表示代码已经实现。
### 2. 模板包版本不可变,manifest 是唯一事实来源
模板包以 packageKey + version + checksum 标识。导出包必须确定性生成;同 key/version 的不同 checksum 拒绝导入,同 checksum 的重复导入幂等。manifest 负责声明页面、模块、编辑 binding、资源、能力、行业兼容性、preview fixture、bootstrap 策略和 renderer contract。
生成的 catalog 可以作为构建产物,但不能继续维护一份手工模板注册表作为第二事实来源。模板 sample content 仍属于包,不进入全局 Prisma seed。
### 3. 平台模板管理和品牌内容管理分离
新增平台级模板管理页面,负责导入、校验、独立预览、目录发布、撤回和审计。品牌工作台负责安装已发布版本、显式导入起始内容、编辑、发布、升级和回滚。品牌 owner 不能因为拥有品牌就获得平台模板管理权限。
### 4. 第一阶段只导入声明式包和受信 renderer 引用
线上导入器第一阶段接受 manifest、资源、fixture、bootstrap 声明和已部署的 renderer key/version。API 进程不执行上传包中的任意脚本或源码。模板包如果要求新的 renderer,必须先走平台 renderer release 和兼容性门禁;导入页面必须显示阻断原因。
这明确承认“导入任意全新 renderer 后立即运行”不属于第一阶段能力。若未来确实需要该能力,必须建设隔离构建 Worker、依赖 allow-list、资源限制、产物扫描、签名和版本化 H5/weapp artifact 流程,不能绕过平台发布。
### 5. 预览、bootstrap、安装和发布分别建模
预览使用包内演示数据和临时隔离 session,不创建真实品牌或业务数据。安装只记录品牌使用的精确模板版本和快照。bootstrap 由管理员明确触发,先 dry-run,再按 missing-only 导入;已有值、管理员主动保存的空值和历史数据保留。品牌发布产生独立 release snapshot,小程序构建、上传、审核和上线再分别记录状态。
### 6. 行业模板、视觉模板、能力和 renderer 分别版本化
行业兼容性不能由客户端自行选择或由默认行业映射猜测。模板包版本、package schema、Runtime contract、renderer、capability、toolchain、brand release 和 build/upload attempt 分开记录。breaking change 必须有迁移和回滚方案。
### 7. 状态迁移使用可恢复的 job 和幂等操作
导入、校验、预览资源处理、构建和上传等异步操作都有 operation/idempotency key、attempt、lease、心跳、顺序日志和原子终态。构建成功不代表上传成功,上传成功不代表微信审核或线上发布成功。进程退出、超时、重试和重复请求必须收敛到可查询状态。
### 8. 安全校验在导入边界完成
导入包必须检查 path traversal、绝对路径、symlink、展开体积、文件数量、资源类型、checksum 和版本冲突;旧版本资源按版本或内容寻址保留。预览使用受限 origin/CSP 和短期权限,禁止真实咨询、客户记录和品牌发布。所有模板管理和品牌变更操作写审计与 requestId。
### 9. 完成判定必须包含真实数据和外部证据
template:doctor、manifest 静态校验、mock 请求和页面能打开只能证明局部条件。模板完成必须同时通过 package-discovered conformance、API 授权和隔离测试、真实品牌编辑保存重载发布、Taro 双端构建产物检查、并行品牌和重启恢复测试。微信开发者工具或真机上传结果单独记录,不能用自动化 mock 宣称已上线。
## 替代方案
### 继续使用手工注册表和 Prisma seed
实现成本低,但新模板必须修改全局 seed 和多处注册表,线上导入、版本冲突和示例来源无法追踪;不采用。
### 每个模板复制一套完整小程序
可以快速还原单个设计,但会复制品牌核心、发布和能力逻辑,导致 renderer、字段和修复持续分叉;不采用。
### 在线直接执行模板源码
可以让新 renderer 不依赖平台部署,但会把上传包变成代码执行边界,增加供应链、租户隔离和构建依赖风险;第一阶段不采用。未来若确有需求,按隔离构建 Worker 的独立架构评审。
### 只把预览做成静态截图
截图不能验证真实 Runtime 数据投影、编辑 binding、空态、CTA、咨询禁用和页面导航;不采用。预览必须使用真实 renderer 和受控 sample 数据。
### 复用现有 BrandTemplateInstallation 承担全部版本
现有模型主要承担行业模板安装,直接改变含义会破坏旧查询、发布快照和回滚;先保留兼容边界,新增视觉包安装或可逆扩展后再评估合并。
## 后果
### 正面后果
- 本地导出和线上导入拥有同一份可校验契约;
- 模板版本、行业兼容性、renderer 和能力依赖可以在品牌安装前发现;
- 预览不会污染品牌数据,bootstrap 来源可追踪,升级可以保护用户内容;
- 模板管理员和品牌管理员的职责、权限和页面操作清楚;
- 构建、上传和发布故障有独立状态,重试和重启可以恢复;
- 新模板可以通过自动发现和统一门禁进入目录,减少手工分支。
### 成本和限制
- 需要新增包导出、artifact、校验报告、预览 session、安装快照和导入记录等数据和运维能力;
- 第一阶段的新 renderer 仍需要平台 release,模板包自由度受已部署 renderer 限制;
- 升级和回滚要保存差异、历史快照和资源,数据库与对象存储容量会增加;
- 视觉验收和真实微信验证比静态检查耗时更长;
- 旧注册表、行业默认映射和原生 renderer 需要迁移,不能一次删除。
## 迁移计划
1. 先完成 docs/template-management-delivery-plan.md、本文、注册表和运行时进度入口的统一;
2. 盘点并修复当前模板包版本、manifest、package metadata、generated catalog、Taro/原生目录和 release 打包清单;
3. 扩展 packages/template-contract,实现确定性导出、checksum 和 package-discovered conformance;
4. 增加模板包版本、校验报告、artifact 和独立平台权限,先支持线上导入和目录发布;
5. 建立真实 Runtime 的行业预览 session 和 /admin/templates 页面;
6. 增加品牌视觉包安装、bootstrap 来源记录、missing-only 导入和升级差异;
7. 拆分 build/upload/review/release 状态,补充依赖闭包、重启恢复、并发品牌和真实产物门禁;
8. 完成升级、冲突、回滚和最终端到端验收后,再逐步淘汰手工注册表、默认行业映射和重复 renderer 分支。
## 与既有决策的关系
- 补充 [ADR 0008:视觉模板包契约](0008-visual-template-package-contract.md):将 manifest、资源、样例和安装扩展到线上导入、checksum 和目录生命周期;
- 补充 [ADR 0019:Taro 模板双端运行时](0019-taro-template-runtime.md):明确线上模板包第一阶段引用受信 renderer,任意新 renderer 另行建设隔离构建;
- 补充 [ADR 0022:模板完成度诊断](0022-template-completion-diagnostics.md):把稳定 issue identity、真实编辑重载发布和视觉证据纳入模板目录门禁;
- 补充 [ADR 0028:按当前视觉模板显式导入示例](0028-template-selected-sample-import.md):将 sample preview、bootstrap import、来源和升级规则统一到模板管理生命周期;
- 取代旧注册表中“手工列出所有可用模板即可完成注册”的隐含假设;docs/template-registry.md 只保留当前盘点和迁移入口;
- 不删除或否定 [ADR 0010:模板示例内容注册表](0010-template-sample-content-registry.md) 的历史背景,但其中与“全局注册表或 seed 作为模板事实来源”冲突的部分以本 ADR 和模板数据流规则为准。
+544
View File
@@ -0,0 +1,544 @@
# 模板管理与分发交付计划
> 任务 ID:TMP-PLATFORM-001
>
> 状态:规划已固化,分阶段实施尚未完成
>
> 唯一任务入口:本文档
>
> 架构决策:ADR 0029:模板管理、导入与分发边界
本文档把模板从本地开发、导出、线上导入、校验、预览、安装到小程序发布的完整工作固化为一个可追踪任务。后续代码、迁移、接口、后台页面、测试证据和已知缺口都必须回到本文登记。本文描述的是目标和实施门禁;没有对应代码、测试和运行证据的条目不能标记为完成。
## 1. 背景和目标
过去的模板交付把多个层次混在了一起:
- 本地分支的代码、线上 release 目录、数据库中的品牌内容、发布快照和微信开发者工具中的代码不是同一份状态;
- 行业模板和视觉模板同时存在,但安装、选择和展示依赖分散的注册表与默认值;
- 模板有 manifest 和 sample content,却没有完整的导出、线上导入、版本校验和独立预览闭环;
- 示例数据只在一次性 seed 或脚本里出现,老品牌升级时不会自动补齐新字段;
- 构建、上传、发布的状态被压缩成一个状态,依赖缺失、产物路径错误、日志乱序和重启恢复都可能让后台永久轮询;
- 静态 doctor、页面能打开或 mock 成功不能证明真实字段可编辑、保存可重载、发布可见和小程序可上传。
本任务的目标是让平台具备以下稳定流程:
本地模板包开发
-> 确定性校验与导出
-> 线上导入与 checksum 去重
-> 兼容性校验与诊断
-> 按行业选择的独立预览
-> 发布到模板目录
-> 创建或选择品牌
-> 安装精确版本
-> 显式导入起始内容
-> 编辑、保存、重载、发布
-> 使用真实品牌参数构建和上传小程序
-> 升级、冲突处理和回滚
完成标准不是“以后绝不出 bug”,而是每个状态转换都有明确契约、失败路径、可恢复操作和自动化证据;外部微信审核或上传结果必须单独记录,不能用本地 mock 代替。
## 2. 范围和非目标
### 2.1 本任务范围
- 建立平台级模板管理页面,和单品牌的内容配置、配置发布页面分离;
- 支持从仓库中的模板包生成可校验、可复现的导出包;
- 在线导入模板包,进行文件安全检查、manifest/schema 校验、运行时和 renderer 兼容性校验;
- 按行业选择可预览的模板组合,并使用模板包内演示数据通过真实 Runtime 投影;
- 管理模板版本的导入、校验、目录发布、撤回和审计;
- 在品牌上下文安装精确的行业模板和视觉模板版本;
- 将预览演示数据和品牌起始内容分开,支持显式、可追踪、缺失字段优先的 bootstrap 导入;
- 支持升级预览、冲突报告、用户内容保护和回滚;
- 将构建、上传、发布的任务状态、依赖、产物、重试和重启恢复纳入同一交付门禁;
- 为上述行为建立 API integration test、client contract test、Admin 关键交互测试、构建产物检查和最终 E2E 证据。
### 2.2 非目标
- 不允许 API 进程直接执行上传包中的任意 JavaScript、TypeScript、shell 或安装脚本;
- 不把所有模板 sample content 复制进 Prisma seed,也不把 seed 当成模板目录;
- 不把品牌 owner 的权限扩展为平台模板管理员权限;
- 不把一次性的线上修复脚本当成模板安装能力;
- 不在同一阶段长期维护两套业务 renderer。Taro 是统一的双端业务 renderer,旧原生实现只作为迁移和回滚基线;
- 不承诺第一阶段可以导入任意全新 renderer 源码后立即运行。第一阶段只接收声明式 manifest、资源、演示数据和已部署的受信 renderer 引用;
- 不把生成一张预览图、静态文件存在或页面能打开当成模板交付完成。
如果产品最终要求“线上导入任何全新 renderer 源码即可运行”,必须另行完成可信第一方源码包、隔离构建 Worker、依赖 allow-list、签名、产物扫描和 H5/weapp 版本化发布;不能把平台重新部署伪装成导入闭环。
## 3. 当前状态和目标状态
| 领域 | 当前状态 | 目标状态 | 进入目标状态的证据 |
| ------------ | --------------------------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------- |
| 模板发现 | packages/config 有生成注册表,文档注册表仍是手工清单 | 所有可用版本由可校验包 manifest 发现,生成注册表只作为构建产物 | 包发现测试、目录接口测试、无手工重复定义 |
| 版本 | 模板 key、manifest version、package metadata 可能漂移 | key + version + checksum 唯一且不可变 | 导出 checksum、重复导入、冲突导入测试 |
| 行业与视觉 | 行业安装和视觉选择已有部分能力,但没有完整版本化目录 | 行业兼容性、视觉包版本、renderer contract 一起校验 | 组合矩阵、安装快照和跨行业测试 |
| 示例内容 | 包内 sample 可用于部分预览和显式导入 | preview fixture、bootstrap 内容、品牌真实数据严格分离 | 预览无品牌写入、显式导入审计、缺失值规则测试 |
| 模板管理页面 | 现有工作台可以选择部分已注册模板 | 独立 /admin/templates 管理导入、校验、预览、发布和版本 | 页面状态测试、API 权限测试、错误重试测试 |
| 安装和升级 | BrandTemplateInstallation 主要承担行业安装 | 行业安装、视觉包安装、样例导入、升级计划和发布快照各有边界 | schema 迁移、旧数据回填、升级/回滚 integration test |
| 构建发布 | 构建、上传和发布曾共用状态,容易死锁或误报 | build、upload、review、publish 分层,attempt/lease/产物隔离 | 并发、重启、超时、错误收敛、真实参数产物测试 |
| 版本事实 | atelier-solopreneur 的 manifest 为 1.1.0,package metadata 仍为 1.0.0 | 包内版本字段和导出元数据在导出前强一致 | 第一阶段盘点修复并添加阻断测试 |
当前存在的 Runtime Workspace、模板 manifest、样例导入和 Taro 构建能力是基础组件,不代表本任务已完成。实施进度必须引用本文的阶段和证据。
## 4. 领域边界和术语
| 名称 | 责任 | 不负责的事情 |
| ------------------------------------- | ----------------------------------------------------------------- | -------------------------------------------- |
| 行业模板(industry template) | 定义行业字段、Offering schema、表单用途和能力依赖 | 不定义视觉包的完整页面代码和样例内容 |
| 视觉模板包(visual template package) | 定义页面结构、模块变体、theme token、资源槽位、编辑绑定和演示内容 | 不把品牌真实数据写进平台全局 seed |
| Capability | 定义咨询、上传、排期等可复用业务能力及其 API/Admin/小程序契约 | 不通过页面分支偷偷引入行业专属字段 |
| Template package version | 一个不可变的 manifest、资源、fixture、bootstrap 声明和兼容性声明 | 不在导入时执行任意包脚本 |
| Preview session | 对某个已校验版本和行业组合的临时演示上下文 | 不创建品牌、咨询提交、发布快照或真实客户记录 |
| Bootstrap import | 管理员明确触发的起始内容导入 | 不覆盖品牌主动设置的值,不等同于模板注册 |
| Brand installation | 某品牌使用的精确行业/视觉包版本快照 | 不修改历史发布快照,不代表样例已导入 |
| Release snapshot | 某次品牌发布时冻结的全部运行时定义和品牌内容 | 不随着模板目录更新而隐式变化 |
平台要维护两种唯一性:
1. 模板包的事实唯一性由包 manifest 和 checksum 决定;
2. 品牌公开内容的事实唯一性由品牌数据库草稿和发布快照决定。
模板包不能成为品牌运行时的隐式 fallback。模板 renderer 读取的品牌事实必须来自 Runtime contract;缺失内容要显示空态、降级或阻止发布,不能自动填充未经管理员确认的假身份、经验、背书或接单状态。
## 5. 用户流程和页面职责
### 5.1 平台模板管理员流程
1. 在本地开发模板包,运行 schema、编辑绑定、资源、renderer 和构建检查;
2. 导出确定性包,生成 manifest 摘要、文件清单和 checksum;
3. 在 /admin/templates 导入包,看到导入进度、大小、文件数量和失败原因;
4. 打开版本详情,查看兼容行业、runtime contract、renderer、能力、页面区域、编辑绑定、sample 和阻断诊断;
5. 为某个行业启动独立预览,预览只消费包内演示数据,不写入品牌数据库;
6. 通过所有门禁后发布到模板目录;未发布版本只对平台模板管理员可见;
7. 发布后仍保留版本和资源,撤回只影响可选目录,不删除已安装品牌和历史发布快照;
8. 查看导入、校验、预览、发布和撤回审计。
### 5.2 品牌管理员流程
1. 在品牌工作台选择已发布且和当前行业兼容的模板版本;
2. 查看安装前差异、能力依赖和是否已有品牌内容;
3. 安装精确版本,记录安装快照;
4. 独立点击“导入起始内容”,先查看 dry-run 的新增、保留和冲突;
5. 编辑模板声明的字段,保存后刷新页面验证重载;
6. 通过结构完整性校验后发布品牌内容;
7. 使用真实品牌 slug、模板 key、版本和 API 地址构建小程序;
8. 上传、审核、上线状态单独展示,失败可以重试同一 attempt 或创建新 attempt;
9. 新版本升级前查看差异,发生冲突时逐项处理;回滚时明确恢复配置基线还是撤销尚未采用的新内容。
### 5.3 页面分工
| 页面 | 面向对象 | 核心职责 | 必须具备的状态 |
| ---------------- | ---------------------------- | -------------------------------------------- | ---------------------------------------------------------------- |
| /admin/templates | 平台模板管理员 | 模板包导入、版本列表、校验、目录发布和审计 | loading、empty、importing、invalid、ready、published、retry |
| 模板版本详情 | 平台模板管理员 | manifest、兼容矩阵、诊断、资源、能力、历史 | schema error、renderer incompatible、missing asset、audit |
| 模板预览 | 平台模板管理员或受控内部用户 | 选择行业、使用 sample 渲染真实 Runtime | preview loading、组合不兼容、空值、错误、禁止提交 |
| 品牌模板安装 | 品牌管理员 | 选择已发布版本、查看差异、安装快照 | unauthorized、incompatible、already installed、conflict、success |
| 品牌起始内容导入 | 品牌管理员 | dry-run、确认导入、显示来源和保留规则 | no-op、new records、preserved values、conflict、failure |
| 品牌配置与发布 | 品牌管理员 | 编辑、保存、重载、发布 | field error、save failure、stale version、publish blocked |
| 构建与上传记录 | 品牌管理员/平台运维 | 展示 build、upload、review、release 分层状态 | queued、running、retryable failure、terminal failure、recovered |
模板管理页面不能代替品牌内容页面。平台管理员发布的是目录版本,品牌管理员发布的是某个品牌的内容快照。
## 6. 模板包契约
### 6.1 版本和兼容性字段
实施时应扩展 packages/template-contract,并让 manifest 成为唯一输入。字段名称可以在实现阶段经过类型审查调整,但必须保留以下语义:
| 字段 | 规则 |
| -------------------------- | ------------------------------------------------------------------- |
| packageKey | 稳定标识,只允许小写、数字和短横线;发布后不能复用给另一个产品 |
| version | 模板包版本,遵循明确的 semver 规则;同 key + version 不允许内容变化 |
| packageSchemaVersion | 包格式版本,和模板业务版本分开 |
| runtimeContract | 所需 Runtime Workspace contract,必须通过兼容矩阵 |
| renderer | renderer key、版本、支持端和最小兼容版本 |
| supportedIndustryTemplates | 行业 allow-list,不能由客户端任意修改 |
| capabilities | 能力 key、版本、必选/可选及配置 schema |
| pages / modules | 页面入口、区域、模块顺序、变体和公开数据槽位 |
| admin.sections | 编辑区、真实 binding、输入类型、必填规则和预览目标 |
| assetSlots | 资源 binding、类型、尺寸约束和是否必需 |
| previewFixture | 只读预览用演示内容,声明敏感字段和提交禁用策略 |
| bootstrap | 可显式导入的起始内容、映射、稳定 key 和导入策略 |
| compatibility | renderer、capability、API 和 toolchain 的兼容范围 |
admin.sections 和 renderer 必须互相校验:每个可见、可编辑的品牌事实都有可追踪 binding,每个 binding 都有真实 renderer 消费点。字段出现在 mock 输入框、静态文件或隐藏 fallback 中,不能算作完成。
### 6.2 推荐包结构
template-package/
template.json
assets/
fixtures/
preview/
bootstrap/
checksums.json
README.md
仓库内的模板包可以额外包含 taro/ 源码和迁移用的旧 miniapp/;线上导入器第一阶段只接受 allow-list 中的声明式文件、资源和已部署 renderer 引用。包中发现新的 renderer 源码时必须明确返回“需要平台 renderer release”,不能静默忽略。
### 6.3 导出和导入规则
- 导出使用排序稳定的文件清单、规范化 JSON、固定压缩参数和 UTF-8 编码;
- checksum 覆盖 manifest、资源、fixture、schema 和允许的元数据;
- 导入先写入临时对象存储或临时目录,完成 path traversal、绝对路径、symlink、压缩炸弹、大小、文件数量、扩展名、MIME 和 checksum 检查后才进入版本表;
- 不解析或执行 postinstall、prepare、构建脚本和包内任意代码;
- 同一 packageKey + version + checksum 重试必须幂等;
- 同一 packageKey + version 但 checksum 不同必须拒绝并生成稳定错误 code;
- 导入失败不能留下可被目录接口读取的半版本;
- 旧已发布版本的资源必须可继续读取,不能因为目录撤回或新版本导入而删除。
## 7. 版本、数据来源和状态机
### 7.1 版本维度
以下版本必须分开记录:
1. 模板包业务版本,例如 atelier-solopreneur@1.1.0;
2. package schema version,表示包格式;
3. Runtime contract version,表示数据投影契约;
4. renderer version,表示预部署的 Taro renderer;
5. capability version,表示能力 API 和配置;
6. toolchain version,表示 Taro、React、Node 和构建依赖;
7. brand release version,表示某品牌的一次发布;
8. miniapp build/upload attempt,表示某次构建和上传尝试。
不能因为包格式升级就自动把 Runtime contract 从 1.x 升到 2.0;每次 breaking change 都必须有兼容策略、迁移和回滚说明。
### 7.2 模板版本状态
importing -> rejected
importing -> imported -> validating -> invalid
validating -> previewable -> published -> retired
- imported 表示文件入库,不表示可使用;
- previewable 表示 manifest、资源、renderer、行业兼容性和 preview fixture 通过;
- published 才能被品牌管理员选择;
- retired 不影响已有安装、历史快照和预览证据;
- 任意状态迁移都写审计,重复请求使用 operation/idempotency key。
### 7.3 品牌模板和内容状态
安装、起始内容导入、品牌内容发布分别记录:
installation: requested -> installed -> upgrade_pending -> conflicted
bootstrap: previewed -> confirmed -> imported | failed
brand content: draft -> publish_validating -> published | blocked
模板安装成功不能自动代表 sample 已导入,sample 导入成功也不能自动代表品牌内容已发布。
### 7.4 构建和上传状态
build: queued -> running -> built | failed | timed_out
upload: queued -> running -> uploaded | failed | timed_out
review: pending -> approved | rejected
release: pending -> released | rolled_back
后台 UI 不得只轮询一个“发布”状态。每个 job 有 attemptId、lease、开始和结束时间、最后心跳、版本、产物路径、错误 code 和可重试性。日志按 sequence 写入,终态使用 compare-and-set 或事务状态迁移;禁止多个异步日志写入同时覆盖任务终态。
## 8. 数据模型和迁移策略
以下是目标模型,最终字段名以 Prisma schema、shared client 和 integration test 一起确定:
| 目标模型 | 主要内容 | 设计要求 |
| ------------------------------- | --------------------------------------------------------------------------- | ------------------------------------ |
| TemplatePackage | 稳定 key、名称、所有者和描述 | 不保存某个品牌的内容 |
| TemplatePackageVersion | manifest snapshot、版本、checksum、兼容性、renderer、artifact ref、校验状态 | 版本不可变,checksum 唯一 |
| TemplateValidationRun | 校验器版本、issue code、语义指纹、结果和日志 | issue identity 不能依赖行号 |
| TemplatePreviewSession | package version、行业、fixture、过期时间、权限和 origin | 不关联真实品牌数据,不持久化真实提交 |
| BrandVisualTemplateInstallation | 品牌使用的精确视觉包版本和快照 | 和行业安装区分,保留历史 |
| TemplateBootstrapImport | 来源包、版本、checksum、actor、策略、结果和审计 | 记录每条记录的来源和稳定 key |
| TemplateUpgradePlan | from/to、差异、冲突、用户确认和执行结果 | 支持 dry-run、重试和回滚 |
| TemplateOperationJob | 导入、校验、资源处理、build/upload 的 attempt 和 lease | 支持重启恢复和终态收敛 |
现有 BrandTemplateInstallation 当前主要承担行业模板安装记录,不能直接把它改成视觉包版本记录并破坏旧快照。实施前先盘点其查询、发布快照和旧回滚行为;优先新增边界清晰的模型或新增可为空字段,完成兼容读取后再考虑收敛。
数据库迁移必须遵循以下顺序:
1. 备份并记录当前 schema、模板安装、品牌配置和发布快照数量;
2. 先增加可为空的新字段或新表,不改变旧读路径;
3. 回填只写可从旧数据确定推导出的值,不能猜测版本、checksum 或样例来源;
4. 双读对比旧路径和新路径,记录不一致;
5. 切换写入,再保留旧读兼容窗口;
6. 清理旧字段前提供备份、回滚脚本和历史快照验证;
7. 重复执行迁移和导入不得生成重复安装、重复 offering、重复 inquiry form 或重复审计。
模板 sample 永远来自包。开发 demo 可以保留少量显式 fixture,但新模板不能要求在 apps/api/prisma/seed.ts 增加一套全局注册和样例记录。
### 8.1 Bootstrap 的保留规则
导入前必须生成 dry-run:
- missing:数据库中没有该 binding 或稳定业务 key,可以创建;
- existing:已有值,保留并显示来源;
- explicit-empty:管理员主动保存的空字符串、null 或空数组,视为已有值,不能被样例覆盖;
- conflict:同一稳定 key 的结构或类型不兼容,必须人工处理;
- removed-in-target:新版本不再声明旧字段,不能隐式删除用户数据。
导入记录保存 sourcePackageKey、sourceVersion、sourceChecksum、sourcePath、targetRecordId、operationId 和导入时的值摘要。不会为了通过 ready check 自动导入假姓名、十年经验、虚构背书、营业状态或公开案例。
## 9. API、权限和客户端契约
接口命名和资源路径在实现阶段通过 shared client 固化;以下是必须覆盖的接口族:
| 接口族 | 作用 | 权限和隔离 | 必测路径 |
| ----------------------- | ---------------------- | ---------------------------- | --------------------------------------------------- |
| template package import | 上传、导入、查询 job | 独立平台模板管理权限 | 无凭证、错误角色、包非法、成功、重复、checksum 冲突 |
| template validation | 运行或查询校验、诊断 | 平台模板管理权限 | 未导入版本、未授权、兼容失败、重试幂等 |
| template catalog | 查询已校验/已发布版本 | 未发布版本仅平台权限 | 目录隔离、撤回、分页、版本排序 |
| template preview | 按版本和行业创建预览 | 平台权限或受控 preview token | 行业不兼容、资源缺失、过期、真实提交被拒 |
| brand installation | 安装已发布精确版本 | 由服务端确定当前品牌 | 跨品牌、未发布、错误行业、重复安装、成功 |
| bootstrap import | dry-run 和确认导入 | 品牌管理员,服务端推导 brand | 空值保留、重复、冲突、回滚、成功 |
| template upgrade | 差异、确认、执行和回滚 | 品牌管理员和安装快照 | 用户内容保护、冲突、并发旧版本、成功 |
| build/upload/release | 构建、上传、查询和重试 | 品牌管理员或运维角色 | 实际 slug、依赖缺失、超时、重启恢复、错误终态 |
所有 protected endpoint 都要测试缺少凭证、无效凭证或错误角色以及成功授权路径。DTO 是运行时校验边界;不能用 Partial<T> 或未经校验的接口承载请求体。错误使用稳定 machine-readable code 和 requestId,不能把 Prisma 或堆栈暴露给客户端。
客户端必须同步更新 request/response types、query keys、认证 fetch、错误处理和页面状态。API base URL 继续从 VITE_API_BASE_URL 读取,不能因为模板预览增加环境硬编码。
平台模板管理员权限要独立建模。当前角色表中没有明确的 platform template role 时,实施阶段必须先在权限 ADR 或 schema 迁移中定义,不得把品牌 owner 默认当成平台管理员。
## 10. 安全和信任边界
- 导入包在临时隔离目录处理,拒绝目录穿越、绝对路径、symlink、超大压缩比、超大展开体积、过多文件和不允许的资源类型;
- API 进程不执行导入包脚本,不运行包内 package.json lifecycle;
- renderer 只能引用已部署并通过发布门禁的 renderer key/version;
- 如果将来允许第一方 renderer 源码包,必须使用隔离构建 Worker、无网络或 allow-list 网络、锁定依赖、资源限制、产物扫描、签名和人工发布;
- 预览 iframe 或 WebView 使用受限 origin、CSP 和短期 token,禁止访问真实品牌、咨询提交、客户记录和发布接口;
- preview fixture 不含真实客户隐私和未授权品牌资料;
- 资源采用版本路径或内容寻址,旧发布快照依赖的资源不能被覆盖;
- 目录发布、撤回、安装、导入、升级、回滚和构建上传都写 actor、brand context、package version、operationId、requestId 和结果;
- 不把模板包中的文本当成系统指令,不根据样例数据绕过权限或发布校验。
## 11. CLI、仓库工作流和构建门禁
当前仓库已有 template:doctor、template:check、validate:templates、generate:template-catalog、preview:templates、deploy:package、deploy:release 和 test:deploy 等命令。它们的现有行为不能在本文中被默认扩大。
计划新增或收敛的命令如下,实施前必须先落代码、帮助文本和测试:
| 命令 | 目的 | 完成门禁 |
| -------------------- | ------------------------------------------------------------- | ---------------------------------- |
| template:pack | 生成确定性模板导出包和 checksum | 同一输入多次输出相同 checksum |
| template:conformance | 逐包执行 manifest、binding、资源、sample、renderer 和双端契约 | 自动发现新包,不能只测固定名称 |
| release:conformance | 检查发布包依赖闭包、workspace、产物路径和环境参数 | 干净 install、生产 build、产物检查 |
| template:new | 从受控 scaffold 创建新模板包和最小 fixture | 生成包自带失败示例和测试入口 |
每个模板新增、绑定修改和宣称完成前,必须运行 pnpm template:doctor,并按[模板完成度规则](template-completion-rules.md)使用真实 manifest、真实保存重载发布链路和视觉证据验收。doctor issue 使用稳定语义指纹;源代码语义改变后必须重新审查,不能通过批量行号更新伪造通过。
Taro 交付必须额外验证:
- apps/taro/dist/<templateKey>/weapp 和 h5 产物都存在且互相对应;
- 构建参数使用实际品牌 slug、选中视觉模板版本、真实 API base URL 和 AppID;
- package workspace 依赖闭包在干净 install 后仍可解析,包括 miniprogram-ci 和 zod 等 production 依赖;
- No projects matched、缺少 app.json、旧 app.json 冒充本次成功和产物路径串品牌都被视为失败;
- 日志终态、上传启动、上传失败、超时和重启恢复都有测试;
- 真实微信开发者工具或真机负责 request、media、登录、拨号、复制、滚动、安全区和最终视觉证据。
## 12. 分阶段实施清单
阶段按依赖顺序执行。每个阶段都要在本文的进度区补充 commit、测试命令、证据路径和未解决问题;阶段未过门禁不得进入下一阶段。
### Phase 0:任务固化和现状盘点
- [x] 建立本文档和 ADR 0029,并将其设为唯一任务入口;
- [ ] 盘点所有模板包的 manifest/package metadata、renderer、fixture、资源和版本差异;
- [ ] 盘点现有行业安装、视觉选择、发布快照和 Admin 页面调用关系;
- [ ] 为历史事故建立可执行回归清单;
- [ ] 解决 atelier-solopreneur manifest/package metadata 版本漂移;
- [ ] 明确平台模板管理员角色和线上隔离环境。
退出门禁:模板目录、版本事实、现有数据模型和已知失败路径有可审阅清单;没有“默认值能猜出来”的隐含项。
### Phase 1:包契约和确定性导出
- [ ] 扩展 packages/template-contract,定义 package schema、rendererRef、preview/bootstrap、资源和兼容矩阵;
- [ ] 实现 template:pack,生成稳定清单和 checksum;
- [ ] 实现 package-discovered template:conformance;
- [ ] 为每个当前模板补齐真实 manifest、可见字段、编辑绑定、空态和 fixture;
- [ ] 把版本漂移、缺资源、未知 binding、未消费字段和不兼容 renderer 变成阻断 issue;
- [ ] 记录旧原生 miniapp 和 Taro 目录的迁移边界。
退出门禁:干净 checkout 中所有模板包可被发现、导出、校验;相同输入 checksum 稳定;不执行包脚本;每个页面的可见品牌事实都有 renderer 和 editor 证据。
### Phase 2:线上导入、校验和模板目录
- [ ] 增加 TemplatePackage、TemplatePackageVersion、validation run 和 artifact 引用;
- [ ] 实现临时存储、安全检查、checksum 幂等和冲突拒绝;
- [ ] 完成 manifest、runtime、renderer、industry、capability、资源和 fixture 诊断;
- [ ] 实现目录发布、撤回、分页、审计和旧资源保留;
- [ ] 增加独立平台模板权限;
- [ ] API、DTO、shared client 和 integration test 一起交付。
退出门禁:非法包不会进入可用目录;重复导入不重复建版本;同版本不同 checksum 明确失败;未发布版本不能被品牌管理员安装。
### Phase 3:独立预览和模板管理页面
- [ ] 增加 preview session 或同等短期隔离上下文;
- [ ] 按行业选择兼容组合,使用 preview fixture 通过真实 Runtime projection 渲染;
- [ ] 页面展示模块顺序、字段来源、资源缺失、能力依赖和诊断;
- [ ] 预览禁止真实咨询、客户记录、品牌发布和上传;
- [ ] /admin/templates 完成导入、详情、校验、预览、发布、撤回和审计交互;
- [ ] 覆盖 loading、empty、error、retry、success 和权限失败状态。
退出门禁:预览不创建品牌和业务数据;不同版本、行业和资源组合不会串数据;页面失败时保留上传和选择上下文;真实 Runtime 和预览数据映射有测试。
### Phase 4:品牌安装、bootstrap 和发布
- [ ] 区分行业安装和视觉包安装,保存精确版本与 checksum 快照;
- [ ] 实现 sample dry-run、显式确认、missing-only、空值保留、冲突和来源审计;
- [ ] 建立模板驱动的 Admin editor binding,保存后重载仍能看到相同值;
- [ ] 发布校验基于当前安装版本和真实品牌 manifest;
- [ ] 通过 shared client、Admin 页面和 API integration test 验证跨品牌隔离;
- [ ] 验证模板安装不自动导入未确认的身份、背书、案例和咨询数据。
退出门禁:干净品牌可以通过安装和显式导入完成编辑发布;已有用户值、主动清空值和历史发布快照均不被覆盖;错误请求不会改变表单。
### Phase 5:构建、上传和线上发布闭环
- [ ] 将 build、upload、review、release 状态拆分并建 attempt/lease;
- [ ] 产物路径包含品牌 slug、模板 key、精确版本和 release/attempt id;
- [ ] 生产依赖闭包在干净安装和重启后可用;
- [ ] 构建失败、上传失败、超时、进程退出、重试和恢复有自动化测试;
- [ ] 防止 No projects matched、缺产物、旧产物冒充和并行品牌串产物;
- [ ] 用实际品牌参数构建并保存日志、产物检查和上传结果。
退出门禁:API 不会因为 fire-and-forget 日志或并行重试永久轮询;任何终态都可查询;构建成功不再隐含上传成功;上传结果有真实 weappUploadId 或明确外部失败证据。
### Phase 6:升级、冲突、回滚和恢复
- [ ] 生成旧版本到新版本的字段、模块、资源、能力和 renderer 差异;
- [ ] 升级支持 dry-run、显式确认、冲突逐项处理和用户内容保护;
- [ ] 回滚明确恢复安装配置、发布快照或取消升级计划的语义;
- [ ] 旧版本资源、品牌历史发布和咨询提交持续可读;
- [ ] 模拟数据库、API、worker 和 Admin 重启,验证 job 恢复和幂等。
退出门禁:升级失败可恢复到升级前状态;回滚不会删除用户历史数据;重试和重启不会重复导入或重复写终态。
### Phase 7:规模化模板生产和持续回归
- [ ] 新模板可通过 scaffold、package-discovered conformance 和模板管理页面进入目录;
- [ ] 行业、视觉、能力、renderer 和 toolchain 组合有兼容矩阵;
- [ ] 固定页面角色的视觉基线和真实数据 fixture;
- [ ] CI 在新增模板时自动发现并执行契约、API、构建和必要的视觉检查;
- [ ] 统计导入失败、预览失败、安装冲突、构建失败和上传失败,定期审阅高频问题;
- [ ] 删除或迁移旧注册表、默认行业映射和重复 renderer 分支。
退出门禁:增加一个新模板不需要修改全局 seed 才能被发现,不需要在 Controller 写行业分支,不需要手工改线上数据库才能选择、预览、安装和发布。
## 13. 历史问题到自动化验收的映射
| 已发生问题 | 必须新增的验收 |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| 代码部署了但线上没有品牌数据库内容 | 部署 smoke test 明确代码、migration、seed fixture 和品牌内容;模板样例只通过显式 bootstrap 进入品牌 |
| 线上选择不到新品牌模板 | 目录接口返回版本、行业兼容矩阵和发布状态;Admin 有创建/选择兼容品牌的路径;跨行业组合被明确拒绝 |
| 新模板没有基础数据 | preview fixture 可独立预览;bootstrap 有 dry-run、来源记录和缺失字段测试;不依赖一次性 seed |
| 老品牌没有新字段 | 升级测试验证 missing-only、显式空值保留、冲突和重复执行 |
| 首页/我的页面缺主理人内容 | manifest 的页面区域、renderer 消费、editor binding 和固定 fixture 同时验收;个人页不是由记录数量决定是否出现 |
| 咨询、关于、我的的页面角色混乱 | 导航 manifest、CTA 目标、页面责任和端到端点击路径测试;第三个 tab 的角色由模板声明驱动 |
| 修改 tab 名称但实际页面未梳理 | 导航 label、route、页面标题、CTA 和截图 fixture 一致性测试 |
| Taro、原生、theme、文档多套漂移 | package-discovered renderer/conformance、双端产物检查和唯一默认 renderer 门禁 |
| release 包漏 apps/taro 或模板源码 | release:conformance 在干净安装中检查 workspace、文件清单、构建入口和缺失产物 |
| production 使用 devDependencies 缺 CLI | production install + build + runtime import test,明确依赖分类 |
| 分次安装丢 miniprogram-ci 或 zod | 依赖闭包测试、lockfile 复现、API/回滚路径实际 import |
| No projects matched 但命令退出 0 | 构建命令必须检查 project count 和 app.json,无匹配返回非零并记录诊断 |
| 每行日志并发写导致 P2034、状态永久轮询 | attempt/lease、顺序日志、原子状态迁移、终态收敛、超时和进程重启测试 |
| 使用默认 brand slug 或旧 app.json 冒充成功 | 产物读取 app.json、请求 URL、品牌 slug、模板版本和 release id 的一致性检查 |
| doctor 只按 file/line 机械更新 | issue 采用稳定语义指纹,源代码变化使 review 失效;静态通过仍需真实编辑、保存、重载、发布和视觉证据 |
| 用 mock/API 成功宣称微信上线 | 自动化证据和真实微信开发者工具/真机上传证据分栏记录;没有外部结果就标记未完成 |
## 14. 最终端到端验收
验收在独立环境完成,使用干净 checkout、隔离数据库、隔离对象存储前缀和专用测试品牌。步骤和证据必须按顺序保存:
1. 从干净分支导出一个新模板包,记录 commit、包版本、package schema、runtime contract、renderer、文件清单和 checksum;
2. 重复导出并证明 checksum 相同;修改一个文件后证明 checksum 改变;
3. 将包导入隔离线上环境,确认非法路径、超限文件、symlink、未知 binding 和版本冲突被拒绝;
4. 用有效包完成导入、校验和目录发布,记录 job、validation report 和审计;
5. 选择 personal、food、doors 中至少两个行业分别预览,确认兼容矩阵正确;
6. 确认预览能看到主理人/身份、信任、业务内容、咨询入口和第三个 tab 的完整页面角色;
7. 确认预览不会创建品牌、写入 TrustContent、创建 inquiry form、保存咨询提交或生成 release;
8. 创建兼容测试品牌,安装精确模板版本,记录安装快照;
9. 对 bootstrap 执行 dry-run,确认新增、保留、显式空值和冲突,确认来源包含 key/version/checksum;
10. 编辑一个字段、主动清空一个字段、增加一条业务内容,保存后刷新页面确认值仍在;
11. 发布品牌内容,确认 public workspace 只读发布快照,未发布草稿不会公开;
12. 用真实品牌 slug、模板版本、API 地址和 AppID 构建 H5/weapp,检查产物路径、app.json、请求地址、媒体资源和模板版本;
13. 上传并分别记录 build、upload、review、release 的状态、日志、attempt 和外部返回 id;
14. 同一品牌安装新模板版本,执行差异预览、冲突处理和成功升级;注入失败后重试和重启 worker,确认不会重复导入或永久轮询;
15. 回滚并确认用户数据、历史 release、咨询提交和旧资源仍可读取;
16. 并行对第二个品牌执行构建、上传和发布,确认路径、日志、状态和内容不串品牌;
17. 重复执行导入、bootstrap、升级和重试,确认所有幂等约束成立;
18. 归档 API、Admin、构建、数据库、预览截图和微信外部结果,更新本文进度。
自动化可以覆盖 1 至 12、14 至 17 的大部分行为,但微信开发者工具、真机、审核和线上代码上传结果必须在验收记录中明确标为“真实外部验证”。没有这部分证据时,只能说自动化链路通过,不能说小程序已上线。
## 15. 进度登记模板
每个阶段完成时追加一条记录,不覆盖历史:
日期:
阶段:
实现 commit:
数据库 migration:
接口和页面:
测试命令:
测试结果:
真实环境:
外部证据:
未解决问题:
风险负责人和后续动作:
阶段状态只使用:
- 未开始:尚未实现;
- 进行中:有代码但未通过全部退出门禁;
- 待外部验证:自动化和内部证据通过,仍缺真实微信或线上环境结果;
- 已完成:退出门禁和所需外部证据都已归档;
- 阻断:明确阻断原因、影响阶段和恢复动作。
## 16. 未决决策
以下问题必须在对应阶段开始前作出可审阅决定,不允许用临时默认值带过:
| 问题 | 推荐方向 | 最晚决定阶段 |
| ----------------------------------------------- | ------------------------------------------------------------------- | ------------ |
| 平台模板管理员角色名称和权限来源 | 独立于品牌 owner 的平台级权限,所有操作审计 | Phase 0 |
| artifact 存储 | 版本化对象存储或受控 release 目录,按 checksum/版本寻址 | Phase 2 |
| preview session 存储 | 第一阶段使用短期 token + 服务端受控数据;需要审计时再持久化 session | Phase 3 |
| 视觉安装模型 | 新增清晰的视觉包安装边界,兼容读取旧行业安装 | Phase 4 |
| renderer 分发 | 第一阶段只引用预部署 renderer;任意新 renderer 走独立可信构建方案 | Phase 1 |
| 包签名 | 内网 MVP 先 checksum,跨环境或第三方来源前增加签名和信任根 | Phase 2 |
| 目录可见性 | 未发布版本只给平台管理员,已发布版本才给品牌管理员 | Phase 2 |
| template package version 与 npm package version | 导出前强制一致,若不一致直接阻断 | Phase 1 |
## 17. 可观察性和风险
必须记录并可查询:
- 模板包 key、version、checksum、schema、runtime、renderer 和 capability;
- import/validation/preview/install/bootstrap/upgrade/build/upload/release 的 operationId、attemptId、requestId、actor 和 brand context;
- job 的开始、心跳、重试、lease 过期、终态和外部返回 id;
- 诊断 issue code、稳定语义指纹、文件/manifest 路径和修复建议;
- 预览创建量、预览失败量、安装冲突、bootstrap no-op、构建失败、上传失败和永久轮询告警。
重点风险:
- 如果仍把模板代码作为线上任意上传内容执行,平台会引入供应链和租户隔离风险;
- 如果行业安装和视觉安装继续共用不清晰的字段,升级和回滚会误改品牌;
- 如果 sample 和 bootstrap 不分离,预览数据会污染品牌内容或产生虚假公开背书;
- 如果 renderer、runtime、toolchain 版本没有分别记录,新模板会在部署后才暴露兼容问题;
- 如果只测试 happy path,依赖丢失、进程重启和并行构建仍会回到永久轮询;
- 如果视觉验收继续依赖静态源码匹配,首页、关于/我的、咨询和 CTA 的逻辑问题仍会漏掉。
风险的接受条件是有明确 owner、触发指标和恢复动作;“暂时没复现”不能作为关闭依据。
## 18. 相关文档
- [ADR 0029:模板管理、导入与分发边界](adr/0029-template-management-and-distribution.md)
- [模板注册表](template-registry.md)
- [模板运行时实施进度](template-runtime-progress.md)
- [模板完成度规则](template-completion-rules.md)
- [模板数据流](template-data-flow.md)
- [工程交付清单](engineering-delivery-checklist.md)
- [ADR 0008:视觉模板包契约](adr/0008-visual-template-package-contract.md)
- [ADR 0019:Taro 模板双端运行时](adr/0019-taro-template-runtime.md)
- [ADR 0022:模板完成度诊断](adr/0022-template-completion-diagnostics.md)
- [ADR 0028:按当前视觉模板显式导入示例](adr/0028-template-selected-sample-import.md)
+26 -13
View File
@@ -1,26 +1,39 @@
# 模板注册表
模板采用“行业模板 + 视觉模板”组合,不再为每个行业复制一套小程序代码。
本文只记录当前盘点和迁移状态,不是模板目录的第二份事实来源。模板管理、导入、校验、预览、安装、升级和验收统一由[模板管理与分发交付计划](template-management-delivery-plan.md)统筹;可复用的架构边界见 [ADR 0029](adr/0029-template-management-and-distribution.md)。
## 当前注册
模板采用“行业模板 + 视觉模板包 + Capability”组合,不为每个行业复制一套小程序代码。最终目录必须由可校验 package manifest 发现,手工修改本文不能让模板在线可用。
## 当前盘点
### 行业模板
- `personal@1.0.0`:个人品牌基线。
- `food@1.0.0`:餐饮业务表达示例。
- personal@1.0.0:个人品牌基线。
- food@1.0.0:餐饮业务表达示例。
- doors@1.0.0:门窗业务表达示例。
### 视觉模板
### 仓库内视觉模板包
- `linjing-editorial@1.0.0`:林境建筑画册,适合高端定制和项目型业务。
- 当前正式视觉模板包:`linjing-editorial@1.0.0`。个人、餐饮和门窗属于行业数据模板,不是独立视觉模板。
- acheng-campus-food@1.0.0:餐饮场景,使用 food 行业能力。
- linjing-editorial@1.0.0:林境建筑画册,可用于 doors 和 personal 组合。
- atelier-solopreneur:template.json 声明为 1.1.0,但 package.json 仍为 1.0.0;在版本事实收敛前不得作为可导入线上版本。
以上是仓库盘点,不表示三个包都已经通过线上导入、预览、品牌安装和微信上传验收。生成目录当前位于 packages/config/src/generated-template-packages.ts,后续必须由导出和 conformance 流程生成并校验。
## 组合规则
行业模板决定字段、Offering schema、表单用途和能力依赖;视觉模板决定模块变体、主题 token 和页面表达。安装结果必须保存行业模板和视觉模板的版本快照,后续升级只能显式执行并提供差异预览。
行业模板决定字段、Offering schema、表单用途和能力依赖;视觉模板包决定页面模块、变体、theme token、资源槽位、数据槽位和 Admin binding;Capability 决定可复用业务能力。安装结果必须保存行业和视觉包的精确版本、checksum 与配置快照,升级只能显式执行并提供差异预览。
## 后续
预览使用包内 previewFixture,不写入品牌。起始内容使用显式 bootstrap import,来源记录必须包含 package key、版本和 checksum。模板包的样例内容不能成为 Prisma seed 中的全局品牌内容。
1. Prisma 增加视觉模板安装快照字段;
2. Admin 模板中心展示行业 / 视觉模板组合预览;
3. Runtime Workspace 合并两类模板的模块和主题;
4. 为每个组合生成 fixture 和视觉回归基线。
## 当前缺口
- [ ] 版本导出、线上导入、checksum 幂等和目录发布尚未形成统一闭环;
- [ ] 独立模板管理页面尚未覆盖导入、校验、预览、发布和审计全流程;
- [ ] 行业安装和视觉包安装的持久化边界需要迁移设计;
- [ ] 预览 fixture 和可导入 bootstrap 内容需要明确分离;
- [ ] Taro renderer、Runtime contract、package schema 和 toolchain 的兼容矩阵需要落库;
- [ ] atelier-solopreneur 的 manifest/package metadata 版本漂移需要先修复;
- [ ] 每个模板仍需完成真实品牌编辑、保存重载、发布、双端构建和真实微信外部验收。
新增模板时先修改模板包和契约测试,再更新生成产物;不要直接在本文追加一条“已注册”来绕过门禁。
+14 -2
View File
@@ -1,6 +1,12 @@
# 模板运行时实施进度
关联决策:`docs/adr/0005-template-runtime-and-stitch-pipeline.md`
关联决策:docs/adr/0005-template-runtime-and-stitch-pipeline.md
统一任务入口:[模板管理与分发交付计划](template-management-delivery-plan.md)
模板管理边界:[ADR 0029](adr/0029-template-management-and-distribution.md)
> 状态校正(2026-10-16):本文中标记为 [x] 的条目只表示对应的局部代码或接口曾经落地,不代表已经通过模板包导出、线上导入、独立预览、品牌安装、升级回滚和微信上传的完整门禁。Phase 3 的“模板中心、安装快照、升级和回滚”整体仍未完成,后续进度以统一任务入口的阶段和证据为准。
## 当前分支
@@ -49,7 +55,7 @@
- [x] 建立 `Records`、`Profile`、`SuccessSummary` 用户链路模块骨架。
- [x] 建立林境门作模板 fixture 和标准模块 / 页面完整性检查。
- [x] 建立固定页面状态、视口和视觉锚点清单,可供后续截图回归执行。
- [ ] Phase 3:模板中心、安装快照、升级和回滚。
- [ ] Phase 3:模板中心、安装快照、升级和回滚,统一由 [TMP-PLATFORM-001](template-management-delivery-plan.md) 的 Phase 2 至 Phase 6 继续实施。
- [x] 建立行业模板与视觉模板注册表,并注册林境建筑画册与极简留白视觉模板。
- [x] Runtime Workspace 合并品牌配置中的视觉模板主题、版本和模块变体。
- [x] Admin 工作空间支持切换视觉模板并保存 `visualTemplateKey`。
@@ -90,6 +96,12 @@
在 Phase 1 的 API 契约、测试和客户端消费完成前,不新增第二个行业页面,也不继续扩展行业专属固定 WXML。当前 API 契约已建立,下一步优先补测试和客户端消费。
当前交付门槛还包括:模板版本事实一致、导出 checksum 稳定、线上导入幂等、未发布版本不可安装、预览不写入品牌、bootstrap 来源可追踪,以及构建/上传/发布状态能够在失败和重启后收敛。局部 Runtime Workspace 或模板目录接口通过,不能单独标记本任务完成。
## 统一任务进度
详见 [模板管理与分发交付计划](template-management-delivery-plan.md)。完成阶段时必须登记实现 commit、migration、测试命令、运行环境、外部证据和未解决问题;不要只修改本页的 checkbox。
## 当前边界说明
能力插件目前由模板注册表声明并以 `enabled` 状态输出,尚未提供品牌级启用 / 停用写入。下一步必须先增加独立的 `CapabilityInstallation` 持久化模型、权限校验、审计记录和 Runtime Workspace 合并规则,再开放 Admin 操作;不得将插件状态临时写入 `BrandProfile.config`。