Files
persionalBrand/docs/adr/0005-template-runtime-and-stitch-pipeline.md
T

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