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/hooks/useResolvedAssetReadUrl.test.tsx

@@ -1,10 +1,13 @@
 // @vitest-environment jsdom
 
-import { render, screen, waitFor } from '@testing-library/react';
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
 import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
 
 import { ResolvedAssetImage } from '../components/ResolvedAssetImage';
-import { clearStoredAccessToken, setStoredAccessToken } from '../services/apiClient';
+import {
+  clearStoredAccessToken,
+  setStoredAccessToken,
+} from '../services/apiClient';
 import { clearSignedAssetReadUrlCache } from '../services/assetReadUrlService';
 
 describe('useResolvedAssetReadUrl', () => {
@@ -59,7 +62,9 @@ describe('useResolvedAssetReadUrl', () => {
     expect(screen.queryByRole('img', { name: '候选图' })).toBeNull();
 
     const image = await screen.findByRole('img', { name: '候选图' });
-    expect(image.getAttribute('src')).toBe('https://signed.example.com/puzzle.png');
+    expect(image.getAttribute('src')).toBe(
+      'https://signed.example.com/puzzle.png',
+    );
     expect(globalThis.fetch).toHaveBeenCalledTimes(1);
     expect(String(vi.mocked(globalThis.fetch).mock.calls[0]?.[0])).toContain(
       'legacyPublicPath=%2Fgenerated-puzzle-assets%2Fpuzzle-session-1%2Fcandidate-1%2Fasset-1%2Fimage.png',
@@ -106,37 +111,40 @@ describe('useResolvedAssetReadUrl', () => {
     expect(screen.queryByRole('img', { name: '候选图' })).toBeNull();
 
     const image = await screen.findByRole('img', { name: '候选图' });
-    expect(image.getAttribute('src')).toBe('https://signed.example.com/puzzle.png');
+    expect(image.getAttribute('src')).toBe(
+      'https://signed.example.com/puzzle.png',
+    );
   });
 
   test('refreshKey changes force a fresh signed url request without mutating OSS signature query', async () => {
-    vi.spyOn(globalThis, 'fetch').mockImplementation(async () =>
-      new Response(
-        JSON.stringify({
-          ok: true,
-          data: {
-            read: {
-              objectKey:
-                'generated-puzzle-assets/puzzle-session-1/candidate-1/asset-1/image.png',
-              signedUrl: 'https://signed.example.com/puzzle.png',
-              expiresAt: '2099-01-01T00:10:00Z',
+    vi.spyOn(globalThis, 'fetch').mockImplementation(
+      async () =>
+        new Response(
+          JSON.stringify({
+            ok: true,
+            data: {
+              read: {
+                objectKey:
+                  'generated-puzzle-assets/puzzle-session-1/candidate-1/asset-1/image.png',
+                signedUrl: 'https://signed.example.com/puzzle.png',
+                expiresAt: '2099-01-01T00:10:00Z',
+              },
+            },
+            error: null,
+            meta: {
+              apiVersion: '2026-04-08',
+              routeVersion: '2026-04-08',
+              latencyMs: 1,
+              timestamp: '2099-01-01T00:00:00Z',
+            },
+          }),
+          {
+            status: 200,
+            headers: {
+              'Content-Type': 'application/json',
             },
           },
-          error: null,
-          meta: {
-            apiVersion: '2026-04-08',
-            routeVersion: '2026-04-08',
-            latencyMs: 1,
-            timestamp: '2099-01-01T00:00:00Z',
-          },
-        }),
-        {
-          status: 200,
-          headers: {
-            'Content-Type': 'application/json',
-          },
-        },
-      ),
+        ),
     );
 
     const { rerender } = render(
@@ -148,7 +156,9 @@ describe('useResolvedAssetReadUrl', () => {
     );
 
     const firstImage = await screen.findByRole('img', { name: '候选图' });
-    expect(firstImage.getAttribute('src')).toBe('https://signed.example.com/puzzle.png');
+    expect(firstImage.getAttribute('src')).toBe(
+      'https://signed.example.com/puzzle.png',
+    );
 
     rerender(
       <ResolvedAssetImage
@@ -161,9 +171,9 @@ describe('useResolvedAssetReadUrl', () => {
     await waitFor(() => {
       expect(globalThis.fetch).toHaveBeenCalledTimes(2);
     });
-    expect(screen.getByRole('img', { name: '候选图' }).getAttribute('src')).toBe(
-      'https://signed.example.com/puzzle.png',
-    );
+    expect(
+      screen.getByRole('img', { name: '候选图' }).getAttribute('src'),
+    ).toBe('https://signed.example.com/puzzle.png');
   });
 
   test('generated 私有资源签名失败时保持空图像而不是回退裸路径', async () => {
@@ -204,4 +214,70 @@ describe('useResolvedAssetReadUrl', () => {
     });
     expect(screen.queryByRole('img', { name: '候选图' })).toBeNull();
   });
+
+  test('generated 私有资源签名失败时可使用显式 fallbackSrc', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          ok: false,
+          data: null,
+          error: {
+            code: 'NOT_FOUND',
+            message: '对象不存在',
+          },
+          meta: {
+            apiVersion: '2026-04-08',
+            routeVersion: '2026-04-08',
+            latencyMs: 1,
+            timestamp: '2099-01-01T00:00:00Z',
+          },
+        }),
+        {
+          status: 400,
+          headers: {
+            'Content-Type': 'application/json',
+          },
+        },
+      ),
+    );
+
+    render(
+      <ResolvedAssetImage
+        src="/generated-puzzle-assets/puzzle-session-1/candidate-1/asset-1/image.png"
+        fallbackSrc="/creation-type-references/puzzle.webp"
+        alt="候选图"
+      />,
+    );
+
+    expect(
+      screen.getByRole('img', { name: '候选图' }).getAttribute('src'),
+    ).toBe('/creation-type-references/puzzle.webp');
+    await waitFor(() => {
+      expect(globalThis.fetch).toHaveBeenCalledTimes(1);
+    });
+    expect(
+      screen.getByRole('img', { name: '候选图' }).getAttribute('src'),
+    ).toBe('/creation-type-references/puzzle.webp');
+  });
+
+  test('普通封面加载失败时切换到显式 fallbackSrc', async () => {
+    render(
+      <ResolvedAssetImage
+        src="/covers/missing-cover.webp"
+        fallbackSrc="/creation-type-references/puzzle.webp"
+        alt="草稿封面"
+      />,
+    );
+
+    const image = screen.getByRole('img', { name: '草稿封面' });
+    expect(image.getAttribute('src')).toBe('/covers/missing-cover.webp');
+
+    fireEvent.error(image);
+
+    await waitFor(() => {
+      expect(
+        screen.getByRole('img', { name: '草稿封面' }).getAttribute('src'),
+      ).toBe('/creation-type-references/puzzle.webp');
+    });
+  });
 });