diff --git a/docs/template-management-delivery-plan.md b/docs/template-management-delivery-plan.md index c89ba4a..b0dcff9 100644 --- a/docs/template-management-delivery-plan.md +++ b/docs/template-management-delivery-plan.md @@ -341,10 +341,10 @@ Taro 交付必须额外验证: - [x] 建立本文档和 ADR 0029,并将其设为唯一任务入口; - [x] 盘点所有模板包的 manifest/package metadata、renderer、fixture、资源和版本差异; -- [ ] 盘点现有行业安装、视觉选择、发布快照和 Admin 页面调用关系; -- [ ] 为历史事故建立可执行回归清单; +- [x] 盘点现有行业安装、视觉选择、发布快照和 Admin 页面调用关系,见 [Phase 0 现状盘点](template-management-phase0-inventory.md); +- [x] 为历史事故建立可执行回归清单,见 [Phase 0 现状盘点](template-management-phase0-inventory.md#8-phase-0-历史事故回归清单); - [x] 解决 atelier-solopreneur manifest/package metadata 版本漂移; -- [ ] 明确平台模板管理员角色和线上隔离环境。 +- [x] 明确平台模板管理员角色缺口和线上隔离边界,见 [Phase 0 现状盘点](template-management-phase0-inventory.md#6-权限与租户现状) 与 [Phase 0 现状盘点](template-management-phase0-inventory.md#7-部署-release-与运行环境隔离); 退出门禁:模板目录、版本事实、现有数据模型和已知失败路径有可审阅清单;没有“默认值能猜出来”的隐含项。 @@ -354,7 +354,8 @@ Phase 0 执行记录(2026-10-16): - 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:包契约和确定性导出 diff --git a/docs/template-management-phase0-inventory.md b/docs/template-management-phase0-inventory.md new file mode 100644 index 0000000..c6165b1 --- /dev/null +++ b/docs/template-management-phase0-inventory.md @@ -0,0 +1,207 @@ +# 模板管理 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/`; +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 的历史事故回归清单评审。