# 图片画布编辑器 Lovart 化执行跟踪

更新时间：`2026-06-14`

## 目标

- 先落文档、测试用例和进度跟踪文件。
- 再实施 `/editor/canvas` 的 Lovart 风格画布交互、缩放二级菜单、吸附线、元数据窗口、真实生成 / 修改入口和工程 / 画布持久化。

## 进度

| 阶段 | 状态 | 记录 |
| --- | --- | --- |
| 文档 | 已完成 | 已补领域词、技术方案和后端表 / API 边界。 |
| 测试用例 | 已完成 | 已补前端交互测试和 editor project client 测试。 |
| 后端持久化 | 已完成 | 已新增 editor project/resource 表、SpacetimeDB procedure、spacetime-client facade 与 api-server BFF。 |
| 前端交互 | 已完成 | 已实现缩放菜单、工具模式、Space 抓手、中键平移、吸附线、元数据弹窗和右侧真实修改结果。 |
| 素材库增强 | 已完成 | 已实现账号级素材库持久化、文件夹新建 / 折叠 / 重命名 / 删除、多文件上传、拖拽定向上传、素材框选与批量删除。 |
| 画布增强 | 已完成 | 已实现拖拽上传到画布并创建图层、图层打组、Ctrl/Cmd 滚轮缩放、普通滚轮纵向滚动和小地图拖拽移动视图。 |
| 验证 | 已完成 | 聚焦测试、类型检查、Rust 检查、schema guard、编码检查、diff 空白检查和浏览器 smoke 已通过。 |

## 待办清单

- [x] 更新图片画布编辑器技术方案，明确 v2 范围。
- [x] 补充 `/editor/canvas` 领域词，区分图片画布工程和单图资产编辑。
- [x] 添加前端组件交互测试。
- [x] 添加 editor project API client 测试。
- [x] 新增 `editor_project`、`editor_canvas` 与 `editor_project_resource` 表。
- [x] 同步 SpacetimeDB migration 表清单、生成绑定和后端架构表目录。
- [x] 新增 api-server `/api/editor/projects*` BFF。
- [x] 接入前端自动保存与资源创建 API。
- [x] 实现 Lovart 风格缩放菜单和快捷键。
- [x] 实现 AI 画布底部工具栏、工具模式和临时抓手。
- [x] 实现核心吸附线和拖拽吸附。
- [x] 实现生成资源元数据窗口和真实修改右侧结果。
- [x] 执行并记录验证命令。
- [x] 新增 `/project` 项目页，接入项目列表、单项重命名 / 删除、批量选择和批量删除。
- [x] 接入“我的”页项目入口与 `/editor/canvas?projectid=<projectId>` 精准加载。
- [x] 新增账号级素材库表、API、前端服务和编辑器接入。
- [x] 素材文件夹支持新建、折叠、重命名和删除。
- [x] 上传按钮与拖拽上传均支持多文件；拖到文件夹 / 素材行进入对应文件夹，拖到画布进入默认文件夹并创建图层。
- [x] 素材选择模式支持框选多选和批量删除。
- [x] 图层面板支持对当前选中图层打组并持久化 groupId。
- [x] 小地图支持拖拽移动画布视图。
- [x] 滚轮语义调整为普通滚轮纵向滚动，Ctrl/Cmd 滚轮缩放并阻止浏览器缩放。

## 决策记录

- `/editor/canvas` 的长期领域对象命名为“图片画布工程的画布入口”。
- project 保存工程元数据；canvas 保存 viewport 与图层布局；资源表保存 OSS 引用和上传 / 生成元数据。
- 本期工程与资源持久化真实落库；图片生成 / 修改已接入 api-server VectorEngine BFF，暂不接入计费和队列进度。
- `适合视图` 的语义为显示画布所有可见元素。
- 吸附范围为核心对齐：左右 / 上下边缘和水平 / 垂直中心线。
- 缩放控件采用 Lovart 风格百分比按钮和二级菜单。

## 验证记录

- `npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx`
- `npm run test -- src/services/image-editor/editorProjectClient.test.ts`
- `npm run test -- src/routing/appPageRoutes.test.ts`
- `npm run typecheck`
- `cargo check -p spacetime-client --manifest-path server-rs/Cargo.toml`
- `cargo check -p api-server --manifest-path server-rs/Cargo.toml`
- `npm run check:spacetime-schema`
- `npm run check:encoding`
- `git diff --check`
- Headless Playwright smoke：`http://127.0.0.1:10000/editor` 可展示画布、缩放菜单、底部工具栏和图片工具栏；只启动 `dev:web` 时 `/api/*` 代理 500 属于未启动后端的预期现象。
- 2026-06-12 Lovart 布局修正 smoke：`http://127.0.0.1:10000/editor` 已移除左侧竖向工具栏和右侧独立图层栏；素材、已生成文件、图层统一收在左侧可折叠面板，中央画布和周边面板保持浅色一体布局；截图留存于 `output/playwright/editor-left-integrated-light.png`。
- 2026-06-12 外圈背景修正 smoke：`http://127.0.0.1:10000/editor` 的编辑器宿主和画布根容器已铺成同一块白色工作台，不再通过圆角边框露出底部平台背景；截图留存于 `output/playwright/editor-no-outer-background.png`。
- 2026-06-12 画布背景与原生菜单修正 smoke：`http://127.0.0.1:10000/editor` 已拦截编辑器区域右键菜单，禁用长按文本选择 / iOS callout，并移除画布网格线与棋盘格底纹；截图留存于 `output/playwright/editor-plain-background.png`。
- 2026-06-12 Lovart 面板与外层 padding 修正：`/editor` 外层 `platform-ui-shell` 已按 `image-editor` stage 使用 `p-0 bg-white`，其它页面保留原 padding；已生成文件和图层改为画布左下入口按钮触发的浮层面板，不再堆叠在左侧素材栏；浏览器样式检查确认 shell padding 为 `0px`、画布背景无 `background-image`，截图留存于 `output/playwright/editor-lovart-panel-popup-final.png`。
- 2026-06-12 侧栏切换修正：删除“已生成文件”入口，删除侧栏内展开 / 折叠按钮；画布左下仅保留“素材”和“图层”入口，二者复用同一个左侧栏，点击当前已打开入口会关闭侧栏。
- 2026-06-12 工具栏能力修正：删除底部“局部修改工具”入口；上传工具接入隐藏文件选择并将图片加入画布图层；图片浮动工具栏的删除按钮改为真实删除当前图层。
- 2026-06-12 生成工具修正：移除拼图素材的生成图 mock 元数据，使其作为普通素材显示；底部生成工具改为先打开生成图片对话框，再进入生成中状态并把生成结果加入画布，生成结果保留元数据与修改入口。
- 2026-06-13 真实生图修正：`/api/editor/images/generations` 和 `/api/editor/images/edits` 统一走 api-server VectorEngine `gpt-image-2` BFF；前端不再创建 mock 成功图，生成 / 修改失败会留在对话框内显示错误；生成图右上角 `{}` 元数据按钮可直接点击打开元数据窗口。
- 2026-06-13 素材库修正：素材栏按文件夹分组，文件夹支持折叠和新建；上传入口可定向到当前文件夹，上传素材进入素材库并支持删除，内置素材只保留添加和重命名。
- 2026-06-13 生图鉴权修正：编辑器工程和真实生图请求不再使用禁止 refresh 的局部鉴权策略，可通过 refresh cookie 静默补 access token；真实生图遇到 401 / 403 时弹窗显示“请先登录后再生成图片”，不再暴露后端 requestId 主文案。
- 2026-06-13 Lovart 生图交互修正：纯文本生图不再使用居中弹窗，点击底部生成工具后在画布中心显示 `Image Generator` 占位框，并在占位框下方显示跟随式生成输入框、参考图入口、比例和模型占位按钮；生成成功后真实图片落在占位框位置。
- 2026-06-13 Lovart 生图 smoke：`http://127.0.0.1:10003/editor` 点击底部生成工具后已显示画布内占位框和底部浮动输入框，截图留存于 `output/playwright/editor-lovart-generation-composer.png`。
- 2026-06-13 生图占位交互修正：`Image Generator` 占位框支持拖拽移动，生成输入框跟随占位框；生成成功图层沿用拖拽后的占位位置，生成输入框继续锚定在新生成图片下方，点击其它图片或画布空白不会自动关闭。
- 2026-06-13 生图锚定 smoke：`http://127.0.0.1:10003/editor` 中占位框拖拽前后坐标从 `(616,217)` 到 `(712,289)`，生成输入框同步从 `(516,571)` 到 `(612,643)`，保持锚定在生成对象下方；截图留存于 `output/playwright/editor-generation-composer-anchored.png`。
- 2026-06-13 Lovart 小地图与背景色修正：画布左下角补回背景色圆点、小地图开关和小地图预览；小地图展示图层缩略分布与当前视口框，点击执行显示所有元素，背景色菜单可切换工作区底色且不恢复网格 / 棋盘底纹。
- 2026-06-13 小地图与背景色 smoke：`http://127.0.0.1:10003/editor` 可见左下角小地图、背景色按钮和小地图开关；切换暖灰后画布工作区 `background-color` 为 `rgb(243, 240, 234)`，`background-image` 仍为 `none`；截图留存于 `output/playwright/editor-minimap-background-warm.png`。
- 2026-06-13 路由与数据归属修正：图片画布页面路由改为 `/editor/canvas`；新增 `editor_canvas` 表作为 project 下的画布数据表，当前工程创建时同步创建默认画布，保存 layout 时写入默认画布，API 响应同时返回 `project.canvas` 和兼容顶层 `viewport/layers`。
- 2026-06-13 项目页修正：新增 `/project` 作为图片画布工程列表入口；从“我的”页进入项目页，项目卡片进入 `/editor/canvas?projectid=<projectId>`，并补齐项目列表、重命名、删除和批量删除 API。`GET /api/editor/projects` 在重启后的 api-server 上返回未登录 401，不再是旧进程的 405；`/project` 前端路由 smoke 可渲染项目页白底布局。
- 2026-06-14 组件复用修正：项目页重命名弹窗改为复用 `UnifiedModal`、`PlatformTextField` 和 `PlatformActionButton`，删除项目页局部 modal / input 样式，避免同类弹窗和表单 chrome 重复实现。
- 2026-06-14 组件复用修正：新增 `PlatformFloatingMenu` / `PlatformFloatingMenuItem`，项目卡片右下角更多菜单改为复用平台浮层菜单原语；验证命令：`npm run test -- src/components/common/PlatformFloatingMenu.test.tsx src/components/project/ProjectGalleryView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
- 2026-06-14 组件复用修正：`PlatformFloatingMenu` 增加菜单标签和四向定位，编辑器顶部缩放菜单改为复用同一浮层菜单原语；验证命令：`npm run test -- src/components/common/PlatformFloatingMenu.test.tsx src/components/project/ProjectGalleryView.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
- 2026-06-14 组件复用修正：编辑器生成图元数据弹窗改为复用 `UnifiedModal`，不再手写元数据弹窗遮罩、dialog role 和关闭按钮；验证命令：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/common/UnifiedModal.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
- 2026-06-14 组件复用修正：编辑器“修改图片”弹窗改为复用 `UnifiedModal`，删除编辑器局部 modal backdrop、dialog role、header 和关闭按钮样式；验证命令：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/common/UnifiedModal.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
- 2026-06-14 组件复用修正：新增 `PlatformBatchActionToolbar`，项目页选择模式底部批量操作栏改为复用平台批量工具栏原语；验证命令：`npm run test -- src/components/common/PlatformBatchActionToolbar.test.tsx src/components/project/ProjectGalleryView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
- 2026-06-14 组件复用修正：项目页读取失败提示改为复用 `PlatformStatusMessage`，页面局部错误样式只保留布局间距；验证命令：`npm run test -- src/components/project/ProjectGalleryView.test.tsx src/components/common/PlatformStatusMessage.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
- 2026-06-14 组件复用修正：编辑器生成 / 修改流程中的生成中与失败提示改为复用 `PlatformStatusMessage`，删除局部状态条颜色和错误变体样式；验证命令：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/common/PlatformStatusMessage.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
- 2026-06-14 组件复用修正：编辑器画布背景色菜单改为复用 `PlatformFloatingMenu` 和 `PlatformFloatingMenuItem`，删除局部菜单容器定位 / 边框 / 阴影样式；验证命令：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/common/PlatformFloatingMenu.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
- 2026-06-14 组件复用修正：编辑器“修改图片”弹窗提交按钮改为复用 `PlatformActionButton`，删除局部提交按钮颜色、边框和禁用态样式；验证命令：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/common/PlatformActionButton.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
- 2026-06-14 组件复用修正：项目卡片预览改为复用 `PlatformMediaFrame`，删除项目页局部预览框比例、图片填充和背景样式；验证命令：`npm run test -- src/components/project/ProjectGalleryView.test.tsx src/components/common/PlatformMediaFrame.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
- 2026-06-14 素材库与画布持久化修正：新增 `editor_asset_folder` / `editor_asset` 账号级素材库表、SpacetimeDB procedure、spacetime-client facade 和 api-server `/api/editor/assets*` BFF；编辑器接入文件夹新建 / 折叠 / 重命名 / 删除、素材重命名 / 删除、多文件上传、拖拽定向上传、拖入画布生成图层、素材框选批量删除、图层打组、小地图拖拽、普通滚轮纵向滚动与 Ctrl/Cmd 滚轮缩放。验证命令：`npm run spacetime:generate -- --rust-only`、`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/services/image-editor/editorProjectClient.test.ts`、`npm run typecheck`、`npm run check:spacetime-schema`、`npm run check:encoding`、`cargo check -p spacetime-client -p api-server --manifest-path server-rs/Cargo.toml`、`git diff --check`。
- 2026-06-14 组件复用修正：编辑器 `EditorIconButton` 改为委托 `PlatformIconButton` 的薄包装，保留编辑器局部 class 与调用方式，但不再维护重复的原生图标按钮可访问性和基础 chrome；验证命令：`npm run test -- src/components/image-editor/ImageCanvasEditorPrimitives.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/common/PlatformIconButton.test.tsx`、`npm run typecheck`。
- 2026-06-14 组件复用修正：编辑器生成输入框的提交按钮改为复用 `PlatformActionButton`，仅保留生成器局部尺寸和 Lovart 式浅灰覆盖，不再直接维护原生 submit 按钮基础 chrome；验证命令：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/common/PlatformActionButton.test.tsx`、`npm run typecheck`。
- 2026-06-14 组件复用修正：编辑器生成输入框的“参考图”按钮改为复用 `PlatformIconButton variant="surfaceFloating"`，用 children 承载短标签，仅保留生成器局部尺寸和浅灰覆盖；验证命令：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/common/PlatformIconButton.test.tsx`、`npm run typecheck`。