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

@@ -63,6 +63,14 @@
 - 验证：运行触达文件的定向 `vitest`，必要时追加 `npm run typecheck`、`npm run check:encoding` 和 `git diff --check`。
 - 关联：`docs/technical/【前端测试】React组件测试准则-2026-06-26.md`、`src/components/image-editor/useCanvasGenerationDialogs.test.tsx`、`src/components/image-editor/ImageCanvasBottomToolbarView.test.tsx`。
 
+## 带 objectKey 的画布图片测试要等待换签后可见
+
+- 现象：测试点击“添加素材”后，图层状态已经写入，但立即用 `getByAltText('画布图片：...')` 偶发或稳定找不到图片；前一张图可能通过，紧接着添加的第二张失败。
+- 原因：带 `objectKey` 的画布图片通过 `useResolvedAssetReadUrl` 异步获取签名 URL，`resolvedUrl` 就绪前不会渲染带 `alt` 的 `<img>`。`user.click` 只等待点击交互完成，不等待 effect 内的换签 Promise；前一张图在后续操作期间出现只是调度时机，不是同步契约。
+- 处理：每次点击添加后分别用 `await screen.findByAltText(...)` 等待对应图片可见，再执行依赖该图层的下一步操作；不要用固定 sleep，也不要只等待最后一张图而让前面的断言依赖偶然调度。
+- 验证：先精确运行目标用例并连续重复，再运行所在测试文件和完整前端测试；删除场景仍要保留 A/B 都消失、两个删除调用和撤销不恢复已删除素材的断言。
+- 关联：`src/hooks/useResolvedAssetReadUrl.ts`、`src/components/image-editor/ImageCanvasWorldView.tsx`、`src/components/image-editor/ImageCanvasEditorAssetsIntegration.test.tsx`。
+
 ## 图片画布素材库删除要匹配 sourceResourceId
 
 - 现象：素材库中删除了已经生成并进入素材库的资源，但画布上对应图层仍然存在，刷新后还可能从已保存布局里恢复。

src/components/image-editor/ImageCanvasEditorAssetsIntegration.test.tsx

@@ -826,9 +826,9 @@ describe('ImageCanvasEditorView asset library integration', () => {
     await user.click(
       await screen.findByRole('button', { name: '添加账号素材A' }),
     );
+    expect(await screen.findByAltText('画布图片：账号素材A')).toBeTruthy();
     await user.click(screen.getByRole('button', { name: '添加账号素材B' }));
-    expect(screen.getByAltText('画布图片：账号素材A')).toBeTruthy();
-    expect(screen.getByAltText('画布图片：账号素材B')).toBeTruthy();
+    expect(await screen.findByAltText('画布图片：账号素材B')).toBeTruthy();
 
     fireEvent.keyDown(window, { key: 'ArrowRight', code: 'ArrowRight' });
     expect(screen.getByRole('button', { name: '撤销' })).toHaveProperty(