Files
persionalBrand/docs/adr/0026-brand-single-industry-template.md
T
que01 6073e72940 feat: 收敛行业模板身份为品牌单一真相
- BrandProfile.templateKey 为唯一真相,安装记录降级为同模板的版本台账
- 安装只允许补建当前模板台账,跨行业模板请求返回 400,杜绝身份漂移
- preview 不再强制要求台账存在,台账缺失时以模板目录版本为准
- seed 按品牌身份补齐模板台账,消除「身份有、台账无」
- 记录 ADR 0026
2026-10-14 13:55:54 +08:00

3.6 KiB
Raw Blame History

0026 品牌单一行业模板与后台页面职责拆分

  • 状态:已采纳
  • 日期:2026-10-14

背景

后台的「模板与表单设置」页面把两类目标完全不同的事情放在了一起:日常经营(咨询入口表单、高级自定义字段)与半技术的模板治理(行业模板安装、模板版本升级/回滚、视觉模板切换、模板组合预览)。结果是运营者看到的页面既像内容配置页,又像技术设置页。

同时发现一个身份漂移问题:品牌的行业模板身份写在 BrandProfile.templateKey,但模板版本台账写在 BrandTemplateInstallation。旧实现里「品牌是否已使用某行业模板」以安装记录为准,seed 只写身份、不建台账,install 又允许换到另一个行业模板。于是可能出现「品牌在跑 A 模板、台账记的是 B」,并把发布快照接到不适配的视觉模板上。

决策

1. BrandProfile.templateKey 是唯一真相,一个品牌只使用一个行业模板

  • getEffectiveTemplateKey 优先读 BrandProfile.templateKey,BrandTemplateInstallation 降级为同一模板的版本台账,缺失时不再反过来改写品牌身份。
  • install 只允许为当前模板补建/修复台账;请求的行业模板与品牌身份不一致时返回 400,并说明「更换行业模板不在本版本范围内」。
  • 安装写入时同时落 templateKey 与台账,保证身份与台账一致;已自定义视觉模板的品牌在补建台账时保留原视觉选择。
  • preview 不再要求台账存在:台账缺失时以模板目录版本为当前版本,不报错。

2. 后台页面按「日常经营」与「模板治理」拆开

  • 咨询表单与字段(/admin/workspace)只负责咨询入口表单与高级自定义字段,归入「日常经营」,不再承载任何模板、视觉或组合预览。
  • 模板治理归入「配置与发布 → 内容发布」的「选择表达方式」:行业模板只读展示、视觉模板选择、模板版本升级与回滚。视觉模板是行业模板的排版变体,不是新的行业身份。

替代方案

  • 保留单一页面并把模板部分折叠收起:仍会让运营者看到技术设置,职责没有真正分开。
  • 增加第二条「模板切换」流程支持换行业:属于产品范围扩张,且与「模板是可替换的行业表达、品牌身份跨行业稳定」的既有边界冲突。
  • 只在 seed 里补齐台账而不加后端守卫:换行业模板仍会漂移,属于治标不治本。

后果

  • 品牌身份、模板台账、发布快照三者不会再互相漂移;公开运行时始终跑品牌当前的行业模板。
  • 行业模板不可在后台切换,切换到另一行业需要显式的产品与迁移方案。
  • 视觉模板切换历史/回滚、模板组合预览从 UI 中移除。当前每个行业实际只适配一个视觉模板,这两块属于不可达的死 UI。
  • 后台的模板治理不再是 owner 专属的高深设置,而是和发布放在同一处。

迁移计划

  • 后端:TemplateWorkspaceService 守卫与 preview 调整;seed 新增 ensureTemplateInstallation 按品牌身份补齐台账。
  • 前端:WorkspacePage 收敛为咨询表单与字段;PublicationPage 承接模板版本升级/回滚;CapabilitiesPage、main.tsx 导航与路由同步。
  • 文档:更新 apps/admin/design.md 页面结构表。
  • 验收:pnpm check,API 集成测试覆盖「台账缺失仍可预览」「跨行业安装被拒且身份不漂移」「删台账后同行业安装可修复」,并用真实渲染复核后台页面。