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

7.1 KiB
Raw Blame History

ADR 0005:模板运行时、视觉风格与 Stitch 转换流程

  • 状态:已采纳
  • 日期:2026-09-22

背景

平台的核心目标是帮助已有业务的个人建立品牌、表达信任并获得咨询或合作。一个行业客户可能需要多种小程序视觉模板;不同行业又会有不同的业务字段、展示结构和操作流程。

当前的林境门作静态小程序验证了两件事:

  1. 个人品牌、信任内容、业务提供项、咨询和记录可以复用;
  2. 单纯使用固定 WXML 加少量文案配置,无法可靠覆盖高端门系统、摄影、咨询、餐饮等不同业务和视觉表达。

同时,设计生产流程使用 Google Stitch 生成设计图和 HTML,再由 AI 转换为小程序。如果直接把 HTML 改写成最终 WXML,设计结构、业务语义、接口能力和测试会互相脱节。

决策

1. 行业模板和视觉模板分离

一个客户工作空间由以下部分组成:

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、主题和能力契约。

运行时契约至少包含:

brand
navigation
modules
offerings
inquiryForms
capabilities
theme
schemaVersion

未知模块必须安全降级并产生可观测错误,不能导致整个页面崩溃。

4. 复杂业务由 Capability Plugin 提供

通用品牌展示和咨询属于核心能力。预约排期、上门量房、文件上传、地图、报价、库存、支付、项目状态和 CRM 同步属于可独立安装的 capability。

插件必须拥有明确的 API、数据模型、权限、Admin 配置页、小程序模块、状态转换、错误处理和自动化测试。模板只能声明依赖插件,不能隐藏实现业务流程。

5. Stitch HTML 不是业务协议

Stitch 产物进入平台的正式流程为:

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