# 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 纳入正式部署流水线。