Files
persionalBrand/docs/adr/0029-template-management-and-distribution.md
T

10 KiB
Raw Blame History

0029 模板管理、导入与分发边界

背景

平台已经有行业模板、视觉模板包、Runtime Workspace、样例导入和 Taro 构建的部分实现,但这些能力还没有形成从本地模板包到线上安装和小程序发布的统一生命周期。之前出现过以下类型的故障:

  • 新模板代码在本地分支存在,但线上没有对应数据库内容或可选择的品牌;
  • 模板 manifest、package metadata、生成注册表和部署包的版本可能不一致;
  • 模板预览、品牌草稿、发布快照和微信代码上传被当成同一个状态;
  • sample 只在一次性 seed 或脚本中出现,无法支持独立预览、显式导入和后续升级;
  • 构建包缺少 apps/taro 或 production dependency,上传阶段才发现 miniprogram-ci 不可用;
  • 构建任务日志并发写入导致状态回退、永久轮询和重启后无法恢复;
  • 静态 doctor 或 mock 成功被误认为真实模板交付完成。

如果继续按单模板修补,模板数量增加后会重复出现版本漂移、权限遗漏、数据污染、构建串品牌和失败不可恢复的问题。需要一个单独的模板管理页面、可验证的包契约、明确的安装边界和可复验的端到端门禁。

决策

1. 以模板管理交付计划作为唯一任务入口

使用模板管理与分发交付计划统筹目标、阶段、证据、风险和进度。运行时进度、模板注册表和后续实现文档必须链接到该入口,不能各自维护一套互相冲突的完成状态。

这是一项目标架构决策,尚未表示代码已经实现。

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:视觉模板包契约:将 manifest、资源、样例和安装扩展到线上导入、checksum 和目录生命周期;
  • 补充 ADR 0019:Taro 模板双端运行时:明确线上模板包第一阶段引用受信 renderer,任意新 renderer 另行建设隔离构建;
  • 补充 ADR 0022:模板完成度诊断:把稳定 issue identity、真实编辑重载发布和视觉证据纳入模板目录门禁;
  • 补充 ADR 0028:按当前视觉模板显式导入示例:将 sample preview、bootstrap import、来源和升级规则统一到模板管理生命周期;
  • 取代旧注册表中“手工列出所有可用模板即可完成注册”的隐含假设;docs/template-registry.md 只保留当前盘点和迁移入口;
  • 不删除或否定 ADR 0010:模板示例内容注册表 的历史背景,但其中与“全局注册表或 seed 作为模板事实来源”冲突的部分以本 ADR 和模板数据流规则为准。

Phase 3 实现补充(2026-10-16)

独立演示内容使用 previewFixture.<industry>,与既有 sampleContent(品牌起始内容)分别维护。契约校验复用 packages/validation 的 Zod;导出和线上导入共用规则。旧包兼容使用 sample 时必须给出显式诊断;声明 fixture 后缺失或无效则阻断,不能静默回退。

第一步包内预览图片采用受权限保护的预览响应内嵌 data URL,与版本 checksum 和 Runtime 同时交付。服务核对已导入 archive、内容及逐图片摘要,只接受 raster 格式,不执行或公开解压包内代码。限制为单图 2 MiB、总计 8 MiB、128 张;超限或外链返回诊断。该方案优先保证精确版本和权限隔离,代价是响应体积与重复读取;后续可迁移为同 checksum 的短期资源 URL/CDN,不改变模板内容契约。它不替代尚未完成的 sandbox/origin/CSP 门禁。