feat: 收口模板升级与阶段七持续回归

This commit is contained in:
que01 committed 2026-10-17 21:33:57 +08:00
1 parent ec16fff70e
commit 71c528de34
29 files changed
+1962 -304

No files matched your search

+38 -19
View File
@@ -2,7 +2,7 @@
> 任务 ID:TMP-PLATFORM-001
>
> 状态:Phase 0/1/2/3/4/5 已收口;Phase 5 的本地实现与验证完成,真实微信上传未成功,后续出现发布问题时再按需核查
> 状态:Phase 0/1/2/3/4/5/6 已收口;Phase 7 进行中
>
> 唯一任务入口:本文档
>
@@ -312,16 +312,16 @@ admin.sections 和 renderer 必须互相校验:每个可见、可编辑的品
## 11. CLI、仓库工作流和构建门禁
当前仓库已有 template:doctor、template:check、validate:templates、generate:template-catalog、preview:templates、deploy:package、deploy:release 和 test:deploy 等命令。它们的现有行为不能在本文中被默认扩大。
当前仓库已有 `template:doctor`、`template:check`、`validate:templates`、`template:compatibility`、`template:new`、`generate:template-catalog`、`preview:templates`、`deploy:package`、`deploy:release` 和 `test:deploy` 等命令。它们的现有行为不能在本文中被默认扩大。
计划新增或收敛的命令如下,实施前必须先落代码、帮助文本和测试:
| 命令 | 目的 | 完成门禁 |
| -------------------- | ------------------------------------------------------------- | ---------------------------------- |
| template:pack | 生成确定性模板导出包和 checksum | 同一输入多次输出相同 checksum |
| template:conformance | 逐包执行 manifest、binding、资源、sample、renderer 和双端契约 | 自动发现新包,不能只测固定名称 |
| release:conformance | 检查发布包依赖闭包、workspace、产物路径和环境参数 | 干净 install、生产 build、产物检查 |
| template:new | 从受控 scaffold 创建新模板包和最小 fixture | 生成包自带失败示例和测试入口 |
| 命令 | 目的 | 完成门禁 |
| -------------------- | ------------------------------------------------------------- | ---------------------------------------- |
| template:pack | 生成确定性模板导出包和 checksum | 同一输入多次输出相同 checksum |
| template:conformance | 逐包执行 manifest、binding、资源、sample、renderer 和双端契约 | 自动发现新包,不能只测固定名称 |
| release:conformance | 检查发布包依赖闭包、workspace、产物路径和环境参数 | 干净 install、生产 build、产物检查 |
| template:new | 从受控 scaffold 创建新模板包与待完成 fixture | 生成包明确标为未验收并通过 scaffold 测试 |
每个模板新增、绑定修改和宣称完成前,必须运行 pnpm template:doctor,并按[模板完成度规则](template-completion-rules.md)使用真实 manifest、真实保存重载发布链路和视觉证据验收。doctor issue 使用稳定语义指纹;源代码语义改变后必须重新审查,不能通过批量行号更新伪造通过。
@@ -496,23 +496,42 @@ Phase 5 首轮实现记录(2026-10-17):
### Phase 6:升级、冲突、回滚和恢复
- [ ] 生成旧版本到新版本的字段、模块、资源、能力和 renderer 差异;
- [ ] 升级支持 dry-run、显式确认、冲突逐项处理和用户内容保护;
- [ ] 回滚明确恢复安装配置、发布快照或取消升级计划的语义;
- [ ] 旧版本资源、品牌历史发布和咨询提交持续可读;
- [ ] 模拟数据库、API、worker 和 Admin 重启,验证 job 恢复和幂等。
- [x] 生成旧版本到新版本的字段 binding、页面入口、包文件、资源槽位和能力差异;视觉模块与 renderer 标记为平台视觉 manifest 所有,不随模板包升级;
- [x] 升级支持 dry-run、显式确认、逐项保留现有 binding 冲突和用户内容保护;同一预览并发执行时 compare-and-set 保证最多一个成功;
- [x] 回滚要求显式确认并校验当前版本,只恢复安装配置快照及不可变包关联,不恢复已删除的用户数据,也不删除当前用户数据;
- [x] 验证旧模板版本、品牌历史发布快照和客户咨询提交在升级/回滚后持续可读;新旧包文件清单分别从验证报告或已验证归档读取;
- [x] API / Prisma Client 重建后读取持久化安装状态;该升级操作是同步数据库事务,没有独立 worker job,Admin 页面重载后由查询重新读取 preview,陈旧操作会被版本校验拒绝。
退出门禁:升级失败可恢复到升级前状态;回滚不会删除用户历史数据;重试和重启不会重复导入或重复写终态。
退出门禁:升级冲突/陈旧预览不改变安装状态;回滚不会删除用户历史数据;并发重试和 API 重建不会重复升级或覆盖终态。
Phase 6 收口记录(2026-10-17):
- 升级目标切换为当前视觉模板最新已发布的不可变 `TemplatePackageVersion`;preview 比较模板配置 binding、页面入口、语义资源槽位、能力和校验报告中的逐文件 SHA-256。视觉模块/renderer 明确标为平台视觉 manifest 管理,包升级不替换 renderer;未有历史文件清单的旧包会明确报告不可比较。
- 升级 API 要求 DTO 显式确认并携带目标 package id/checksum、来源 package id/版本及每个冲突 binding 的 `preserve` 选择;执行时再次验证包状态、行业兼容性和冲突集合,数据库 compare-and-set 防止并发重复升级。品牌现有值不被改写,升级不删除数据。
- 回滚要求显式确认和预期当前版本,compare-and-set 防止覆盖并发升级;回滚恢复配置快照和对应不可变包关联,不删除品牌内容、历史发布或客户提交。升级/回滚写入 package audit log,记录 actor、brand、版本、checksum、保留选择与 requestId。
- 归档兼容:新导入包的 checksum 文件清单保存于 `validationReport`;旧记录在 preview 时从隔离存储中的已导入 archive 只读提取 `checksums.json`,缺失/损坏时返回明确不可比较,不执行包内脚本。
- 自动化验证:无凭据/错误角色、DTO 校验、目标版本 preview、冲突未确认拒绝、同一预览并发一胜一冲突、升级与回滚审计、Prisma Client 断开重连、Nest app 重建后读取版本、历史发布与咨询内容保留;API HTTP integration `53/53`、upload integration `2/2`、API unit `64/64`、API Client `7/7`、Admin `6/6`、API/API Client/Admin typecheck、Admin production build、格式检查通过。全仓 lint 仍有本阶段之外的既有错误,本次变更文件的 lint 单独通过。
- `pnpm template:doctor` completionStatus 仍为 `unverified`,因为真实 manifest 的品牌编辑保存/重载/发布和视觉证据未提供;这是模板完成度独立门禁,不由本阶段升级 API 测试替代。
### Phase 7:规模化模板生产和持续回归
- [ ] 新模板可通过 scaffold、package-discovered conformance 和模板管理页面进入目录;
- [ ] 行业、视觉、能力、renderer 和 toolchain 组合有兼容矩阵;
- [ ] 固定页面角色的视觉基线和真实数据 fixture;
- [ ] CI 在新增模板时自动发现并执行契约、API、构建和必要的视觉检查;
- [ ] 统计导入失败、预览失败、安装冲突、构建失败和上传失败,定期审阅高频问题;
- [x] 新模板可通过 `pnpm template:new <package-key>` scaffold、package-discovered conformance 和模板管理页面进入目录;生成包明确保留待填写的 industry/fixture 占位,不能误当成已验收模板;
- [x] 行业、视觉、能力、renderer 和 Taro/React toolchain 组合有自动兼容矩阵,未知 renderer、未知 capability、行业不兼容和依赖版本漂移都会阻断;
- [x] 固定页面角色的浏览器视觉 smoke 与真实 package fixture 已由 CI browser job 执行;原型对照、真实编辑保存重载发布证据仍遵循模板完成度规则单独验收;
- [x] CI 在新增模板时自动发现并执行契约、API 预览矩阵、compatibility、包构建 conformance 和 browser smoke;
- [x] 统一统计导入失败、预览失败、安装失败/冲突、升级/回滚失败、构建失败和上传失败;平台模板管理员可查询窗口聚合,且不暴露错误正文;定期审阅流程仍需运营安排;
- [ ] 删除或迁移旧注册表、默认行业映射和重复 renderer 分支。
Phase 7 进展记录(2026-10-17):
- 新增 `pnpm template:new <package-key>`,生成 package metadata、manifest、Taro renderer 和明确未完成的 README;重复 key 会拒绝,不生成可伪装完成的空样例数据。
- 新增 `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 整体继续进行。
运营指标说明:新增 `TemplateOperationFailureEvent` 记录导入、预览、安装/冲突、升级和回滚失败;构建/上传从已有 release attempt 聚合。事件只保留 action、稳定 `HTTP_*` resultCode、可选实体标识和 requestId,查询只返回类别/数量;按 180 天 best-effort 清理,不回填历史失败数。定期审阅仍需运营流程和负责人。
退出门禁:增加一个新模板不需要修改全局 seed 才能被发现,不需要在 Controller 写行业分支,不需要手工改线上数据库才能选择、预览、安装和发布。
## 13. 历史问题到自动化验收的映射
+6 -6
View File
@@ -28,12 +28,12 @@
## 当前缺口
- [ ] 版本导出、线上导入、checksum 幂等和目录发布尚未形成统一闭环;
- [ ] 独立模板管理页面尚未覆盖导入、校验、预览、发布和审计全流程;
- [ ] 行业安装和视觉包安装的持久化边界需要迁移设计;
- [ ] 预览 fixture 和可导入 bootstrap 内容需要明确分离;
- [ ] Taro renderer、Runtime contract、package schema 和 toolchain 的兼容矩阵需要落库;
- [x] 版本导出、导入、checksum 幂等、目录发布/撤回与审计已由 template pack 和管理 API 实现;
- [x] `/admin/templates` 覆盖导入、校验、预览、发布、撤回和审计;
- [x] 行业安装与视觉包精确版本通过兼容读取和不可变版本台账关联;新安装保存 package version/checksum;
- [x] 预览 fixture 与显式 bootstrap 内容分离,预览不写入品牌;
- [x] `pnpm template:compatibility` 自动检查 package、行业、平台视觉 manifest、Taro renderer 和 Admin renderer discovery;Runtime contract 及 package schema 由 `pnpm validate:templates` 校验;toolchain 产物由 `pnpm template:conformance` 验证;
- [x] atelier-solopreneur 的 manifest/package metadata 版本已统一,并由 validate:templates 阻断后续漂移;
- [ ] 每个模板仍需完成真实品牌编辑、保存重载、发布、双端构建和真实微信外部验收。
- [ ] 每个模板仍需完成真实品牌编辑、保存重载、发布和视觉证据;双端生产构建按交付变更执行,真实微信外部上传/审核尚未证明。
新增模板时先修改模板包和契约测试,再更新生成产物;不要直接在本文追加一条“已注册”来绕过门禁。