refactor: 统一模板契约并修复预览版本

This commit is contained in:
que01 committed 2026-10-18 17:09:09 +08:00
1 parent cd2992c00a
commit 50b87e48de
56 files changed
+7849 -5756

No files matched your search

+33 -32
View File
@@ -59,6 +59,7 @@
- 不把所有模板 sample content 复制进 Prisma seed,也不把 seed 当成模板目录;
- 不把品牌 owner 的权限扩展为平台模板管理员权限;
- 不把一次性的线上修复脚本当成模板安装能力;
- 不建设模板兼容层:运行时只读唯一正式 manifest/runtime contract;历史数据通过失败即停止的一次性迁移转换,不能保留双读、双写、默认映射或旧格式 fallback;
- 不在同一阶段长期维护两套业务 renderer。Taro 是统一的双端业务 renderer,旧原生实现只作为迁移和回滚基线;
- 不承诺第一阶段可以导入任意全新 renderer 源码后立即运行。第一阶段只接收声明式 manifest、资源、演示数据和已部署的受信 renderer 引用;
- 不把生成一张预览图、静态文件存在或页面能打开当成模板交付完成。
@@ -67,16 +68,16 @@
## 3. 当前状态和目标状态
| 领域 | 当前状态 | 目标状态 | 进入目标状态的证据 |
| ------------ | ------------------------------------------------------------------ | -------------------------------------------------------------- | --------------------------------------------------- |
| 模板发现 | packages/config 有生成注册表,文档注册表仍是手工清单 | 所有可用版本由可校验包 manifest 发现,生成注册表只作为构建产物 | 包发现测试、目录接口测试、无手工重复定义 |
| 版本 | 当前模板包 metadata 已与 manifest 对齐,导入 checksum 闭环尚未实现 | key + version + checksum 唯一且不可变 | 导出 checksum、重复导入、冲突导入测试 |
| 行业与视觉 | 行业安装和视觉选择已有部分能力,但没有完整版本化目录 | 行业兼容性、视觉包版本、renderer contract 一起校验 | 组合矩阵、安装快照和跨行业测试 |
| 示例内容 | 包内 sample 可用于部分预览和显式导入 | preview fixture、bootstrap 内容、品牌真实数据严格分离 | 预览无品牌写入、显式导入审计、缺失值规则测试 |
| 模板管理页面 | 现有工作台可以选择部分已注册模板 | 独立 /admin/templates 管理导入、校验、预览、发布和版本 | 页面状态测试、API 权限测试、错误重试测试 |
| 安装和升级 | BrandTemplateInstallation 主要承担行业安装 | 行业安装、视觉包安装、样例导入、升级计划和发布快照各有边界 | schema 迁移、旧数据回填、升级/回滚 integration test |
| 构建发布 | 构建、上传和发布曾共用状态,容易死锁或误报 | build、upload、review、publish 分层,attempt/lease/产物隔离 | 并发、重启、超时、错误收敛、真实参数产物测试 |
| 版本事实 | atelier-solopreneur 的 manifest 和 package metadata 已统一为 1.1.0 | 包内版本字段和导出元数据在导出前强一致 | validate:templates 的版本一致性检查 |
| 领域 | 当前状态 | 目标状态 | 进入目标状态的证据 |
| ------------ | ------------------------------------------------------------------ | -------------------------------------------------------------- | ------------------------------------------------------ |
| 模板发现 | packages/config 有生成注册表,文档注册表仍是手工清单 | 所有可用版本由可校验包 manifest 发现,生成注册表只作为构建产物 | 包发现测试、目录接口测试、无手工重复定义 |
| 版本 | 当前模板包 metadata 已与 manifest 对齐,导入 checksum 闭环尚未实现 | key + version + checksum 唯一且不可变 | 导出 checksum、重复导入、冲突导入测试 |
| 行业与视觉 | 行业安装和视觉选择已有部分能力,但没有完整版本化目录 | 行业兼容性、视觉包版本、renderer contract 一起校验 | 组合矩阵、安装快照和跨行业测试 |
| 示例内容 | 包内 sample 可用于部分预览和显式导入 | preview fixture、bootstrap 内容、品牌真实数据严格分离 | 预览无品牌写入、显式导入审计、缺失值规则测试 |
| 模板管理页面 | 现有工作台可以选择部分已注册模板 | 独立 /admin/templates 管理导入、校验、预览、发布和版本 | 页面状态测试、API 权限测试、错误重试测试 |
| 安装和升级 | 品牌配置、行业安装和视觉选择存在重复来源 | 唯一安装记录锁定行业模型与精确视觉包版本 | 一次性数据转换、唯一性约束、升级/回滚 integration test |
| 构建发布 | 构建、上传和发布曾共用状态,容易死锁或误报 | build、upload、review、publish 分层,attempt/lease/产物隔离 | 并发、重启、超时、错误收敛、真实参数产物测试 |
| 版本事实 | atelier-solopreneur 的 manifest 和 package metadata 已统一为 1.1.0 | 包内版本字段和导出元数据在导出前强一致 | validate:templates 的版本一致性检查 |
当前存在的 Runtime Workspace、模板 manifest、样例导入和 Taro 构建能力是基础组件,不代表本任务已完成。实施进度必须引用本文的阶段和证据。
@@ -251,15 +252,15 @@ admin.sections 和 renderer 必须互相校验:每个可见、可编辑的品
| TemplateUpgradePlan | from/to、差异、冲突、用户确认和执行结果 | 支持 dry-run、重试和回滚 |
| TemplateOperationJob | 导入、校验、资源处理、build/upload 的 attempt 和 lease | 支持重启恢复和终态收敛 |
现有 BrandTemplateInstallation 当前主要承担行业模板安装记录,不能直接把它改成视觉包版本记录并破坏旧快照。实施前先盘点其查询、发布快照和旧回滚行为;优先新增边界清晰的模型或新增可为空字段,完成兼容读取后再考虑收敛。
BrandTemplateInstallation 必须收敛为品牌唯一的当前模板安装,记录行业模型及精确视觉包版本。先只读盘点数据,再以一次性事务迁移完成无歧义映射;迁移后删除重复状态和旧字段,不保留兼容读取窗口。发布历史通过不可变 release snapshot 保留,不依赖旧安装形状。
数据库迁移必须遵循以下顺序:
1. 备份并记录当前 schema、模板安装、品牌配置和发布快照数量;
2. 先增加可为空的新字段或新表,不改变旧读路径;
3. 回填只写可从旧数据确定推导出的值,不能猜测版本、checksum 或样例来源;
4. 双读对比旧路径和新路径,记录不一致;
5. 切换写入,再保留旧读兼容窗口;
4. 生成新旧数据的只读差异报告;有歧义时停止迁移并修正数据;
5. 执行一次性事务迁移,校验唯一安装及 package/version/checksum/industry 一致后删除旧表示;
6. 清理旧字段前提供备份、回滚脚本和历史快照验证;
7. 重复执行迁移和导入不得生成重复安装、重复 offering、重复 inquiry form 或重复审计。
@@ -419,7 +420,7 @@ Phase 3 初版实现(提交 `6edde5a`,2026-10-16):
Phase 3 独立 fixture 与资源进展(2026-10-16):
- 新增 `previewFixture.<industry>`:`schemaVersion: "1"`、身份白名单 `brand`、独立 `content` 和固定禁用策略 `safety`;使用 `packages/validation` 的同一 Zod 规则校验本地包和线上导入,不引入新校验体系。声明 fixture 的包必须覆盖全部兼容行业;无效声明不能回退到 `sampleContent`。
- atelier 升为 `1.2.0`,保持旧版本不可变;预览主理人和品牌身份单独声明,`sampleContent` 仍只用于品牌起始内容,不修改 seed 或自动安装到现有品牌。尚未迁移的旧包走明确标注的兼容路径。
- atelier 升为 `1.2.0`,保持不可变版本;预览主理人和品牌身份单独声明,`sampleContent` 只用于显式品牌起始内容。所有可发布包必须满足同一 manifest 契约;不提供旧包运行兼容路径。
- 管理页展示当前页面的 Admin 模块声明顺序、字段 binding、资源配置数量和缺失状态。这是声明诊断,不代表已经验证 renderer 的实际视觉顺序或全部字段消费。
- 预览读取已导入 archive,核对 archive/content checksum 及逐图片 SHA-256,校验实际图片格式后以内嵌 data URL 提供给画布;不执行源码、不解压到公共目录、不回退到当前部署的同名图片。每图最多 2 MiB、总图片最多 8 MiB、最多 128 张,超出限额返回明确诊断;外链图片仍为待验证。
- 同一预览响应同时包含版本 checksum、Runtime 和图片映射,切换版本/行业不会复用另一份图片;当前实现尚不包含可公开访问的资源 URL、远程资源探测或 CDN 缓存。
@@ -442,7 +443,7 @@ Phase 3 现场验收纠偏(2026-10-16):
- 现场核对发现旧模板 `sampleContent` 只有少量业务数据,`brandConfig` 和媒体槽位为空,导致 food/linjing 预览像缺数据。已为 `acheng-campus-food@1.0.1`、`linjing-editorial@1.0.3` 补齐包内演示主图、头像、封面和视觉文案;旧版本保持 immutable 并撤回。
- atelier 独立 fixture 也没有头像。已升为 `atelier-solopreneur@1.3.0`,在 `previewFixture.personal.brand` 中加入包内头像,继续保持预览数据与 bootstrap sample 分离。
- 修复 Admin 导入包预览中 food renderer 的资源 key 前缀映射:包内 `/assets/service/*.png` 等图标现在可从 archive 校验后的 data URL 渲染,不回退到本地部署资源。
- 矩阵 API 回归新增断言:每个支持行业的主理人身份非空、头像指向包内资源、所有 asset slot 都是 `ready`、除 `LEGACY_PREVIEW_SAMPLE` 外没有诊断。
- 矩阵 API 回归新增断言:每个支持行业的主理人身份非空、头像指向包内资源、所有 asset slot 都是 `ready`、没有诊断。
- 新增 Playwright 媒体矩阵:覆盖 `acheng/food`、`atelier/personal`、`linjing/personal`、`linjing/doors`,使用真实 `template:pack` 产物和 API preview service;验证失败重试、founder 可见、所有 `data:` 图像 `naturalWidth > 0`、无“内容缺失”、无真实写入请求。四张截图已人工检查。
- 本轮本地目录以最新已发布版本为准:`acheng-campus-food@1.0.1`、`atelier-solopreneur@1.3.0`、`linjing-editorial@1.0.3`;被取代的旧演示版本进入 retired。
@@ -466,15 +467,15 @@ Phase 3 隔离、导航和矩阵收口(2026-10-16):
- [x] 通过 shared client、Admin 页面和 API integration test 验证跨品牌隔离;
- [x] 验证模板安装不自动导入未确认的身份、背书、案例和咨询数据。
当前进展:安装台账已保存 `templatePackageVersionId`、视觉 key 和 `contentChecksum`;bootstrap 只读取已发布 package version 的 `manifestSnapshot.sampleContent`,preview 只 dry-run,import 必须显式传入 `strategy: "missing_only"` 和 `confirm: true`。已有品牌值(包括显式空值)、同名 offering、相同 `type + title` 的 trust content、相同 inquiry field,以及已启用表单都会被保留;重复导入按品牌、版本和 checksum 幂等返回,并写入 `TemplateBootstrapImport` 和 capability audit。
当前进展:安装台账只引用精确的 `templatePackageVersionId` 并记录 `contentChecksum`;renderer key 只从该版本的 package manifest 读取。bootstrap 只读取已发布 package version 的 `manifestSnapshot.sampleContent`,preview 只 dry-run,import 必须显式传入 `strategy: "missing_only"` 和 `confirm: true`。已有品牌值(包括显式空值)、同名 offering、相同 `type + title` 的 trust content、相同 inquiry field,以及已启用表单都会被保留;重复导入按品牌、版本和 checksum 幂等返回,并写入 `TemplateBootstrapImport` 和 capability audit。
seed 边界已收口:`ensureRuntimeContent` 写入的 offerings、trust content、inquiry fields、表单名称和模板品牌样例均来自对应 package 的 `sampleContent`,food、doors 的媒体和结构化展示字段已通过真实公开 workspace 验证;`runtimeSeedTemplates` 仅保留明确的开发演示品牌 profile 以及旧 offering 停用兼容 fixture,不作为模板目录或业务样例来源。新增模板不需要修改全局 seed;没有 package version 台账的历史 seed 品牌继续使用 registry 兼容路径,新安装品牌必须使用精确已发布版本。
seed 边界已收口:`ensureRuntimeContent` 写入的 offerings、trust content、inquiry fields、表单名称和模板品牌样例均来自对应 package 的 `sampleContent`,food、doors 的媒体和结构化展示字段已通过真实公开 workspace 验证;`runtimeSeedTemplates` 仅保留明确的开发演示品牌 profile,不作为模板目录或业务样例来源。新增模板不需要修改全局 seed;每个运行品牌都必须有精确已发布 package version 安装,缺失时启动/操作明确失败,不走 registry fallback。
退出门禁:干净品牌可以通过安装和显式导入完成编辑发布;已有用户值、主动清空值和历史发布快照均不被覆盖;错误请求不会改变表单。
### Phase 5:构建、上传和线上发布闭环
- [x] 将 build、upload、review 状态拆分,并为构建/上传增加持久化 attempt 和 lease;旧聚合 `status` 暂时保留兼容;
- [x] 将 build、upload、review 状态拆分,并为构建/上传增加持久化 attempt 和 lease;
- [x] 产物路径包含品牌 slug、模板 key、模板包精确版本和 build attempt id;
- [x] 生产依赖闭包通过 Node 24 release package、干净 `--prod --frozen-lockfile` 安装、Prisma Client generate、API runtime import 和 production API health check 验证;API app 重建后的 attempt 恢复由真实 Prisma integration 覆盖;
- [x] 构建失败、上传失败、超时、进程退出、重试和恢复有自动化测试;覆盖 build worker 非零退出/watchdog kill、失败构建、上传子进程超时、attempt lease 竞争/接管、真实 Prisma/API app 重建恢复;本机 Node 24 production bundle 已启动、停止并重启验证;生产机 PM2/主机重启仍属于部署环境验收;
@@ -528,7 +529,7 @@ Phase 7 进展记录(2026-10-17):
- 新增 `pnpm template:compatibility`,通过 TypeScript AST 读取行业、能力和视觉注册表,自动发现所有 package manifest;比较平台视觉 renderer、Admin glob、Taro renderer 导出、行业 capability 和 package/platform Taro/React 依赖主次版本,支持 JSON 报告。
- API 模板预览矩阵自动扫描真实 manifest,逐个验证声明行业、版本隔离、品牌隔离和归档资源;CI 静态 job 显式执行 package validation、compatibility、API matrix 和 conformance。CI browser job 已执行真实包 fixture 的页面/资源/编辑回归截图。
- 自动化验证:`pnpm template:check` 通过(contract `22/22`、scaffold/compatibility `3/3`、pack `3/3`、conformance `1/1`、compiler `10/10`、miniapp fixture `3/3`);API matrix `2/2`;compatibility 报告有 4 个支持组合;API unit `65/65`、HTTP integration `54/54`、upload integration `2/2`、API Client `8/8`、Admin `6/6`;API/API Client/Admin typecheck、Admin production build、Prettier 和 `git diff --check` 通过。
- 剩余:指标已有统一持久化和平台管理员查询接口,但定期审阅流程仍需运营安排;旧 renderer/默认行业映射仍有兼容职责,暂不能删除。模板 doctor 的真实品牌编辑保存重载发布与原型视觉证据仍为 `unverified`,不能以 CI smoke 代替;因此 Phase 7 整体继续进行。
- 剩余:指标已有统一持久化和平台管理员查询接口,但定期审阅流程仍需运营安排;模板运行时仍有旧 renderer/默认行业映射等兼容路径待移除。模板 doctor 的真实品牌编辑保存重载发布与原型视觉证据仍为 `unverified`,不能以 CI smoke 代替;因此 Phase 7 整体继续进行。
运营指标说明:新增 `TemplateOperationFailureEvent` 记录导入、预览、安装/冲突、升级和回滚失败;构建/上传从已有 release attempt 聚合。事件只保留 action、稳定 `HTTP_*` resultCode、可选实体标识和 requestId,查询只返回类别/数量;按 180 天 best-effort 清理,不回填历史失败数。定期审阅仍需运营流程和负责人。
@@ -541,7 +542,7 @@ Phase 7 进展记录(2026-10-17):
- [ ] 使用真实部署参数完成 H5 和 weapp 构建,检查 AppID、API 地址、媒体地址、模板版本和产物路径;
- [ ] 在微信开发者工具或真机完成 request、media、拨号、复制、表单提交和安全区验证;外部上传、审核、发布结果单独归档;
- [ ] 由平台模板管理员执行一次失败指标审阅,确认高频问题、负责人和后续动作,形成审阅记录;
- [ ] 基于实际迁移证据决定旧 registry/default mapping 是否可以逐项下线;未完成历史品牌回填和兼容验证前不得删除兼容层。
- [ ] 完成一次性品牌安装与 package version 数据转换,之后删除旧 registry/default mapping 和所有模板兼容读写;迁移歧义必须阻断,不得延长兼容窗口。
Phase 8 启动记录(2026-10-17):
@@ -559,9 +560,9 @@ Phase 8 自动化持久化与兼容审查(2026-10-17):
- API unit `65/65`、API Client `8/8`、Admin `6/6`、发布验证/部署测试 `8/8` 通过;隔离 PostgreSQL schema 中执行完整 `pnpm --filter @personal-brand/api test:integration`,HTTP integration `54/54`、upload integration `2/2` 通过,schema migration 与重复 seed 幂等性通过;
- 隔离 integration 中真实 manifest bindings 经数据库持久化、草稿预览和发布快照测试通过(193 个 manifest bindings);这证明自动化数据链,不等价于人工在 Admin 实际点选编辑,也不替代独立模板视觉审查;
- 旧默认视觉映射仍被 seed、草稿/公开 Runtime、release snapshot 和显式 bootstrap 调用。当前没有完整的历史品牌回填与双读/回滚机制,故不能安全删除;后续应先为现有品牌持久化明确 visual package version/checksum,再验证旧行兼容读取,最后分批移除 fallback。
- 旧默认视觉映射仍被 seed、草稿/公开 Runtime、release snapshot 和显式 bootstrap 调用,违反单一契约决策。必须先输出只读迁移报告,将每个运行品牌明确绑定到已发布 visual package version/checksum;无法唯一映射时阻断。完成一次性转换后删除所有 fallback,不提供双读或兼容窗口。
退出门禁:真实品牌保存重载发布、视觉证据、双端外部验证和运营审阅记录全部归档;旧兼容层只有在历史品牌迁移验证后才允许删除。
退出门禁:真实品牌保存重载发布、视觉证据、双端外部验证和运营审阅记录全部归档;历史品牌通过一次性迁移满足唯一模板契约,所有兼容层和旧字段已删除。
Phase 8 编辑闭环回归(2026-10-18):
@@ -647,16 +648,16 @@ Phase 8 编辑闭环回归(2026-10-18):
以下问题必须在对应阶段开始前作出可审阅决定,不允许用临时默认值带过:
| 问题 | 推荐方向 | 最晚决定阶段 |
| ----------------------------------------------- | ------------------------------------------------------------------- | ------------ |
| 平台模板管理员角色名称和权限来源 | 独立于品牌 owner 的平台级权限,所有操作审计 | Phase 0 |
| artifact 存储 | 版本化对象存储或受控 release 目录,按 checksum/版本寻址 | Phase 2 |
| preview session 存储 | 第一阶段使用短期 token + 服务端受控数据;需要审计时再持久化 session | Phase 3 |
| 视觉安装模型 | 新增清晰的视觉包安装边界,兼容读取旧行业安装 | Phase 4 |
| renderer 分发 | 第一阶段只引用预部署 renderer;任意新 renderer 走独立可信构建方案 | Phase 1 |
| 包签名 | 内网 MVP 先 checksum,跨环境或第三方来源前增加签名和信任根 | Phase 2 |
| 目录可见性 | 未发布版本只给平台管理员,已发布版本才给品牌管理员 | Phase 2 |
| template package version 与 npm package version | 导出前强制一致,若不一致直接阻断 | Phase 1 |
| 问题 | 推荐方向 | 最晚决定阶段 |
| ----------------------------------------------- | ------------------------------------------------------------------------ | ------------ |
| 平台模板管理员角色名称和权限来源 | 独立于品牌 owner 的平台级权限,所有操作审计 | Phase 0 |
| artifact 存储 | 版本化对象存储或受控 release 目录,按 checksum/版本寻址 | Phase 2 |
| preview session 存储 | 第一阶段使用短期 token + 服务端受控数据;需要审计时再持久化 session | Phase 3 |
| 视觉安装模型 | 唯一品牌安装记录锁定行业模型和精确视觉包版本,完成一次性迁移并删除旧状态 | Phase 4 |
| renderer 分发 | 第一阶段只引用预部署 renderer;任意新 renderer 走独立可信构建方案 | Phase 1 |
| 包签名 | 内网 MVP 先 checksum,跨环境或第三方来源前增加签名和信任根 | Phase 2 |
| 目录可见性 | 未发布版本只给平台管理员,已发布版本才给品牌管理员 | Phase 2 |
| template package version 与 npm package version | 导出前强制一致,若不一致直接阻断 | Phase 1 |
## 17. 可观察性和风险