# ADR 0005:模板运行时、视觉风格与 Stitch 转换流程 - 状态:已采纳 - 日期:2026-09-22 ## 背景 平台的核心目标是帮助已有业务的个人建立品牌、表达信任并获得咨询或合作。一个行业客户可能需要多种小程序视觉模板;不同行业又会有不同的业务字段、展示结构和操作流程。 当前的林境门作静态小程序验证了两件事: 1. 个人品牌、信任内容、业务提供项、咨询和记录可以复用; 2. 单纯使用固定 WXML 加少量文案配置,无法可靠覆盖高端门系统、摄影、咨询、餐饮等不同业务和视觉表达。 同时,设计生产流程使用 Google Stitch 生成设计图和 HTML,再由 AI 转换为小程序。如果直接把 HTML 改写成最终 WXML,设计结构、业务语义、接口能力和测试会互相脱节。 ## 决策 ### 1. 行业模板和视觉模板分离 一个客户工作空间由以下部分组成: ```text Brand Core + Industry Template + Visual Template + Capability Plugins + Runtime Workspace ``` 行业模板负责行业字段、Offering 结构、表单和默认模块;视觉模板负责布局、颜色、字体、图片比例、模块变体和页面顺序。一个行业可以安装多个视觉模板,视觉变化不得复制一套行业数据模型。 ### 2. 模板必须是声明式配置包 模板不允许注入任意代码,不得绕过核心鉴权、品牌隔离、发布状态和数据校验。模板包至少声明: - `templateKey`、版本和兼容范围; - 所需核心模块和可选模块; - Offering schema; - Inquiry schema; - 所需和可选 capability; - 默认主题 token; - 默认内容、图片槽位和模块顺序。 安装模板时生成品牌自己的配置快照。模板升级必须提供差异预览、显式确认和可回滚路径,不能覆盖品牌已经修改的内容。 ### 3. 小程序和 Admin 只消费 Runtime Workspace 后端将已安装的行业模板、视觉模板、模块配置和插件能力编译成稳定的 `RuntimeWorkspace`。小程序和 Admin 不根据 `templateKey` 编写行业分支,只依赖运行时模块、字段 schema、主题和能力契约。 运行时契约至少包含: ```text brand navigation modules offerings inquiryForms capabilities theme schemaVersion ``` 未知模块必须安全降级并产生可观测错误,不能导致整个页面崩溃。 ### 4. 复杂业务由 Capability Plugin 提供 通用品牌展示和咨询属于核心能力。预约排期、上门量房、文件上传、地图、报价、库存、支付、项目状态和 CRM 同步属于可独立安装的 capability。 插件必须拥有明确的 API、数据模型、权限、Admin 配置页、小程序模块、状态转换、错误处理和自动化测试。模板只能声明依赖插件,不能隐藏实现业务流程。 ### 5. Stitch HTML 不是业务协议 Stitch 产物进入平台的正式流程为: ```text Stitch 设计 / HTML -> 设计审查 -> Design Manifest -> Template Manifest -> 模块与能力映射 -> 小程序模板生成 -> 构建、接口、交互和视觉测试 -> 人工确认后发布 ``` `Design Manifest` 描述视觉 token、页面模块、布局和数据槽位;`Template Manifest` 描述行业字段、业务表单、模块组合和能力依赖。AI 负责解析和映射,不能直接把 HTML 作为生产运行时页面。 ### 6. 自定义模块采用受控逃生舱 标准模块无法表达的独特设计可以使用 `Custom Module`,但必须: - 声明输入 schema 和版本; - 只能读取 Runtime Workspace 数据; - 不能直接请求任意 API 或修改业务状态; - 实现加载、空态、错误态和基础无障碍行为; - 通过小程序构建、交互和视觉回归测试; - 记录模块版本和来源。 这允许保留行业和品牌的独特表达,同时避免每个客户生成一套不可维护的独立代码。 ## 实施阶段 ### Phase 0:冻结林境门作基线 - 保留当前静态版本作为视觉和交互基准; - 固化首页、案例、详情、咨询、成功、记录和主理人页面 fixture; - 记录已知设计差异和远程图片依赖。 ### Phase 1:Runtime Workspace - 定义 `TemplateManifest`、`ModuleManifest`、`CapabilityManifest` 和 `RuntimeWorkspace` schema; - 增加 DTO、版本校验、错误降级和 API 测试; - 让 Admin 与小程序消费同一运行时契约。 ### Phase 2:标准模块库 - 将现有固定页面拆分为品牌、信任、作品、Offering、详情、表单、记录、联系和成功模块; - 提取主题 token; - 支持模块顺序、可见性和模块变体; - 为模块建立单元测试和预览 fixture。 ### Phase 3:模板中心和安装快照 - Admin 支持行业模板和视觉模板浏览、预览、安装、差异、升级和回滚; - 记录安装来源、模板版本和用户修改; - 迁移 `personal`、`food` 和林境门作配置为正式模板包。 ### Phase 4:Capability Plugin - 先实现通用咨询和文件上传; - 再根据真实行业验证增加上门量房、日历排期或报价能力; - 插件具备 API、Admin、小程序和测试闭环。 ### Phase 5:双行业验证 使用差异明显的林境门作和摄影师模板验收: - 不修改 Brand Core; - 不增加小程序行业分支; - 使用不同视觉模板; - 使用不同表单 schema; - 使用不同 capability; - 两套模板同时通过交互和视觉测试。 ### Phase 6:Stitch 转换流水线 - 建立 HTML 解析和 Design Manifest 生成规范; - 自动识别不可映射模块和缺失能力; - 生成模板包、fixture 和测试; - 人工确认后才允许安装或发布。 ## 测试门槛 每套模板必须通过以下测试: 1. Schema:key、版本、模块、字段、能力依赖和入口完整性; 2. API:安装、升级、回滚、工作空间、品牌隔离和权限; 3. 小程序交互:首页、Tab、列表、详情、表单、成功页、记录、空态、错误态和禁用态; 4. 视觉回归:固定数据下的首页、列表、详情、表单、记录和主理人页面截图; 5. 构建门禁:格式化、类型检查、API 测试、小程序静态检查和生产构建。 任何模板不得以“页面能打开”作为交付标准。必须同时验证 API 路径、失败路径、数据快照、能力开关、用户操作语义和视觉基线。 ## 取舍与后果 - 运行时 schema 和模块库会增加前期工程成本,但能避免行业模板复制和客户端分支爆炸; - 模板自由度不会等同于任意代码自由度,极端设计需要通过受控 Custom Module 实现; - Stitch 到小程序不再是一键转换,而是经过 Manifest 和测试的编译流程; - 模板安装、升级和回滚需要额外的版本管理,但可以保护品牌的已编辑内容和历史记录; - 在完成 Runtime Workspace 和标准模块前,不继续批量增加行业页面。 ## 当前执行分支 后续相关工作在 `feat/template-runtime-platform` 分支推进。第一组交付为 Runtime Workspace schema、林境门作模板包迁移和固定测试 fixture;完成并通过检查后,才进入模板中心 UI 和插件能力实现。