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

208 lines
19 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 模板管理 Phase 0 现状盘点
> 任务:TMP-PLATFORM-001
>
> 日期:2026-10-16
>
> 本文是 [模板管理与分发交付计划](template-management-delivery-plan.md) 的现状证据,不是新的模板注册表。本文记录的是当前代码真实行为;目标模型仍以 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 的历史事故回归清单评审。