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