diff --git a/docs/adr/0005-template-runtime-and-stitch-pipeline.md b/docs/adr/0005-template-runtime-and-stitch-pipeline.md new file mode 100644 index 0000000..e88c9b5 --- /dev/null +++ b/docs/adr/0005-template-runtime-and-stitch-pipeline.md @@ -0,0 +1,175 @@ +# 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 和插件能力实现。