Files
persionalBrand/docs/adr/0008-visual-template-package-contract.md
T

32 lines
2.0 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.
# ADR 0008:小程序视觉模板包契约
## 背景
现有视觉模板只有颜色、圆角和少量页面变体,无法忠实承载 Stitch 设计中的页面结构、模块顺序、图片资源和数据依赖。继续在页面代码中增加行业分支会让视觉和业务耦合,且新品牌无法可靠导入初始内容。
## 决策
引入共享的 `VisualTemplateManifest` 和 `TemplatePackage` 契约。视觉 manifest 明确页面、模块、variant、设计 tokens、资源槽位、数据槽位和能力依赖;模板包在此基础上携带可导入的内容、表单、能力和 fixture。视觉模板只描述呈现结构,不写死行业字段;行业模板和能力插件通过数据槽位与能力 key 连接。
模板安装必须以 manifest 为边界,完成结构校验、数据导入和快照生成。Stitch HTML 仅作为映射输入,不能直接作为小程序运行时。
## 备选方案
- 继续扩展 `VisualTemplateDefinition`:无法表达资源、数据和安装边界,且容易继续堆叠可选字段。
- 每个行业复制一套 Miniapp 页面:视觉还原快,但品牌主线和跨行业复用失败,后续维护成本不可控。
- 直接运行 Stitch HTML:与小程序组件、接口、无障碍和测试体系不一致,不可作为生产方案。
## 后果
- 需要先建立 manifest 和映射,再改造 Miniapp 渲染器;短期类型和配置增加,长期可避免页面硬编码。
- 模板安装、升级、快照和回滚可以共享同一份契约;模板默认内容仍可被品牌编辑。
- 视觉回归需要固定 fixture 和截图基线,模板交付周期会增加,但能够在用户验收前发现明显偏差。
## 迁移计划
1. 定义共享类型并登记林境 manifest;
2. 将现有 `VisualTemplateDefinition` 兼容映射到新 manifest;
3. 改造 Miniapp 页面按页面 schema 和模块 registry 渲染;
4. 增加模板安装、初始数据导入和快照;
5. 以接口、构建、fixture 和截图测试作为发布门禁。