45 KiB
模板管理与分发交付计划
任务 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 发现,生成注册表只作为构建产物 | 包发现测试、目录接口测试、无手工重复定义 |
| 版本 | 当前模板包 metadata 已与 manifest 对齐,导入 checksum 闭环尚未实现 | 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 和 package metadata 已统一为 1.1.0 | 包内版本字段和导出元数据在导出前强一致 | validate:templates 的版本一致性检查 |
当前存在的 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 | 某次品牌发布时冻结的全部运行时定义和品牌内容 | 不随着模板目录更新而隐式变化 |
平台要维护两种唯一性:
- 模板包的事实唯一性由包 manifest 和 checksum 决定;
- 品牌公开内容的事实唯一性由品牌数据库草稿和发布快照决定。
模板包不能成为品牌运行时的隐式 fallback。模板 renderer 读取的品牌事实必须来自 Runtime contract;缺失内容要显示空态、降级或阻止发布,不能自动填充未经管理员确认的假身份、经验、背书或接单状态。
5. 用户流程和页面职责
5.1 平台模板管理员流程
- 在本地开发模板包,运行 schema、编辑绑定、资源、renderer 和构建检查;
- 导出确定性包,生成 manifest 摘要、文件清单和 checksum;
- 在 /admin/templates 导入包,看到导入进度、大小、文件数量和失败原因;
- 打开版本详情,查看兼容行业、runtime contract、renderer、能力、页面区域、编辑绑定、sample 和阻断诊断;
- 为某个行业启动独立预览,预览只消费包内演示数据,不写入品牌数据库;
- 通过所有门禁后发布到模板目录;未发布版本只对平台模板管理员可见;
- 发布后仍保留版本和资源,撤回只影响可选目录,不删除已安装品牌和历史发布快照;
- 查看导入、校验、预览、发布和撤回审计。
5.2 品牌管理员流程
- 在品牌工作台选择已发布且和当前行业兼容的模板版本;
- 查看安装前差异、能力依赖和是否已有品牌内容;
- 安装精确版本,记录安装快照;
- 独立点击“导入起始内容”,先查看 dry-run 的新增、保留和冲突;
- 编辑模板声明的字段,保存后刷新页面验证重载;
- 通过结构完整性校验后发布品牌内容;
- 使用真实品牌 slug、模板 key、版本和 API 地址构建小程序;
- 上传、审核、上线状态单独展示,失败可以重试同一 attempt 或创建新 attempt;
- 新版本升级前查看差异,发生冲突时逐项处理;回滚时明确恢复配置基线还是撤销尚未采用的新内容。
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 版本维度
以下版本必须分开记录:
- 模板包业务版本,例如 atelier-solopreneur@1.1.0;
- package schema version,表示包格式;
- Runtime contract version,表示数据投影契约;
- renderer version,表示预部署的 Taro renderer;
- capability version,表示能力 API 和配置;
- toolchain version,表示 Taro、React、Node 和构建依赖;
- brand release version,表示某品牌的一次发布;
- 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 当前主要承担行业模板安装记录,不能直接把它改成视觉包版本记录并破坏旧快照。实施前先盘点其查询、发布快照和旧回滚行为;优先新增边界清晰的模型或新增可为空字段,完成兼容读取后再考虑收敛。
数据库迁移必须遵循以下顺序:
- 备份并记录当前 schema、模板安装、品牌配置和发布快照数量;
- 先增加可为空的新字段或新表,不改变旧读路径;
- 回填只写可从旧数据确定推导出的值,不能猜测版本、checksum 或样例来源;
- 双读对比旧路径和新路径,记录不一致;
- 切换写入,再保留旧读兼容窗口;
- 清理旧字段前提供备份、回滚脚本和历史快照验证;
- 重复执行迁移和导入不得生成重复安装、重复 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 或未经校验的接口承载请求体。错误使用稳定 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,并按模板完成度规则使用真实 manifest、真实保存重载发布链路和视觉证据验收。doctor issue 使用稳定语义指纹;源代码语义改变后必须重新审查,不能通过批量行号更新伪造通过。
Taro 交付必须额外验证:
- apps/taro/dist//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:任务固化和现状盘点
- 建立本文档和 ADR 0029,并将其设为唯一任务入口;
- 盘点所有模板包的 manifest/package metadata、renderer、fixture、资源和版本差异;
- 盘点现有行业安装、视觉选择、发布快照和 Admin 页面调用关系,见 Phase 0 现状盘点;
- 为历史事故建立可执行回归清单,见 Phase 0 现状盘点;
- 解决 atelier-solopreneur manifest/package metadata 版本漂移;
- 明确平台模板管理员角色缺口和线上隔离边界,见 Phase 0 现状盘点 与 Phase 0 现状盘点;
退出门禁:模板目录、版本事实、现有数据模型和已知失败路径有可审阅清单;没有“默认值能猜出来”的隐含项。
Phase 0 执行记录(2026-10-16):
- 已将三个仓库模板的 package metadata 与 manifest 对照,并修复 atelier-solopreneur 的 1.0.0/1.1.0 漂移;
- validate:templates 新增 package name 和 version 一致性阻断;
- template-doctor 生成 after 报告:三个模板 staticStatus 均为 pass,completionStatus 保持 unverified,112 个 review 均有登记;
- template:check、template-doctor 测试和 typecheck 通过;完整证据保存在本次工作区的 Phase 0 运行记录中;
- 行业安装、视觉选择、发布快照和 Admin 调用链已完成盘点,证据见
docs/template-management-phase0-inventory.md; - 已确认平台模板管理员不能复用品牌 membership 字符串,线上模板 artifact、版本目录和小程序构建 attempt 仍需后续阶段实现;
Phase 1:包契约和确定性导出
- 扩展 packages/template-contract,定义 package schema、rendererRef、preview/bootstrap、资源和兼容矩阵;
- 实现
template:pack,生成稳定清单和 checksum;当前覆盖 3 个仓库模板,测试重复导出目录和 archive 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、隔离数据库、隔离对象存储前缀和专用测试品牌。步骤和证据必须按顺序保存:
- 从干净分支导出一个新模板包,记录 commit、包版本、package schema、runtime contract、renderer、文件清单和 checksum;
- 重复导出并证明 checksum 相同;修改一个文件后证明 checksum 改变;
- 将包导入隔离线上环境,确认非法路径、超限文件、symlink、未知 binding 和版本冲突被拒绝;
- 用有效包完成导入、校验和目录发布,记录 job、validation report 和审计;
- 选择 personal、food、doors 中至少两个行业分别预览,确认兼容矩阵正确;
- 确认预览能看到主理人/身份、信任、业务内容、咨询入口和第三个 tab 的完整页面角色;
- 确认预览不会创建品牌、写入 TrustContent、创建 inquiry form、保存咨询提交或生成 release;
- 创建兼容测试品牌,安装精确模板版本,记录安装快照;
- 对 bootstrap 执行 dry-run,确认新增、保留、显式空值和冲突,确认来源包含 key/version/checksum;
- 编辑一个字段、主动清空一个字段、增加一条业务内容,保存后刷新页面确认值仍在;
- 发布品牌内容,确认 public workspace 只读发布快照,未发布草稿不会公开;
- 用真实品牌 slug、模板版本、API 地址和 AppID 构建 H5/weapp,检查产物路径、app.json、请求地址、媒体资源和模板版本;
- 上传并分别记录 build、upload、review、release 的状态、日志、attempt 和外部返回 id;
- 同一品牌安装新模板版本,执行差异预览、冲突处理和成功升级;注入失败后重试和重启 worker,确认不会重复导入或永久轮询;
- 回滚并确认用户数据、历史 release、咨询提交和旧资源仍可读取;
- 并行对第二个品牌执行构建、上传和发布,确认路径、日志、状态和内容不串品牌;
- 重复执行导入、bootstrap、升级和重试,确认所有幂等约束成立;
- 归档 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、触发指标和恢复动作;“暂时没复现”不能作为关闭依据。