feat: 建立组件化模板预览基线并规划可视化编辑

This commit is contained in:
que01 committed 2026-10-09 12:32:24 +08:00
1 parent c5af790554
commit 0b14b5a814
46 files changed
+1880 -427

No files matched your search

+42
View File
@@ -0,0 +1,42 @@
# 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 纳入正式部署流水线。
+13 -2
View File
@@ -21,10 +21,21 @@ location /api/ {
}
```
构建管理后台时使用:
生产构建会先把所有已接入模板的 H5 renderer 编译进一个静态预览应用,再将其放到 Admin 的 `/template-preview/` 下。线上无需启动 Vite,也无需为每个模板运行单独服务。构建管理后台与预览应用时使用:
```bash
VITE_APP_BASE_PATH=/admin/ VITE_API_BASE_URL=/api pnpm --filter @personal-brand/admin build
pnpm build:admin:preview
```
部署时将 `apps/admin/dist` 作为同一个静态站点发布。预览 iframe 与 Admin 同源,运行时根据品牌公开工作区中的 `visualTemplateKey` 选择已打包的模板 renderer,并通过 `/api` 读取已发布数据;管理员正在编辑的草稿由 Admin 经 `postMessage` 投影到 iframe,不会写回公开 API。
本地开发只需启动一个多模板 H5 服务和 Admin:
```bash
pnpm preview:templates
VITE_APP_BASE_PATH=/ ADMIN_PORT=3000 pnpm --filter @personal-brand/admin dev
```
本地 Admin 默认连接 `http://localhost:3002` 上的统一预览服务。`VITE_TEMPLATE_PREVIEW_URL` 只用于部署时覆盖预览应用地址,不再按模板配置 URL map。
如果希望 API 服务自身也带前缀,可设置 `API_PREFIX=api`。使用 Nginx 去前缀转发时保持默认空值即可,避免重复 `/api/api`。
+39
View File
@@ -0,0 +1,39 @@
# 可视化编辑后续任务
## 当前基线
Admin 直接复用 Taro renderer,模板原始 CSS 按 750 设计宽度转换为预览容器单位,模板图片经 Vite 打包。已有区域点击、选中样式、品牌字段筛选、即时草稿和显式保存;保留 H5 iframe 作为回退。当前不代表所有页面、记录与字段均已完成编辑闭环。
## 1. 统一选区契约
- 统一 selection 为模板、页面、targetKey、实体类型、recordId;重复餐品和信任卡片必须带记录标识。
- 从 manifest 解析中文名称、binding、编辑能力,不在 Admin 中新增行业条件分支。
- 校验 target 存在、binding 可解析、页面归属正确;切页、删记录和换模板清理无效选区。
- 验收:嵌套区块选最近目标,重复卡片准确选中对应记录,未知目标不打开错误表单。
## 2. 完成点选与高亮交互
- 区分浏览模式与编辑模式;编辑模式阻止咨询提交、导航等真实操作。
- 使用独立覆盖层显示悬停边框、选中边框及中文区域名,避免改变模板背景、尺寸和布局。
- 覆盖层随滚动、容器尺寸、图片加载和字段换行更新;支持空白取消、Escape 取消及键盘选择。
- 验收:320/390 画布、长页面、滚动及图片加载后边框仍准确,不遮挡按钮和表单。
## 3. 打通绑定值编辑
- 右侧固定显示区域名称、数据来源、对应字段、未保存状态;点字段时定位关联区域。
- 品牌配置、业务记录、信任内容、咨询表单使用各自现有 API 和验证规则;记录 ID 由选区携带。
- 把当前仅跳转管理页的记录区域接入对应编辑器,复用原有表单与 mutation。
- 图片、列表、条件字段按模板声明渲染;空值、默认值、继承值明确区分。
- 验收:改值即时预览;保存后重新读取仍一致;失败保留输入并可重试;未保存切页给出明确选择。
## 4. 自动化验收和部署
- 按模板包自动发现 renderer、页面与资源,去掉现有 renderer 注册的手工二选一;未知模板明确显示不支持。
- 对每个模板覆盖首页、列表、详情、信任区及表单:选择→字段→草稿→保存→重载。
- 覆盖非空真实结构数据、嵌套/重复目标、授权失败、图片实际解码、样式尺寸和溢出;仅 DOM 存在不能作为视觉通过。
- 校验发布前后隔离:草稿不影响公开页面,发布后访客读取新值;受保护接口覆盖无凭证、错误角色及成功路径。
- 验收生产静态构建及子路径部署,不按模板新增 Vite 服务。
## 推进顺序
先完成选区契约与覆盖层,作为一个可验收提交;再分批接入记录编辑与保存语义;最后补齐跨模板测试和发布验收。每次提交展示具体可操作闭环,保留回退到当前分支基线的能力。