Files
persionalBrand/docs/adr/0020-visual-editor-preview.md
T

43 lines
3.4 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.
# 0020:后台可视化页面编辑预览
## Context
后台已能根据模板 manifest 展示字段,但管理员难以判断字段对应小程序的哪个区块。Taro H5 renderer 可复用小程序页面结构;按模板分别构建和运行 H5 服务、编译时固定单个 renderer,则无法支撑多个品牌和模板的生产部署。
## Decision
采用基于模板 renderer 的可视化编辑器,并将 H5 预览作为同一套 Admin 产品的静态运行时:
1. `admin.sections` 是编辑字段分组,不等同 DOM 区块。section 声明稳定的 `previewTargets`,字段声明 `previewTarget`。
2. renderer 在可编辑区域输出 `data-editor-target`。新增模板必须为所有页面字段声明 binding 和 target,并通过自动发现的契约测试。
3. 一个 H5 预览应用在构建时收集所有带 Taro renderer 的模板包,运行时根据品牌当前模板选择 renderer。
4. 本地开发只启动一个 Vite H5 预览服务。生产构建将 H5 静态文件复制到 Admin `/template-preview/`,与 Admin 一起部署;线上不运行 Vite,也不按模板运行服务。
5. Admin iframe 与 renderer 使用带版本的 `postMessage` 协议,校验 origin、source 和协议版本。Admin 发送品牌草稿和 target focus;renderer 回传 target 选择。
6. 表单输入立即投影到预览草稿,保存仍是显式动作。失败时保留用户输入和草稿。
7. Admin 按模板契约运行,不按模板 key、行业名或字段名增加业务分支。
8. 信任内容、业务提供项、咨询表单等记录数据继续由通用 Admin feature 编辑;它们的页面区域需提供明确的对应编辑入口,不能冒充品牌 config 字段。
9. 不支持拖拽布局或持久化 HTML。
## Alternatives
- 在 Admin 复制一套 React 预览:会造成后台和小程序视觉分叉,弃用。
- 每模板单独构建并运行 H5 服务:开发和部署负担随模板数量增长,弃用。
- 生产环境运行 Vite:不是静态部署方案且扩大运行时依赖,弃用。
- 将 HTML 存进数据库:无法保持模板升级和字段 binding 一致,弃用。
- 一开始建设完整低代码画布:范围过大,暂缓。
## Consequences
- Preview build、静态资源打包和部署路径是 Admin 发布门槛。
- renderer 需要显式标记可编辑区域;漏掉的字段由模板契约测试拒绝。
- H5 iframe 使用当前已发布 workspace 作为底稿,管理员草稿只在客户端预览,不伪造已发布状态。
- 新模板新增 renderer 后自动进入 preview build;未实现 Taro renderer 的模板必须明确显示不支持,不能显示空白预览。
## Migration Plan
### 组件预览阶段补充
Admin 有 workspace 时直接复用 Taro renderer,iframe 保留为 H5 回退。组件预览必须补齐原运行环境的尺寸、元素选择器及资源映射:750 设计宽度通过容器单位转换,image/text/view 选择器映射到对应 DOM,模板静态资源经 Vite 打包。不得通过猜测 transform 系数修复单位不一致。此方案避免额外预览服务,但仍需验证所有模板的适配能力;当前 renderer 注册尚为显式列表,自动发现纳入后续任务。详见 `docs/visual-editor-next-steps.md`。
先实现单一多模板 H5 静态构建和 Admin 同源部署;补齐现有模板所有页面字段 target;验证即时草稿、保存失败和业务记录编辑入口;再将 preview build 纳入正式部署流水线。