Files
persionalBrand/docs/template-management-phase0-inventory.md
T

19 KiB
Raw Blame History

模板管理 Phase 0 现状盘点

任务:TMP-PLATFORM-001

日期:2026-10-16

本文是 模板管理与分发交付计划 的现状证据,不是新的模板注册表。本文记录的是当前代码真实行为;目标模型仍以 ADR 0029 和主计划为准。

1. 结论摘要

当前系统已经有“行业模板 + 视觉模板包 + Runtime Workspace + 品牌发布快照”的局部能力,但还不是模板管理与分发系统。主要结论如下:

  1. 模板目录的事实来源仍是部署时编译进 packages/config 的仓库文件,不是线上可管理的版本目录。
  2. BrandTemplateInstallation 当前只可靠表达一个品牌的行业模板安装台账;视觉模板选择实际写在 BrandProfile.config.visualTemplateKey,两者没有独立的视觉安装快照。
  3. 预览、sample 导入和品牌发布已经有不同接口,但预览目录仍直接读取运行时注册表,不能按导入版本、checksum 和发布状态隔离。
  4. 发布快照会冻结行业定义、视觉定义、manifest、安装记录和品牌数据;旧发布不会随当前注册表更新而自动改变,这是现有链路中最稳定的边界。
  5. 后台登录身份只有 admin 会话角色,品牌成员角色在 BrandMembership.role 中表达。现有 platform-admin 只是可写入的字符串值,不是独立的平台模板管理员身份,也没有独立的权限作用域或审计主体。
  6. 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 行业模板安装

当前写入路径:

  1. Admin 调用 POST /admin/workspace/install。
  2. AdminWorkspacePreviewController 通过 requireAdminIdentity() 获取 token 中的 brandId。
  3. TemplateWorkspaceService.install() 从 getBrandTemplate(templateKey) 读取行业定义,并从代码注册表解析兼容的默认或已选视觉模板。
  4. 一个事务同时更新 BrandProfile.templateKey、必要时合并 config.visualTemplateKey、创建 BrandTemplateInstallation 和 BrandFieldDefinition。
  5. 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 视觉模板选择

当前写入路径:

  1. Admin 的品牌配置接口 PATCH /admin/config/brand 接收 config.visualTemplateKey。
  2. Controller 通过 AdminAccessService.requireRole() 限制为 owner、admin 或字符串角色 platform-admin。
  3. 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 随当前模板代码变化。

仍需修正的地方:

  1. snapshot 中的 manifest 当前来自部署代码,不包含导入 artifact 的 checksum 和 artifact ref;
  2. installation 的 JSON 只代表当时的行业台账,不能证明视觉包有独立安装版本;
  3. BrandRelease 的 status 是字符串而不是模板发布状态,品牌 release 与模板目录发布不能混用;
  4. 小程序任务只关联 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 字符串使用会产生两个问题:

  1. 平台模板管理员必须先隶属于某个品牌,平台操作会被错误绑定到当前品牌;
  2. 拥有某品牌 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 会:

  1. 校验 release manifest、Node 24 和 pnpm 9.15.0;
  2. 将 release 复制到 /releases/<version>;
  3. 只以 --ignore-scripts 执行受控 workspace install,并显式包含 API、Taro 和当前模板包 workspace;
  4. 执行 Prisma generate/migrate,备份数据库,切换 current 软链接并重启 API/Admin;
  5. 通过 health、Admin、Traefik 和公开 release verifier 做切换验证;
  6. 应用失败时回滚应用软链接和进程,但数据库 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. 后续实施顺序

  1. Phase 1:包契约与确定性导出。 先补 package schema、rendererRef、preview/bootstrap、checksum 和 package-discovered conformance;导出结果必须能在干净 release 中复现。
  2. Phase 2:线上目录和平台权限。 新增模板包、版本、validation run、artifact ref 和独立平台权限;先只让已发布版本进入品牌可见目录。
  3. Phase 3:真实预览。 预览按已导入版本和行业组合创建受控 session,使用 fixture 走和品牌相同的 Runtime 投影,但禁止写真实品牌和提交接口。
  4. Phase 4:品牌安装、视觉安装和 bootstrap。 保留旧 BrandTemplateInstallation 兼容读取,新增清晰的 visual installation 和 bootstrap audit,不直接重写旧 JSON 历史。
  5. Phase 5:Admin 模板管理页面。 页面职责独立于 /admin/publication,完整呈现导入、校验、预览、发布、撤回、失败重试和审计状态。
  6. Phase 6:构建与发布状态收敛。 拆分 build/upload/review/release,补 production dependency、项目匹配、产物清单、attempt/lease 和重启恢复测试。

10. 退出条件

本盘点视为完成,条件是主计划已链接本文,且后续 migration 和 API 设计引用本文件中的事实来源、兼容读取和阻断项。它不代表模板管理功能已经完成;在新增数据库模型、接口或页面之前,必须先通过 Phase 0 的历史事故回归清单评审。