Merge remote-tracking branch 'origin/master' into fix/canva-preview-mismatch

# Conflicts:
#	src/components/image-editor/useImageCanvasProjectPersistence.test.tsx

docs/openapi/genarrative-external-v1.openapi.json

@@ -1761,7 +1761,8 @@
         "type": "object",
         "required": [
           "viewport",
-          "layers"
+          "layers",
+          "expectedRevision"
         ],
         "properties": {
           "viewport": {
@@ -1778,7 +1779,7 @@
           "expectedRevision": {
             "type": "integer",
             "minimum": 0,
-            "description": "可选的画布 revision CAS；不匹配时返回 409。"
+            "description": "必填的画布 revision CAS；不匹配时返回 409。"
           }
         },
         "additionalProperties": false

docs/project-memory/shared-memory/pitfalls.md

@@ -349,7 +349,7 @@
 
 - 现象：`/api/editor/projects*`、素材库、项目资源或 layout payload 里出现数 MB 的 `data:image/*`、`data:video/*`、`data:audio/*`，刷新恢复变慢，发布入口可能 OOM / 413，素材库缩略图还可能只显示文件名。
 - 原因：生成、规范图、角色图、图标 / UI spritesheet、音视频或动画帧如果直接把 Data URL / signed URL 写入 `editor_project_resource`、`editor_asset` 或 `editor_canvas.layers_json`，就把媒体本体塞进了项目快照；signed URL 还会过期，素材库也无法稳定换签。
-- 处理：登录态媒体必须先上传 OSS / asset object，持久化只写 `imageSrc: "/<objectKey>"`、`objectKey`、`assetObjectId`；素材库和图层缩略图都通过 `PlatformMediaFrame -> ResolvedAssetImage` 传 `objectKey` 并调用 `/api/assets/read-url`。layout 序列化和后端保存要递归拒绝 `data:*` / `blob:`；旧行有 `objectKey` 时读出归一成 `/<objectKey>`，没有 `objectKey` 的旧 Data URL 必须走修复上传后回写轻量引用。刷新恢复可先用 session 轻量缓存显示，但缓存不得含内联媒体，也不能在后端快照回来前自动保存。生成扣费、失败退款或 queue 终态后，右上角泥点余额通过 `/profile/dashboard` 回读，不做本地乐观扣减。
+- 处理：登录态媒体必须先上传 OSS / asset object，持久化只写 `imageSrc: "/<objectKey>"`、`objectKey`、`assetObjectId`；素材库和图层缩略图都通过 `PlatformMediaFrame -> ResolvedAssetImage` 传 `objectKey` 并调用 `/api/assets/read-url`。layout 序列化和后端保存要递归拒绝 `data:*` / `blob:`；旧行有 `objectKey` 时读出归一成 `/<objectKey>`，没有 `objectKey` 的旧 Data URL 必须走修复上传后回写轻量引用。刷新恢复可先用 session 轻量缓存显示，但缓存不得含内联媒体，必须按用户隔离，而且不能在后端快照回来前自动保存。认证状态变化重跑加载 effect 时，要同步用 ref 关闭写门禁并清除 revision、pending save 和 timer；不能只等 `isProjectReady=false` 的下一次 render，否则旧 effect 会先消费 skip 标记，再把公司浏览器的旧缓存无版本 PATCH 到服务端，覆盖另一台设备的新画布布局。现役 Web 与 External layout PATCH 的 `expectedRevision` 都必填，三层门禁分别放在 autosave effect、queue 和真正发送前；session cache 即使带 revision 也只有显示权。异步 project resource 创建必须把未发请求队列按用户 / 项目隔离，并记录发起时已接受的权威快照序号；若资源响应前发生认证重载、409 恢复或生成完成快照替换，只把新资源对应图层合并进当前权威布局，禁止用历史 `snapshotLayers` 整体覆盖。生成扣费、失败退款或 queue 终态后，右上角泥点余额通过 `/profile/dashboard` 回读，不做本地乐观扣减。
 - 验证：Network 中 `/api/editor/projects*`、`PATCH /api/editor/projects/{id}`、素材库接口不应出现 `data:image` / `data:video` / `data:audio`；素材库和图层面板缩略图都能换签显示；`npm run test -- src/components/image-editor/ImageCanvasEditorModel.test.ts src/components/image-editor/useImageCanvasProjectPersistence.test.tsx src/components/image-editor/ImageCanvasAssetRowView.test.tsx src/components/common/PlatformMediaFrame.test.tsx src/services/assetReadUrlService.test.ts src/services/image-editor/editorProjectClient.test.ts`，后端跑 `cargo test -p api-server editor_project --manifest-path server-rs/Cargo.toml`。
 - 关联：`server-rs/crates/api-server/src/editor_project.rs`、`src/components/image-editor/ImageCanvasEditorModel.ts`、`src/components/image-editor/useImageCanvasProjectPersistence.ts`、`src/components/common/PlatformMediaFrame.tsx`、`src/services/assetReadUrlService.ts`。
 

docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md

@@ -46,7 +46,7 @@
 - 吸附阈值以屏幕像素为准，换算到世界坐标后参与拖拽计算；边缘 / 中心线和等距吸附共用同一阈值。拖拽结束后只保存最终图层或生成占位布局，不保存临时参考线。
 - 项目页封面和画布图片图层必须先渲染项目卡、图层外框、标题、尺寸和操作 chrome；图片换签或解码未完成时，只在图片区域显示轻量加载态，不阻塞外框和文字等低成本信息先出现。
 - 素材量增大时，拖拽吸附热路径不得对所有素材做全量两两配对。边缘 / 中心线吸附保持线性扫描；等距吸附只在跨轴相交且轴向邻近的候选图层之间计算，避免大量远处素材拖慢 pointermove。
-- 画布自动保存使用防抖 + 串行队列：图层拖拽、缩放、资源新增和修改结果创建后延迟保存工程快照；如果上一次 `PATCH /api/editor/projects/{projectId}` 尚未完成，只保留最新待保存快照，待当前请求结束后再发送下一次保存，避免慢保存请求并发堆积触发发布入口连接限流。手型平移和小地图拖动属于临时 viewport 交互，拖动中只更新画布显示，不触发 `serializeCanvasLayout`、sessionStorage 项目缓存写入或封面快照上传，`pointerup` / `pointercancel` 后再保存最终 viewport。`PATCH /api/editor/projects/{projectId}` 只返回 `{ projectId, canvasId, updatedAt }` 轻量 ack，不再返回完整 project，前端必须以后续显式读取或生成完成返回的后端快照作为项目真相。
+- 画布自动保存使用防抖 + 串行队列：图层拖拽、缩放、资源新增和修改结果创建后延迟保存工程快照；如果上一次 `PATCH /api/editor/projects/{projectId}` 尚未完成，只保留最新待保存快照，待当前请求结束后再发送下一次保存，避免慢保存请求并发堆积触发发布入口连接限流。手型平移和小地图拖动属于临时 viewport 交互，拖动中只更新画布显示，不触发 `serializeCanvasLayout`、sessionStorage 项目缓存写入或封面快照上传，`pointerup` / `pointercancel` 后再保存最终 viewport。每次 `PATCH /api/editor/projects/{projectId}` 都必须携带最近一次服务端权威快照或保存 ack 给出的 `expectedRevision`；缺少版本号的请求在 HTTP 写入口直接拒绝，不允许回退到无版本覆盖。接口只返回 `{ projectId, canvasId, revision, updatedAt }` 轻量 ack，不返回完整 project；前端用 ack 更新后续保存版本，仍必须以后续显式读取或生成完成返回的后端快照作为项目真相。
 - 移动端保留同一套状态模型，底部工具栏可横向滚动，侧边栏默认可收起。
 - 项目页卡片默认点击打开工程；hover 项目卡片右下角显示 `...` 菜单，菜单承载重命名和删除。选择模式下项目卡片只切换选中态，不进入画布；底部批量工具栏提供全选 / 取消全选、已选数量、批量删除和退出选择模式。
 
@@ -68,7 +68,7 @@
 - 画布 Agent 会话按“SpacetimeDB 元数据 + OSS 消息正文”存储：`editor_agent_conversation` 只保存 `conversationId/projectId/ownerUserId/title/messagesObjectKey/deleted/createdAt/updatedAt` 等会话元数据；消息正文整体保存为私有 OSS JSON 文档 `editor-agent/{conversationId}.json`。消息文档单对象上限为 2 MiB，同一会话的消息追加和工具结果回填由 api-server 按 `conversationId` 串行化，避免“读 OSS → 改消息 → 写 OSS”并发覆盖。前端只通过 api-server BFF 读取和发送会话，不直接读写 SpacetimeDB，也不直接读写 OSS。
 - Agent 消息附件只允许引用当前工程画布资源或账号素材库图片，来源类型为 `canvas_resource` / `library_asset`，最多 9 张。附件请求可携带展示用 `imageSrc/thumbnailSrc/objectKey/width/height/label`，但持久化真相仍以后端校验后的 resource / asset 行和 OSS 对象为准；不得把 Data URL、signed URL 或 blob URL 当作会话长期事实。
 - 前端不直接订阅 SpacetimeDB，统一通过 api-server 的 `/api/editor/projects*` BFF 读写。
-- 工程刷新恢复可先应用 session 级轻量项目快照缓存，让画布和素材 chrome 尽快显示；缓存快照必须排除 `data:*` / `blob:` 内联媒体，且在后端项目快照返回前不得触发自动保存。后端快照回来后覆盖本地缓存显示并恢复正常保存队列。
+- 工程刷新恢复可先应用 session 级轻量项目快照缓存，让画布和素材 chrome 尽快显示；缓存 key 和 envelope 必须按当前用户隔离并携带 revision，缓存快照必须排除 `data:*` / `blob:` 内联媒体。session 缓存只提供显示，不授予写权限；项目加载或认证身份变化触发重载时，必须先通过同步 ref 关闭写门禁、清除 revision 与待保存 timer，只有本次服务端权威快照携带 revision 并应用完成后才重新开放保存。不能只依赖异步 `isProjectReady` state 阻止同一轮 effect，也不能把缓存中的 revision 当作权威写凭据。未创建的 project resource 队列必须绑定发起用户和目标项目；已发出的 resource 请求还要捕获发起时的权威快照序号，若响应前画布已被更新权威快照替换，只把本次新资源对应的单个图层合并到当前布局后用最新 revision 保存，不得恢复请求发起前的整份旧图层数组，也不得把一个用户的 pending 图层排入另一个用户项目。后端快照回来后覆盖本地缓存显示并恢复正常保存队列。
 - 未登录用户可以使用本地演示态，但不触发工程自动保存；真实图片生成 / 修改需要登录。编辑器 API 请求允许使用 refresh cookie 静默补 access token，但 401 / 403 只在编辑器局部提示登录，不清空整站登录态，也不把后端 requestId 直接作为生图弹窗主文案。
 
 ## 后端接口
@@ -77,7 +77,7 @@
 - `GET /api/editor/projects`：读取当前用户所有图片画布工程，按更新时间倒序返回。
 - `POST /api/editor/projects`：创建图片画布工程。
 - `GET /api/editor/projects/{projectId}`：读取指定工程及资源列表。
-- `PATCH /api/editor/projects/{projectId}`：保存 viewport 与图层布局快照；响应只包含 `{ projectId, canvasId, updatedAt }` ack，不返回完整工程快照。
+- `PATCH /api/editor/projects/{projectId}`：携带必填 `expectedRevision` 保存 viewport 与图层布局快照；响应只包含 `{ projectId, canvasId, revision, updatedAt }` ack，不返回完整工程快照。
 - `PATCH /api/editor/projects/{projectId}/metadata`：重命名指定工程。
 - `DELETE /api/editor/projects/{projectId}`：删除指定工程，并级联删除默认画布和资源元数据。
 - `POST /api/editor/projects/{projectId}/resources`：创建画布资源记录，接收上传资源或真实生成资源元数据。

docs/【编辑器】图片画布结构化持久化与迁移回滚方案-2026-07-19.md

@@ -45,7 +45,7 @@ layer 只表达“某个资源怎样放在画布上”。`src / prompt / actualP
 
 所有用户布局写入必须携带读取快照时获得的 `expectedRevision`。procedure 在事务中校验 canvas 当前 revision；不一致返回 `409`，前端应重载后端最新快照，不能只换上新 revision 就原样重放冲突前的整包布局。
 
-前端保存队列只对无 HTTP 响应的传输失败以及 `408 / 425 / 429 / 502 / 503 / 504` 做有界退避重试，`400 / 403 / 404 / 413` 等确定性错误不重复提交。若旧请求执行期间已有更新布局排队，旧请求失败后必须继续发送最新布局；`409` 后权威快照暂时加载失败时保留 pending save 并定时重新进入冲突恢复，不能等待用户再次拖动画布才恢复保存。
+前端保存队列只对无 HTTP 响应的传输失败以及 `408 / 425 / 429 / 502 / 503 / 504` 做有界退避重试，`400 / 403 / 404 / 413` 等确定性错误不重复提交。若旧请求执行期间已有更新布局排队，旧请求失败后必须继续发送最新布局；`409` 后冲突布局立即作废，权威快照暂时加载失败时保留冲突恢复状态并定时只重试 GET，不能把旧布局换上新 revision 后重放，也不能等待用户再次拖动画布才恢复。
 
 本次结构化 V1 先保留旧 `{ viewport, layers }` PATCH 作为兼容输入。legacy canvas 即使携带 `expectedRevision` 也只做 CAS legacy 保存，不允许用户写入绕过 migration operator 直接激活 structured；只有已完成 backfill / activate、且 active 迁移记录的 revision / hash / 数量 / 资源引用校验均通过时，后端才在单个事务内把兼容输入拆成 layer / dialog 行并递增一次 revision。旧无 CAS procedure 不得写 structured canvas。V1 快照从 typed 列重组，`item_json / dialog_json` 只保留最大 512 KiB 的未结构化扩展字段。自包含本地图片序列在 active canvas 中只能继续保存已回填且 `layerId / resourceId / sourceType / item_json` 语义完全一致的原行；允许修改几何、层级、分组、显隐等 typed 布局字段。前端序列化按正常资源真相边界省略 `assetKind / generationInputs` 时，后端只从既有结构化行恢复这两个冻结字段再校验；显式修改仍拒绝。active 路径不再经过 legacy 元数据清洗，拒绝新增缺资源序列或改写既有帧、预览、prompt 和生成扩展。后续将新增、移动、缩放、删除、重排和分组收窄为有界 batch mutation；在此之前 2 MiB 仍是兼容整包入口的上限。