176 lines
7.1 KiB
Markdown
176 lines
7.1 KiB
Markdown
# 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 和插件能力实现。
|