Files
persionalBrand/docs/adr/0031-single-template-contract.md
T
que01 4f0b50c7f1 fix: 收口模板契约与安全门禁
统一模板包 visual 契约并补齐完成证据;修复 release 版本一致性、管理员 token 撤销、CORS 与默认品牌配置;收敛依赖安全风险并完成全量回归验证。
2026-10-18 22:05:31 +08:00

46 lines
4.8 KiB
Markdown

# 0031 模板只维护一套正式契约
## 状态
已采纳
## 背景
模板运行时逐步积累了默认行业映射、品牌 config 与安装台账双读、旧注册表 sample fallback、旧包 manifest 推断和聚合发布状态等路径。它们允许契约外的数据继续运行,使模板选择的事实来源不确定,也让每次修改都必须同时维护新旧行为。产品要求模板只维护一套契约,不建设长期兼容层。
## 决策
- 所有模板包必须通过唯一的 `TemplatePackageManifest` 契约及其 `runtimeContract` 校验;`visualPresentation` 是该契约的一部分,承载 description、variants、theme 和 layout。契约外字段、缺失字段、未知 renderer 或不匹配的行业声明均明确失败,不推断、不静默回退。
- 品牌当前使用的模板方案必须有明确、持久化的唯一安装记录,并锁定一个已发布的 `TemplatePackageVersion`。package key、版本、视觉 renderer key 和 checksum 只由该版本的 package manifest 与不可变归档确定;数据库不重复存 renderer key。运行时不得从品牌行业、全局默认值或本地注册表推测视觉模板。
- 模板 manifest 是模板结构、资源、编辑绑定、能力声明、preview fixture 和 bootstrap sample 的唯一事实来源。删除包外的重复 sample 注册表和 fallback。
- `BrandProfile.templateKey` 表示行业模型,不是视觉模板;模板版本选择只由正式安装记录的精确 package version 引用表达。视觉 renderer key 只存在于 package manifest。禁止在 `BrandProfile.config.visualTemplateKey` 或安装/版本表再存一份副本。
- 预览 fixture 与显式 bootstrap sample 是同一 manifest 契约中的不同用途;不为旧字段提供静默替代。必需声明缺失时阻断导入或操作。
- 不保留旧运行时读路径、双写、兼容窗口、字段别名或格式推断。现存数据库状态通过一次性、可审计、失败即停止的 migration 转成正式状态;迁移完成后删除旧列/JSON 键和旧代码路径。
- 不可变包版本、发布快照、显式升级和回滚属于当前契约下的正常生命周期能力,不属于兼容层。
- Web API、Admin Client、数据库模型和 package manifest 是同一契约的边界。任一形状变更必须在同一变更中更新生产者、消费者、迁移和测试,不另设旧格式分支。
## 考虑过的方案
- 长期双读并在缺字段时 fallback:拒绝。它保留歧义并使旧数据问题无法暴露。
- 先新增新模型并永久保留旧模型:拒绝。模型迁移必须有明确的切换和旧字段删除步骤。
- 一次性数据转换:采用。转换可保留既有品牌内容,但所有无法无歧义映射的记录必须报告并阻断,不能猜值。
- 删除所有历史模板版本:拒绝。历史版本可留作审计或回滚,但每个版本都必须满足同一 manifest 契约。
## 后果
- 缺少安装或包版本的品牌会显式报错,直到完成一次性数据迁移;不再被默认视觉模板掩盖。
- 需要清理重复的视觉模板状态、包外 sample registry、旧 manifest 推断、聚合状态读写和相应文档。
- 数据迁移需先生成只读差异报告;遇到缺失、冲突或未知 key 时停止,不覆盖品牌编辑内容。
- 模板包契约的 breaking change 必须通过一次整体迁移升级所有仓库包,不维护多份 runtime parser。
## 迁移计划
1. 使用 `pnpm template:migration:audit` 盘点品牌行业、旧视觉键、安装行和包版本;该命令只读,明确报告候选版本和阻断原因。
2. 仅可用品牌或安装记录中已有的明确 package key 作为一次性迁移来源。必须恰好匹配一个已发布版本,且 manifest 自身的 package key、version、visual renderer key、行业声明和 preview fixture 一致;不得按行业名推断 package key 或按版本号排序挑选。
3. 对唯一明确的映射回填 package version id、version、checksum 和 manifest snapshot。无映射、候选未发布、多候选、声明冲突或安装缺失均失败即停,由管理员先显式解决。
4. 未被品牌安装引用的历史无效快照保留原文供审计,不因缺少新契约字段而阻断迁移;其预览/安装仍由当前 manifest 契约校验拒绝。已安装版本必须通过完整迁移前置校验。
5. 成功后删除 config JSON 键及安装/版本表重复 renderer 列,并约束一品牌唯一安装。
6. 将 API、Admin、Runtime、发布快照、bootstrap 和构建路径切换到安装记录;缺失/损坏状态显式失败。
7. 删除默认映射、包外 sample fallback、旧格式推断和聚合字段兼容读写,补授权、成功和失败集成测试。
8. 运行 template doctor、数据库迁移、API integration、Admin production build、Taro 双端构建及完整格式/类型门禁。