Files
persionalBrand/docs/template-management-delivery-plan.md
T

53 KiB
Raw Blame History

模板管理与分发交付计划

任务 ID:TMP-PLATFORM-001

状态:实施中,Phase 0/1/2 已完成,Phase 3 已接入版本预览、独立 fixture、包内图片校验和短期隔离 session;origin/CSP、CTA 导航、完整矩阵与最终视觉验收待完成

唯一任务入口:本文档

架构决策: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 某次品牌发布时冻结的全部运行时定义和品牌内容 不随着模板目录更新而隐式变化

平台要维护两种唯一性:

  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 或未经校验的接口承载请求体。错误使用稳定 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,自动发现模板并串联真实 compiler、doctor 和产物契约;
  • 为每个当前模板补齐真实 manifest、可见字段、编辑绑定、空态和 fixture;
  • 把版本漂移、缺资源、未知 binding、未消费字段和不兼容 renderer 变成阻断 issue;
  • 记录旧原生 miniapp 和 Taro 目录的迁移边界。

退出门禁:干净 checkout 中所有模板包可被发现、导出、校验;相同输入 checksum 稳定;不执行包脚本;每个页面的可见品牌事实都有 renderer 和 editor 证据。

Phase 2:线上导入、校验和模板目录

  • 增加 TemplatePackage、TemplatePackageVersion、生命周期审计和 artifact 引用;
  • 实现临时存储、安全检查、checksum 幂等和冲突拒绝;
  • 完成 manifest、runtime、renderer、industry、capability、资源和 fixture 诊断;
  • 实现目录发布、撤回、分页、审计和旧资源保留;
  • 增加独立平台模板权限;
  • API、DTO、shared client 和 integration test 一起交付。

退出门禁:非法包不会进入可用目录;重复导入不重复建版本;同版本不同 checksum 明确失败;未发布版本不能被品牌管理员安装。

Phase 2 当前进度(2026-10-16):

  • 已增加 TemplatePackage、TemplatePackageVersion、版本状态和 AdminUser.platformTemplateRole,artifact 路径独立于 release 目录;
  • 已实现平台模板管理员 guard、GET /admin/templates 和 POST /admin/templates/import;普通品牌管理员和 customer 均不能访问;
  • 已实现临时文件导入、archive 路径/链接/重复项检查、文件数和解压体积限制、manifest/package metadata/checksum 校验、幂等和版本冲突拒绝;不执行包内脚本;
  • 已同步 shared client 和 Admin /admin/templates 的导入、版本列表、loading/empty/error/retry/success 状态;
  • 已通过 51/51 API HTTP integration tests 和 2/2 upload tests;
  • 已补充 imported -> published -> retired 生命周期、重复操作幂等、状态竞争保护、分页、审计查询和 Admin 页面发布/撤回/审计操作;
  • 已将模板包和版本及审计写入同一数据库事务,数据库失败时清理已落盘 artifact,避免留下半版本;
  • 已通过 51/51 API HTTP integration tests、2/2 upload tests 和 6/6 API client tests;
  • 尚未完成:独立 validation run / renderer / capability / fixture 诊断、独立 preview session、品牌精确版本安装;因此 Phase 2 目录基础闭环已完成,完整任务继续进入 Phase 3/4。

Phase 3:独立预览和模板管理页面

  • 增加 preview session 或同等短期隔离上下文;
  • 按行业选择兼容组合,使用 preview fixture 通过真实 Runtime projection 渲染;
  • 页面展示模块顺序、字段来源、资源缺失、能力依赖和诊断;
  • 预览禁止真实咨询、客户记录、品牌发布和上传;
  • /admin/templates 完成导入、详情、校验、预览、发布、撤回和审计交互;
  • 覆盖 loading、empty、error、retry、success 和权限失败状态。

退出门禁:预览不创建品牌和业务数据;不同版本、行业和资源组合不会串数据;页面失败时保留上传和选择上下文;真实 Runtime 和预览数据映射有测试。

Phase 3 初版实现(提交 6edde5a,2026-10-16):

  • 增加 GET /admin/templates/:id/preview?industry=<key>,只允许平台模板管理员;DTO 校验查询,服务读取数据库版本的 manifestSnapshot.sampleContent,不读取当前品牌内容,不创建品牌或业务记录。
  • imported 和 published 可预览;retired 和其他不可用状态返回 409。不存在的版本、非法行业组合、Runtime/renderer/capability/sample 校验失败返回 400,沿用统一错误 envelope。
  • 使用 assemblePublicWorkspace 投影演示快照,Client 和 Admin 同步接入;模板管理页按行业选择,并可查看首页、我的、业务详情和咨询等内页,失败保留选择并支持重试。
  • 当前 renderer 兼容策略保守地要求部署 registry 的 package key、visual key 和版本一致;这只是第一步兼容门禁,尚未引入独立 renderer version/hash。API 不执行导入包源码,Admin 只挂载已部署 renderer。
  • 当前预览为请求内存上下文,模拟 ID 使用 template-preview: 前缀,咨询组件使用 preview 模式并禁用提交;客户记录组件沿用不读取客户 API 的预览模式。
  • 自动化:API 集成测试覆盖缺少/无效凭证、普通品牌管理员和 customer 拒绝、真实 atelier 包预览、行业不兼容、无 renderer、无 capability、缺 sample、撤回状态及全局业务表计数不变。浏览器交互使用真实 manifest 和同一生产投影生成 fixture,HTTP mock 仅证明页面交互,不代替 API 授权/数据库证据。
  • 预览入口增加嵌套声明结构门禁;集成测试覆盖 dataSlots、navigation、templateFields、trustContentTypes 和 Admin section 的畸形输入,返回可操作的 400 错误。
  • 本轮验证:API HTTP integration 52/52、upload 2/2、API unit 49/49、Client 6/6、Admin unit 6/6、Playwright 预览交互 1/1;全仓 typecheck、Admin production build、变更范围 lint、format、template:check 通过。template:doctor 未解决项为 0,模板完成度仍为 unverified。Playwright 运行前需构建 API/config 并启动 Admin:ADMIN_PORT=3016 pnpm --filter @personal-brand/admin dev,随后在 apps/taro 运行 pnpm exec playwright test test/browser/template-management.spec.ts。
  • 咨询按钮改动另行完成 atelier 的 weapp 和 h5 构建,参数为 TEMPLATE_KEY=atelier-solopreneur API_BASE_URL=https://wechat.app.que01.top/api WEAPP_APP_ID=wxd75d946d6978d183 pnpm --filter @personal-brand/taro build:<weapp|h5>;产物包含对应 AppID/API 地址并通过 masking 检查。本轮不作为微信真机视觉验收。
  • 初版剩余项(以下续进展为准):独立 previewFixture 与 bootstrap sample 的拆分、包内完整身份和媒体 fixture、按 checksum 提供导入资源、逐资源缺失诊断、画布内 CTA 导航、预览审计、短期 session/origin/CSP 隔离、跨模板/行业/版本矩阵及最终视觉验收。因此以上阶段清单仍保留未完成状态。

Phase 3 独立 fixture 与资源进展(2026-10-16):

  • 新增 previewFixture.<industry>:schemaVersion: "1"、身份白名单 brand、独立 content 和固定禁用策略 safety;使用 packages/validation 的同一 Zod 规则校验本地包和线上导入,不引入新校验体系。声明 fixture 的包必须覆盖全部兼容行业;无效声明不能回退到 sampleContent。
  • atelier 升为 1.2.0,保持旧版本不可变;预览主理人和品牌身份单独声明,sampleContent 仍只用于品牌起始内容,不修改 seed 或自动安装到现有品牌。尚未迁移的旧包走明确标注的兼容路径。
  • 管理页展示当前页面的 Admin 模块声明顺序、字段 binding、资源配置数量和缺失状态。这是声明诊断,不代表已经验证 renderer 的实际视觉顺序或全部字段消费。
  • 预览读取已导入 archive,核对 archive/content checksum 及逐图片 SHA-256,校验实际图片格式后以内嵌 data URL 提供给画布;不执行源码、不解压到公共目录、不回退到当前部署的同名图片。每图最多 2 MiB、总图片最多 8 MiB、最多 128 张,超出限额返回明确诊断;外链图片仍为待验证。
  • 同一预览响应同时包含版本 checksum、Runtime 和图片映射,切换版本/行业不会复用另一份图片;当前实现尚不包含可公开访问的资源 URL、远程资源探测或 CDN 缓存。
  • 本轮不涉及编辑 binding 或 renderer 布局变更;真实品牌编辑/保存/发布闭环及微信视觉验收仍按模板完成度规则独立验收。
  • 预览成功会写平台模板审计:操作者、版本 checksum、行业、fixture 来源及 requestId;不记录演示内容、不创建业务数据,关闭预览后刷新审计缓存。
  • 自动化新增独立 fixture 与 bootstrap 解耦、无效安全策略导入拒绝、敏感身份字段拒绝、兼容来源标识、archive 漂移阻断及图片类型/体积/摘要故障回归。API HTTP integration 52/52、upload 2/2、API unit 51/51、Client/Admin unit 各 6/6、真实包图片浏览器交互 1/1 通过;typecheck、Admin production build、变更范围 lint 和 template:check 通过。
  • 仍待推进:预览上下文与 origin/CSP 隔离、画布内 CTA 导航、跨模板/行业/版本完整矩阵和最终视觉验收。前述初版实现记录中的 fixture 与包内资源缺口由本段更新,其余阶段门禁不变。

Phase 3 短期隔离 session 进展(2026-10-16):

  • 预览响应新增 preview.session;首次预览生成 64 位十六进制短期 token,有效期 15 分钟。GET /admin/templates/:id/preview 支持 session 查询参数,DTO 仅接受预期格式。
  • 服务端 session 只在 API 进程内存中保存已构建投影,上限 20 个并主动清理过期项;每次复用必须匹配同一平台模板管理员、版本 ID 和行业。因此 token 不是跨管理员可重放凭据,不同版本/行业/管理员不会串数据。
  • 带 session 的成功复用不重复读取 archive,也不重复写 previewed 审计;不存在、过期或绑定不匹配返回可操作的 400,管理员可重新创建预览。
  • Admin 预览按版本和行业保留短期 token 供失败重试复用;请求失败时删除对应 token,行业/版本选择和业务记录选择仍保留。
  • 自动化覆盖 session 成功复用、复用不新增审计、跨管理员拒绝、未知 token 拒绝、版本/行业绑定、shared client URL 和 Admin 重试上下文。本轮 API HTTP integration 52/52、upload 2/2、Client 6/6、Admin unit 3/3 和全仓 typecheck 通过;origin/CSP 隔离与最终矩阵验收仍待完成。

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. 相关文档