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

45 lines
3.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 集成测试覆盖「台账缺失仍可预览」「跨行业安装被拒且身份不漂移」「删台账后同行业安装可修复」,并用真实渲染复核后台页面。