Update Match3D/image-generation docs & code

Adds/updates documentation, assets and implementation for Match3D and puzzle image generation workflows. Key changes: decision logs and pitfalls updated to prefer VectorEngine Gemini for Match3D material sheets and to require edits (multipart) for 1:1 container reference images; guidance added for when to use APIMart vs VectorEngine. .env.example clarified APIMart/Responses config. Many new public assets and PPT visuals added. Code changes across frontend and backend: updated shared contracts, server-rs match3d/puzzle/image-generation handlers, VectorEngine/OpenAI image generation clients, and multiple React components/tests to handle UI/background/container image signing, edits workflow, and puzzle UI background resolution. Added src/services/puzzle-runtime/puzzleUiBackgroundSource.ts and related test updates. Includes notes about multipart HTTP/1.1 requirement and test/verification commands in docs.

src/components/match3d-runtime/Match3DRuntimeShell.test.tsx

@@ -474,6 +474,114 @@ test('运行态会换签并渲染抓大鹅中心容器 UI 图', async () => {
       screen.getByTestId('match3d-container-image').getAttribute('src'),
     ).toBe('https://oss.example.com/match3d-container.png');
   });
+  fireEvent.load(screen.getByTestId('match3d-container-image'));
+  expect(screen.getByTestId('match3d-board').className).toContain(
+    'bg-transparent',
+  );
+  expect(screen.getByTestId('match3d-board').className).not.toContain(
+    'rounded-full',
+  );
+});
+
+test('容器图换签失败时保留默认圆形容器兜底', async () => {
+  const run = startLocalMatch3DRun(3);
+  const generatedItemAssets: Match3DGeneratedItemAsset[] = [
+    {
+      itemId: 'match3d-item-1',
+      itemName: '草莓',
+      imageSrc: null,
+      imageObjectKey: null,
+      imageViews: [],
+      status: 'image_ready',
+      modelSrc: null,
+      modelObjectKey: null,
+      backgroundAsset: {
+        prompt: '果园纯背景',
+        imageSrc: null,
+        imageObjectKey: null,
+        containerPrompt: '果园浅盘容器',
+        containerImageSrc: null,
+        containerImageObjectKey:
+          'generated-match3d-assets/session/profile/ui-container/failing-task/container.png',
+        status: 'image_ready',
+        error: null,
+      },
+    },
+  ];
+  vi.spyOn(globalThis, 'fetch').mockRejectedValue(new Error('read-url failed'));
+
+  renderRuntime(run, generatedItemAssets);
+
+  await waitFor(() => {
+    expect(globalThis.fetch).toHaveBeenCalled();
+  });
+  expect(screen.queryByTestId('match3d-container-image')).toBeNull();
+  expect(screen.getByTestId('match3d-board').className).toContain(
+    'rounded-full',
+  );
+  expect(screen.getByTestId('match3d-board').className).not.toContain(
+    'bg-transparent',
+  );
+});
+
+test('运行态会从顶层 UI 资产加载背景和容器图', async () => {
+  const run = startLocalMatch3DRun(3);
+  vi.spyOn(globalThis, 'fetch').mockImplementation((input) => {
+    const url = String(input);
+    const signedUrl = url.includes('ui-container')
+      ? 'https://oss.example.com/match3d-container.png'
+      : 'https://oss.example.com/match3d-background.png';
+    return Promise.resolve(
+      new Response(
+        JSON.stringify({
+          read: {
+            signedUrl,
+            expiresAt: new Date(Date.now() + 60_000).toISOString(),
+          },
+        }),
+        {
+          status: 200,
+          headers: { 'Content-Type': 'application/json' },
+        },
+      ),
+    );
+  });
+
+  render(
+    <Match3DRuntimeShell
+      run={run}
+      generatedItemAssets={[]}
+      generatedBackgroundAsset={{
+        prompt: '果园纯背景',
+        imageSrc: null,
+        imageObjectKey:
+          'generated-match3d-assets/session/profile/background/task/background.png',
+        containerPrompt: '果园浅盘容器',
+        containerImageSrc: null,
+        containerImageObjectKey:
+          'generated-match3d-assets/session/profile/ui-container/task/container.png',
+        status: 'image_ready',
+        error: null,
+      }}
+      onBack={vi.fn()}
+      onRestart={vi.fn()}
+      onOptimisticRunChange={vi.fn()}
+      onClickItem={vi.fn()}
+    />,
+  );
+
+  await waitFor(() => {
+    expect(
+      screen.getByTestId('match3d-background-image').getAttribute('src'),
+    ).toBe('https://oss.example.com/match3d-background.png');
+    expect(
+      screen.getByTestId('match3d-container-image').getAttribute('src'),
+    ).toBe('https://oss.example.com/match3d-container.png');
+  });
+  fireEvent.load(screen.getByTestId('match3d-container-image'));
+  expect(screen.getByTestId('match3d-board').className).toContain(
+    'bg-transparent',
+  );
 });
 
 test('运行态从任意素材读取作品级背景音乐并换签播放', async () => {