19 KiB
模板管理 Phase 0 现状盘点
任务:TMP-PLATFORM-001
日期:2026-10-16
本文是 模板管理与分发交付计划 的现状证据,不是新的模板注册表。本文记录的是当前代码真实行为;目标模型仍以 ADR 0029 和主计划为准。
1. 结论摘要
当前系统已经有“行业模板 + 视觉模板包 + Runtime Workspace + 品牌发布快照”的局部能力,但还不是模板管理与分发系统。主要结论如下:
- 模板目录的事实来源仍是部署时编译进
packages/config的仓库文件,不是线上可管理的版本目录。 BrandTemplateInstallation当前只可靠表达一个品牌的行业模板安装台账;视觉模板选择实际写在BrandProfile.config.visualTemplateKey,两者没有独立的视觉安装快照。- 预览、sample 导入和品牌发布已经有不同接口,但预览目录仍直接读取运行时注册表,不能按导入版本、checksum 和发布状态隔离。
- 发布快照会冻结行业定义、视觉定义、manifest、安装记录和品牌数据;旧发布不会随当前注册表更新而自动改变,这是现有链路中最稳定的边界。
- 后台登录身份只有
admin会话角色,品牌成员角色在BrandMembership.role中表达。现有platform-admin只是可写入的字符串值,不是独立的平台模板管理员身份,也没有独立的权限作用域或审计主体。 - Release 目录、生产数据库、媒体目录和微信上传产物已经有部分隔离,但模板目录没有独立的 artifact/version 存储;小程序构建仍由 API 进程在当前 release 工作目录执行。
因此下一阶段不能直接把现有行业安装表改名为模板版本表,也不能只新增一个 /admin/templates 页面。应先新增平台模板目录模型和独立权限边界,再通过兼容读取逐步接入品牌安装与视觉安装。
2. 当前事实来源
| 事实 | 当前来源 | 当前读取方式 | 主要风险 |
|---|---|---|---|
| 行业模板定义 | packages/config/src/brand-templates.ts |
getBrandTemplate()、brandTemplateKeys |
只能随代码部署变更,线上不能导入或撤回单个版本 |
| 视觉模板定义 | packages/config/src/visual-templates.ts |
getVisualTemplate()、visualTemplateKeys |
视觉 key 和版本存在于代码,未形成线上目录版本 |
| 视觉页面、字段、资源契约 | packages/*/template.json,经 scripts/generate-template-catalog.cjs 生成 packages/config/src/generated-template-packages.ts |
templatePackageRegistry、getTemplatePackageManifestForVisualKey() |
生成注册表是构建产物,不是数据库事实;线上无法独立审计导入包 |
| 品牌当前行业 | BrandProfile.templateKey |
TemplateWorkspaceService.getEffectiveTemplateKey()、发布快照构建 |
与安装台账重复表达,历史数据可能出现缺失台账 |
| 品牌当前视觉 | BrandProfile.config.visualTemplateKey |
AdminBrandConfigService、buildBrandReleaseSnapshot() |
没有独立版本、checksum 和视觉安装状态 |
| 品牌字段定义 | BrandFieldDefinition |
行业安装、升级、工作台查询 | 只描述表单字段,不完整描述 renderer 消费和包来源 |
| 示例内容 | packages/config/src/template-sample-content.ts 和 manifest sample/bootstrap 相关声明 |
Admin sample preview/import | 仍需把 preview fixture 与 bootstrap 来源、版本和 checksum 分开持久化 |
| 品牌公开数据 | BrandProfile 及 Offering、TrustContent、InquiryForm 等品牌表 |
buildBrandReleaseSnapshot() |
草稿和发布快照已分离,但模板版本来源仍是代码注册表 |
模板包本身不是 Prisma seed 的模板目录。apps/api/prisma/seed.ts 可以保留少量开发品牌 fixture,但不能通过增加 seed block 注册生产模板或替代模板导入。
3. 行业安装与视觉选择调用链
3.1 行业模板安装
当前写入路径:
- Admin 调用
POST /admin/workspace/install。 AdminWorkspacePreviewController通过requireAdminIdentity()获取 token 中的brandId。TemplateWorkspaceService.install()从getBrandTemplate(templateKey)读取行业定义,并从代码注册表解析兼容的默认或已选视觉模板。- 一个事务同时更新
BrandProfile.templateKey、必要时合并config.visualTemplateKey、创建BrandTemplateInstallation和BrandFieldDefinition。 BrandTemplateInstallation.configSnapshot保存当时的行业定义、视觉 manifest、能力声明和schemaVersion。
当前读取路径:
- 工作台通过
AdminWorkspaceService返回品牌、安装记录、字段、模板内容和视觉模板; - 模板预览通过
TemplateWorkspaceService.preview()读取品牌当前行业、安装版本和字段缺失情况; - 升级和回滚通过
BrandTemplateInstallation.templateVersion、configSnapshot、previousSnapshots工作; - 发布 readiness 通过安装记录或
BrandProfile.templateKey找行业定义,并从代码注册表找视觉 manifest; - 发布快照通过
buildBrandReleaseSnapshot()再次读取当前数据库和代码注册表内容。
当前约束:
- 一个品牌只能有一个当前行业模板;切换行业模板会被拒绝;
- 安装记录的唯一约束是
[brandId, templateKey],没有 package checksum,也没有独立的视觉安装记录; - 当品牌已有视觉选择但缺少安装台账时,安装会保留
visualTemplateKey,但不会把视觉版本作为独立安装事实持久化; previousSnapshots是 JSON 历史数组,不是可查询、可审计、可并发控制的升级记录;- 旧品牌可以依赖
BrandProfile.templateKey运行,即使没有BrandTemplateInstallation,这也是当前兼容读取必须保留的行为。
3.2 视觉模板选择
当前写入路径:
- Admin 的品牌配置接口
PATCH /admin/config/brand接收config.visualTemplateKey。 - Controller 通过
AdminAccessService.requireRole()限制为owner、admin或字符串角色platform-admin。 AdminBrandConfigService校验视觉模板存在、和当前行业兼容,并把新配置与旧 JSON 合并;视觉历史另存为品牌配置历史快照。
当前读取路径:
- Admin 品牌页和发布页从
BrandProfile.config.visualTemplateKey决定选择状态; - 公开模板目录
GET /public/templates直接返回代码注册表中的行业和视觉定义; - 公开组合预览
GET /public/templates/preview只校验代码注册表中的兼容性和 theme,不创建预览 session,也不使用模板包导入的 fixture; - Runtime Workspace 和发布 readiness 通过当前视觉 key 查代码中的视觉定义和 manifest;
- 发布快照保存
visualTemplateDefinition、visualTemplateManifest和templatePackageManifest,供公开端冻结读取。
因此当前“视觉选择”是品牌配置变更,不是“安装一个精确版本的视觉模板包”。后续必须新增视觉安装边界,但要兼容读取旧的 config.visualTemplateKey。
4. 示例内容、预览和品牌数据边界
当前已经存在以下不同操作,但持久化边界仍不完整:
| 操作 | 当前接口/服务 | 是否写品牌数据 | 当前版本来源 |
|---|---|---|---|
| 公开行业/视觉组合预览 | GET /public/templates/preview |
否 | 代码注册表 |
| Admin 品牌工作台预览 | GET /admin/workspace/preview |
否 | 当前品牌草稿和代码 manifest |
| Admin sample dry-run | GET /admin/workspace/sample-content/preview |
否 | 当前行业/视觉的 sample |
| Admin sample 导入 | POST /admin/workspace/sample-content/import |
是 | 当前代码注册表,部分操作有幂等保护 |
| 品牌内容发布 | POST /admin/releases |
是发布快照 | 当前数据库 + 代码定义 |
必须保留的规则:
- 预览不能创建品牌、Offering、TrustContent、InquiryForm、咨询提交或 BrandRelease;
- sample 导入必须是管理员显式操作,不能由模板安装隐式触发;
- bootstrap 导入结果需要记录 package key、版本、checksum、来源路径、稳定 key、目标记录和策略;
- 品牌数据库里的 sample 一旦导入就是品牌数据,不能再被模板目录自动覆盖;
- 发布快照一旦创建,必须继续使用快照中的模板定义和数据,不应随代码注册表更新而改变。
当前缺口是:预览没有独立的 package version/session,sample 导入也没有完整的 package checksum 来源台账;模板代码部署后,线上无法判断某次品牌发布使用的是哪一个可重现的模板 artifact。
5. 发布快照冻结点
BrandReleaseApiService.publish() 在 Serializable transaction 中执行 readiness 校验、读取最新 release version、将旧发布标为 superseded,然后创建新的 BrandRelease。BrandRelease.snapshot 由 buildBrandReleaseSnapshot() 生成,包含:
templateKey;- 行业模板定义;
- 视觉模板定义和视觉 manifest;
- 模板包 manifest;
BrandTemplateInstallation快照;- BrandProfile、字段、Offering、表单、信任内容和能力安装记录。
公开端 PublicWorkspaceService 读取已发布的 snapshot,public-workspace.snapshot-assembler.ts 从 snapshot 投影 Runtime Workspace;只有显式 draft 预览才读取当前数据库。这个边界能防止未发布草稿直接公开,也能防止历史 release 随当前模板代码变化。
仍需修正的地方:
- snapshot 中的 manifest 当前来自部署代码,不包含导入 artifact 的 checksum 和 artifact ref;
installation的 JSON 只代表当时的行业台账,不能证明视觉包有独立安装版本;BrandRelease的status是字符串而不是模板发布状态,品牌 release 与模板目录发布不能混用;- 小程序任务只关联
BrandRelease,但没有单独记录模板 package version、renderer version、构建 attempt、lease 和确定产物清单。
6. 权限与租户现状
6.1 当前身份模型
AdminUser.role默认是admin,登录 token 中的role只有admin或customer两种会话值;- 当前品牌由 token 中的
brandId指定; - 品牌内角色在
BrandMembership.role中保存,目前主要是owner、editor,代码还允许admin和platform-admin; AdminAccessService.requireBrand()校验用户存在、未要求改密码、membership 启用;AdminMembershipGuard对工作台模板安装、能力、字段和视觉模板操作使用品牌成员角色检查;apps/api/src/modules/workspace/admin-access.identity.ts只检查 token 是否是 admin,并直接信任 token 的 brandId,属于旧接口的轻量鉴权路径。
6.2 缺口和风险
当前没有独立的平台模板管理员主体、平台作用域或平台审计资源。把 platform-admin 作为品牌 membership 字符串使用会产生两个问题:
- 平台模板管理员必须先隶属于某个品牌,平台操作会被错误绑定到当前品牌;
- 拥有某品牌 owner 权限的账号和平台模板管理员权限没有清晰的授权边界。
Phase 2 之前应新增独立的 platform permission/role 设计,至少满足:平台模板接口不依赖 brandId、品牌管理员看不到未发布版本、平台操作记录 actor 和 requestId、错误角色测试覆盖无凭证/无效 token/品牌角色/平台角色/成功路径。
7. 部署、Release 与运行环境隔离
7.1 当前部署边界
scripts/deploy/package-release.mjs 会把 API、Taro、配置包、类型包、校验包、模板包、Admin 静态产物、Prisma migration 和 seed media 复制到带版本的 release 目录,并生成 release manifest/checksum。模板包的 template.json、taro、miniapp 会随 release 一起发布。
线上 deploy/install-release.mjs 会:
- 校验 release manifest、Node 24 和 pnpm 9.15.0;
- 将 release 复制到
/releases/<version>; - 只以
--ignore-scripts执行受控 workspace install,并显式包含 API、Taro 和当前模板包 workspace; - 执行 Prisma generate/migrate,备份数据库,切换
current软链接并重启 API/Admin; - 通过 health、Admin、Traefik 和公开 release verifier 做切换验证;
- 应用失败时回滚应用软链接和进程,但数据库 migration 不回滚。
7.2 当前已隔离和未隔离内容
已存在的隔离:
- 代码通过带版本的 release 目录和
current软链接隔离; - 生产配置位于
shared/.env.production,不会进入 release 包; - 数据库使用生产容器和部署前 dump 备份;
- 媒体通过
LOCAL_MEDIA_ROOT和 seed 目录保留,release 切换不会删除旧媒体; - 公开 API 通过
brandSlug解析品牌,并只读取发布快照。
仍未完成的隔离:
- 模板导入 artifact 没有独立版本化对象存储或数据库引用;
- 本地 package registry、release 内生成 registry 和线上可选模板目录没有三方 checksum 对账;
- 生产发布仍把小程序构建执行在 API 所在 release 工作目录,构建产物根目录和模板包 workspace 依赖缺失会在运行期暴露;
- 构建、微信上传、审核和上线状态仍主要落在
MiniAppReleaseTask的一条记录上,尚未拆分 attempt/lease/产物清单; - 本地数据库、线上数据库、预览 fixture 和品牌 bootstrap 没有统一的环境标识和来源审计。
历史上出现的 No projects matched、缺少 app.json、生产运行时找不到 miniprogram-ci 和重复请求卡住,分别对应“构建输入/模板选择未校验”“旧产物误判成功”“生产依赖闭包未在 release 验证”“异步状态和轮询终态未收敛”。这些不能通过补一条 seed 或手动线上修复解决,必须纳入 release conformance 和 build/upload attempt 设计。
8. Phase 0 历史事故回归清单
下面的清单是后续自动化测试的验收输入;当前只完成现状登记,未将未实现项标为通过:
| 事故 | 可执行回归 | 负责阶段 |
|---|---|---|
| 本地模板线上不可选择 | 发布目录只返回已导入且 published 的版本;品牌安装请求使用服务端 catalog,不读客户端任意 key | Phase 2/4 |
| 新模板没有基础数据 | 独立 preview fixture 可渲染;bootstrap dry-run 能区分新增、保留、显式空值和冲突 | Phase 1/3/4 |
| 行业安装和视觉选择漂移 | 安装快照同时固定 industry、visual、checksum;旧品牌兼容读取对比新读路径 | Phase 4 |
| 发布快照被当前代码覆盖 | 发布后修改注册表或导入新版本,旧 release 的 template manifest、页面和数据仍保持原值 | Phase 4/6 |
| Taro 产物目录错误 | 干净 release 中按真实 template key 构建,检查 project count、app.json、品牌参数和产物 checksum | Phase 6 |
miniprogram-ci 生产缺失 |
生产依赖安装后执行真实 module import;不能只检查 lockfile 中存在包 | Phase 6 |
| 构建完成但上传状态卡住 | build/upload 分层状态、attempt lease、超时、重启恢复和终态 compare-and-set | Phase 6 |
| 轮询重复请求覆盖终态 | 日志按 sequence 写入;重复 retry 不能回退成功或清空失败原因 | Phase 6 |
| 首页、关于/我的和咨询角色混乱 | manifest navigation、页面 renderer、editor binding、CTA 目标和真实 fixture 逐页验收 | Phase 1/3/7 |
9. 后续实施顺序
- Phase 1:包契约与确定性导出。 先补 package schema、rendererRef、preview/bootstrap、checksum 和 package-discovered conformance;导出结果必须能在干净 release 中复现。
- Phase 2:线上目录和平台权限。 新增模板包、版本、validation run、artifact ref 和独立平台权限;先只让已发布版本进入品牌可见目录。
- Phase 3:真实预览。 预览按已导入版本和行业组合创建受控 session,使用 fixture 走和品牌相同的 Runtime 投影,但禁止写真实品牌和提交接口。
- Phase 4:品牌安装、视觉安装和 bootstrap。 保留旧
BrandTemplateInstallation兼容读取,新增清晰的 visual installation 和 bootstrap audit,不直接重写旧 JSON 历史。 - Phase 5:Admin 模板管理页面。 页面职责独立于
/admin/publication,完整呈现导入、校验、预览、发布、撤回、失败重试和审计状态。 - Phase 6:构建与发布状态收敛。 拆分 build/upload/review/release,补 production dependency、项目匹配、产物清单、attempt/lease 和重启恢复测试。
10. 退出条件
本盘点视为完成,条件是主计划已链接本文,且后续 migration 和 API 设计引用本文件中的事实来源、兼容读取和阻断项。它不代表模板管理功能已经完成;在新增数据库模型、接口或页面之前,必须先通过 Phase 0 的历史事故回归清单评审。