# 低代码设计器工作台视觉统一
> status: done
> created: 2026-06-23
> complexity: 🟡中等

## 1. 背景与目标

`copyPage/src` 提供了一套更接近 Figma/低代码搭建器的工作台布局：顶部轻量工具栏、左右固定配置面板、中间页面切换条、点阵背景、居中白色页面和悬浮视图控制。当前 Forge 表单设计器和列表设计器虽然功能已经接近完成，但布局和视觉不统一：

- 表单设计器、列表设计器的左侧面板宽度、右侧面板宽度、顶部工具栏、页面切换条、画布背景和视图控制条分别维护。
- 表单设计器的缩放/视图控制是画布内绝对定位，滚动时存在被遮挡或找不到的问题。
- 列表设计器的 `list-page-switch`、`list-designer-head` 和页面配置行信息过多，占用中间工作区高度。
- 两个设计器按钮密度、分组样式、面板背景、选中态和滚动边界不一致，导致企业低代码产品感不稳定。

本次目标是只做布局、样式和展示交互统一，不改现有功能逻辑、数据协议、保存发布链路和拖拽判定逻辑。中间画布范围严格限定为：

1. 页面切换条。
2. 点阵背景。
3. 居中白色页面。
4. 悬浮视图控制。

可验证结果：

- 表单设计页和列表设计页进入后整体工作台风格一致。
- 中间画布看起来一致：上方页面切换条、浅色点阵底、居中白色页面、浮动视图控制。
- 列表设计 `list-page-switch` 不再占用过多高度，页面配置、参数和数据配置以更紧凑的面板/弹出层/折叠交互承载。
- 表单设计缩放/视图控制不再因为画布滚动和外层滚动而不可见。
- 保存、预览、发布、撤销重做、清空、拖拽、属性配置、页面切换功能行为保持不变。

## 2. 代码现状（Research Findings）

> 每个结论必须有代码出处（文件路径 + 类名/方法名）

### 2.1 参考页面

- `copyPage/src/app/layouts/RootLayout.tsx`
  - 使用 `Header + flex 三栏工作台`，整体 `h-screen bg-[#f8f9fa] overflow-hidden`。
  - 左右面板和中间画布共用一套浅灰背景、边框和固定高度布局。
- `copyPage/src/app/components/Header.tsx`
  - 顶部 48px 工具栏，左侧对象标识，中间工具胶囊，右侧保存/设置/预览/发布。
- `copyPage/src/app/components/LeftPanel.tsx`
  - 左侧 256px，搜索 + 分组 + 两列组件卡片。
- `copyPage/src/app/components/RightPanel.tsx`
  - 右侧 280px，属性/样式/交互三个 Tab，内容滚动。
- `copyPage/src/app/components/Canvas.tsx`
  - 中间区域使用页面切换条、点阵背景、居中白色页面和底部悬浮视图控制。
- `copyPage/src/app/components/canvas/PageDesignSwitcher.tsx`
  - 页面切换条采用三段式：左侧页面标题和简短信息，中间分段 Tab，右侧更多操作。

### 2.2 表单设计器现状

- `forge-admin-ui/src/views/app-center/components/designer/BusinessFormDesigner.vue`
  - `<template>` 中外层仍有 `designer-section-head` 和 `form-builder-grid`，形成表单设计独有的头部和工作区外框。
  - `<style scoped>` 中 `.business-form-designer` 使用 `grid-template-columns: minmax(0, 1fr) 280px`，与列表设计器内部三栏不同。
  - `.form-builder-grid` 当前有 `padding: 8px`、`background: #f8fafc`，会包一层额外工作区。
- `forge-admin-ui/src/views/app-center/components/designer/forge-form-designer/ForgeFormDesigner.vue`
  - `<template>` 已经是左侧 `ForgeFieldShelf`、中间 `ForgeFormCanvas`、右侧 `ForgePropertyPanel`。
  - `.forge-form-designer` 样式存在两段覆盖定义：先定义 `248px/336px`，后又覆盖成 `260px/350px`。
  - `.designer-toolbar` 是表单独有头部，按钮文字较多；`.designer-form-tabs-bar` 是表单切换条，但与列表 `list-page-switch` 样式不统一。
  - `handleCanvasDragStart()` 会拖拽时收起右侧面板，逻辑应保留。
- `forge-admin-ui/src/views/app-center/components/designer/forge-form-designer/ForgeFormCanvas.vue`
  - `.forge-form-canvas` 当前是线性网格背景，不是参考页点阵背景。
  - `.canvas-stage-shell` 和 `.canvas-stage` 已经具备居中白色页面能力。
  - `.canvas-viewport-dock` 是 `position: absolute; bottom/right`，在双层滚动场景下容易脱离用户视线。
  - `handleCanvasWheel()`、`applyCanvasPreviewMode()`、`updateDesignWidth()`、`updateCanvasZoom()` 已经具备鼠标缩放和视口控制能力，逻辑不应重写。
- `forge-admin-ui/src/views/app-center/components/designer/forge-form-designer/ForgeFieldShelf.vue`
  - 左侧已有搜索、组件库/字段资产 Tab、两列组件卡片。
  - 背景、分组标题、卡片 hover 和列表设计器 `palette-panel` 不完全一致。
- `forge-admin-ui/src/views/app-center/components/designer/forge-form-designer/ForgePropertyPanel.vue`
  - 右侧属性功能丰富，顶部是自定义按钮组，主体是 `n-tabs + n-collapse`。
  - 可在不改配置逻辑的前提下统一标题、Tab、搜索、折叠项和表单控件密度。

### 2.3 列表设计器现状

- `forge-admin-ui/src/views/app-center/components/designer/BusinessListDesigner.vue`
  - `.business-list-designer` 使用 `grid-template-rows: auto auto minmax(0, 1fr)`，顶部 `list-designer-head`、中间 `list-page-switch`、底部 `list-workspace`。
  - `.list-designer-head` 已经压缩到 40px，但仍与表单设计顶部工具栏样式不同。
  - `.list-page-switch` 同时承载页面切换、页面配置、参数配置、数据配置，导致高度过高。
  - `.page-config-row`、`.page-param-row`、`.page-data-row` 当前是铺开的卡片行，和参考页“切换条 + 更多操作”不一致。
  - `.list-workspace` 还有额外 `padding: 8px` 和滚动，和内部 `ListPageGridDesigner` 画布滚动叠加。
- `forge-admin-ui/src/components/lowcode-builder/page/ListPageGridDesigner.vue`
  - 顶层 `.list-grid-designer` 是三栏：`280px minmax(0, 1fr) 380px`。
  - `.canvas-panel` 已有点阵背景，但颜色和表单不统一。
  - `.canvas-grid` 是白色页面主体，和表单 `.canvas-stage` 语义类似。
  - `.canvas-viewport-dock` 当前在滚动区内 `position: sticky`，比表单稳定，但样式位置仍需统一。
  - `.canvas-toolbar` 仍显示 `1 个区块 · 20 行 × 12 列 · 1912px · 桌面 1920px / 58%` 这类中间信息，本轮应隐藏行列信息或移到非主展示。

## 3. 功能点

- [ ] 统一工作台框架
  - 输入：现有表单设计器和列表设计器页面结构。
  - 处理：调整模板层级和 scoped CSS，使两者拥有一致的顶部、左栏、中间、右栏、滚动边界和背景。
  - 输出：视觉一致的表单设计页和列表设计页。

- [ ] 统一页面切换条
  - 表单 `designer-form-tabs-bar` 和列表 `list-page-switch` 都对齐 `PageDesignSwitcher`：左侧标题/简短信息，中间分段页签，右侧更多操作。
  - 表单继续切换 `formAssets`，列表继续切换 list/create/edit/detail 等页面配置。
  - 列表页面配置、参数、数据配置从常驻铺开改为紧凑折叠或更多操作弹出，不改配置字段和更新函数。

- [ ] 统一中间画布四项视觉
  - 点阵背景：表单和列表使用同一套浅灰点阵底。
  - 居中白色页面：表单 `.canvas-stage` 和列表 `.canvas-grid` 视觉一致，半径、边框、阴影、留白一致。
  - 悬浮视图控制：表单和列表的视口/宽度/缩放控制使用同样位置、尺寸、图标按钮和弹出层样式。
  - 页面切换条和画布之间边界统一。

- [ ] 统一左侧面板
  - 表单 `ForgeFieldShelf` 和列表 `palette-panel` 的宽度、搜索框、分组标题、两列卡片、禁用态和折叠按钮统一。
  - 保留现有拖拽 MIME、点击追加、禁用原因和字段使用状态逻辑。

- [ ] 统一右侧属性面板
  - 表单 `ForgePropertyPanel` 和列表 `ListPageGridDesigner` 内右侧属性面板统一宽度、背景、标题区、Tab 样式、折叠卡片密度和滚动条。
  - 保留所有属性更新函数、选中逻辑、搜索和源码/交互入口。

- [ ] 按钮展示优化
  - 顶部只保留高频主操作。
  - 撤销/重做/源码/清空/重置/页面设置等次级动作进入图标按钮或更多菜单。
  - 图标按钮保留 `title`，不改变原点击回调。

## 4. 业务规则

- 不修改后端接口、数据库、运行态渲染协议。
- 不修改 `formDesignerSchema`、`pageSchema`、保存发布字段、接口路径和 payload 结构。
- 不修改拖拽容器接收规则、组件树插入规则、列表网格移动/缩放算法。
- 不新增 npm 依赖，不把参考页 React/Tailwind 代码直接迁入 Vue 项目。
- 中间画布只改页面切换条、点阵背景、居中白色页面、悬浮视图控制；画布内业务节点、字段节点、网格项渲染不做功能性改造。
- 可做展示交互：折叠、更多菜单、Popover、图标化按钮、右侧面板拖拽时自动收起、滚动边界优化。

## 5. 数据变更

| 操作 | 表名 | 字段/索引 | 说明 |
|------|------|-----------|------|
| 无 | - | - | 本次仅前端布局、样式和展示交互 |

## 6. 接口变更

| 操作 | 接口 | 方法 | 变更内容 |
|------|------|------|----------|
| 无 | - | - | 不改变接口协议 |

## 7. 影响范围

- `forge-admin-ui/src/views/app-center/components/designer/BusinessFormDesigner.vue`
- `forge-admin-ui/src/views/app-center/components/designer/forge-form-designer/ForgeFormDesigner.vue`
- `forge-admin-ui/src/views/app-center/components/designer/forge-form-designer/ForgeFormCanvas.vue`
- `forge-admin-ui/src/views/app-center/components/designer/forge-form-designer/ForgeFieldShelf.vue`
- `forge-admin-ui/src/views/app-center/components/designer/forge-form-designer/ForgePropertyPanel.vue`
- `forge-admin-ui/src/views/app-center/components/designer/BusinessListDesigner.vue`
- `forge-admin-ui/src/components/lowcode-builder/page/ListPageGridDesigner.vue`

## 8. 风险与关注点

- 表单和列表设计器都有嵌套滚动区，样式调整后要验证中间画布、右侧属性面板和页面外层不会出现双滚动干扰。
- 列表 `ListPageGridDesigner.vue` 文件较大，改动应集中在模板工具区和样式，不触碰网格拖拽、缩放、嵌套块逻辑。
- 表单 `ForgeFormDesigner.vue` 现有 scoped CSS 存在重复覆盖，清理时必须确认折叠状态 `left-collapsed/right-collapsed/right-open` 没有回退。
- 图标化按钮会减少文字说明，必须用 `title` 和可识别图标保证可用性。
- 本次不涉及资金、状态流转、权限变更。

## 8.5 测试策略

- **测试范围**：前端表单设计页、列表设计页、画布缩放/宽度控制、左右栏折叠、页面切换、保存入口、预览入口、拖拽基本路径。
- **覆盖率目标**：样式型变更不设新增单测覆盖率；以构建、lint 和手工视觉验收为主。
- **独立 Test Spec**：是。

## 9. 待澄清

- [ ] 是否确认进入编码阶段后，列表 `page-config-row/page-param-row/page-data-row` 可以从常驻展示改为折叠/弹出式展示，但字段和保存逻辑保持不变？

## 10. 技术决策

- 复用 Vue + Naive UI + scoped CSS，不引入新依赖。
- 优先在现有组件内整理模板和样式，只有出现明显重复且跨表单/列表都需要时，再考虑抽取共享 class。
- 颜色和尺寸按参考页收敛：
  - 页面背景：`#f8f9fa`。
  - 面板背景：左侧 `#fcfcfc`，右侧 `#fafafa`。
  - 边框：`#e4e4e7` / `#e5e7eb`。
  - 主强调：蓝靛色系，避免大面积单一蓝色背景。
  - 控件字号：11px、12px、13px 为主。
  - 左栏约 256px，右栏约 280px，顶部工具区约 48px。
- 视图控制统一为悬浮胶囊：图标触发，点击弹出输入框/选择器；缩放百分比作为紧凑文字按钮保留。

## 11. 执行日志

| Task | 状态 | 实际改动文件 | 备注 |
|------|------|--------------|------|
| Research | 完成 | 无 | 已对照 `copyPage/src`、表单设计器、列表设计器入口和画布组件 |
| Plan | 完成 | `code-copilot/changes/lowcode-designer-workbench-visual-unification/spec.md` | 本文档 |
| Apply | 完成 | 表单/列表设计器相关 Vue 文件 | 统一工作台、页面切换条、点阵画布、白色页面、悬浮视图控制和左右面板样式 |
| Verify | 完成 | 无 | targeted eslint、`pnpm --dir forge-admin-ui build`、`git diff --check` 均通过 |

## 12. 审查结论

待实现后补充。

## 13. 确认记录（HARD-GATE）

- **确认时间**：待确认
- **确认人**：待确认

## 归档记录（HARD-GATE）
- **状态**：done
- **归档时间**：2026-06-27
- **归档人**：yaomd（批量归档）
- **归档路径**：code-copilot/changes/archive/2026-06-27-lowcode-designer-workbench-visual-unification/
- **判定依据**：任务清单全部完成，execution-log 验证通过（编译/构建/lint 闭环）。