Merge pull request '修复 UI 编辑器返回后资源画布平移' (#356) from fix/cant-pan-after-ui-editor into master

Reviewed-on: #356
Reviewed-by: 孔令弘 <ink29535@proton.me>

apps/ai-game-creator-shell/src-tauri/src/ui_editor/commands/separation/persistence.rs

@@ -265,11 +265,11 @@ pub fn inspect_separation_recovery(
 }
 
 pub fn finalize_separation(root: &Path, asset_id: &str) -> Result<(), String> {
-    remove_separation_state(root, asset_id)
+    remove_separation_recovery_files(root, asset_id)
 }
 
 pub fn discard_separation_recovery(root: &Path, asset_id: &str) -> Result<(), String> {
-    remove_separation_state(root, asset_id)
+    remove_separation_recovery_files(root, asset_id)
 }
 
 fn remove_separation_state(root: &Path, asset_id: &str) -> Result<(), String> {
@@ -281,6 +281,33 @@ fn remove_separation_state(root: &Path, asset_id: &str) -> Result<(), String> {
     }
 }
 
+fn remove_separation_recovery_files(root: &Path, asset_id: &str) -> Result<(), String> {
+    let sidecar = separation_sidecar_dir(root, asset_id)?;
+    remove_separation_state(root, asset_id)?;
+    let entries = match fs::read_dir(&sidecar) {
+        Ok(entries) => entries,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(()),
+        Err(error) => return Err(format!("读取 separation 临时文件失败：{error}")),
+    };
+    for entry in entries {
+        let entry = entry.map_err(|error| format!("读取 separation 临时文件失败：{error}"))?;
+        let name = entry.file_name();
+        let name = name.to_string_lossy();
+        if name.starts_with("processed-") || name.starts_with("binding-") {
+            let path = entry.path();
+            if entry
+                .file_type()
+                .map_err(|error| format!("检查 separation 临时文件失败：{error}"))?
+                .is_file()
+            {
+                fs::remove_file(&path)
+                    .map_err(|error| format!("删除 separation 临时文件失败：{error}"))?;
+            }
+        }
+    }
+    Ok(())
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

apps/ai-game-creator-shell/src/view/project-development/index.tsx

@@ -4633,7 +4633,12 @@ export default function ProjectDevelopmentView({
       passive: false,
     });
     return () => manager.removeEventListener('wheel', handleResourceBookWheel);
-  }, [handleResourceBookWheel, mode]);
+  }, [
+    handleResourceBookWheel,
+    mode,
+    // UI 编辑器会卸载整个资源 manager；返回时 ref 指向新节点，必须重新绑定原生 wheel。
+    uiEditorRoute,
+  ]);
 
   const handleResourceBookMainPointerDown = useCallback(
     (event: ReactPointerEvent<HTMLDivElement>) => {

apps/ai-game-creator-shell/src/view/ui-editor/useUiEditorPage.ts

@@ -1212,7 +1212,15 @@ export function useUiEditorSession(
           '自动切分素材结果已写入编辑器，但 State 保存失败；sidecar 已保留，可继续恢复。',
         );
       }
-      if (backfillErrors.length > 0) {
+      if (
+        backfillErrors.length > 0 ||
+        completedResult.problematic_nodes.length > 0
+      ) {
+        if (completedResult.problematic_nodes.length > 0) {
+          backfillErrors.push(
+            `${completedResult.problematic_nodes.length} 个节点达到返工上限，需要人工处理`,
+          );
+        }
         const recovery = await invoke<SeparationRecoveryDTO>(
           'inspect_separation_recovery',
           { projectPath, assetId: resourceId },

apps/ai-game-creator-shell/tests/appSurface/harness.ts

@@ -1227,6 +1227,32 @@ async function openMainProject(projectPath: string) {
   ).not.toBeNull();
 }
 
+export function installResizeObserverStub() {
+  let observerCount = 0;
+  let observerDisconnected = false;
+  class TestResizeObserver {
+    constructor(readonly callback: ResizeObserverCallback) {
+      observerCount += 1;
+    }
+
+    observe() {}
+
+    unobserve() {}
+
+    disconnect() {
+      observerDisconnected = true;
+    }
+  }
+  Object.defineProperty(window, 'ResizeObserver', {
+    configurable: true,
+    value: TestResizeObserver,
+  });
+  return {
+    observerCount: () => observerCount,
+    observerDisconnected: () => observerDisconnected,
+  };
+}
+
 beforeEach(() => {
   resetLlmModelCatalogCacheForTest();
   vi.spyOn(clientApi, 'loadClientLlmModels').mockResolvedValue({

apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts

@@ -34,6 +34,7 @@ import {
   GAME_CREATION_AGENT_RUN_SCHEMA_VERSION,
   type GameCreationAgentRunTrace,
   getResourceSelectButton,
+  installResizeObserverStub,
   it,
   mockRoleAgentReply,
   openResourceFilterPanel,
@@ -4708,25 +4709,7 @@ export function registerProjectWorkbenchFoundationTests() {
         manuallyPlaced: false,
       },
     ];
-    let observerCount = 0;
-    let observerDisconnected = false;
-    class TestResizeObserver {
-      constructor(readonly callback: ResizeObserverCallback) {
-        observerCount += 1;
-      }
-
-      observe() {}
-
-      unobserve() {}
-
-      disconnect() {
-        observerDisconnected = true;
-      }
-    }
-    Object.defineProperty(window, 'ResizeObserver', {
-      configurable: true,
-      value: TestResizeObserver,
-    });
+    const resizeObserver = installResizeObserverStub();
     const animationFrame = vi.spyOn(window, 'requestAnimationFrame');
     const originalGetBoundingClientRect =
       HTMLElement.prototype.getBoundingClientRect;
@@ -4818,7 +4801,7 @@ export function registerProjectWorkbenchFoundationTests() {
         /^url\(#.+-asset-reference-arrow\)$/u,
       );
     });
-    expect(observerCount).toBe(1);
+    expect(resizeObserver.observerCount()).toBe(1);
     expect(
       overlay
         .querySelector('[data-testid="resource-dependency-overlay-scene"]')
@@ -4865,7 +4848,7 @@ export function registerProjectWorkbenchFoundationTests() {
       ),
     );
     rendered.unmount();
-    expect(observerDisconnected).toBe(true);
+    expect(resizeObserver.observerDisconnected()).toBe(true);
     expect(removeViewportListener).toHaveBeenCalledWith(
       'scroll',
       expect.any(Function),
@@ -5916,6 +5899,144 @@ export function registerProjectWorkbenchFoundationTests() {
     );
   });
 
+  it('restores resource canvas panning after returning from the UI editor', async () => {
+    installResizeObserverStub();
+    const manifest = createGameCreationAppManifest(
+      'workbench-ui-editor-return-pan',
+      'UI 编辑器返回平移测试',
+    );
+    manifest.assets = [
+      {
+        id: 'ui-design-resource',
+        kind: 'UI',
+        mediaType: 'application/json',
+        localPath: 'assets/ui-design.json',
+        source: { kind: 'generated' },
+      },
+    ];
+    const invoke = vi.fn(
+      async (command: string, args?: Record<string, unknown>) => {
+        if (command === 'read_local_project_resource_graph') {
+          return resourceGraphForInputs(args);
+        }
+        if (command === 'read_local_project_resource_canvas_layout') {
+          return {
+            schemaVersion: 'game-creator-resource-layout.v1',
+            projectId: manifest.projectId,
+            mode: args?.mode,
+            revision: 0,
+            positions: [],
+            updatedAt: 0,
+          };
+        }
+        if (command === 'update_local_project_resource_canvas_layout') {
+          return {
+            status: 'updated',
+            layout: {
+              schemaVersion: 'game-creator-resource-layout.v1',
+              projectId: manifest.projectId,
+              mode: args?.mode,
+              revision: 1,
+              positions: args?.positions,
+              updatedAt: 1,
+            },
+          };
+        }
+        if (command === 'load_ui_design_state') {
+          return {
+            revision: 0,
+            state: {
+              ui_trees: [],
+              ui_design_images: {},
+              sprite_assets: {},
+              font_assets: {},
+            },
+          };
+        }
+        throw new Error(`unexpected invoke ${command}`);
+      },
+    );
+    window.__TAURI__ = { core: { invoke } };
+    render(
+      React.createElement(ProjectDevelopmentView, {
+        projectName: manifest.name,
+        projectPath: '/tmp/workbench-ui-editor-return-pan',
+        manifest,
+        attachments: [],
+        recentRunStatus: null,
+        recentRunStopReason: null,
+        supervisor: React.createElement('div', null, '项目总控'),
+        onHomeOpen: vi.fn(),
+        onProjectsOpen: vi.fn(),
+      }),
+    );
+
+    await openResourceBookCategory('UI 交互');
+    const canvas = await screen.findByRole('region', { name: 'UI 交互' });
+    const scene = document.querySelector<HTMLElement>(
+      '[data-resource-book-view="child"] .game-resource-book-scene',
+    );
+
+    const wheel = (target: HTMLElement, deltaY: number) => {
+      const event = new WheelEvent('wheel', {
+        bubbles: true,
+        cancelable: true,
+        deltaY,
+        clientX: 120,
+        clientY: 100,
+      });
+      act(() => target.dispatchEvent(event));
+      expect(event.defaultPrevented).toBe(true);
+    };
+    wheel(scene ?? canvas, 120);
+    const world = canvas.querySelector<HTMLElement>('[data-resource-viewport]');
+    expect(world?.getAttribute('data-resource-viewport')).toMatch(
+      /^(?!48,48,1)/u,
+    );
+
+    fireEvent.click(
+      screen.getByRole('button', {
+        name: '选中资源：UI 交互 ui-design.json',
+      }),
+    );
+    fireEvent.click(await screen.findByRole('button', { name: 'UI 编辑器' }));
+    await screen.findByRole('button', { name: '返回资源' });
+    fireEvent.click(screen.getByRole('button', { name: '返回资源' }));
+    await waitFor(() =>
+      expect(screen.queryByRole('button', { name: '返回资源' })).toBeNull(),
+    );
+
+    const restoredCanvas = await screen.findByRole('region', {
+      name: 'UI 交互',
+    });
+    const restoredWorld = restoredCanvas.querySelector<HTMLElement>(
+      '[data-resource-viewport]',
+    );
+    const beforeReturn = world?.getAttribute('data-resource-viewport');
+    const restoredBeforePan = restoredWorld?.getAttribute(
+      'data-resource-viewport',
+    );
+    expect(restoredBeforePan).toBe(beforeReturn);
+
+    const restoredScene = document.querySelector<HTMLElement>(
+      '[data-resource-book-view="child"] .game-resource-book-scene',
+    );
+    const restoredWheelEvent = new WheelEvent('wheel', {
+      bubbles: true,
+      cancelable: true,
+      deltaY: 120,
+      clientX: 120,
+      clientY: 100,
+    });
+    act(() =>
+      (restoredScene ?? restoredCanvas).dispatchEvent(restoredWheelEvent),
+    );
+    expect(restoredWheelEvent.defaultPrevented).toBe(true);
+    expect(restoredWorld?.getAttribute('data-resource-viewport')).not.toBe(
+      restoredBeforePan,
+    );
+  });
+
   it('clears the resource preview cache and cancels the old preview scope on project switch', async () => {
     // 60d8b8fbb 删掉了从未被写入的 `resourcePreviewVersionByResourceId` 死接线，原先钉
     // 那条 prop 与它的清空语句的断言随之取消；用例真正要守的意图不变——项目切换必须把

deploy/container/api-server.env.example

@@ -65,11 +65,5 @@ GENARRATIVE_LLM_PROVIDER=openai-compatible
 GENARRATIVE_LLM_BASE_URL=https://api.vectorengine.cn/v1
 GENARRATIVE_LLM_API_KEY=
 GENARRATIVE_LLM_MODEL=gpt-5.4-mini
-# AGC 官方 LLM Router：api / all 角色启动时硬校验官方 HTTPS 地址、固定模型和以下三个密钥，缺失直接拒绝启动。
-# 容器预览的密钥来自镜像内 /srv/genarrative/.env.secrets.local（Jenkins 预览 secrets 副本），
-# 该副本必须包含 GENARRATIVE_LLM_ROUTER_PROVISIONING_SECRET、
-# GENARRATIVE_LLM_ROUTER_API_KEY_ENCRYPTION_SECRET 和 GENARRATIVE_LLM_ROUTER_ADMIN_TOKEN。
-# 本文件只用于按实例显式覆盖；容器环境变量留空时仍由镜像内 .env.secrets.local 提供取值。
-# GENARRATIVE_LLM_ROUTER_BASE_URL=https://router.genarrative.world/v1
 WECHAT_MINIPROGRAM_MESSAGE_TOKEN=
 WECHAT_MINIPROGRAM_MESSAGE_ENCODING_AES_KEY=

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

@@ -1,5 +1,13 @@
 # 踩坑与排障记录
 
+## 2026-09-14 UI 编辑器返回后资源画布滚轮平移失效
+
+- **现象**：资源管理打开 UI 编辑器再返回后，资源画布滚轮平移/缩放不再响应；返回前同一手势正常。
+- **原因**：资源画布的非 passive `wheel` 监听绑定在 `resourceBookManagerRef` 当前 DOM 上，但 effect 只依赖 `handleResourceBookWheel` 与 `mode`。UI 编辑器切换会卸载旧 manager 并挂载新 manager，依赖不变导致新节点没有重新绑定监听。
+- **处理**：将 `uiEditorRoute` 纳入 wheel effect 依赖，使进入/退出 UI 编辑器时先清理旧节点监听，再给返回后的新 manager 绑定同一处理器。
+- **验证**：`npx vitest run apps/ai-game-creator-shell/tests/appSurface.test.ts -t "restores resource canvas panning"`；回归用例覆盖打开栏目、wheel 平移、进入 UI 编辑器、返回并再次 wheel 平移。
+- **关联**：`apps/ai-game-creator-shell/src/view/project-development/index.tsx`、`apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts`。
+
 ## 2026-09-14 AGC 壳 Rust 套件按「一片一 job」拆分，且分片必须自校验覆盖
 
 - **现象**：`AI game creator shell Rust tests` 一直是客户端 CI 的关键路径。run 2097 实测 15 分 27 秒，其中 `apps/ai-game-creator-shell/src-tauri` 的 bin target 单测（2466 条）一条 `cargo test -- --test-threads=1` 串行占 507 秒。
@@ -5197,7 +5205,6 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - 外层 `start-tauri-dev.mjs` 应在启动 Tauri 前完成配套开发服务准备，并统一收束自有服务进程树；不要让冷编译和数据库发布挤占 Tauri 的前端就绪等待。自动发布必须保留数据库，不能靠清库解决启动问题。
 - CLI 与 standalone 可能是两个独立软链接。必须同时核对 `spacetime --version` 和 `spacetimedb-standalone --version`，不能把 CLI 的版本记录当作宿主版本证明；PATH 中存在宿主时启动器检查两者一致。更换宿主前停机备份数据，按原目录启动，不通过清库处理版本错配。
 - Router 配置缺失不应只在首次请求时报错。API/All 启动必须先校验官方地址、固定模型、provisioning secret、管理员 Token 和凭据加密密钥；否则服务看似 healthy，但登录后的 provisioning/模型调用才延迟失败。
-- 容器预览没有独立的 Router 配置来源，密钥只能来自 Jenkins 预览 secrets 副本内置的 `.env.secrets.local`。新增启动期密钥校验时必须同步维护该副本并重建预览镜像，否则表现为 api-server 退出码 1、nginx 停在 `Created`、worker 反复报“模型定价服务身份尚未初始化”，而 systemd 生产路径仍然正常，容易误判成容器或数据库问题。
 
 ## 共享画布框选需要识别 world 的真实后代命中
 

docs/technical/【开发运维】Jenkins容器预览部署控制面技术方案-2026-08-15.md

@@ -55,8 +55,6 @@ Jenkins 节点上的预览 `.env.local` 与 secrets 只允许来自受控的 Jen
 
 宿主固定目录应由 Jenkins 运行账号所有且权限为 `0700`，两个源文件权限均为 `0600`；缺失、不是普通文件、owner 不匹配或权限过宽时，预览构建必须失败关闭。任一源文件变更后必须重新构建并替换 API 与 worker 预览镜像，只重启容器不会刷新已内置的内容。容器启动时显式注入的运行环境变量优先级高于镜像内的 `.env.local` 与 `.env.secrets.local`，用于按实例覆盖非通用值。
 
-预览 secrets 副本还必须包含 AGC 官方 Router 的三个密钥：`GENARRATIVE_LLM_ROUTER_PROVISIONING_SECRET`、`GENARRATIVE_LLM_ROUTER_API_KEY_ENCRYPTION_SECRET` 与 `GENARRATIVE_LLM_ROUTER_ADMIN_TOKEN`。容器 `api` / `all` 角色启动时会硬校验官方 HTTPS 地址、固定模型和这三个密钥，缺失时 api-server 立即以退出码 1 结束，`nginx` 停在 `Created`、`external-generation-worker` 因模型定价服务身份未初始化而反复重启。该失败发生在镜像构建和模块发布之后，因此新增任何启动期密钥校验时必须同步维护预览 secrets 副本并重建镜像，不能等预览页面报错再排查。
-
 这种方案只隐藏构建传输过程，不能让内置后的 secrets 对镜像持有者保密：能读取、保存或运行 `api-runtime` 镜像的人可以提取该文件。因此该镜像只能留在当前受信任内网 Docker 主机，禁止 push 到公共或跨信任边界的 registry，也禁止通过 `docker save`/构建 artifact 导出传播。需要跨边界分发时必须改用不含 secrets 的镜像与运行时密钥注入。
 
 ## Jenkins 参数与产物

docs/【开发运维】本地开发验证与生产运维-2026-05-15.md

@@ -969,4 +969,3 @@ node scripts/rebind-orphan-work-owners.mjs --in <exported-migration.json> --out
 
 `scripts/deploy/maintenance-on.sh` 只允许把同目录临时普通文件原子替换到普通文件或尚不存在的 `page.html` / `enabled` 目标。目标只要是符号链接（包括指向目录的链接）或目录，脚本必须在替换前失败，不能跟随链接把临时文件移入链接目标，也不能打印“已进入维护模式”。`page_temp` 与 `marker_temp` 必须在 `set -u` 下安全初始化，清理 trap 必须在首次 `mktemp` 前生效；任一失败退出都不得在目标同级遗留 `page.html.tmp.*` 或 `enabled.tmp.*`，成功替换后则清空临时路径并解除 trap，不能误删已安装目标。跨平台实现继续使用 POSIX `mv -f`，安全语义由替换函数的目标类型门禁保证；修改后运行 `bash -n scripts/deploy/maintenance-on.sh` 与 `npm run check:maintenance-page`。
 api-server 启动时会硬校验 AGC 官方 Router 配置：API/All 角色必须使用官方 HTTPS 地址和固定模型，并配置 provisioning secret、Router 管理员 Token，以及专用加密 secret 或有效 JWT secret；缺失或不匹配直接拒绝启动。`test` 环境仅允许 loopback fixture，worker-only 角色不执行 Router 配置校验。
-容器与 Jenkins 预览路径同样受该校验约束，且密钥只能来自预览 secrets 副本内置的 `.env.secrets.local`：缺少上述三个密钥时，预览的 api-server 容器启动即退出，`nginx` 与 `external-generation-worker` 连带失败。维护预览环境时必须先补齐这三个键并重建镜像。