Refine play type integration flow and docs

src/components/custom-world-home/creationWorkShelf.test.ts

@@ -93,7 +93,9 @@ test('buildCreationWorkShelfItems maps wooden fish items with WF public code', (
   expect(items[0]?.sharePath).toContain('/works/detail?work=WF-12345678');
   expect(items[0]?.openActionLabel).toBe('查看详情');
   expect(items[0]?.badges.some((badge) => badge.label === '敲木鱼')).toBe(true);
-  expect(items[0]?.metrics.find((metric) => metric.id === 'play-count')?.value).toBe(9);
+  expect(
+    items[0]?.metrics.find((metric) => metric.id === 'play-count')?.value,
+  ).toBe(9);
   expect(onOpenWoodenFishDetail).toHaveBeenCalledWith(woodenFishWork);
 });
 
@@ -211,9 +213,9 @@ test('buildCreationWorkShelfItems keeps separate bark battle draft and published
   expect(items.find((item) => item.status === 'published')?.id).toBe(
     'BB-PUB00001',
   );
-  expect(items.find((item) => item.status === 'published')?.publicWorkCode).toBe(
-    'BB-PUB00001',
-  );
+  expect(
+    items.find((item) => item.status === 'published')?.publicWorkCode,
+  ).toBe('BB-PUB00001');
 });
 
 test('buildCreationWorkShelfItems falls back to deterministic RPG public work code when library entry is missing', () => {
@@ -303,10 +305,9 @@ test('buildCreationWorkShelfItems gives bark battle draft cover from character o
   expect(items.find((item) => item.id === 'BB-COVER001')?.coverImageSrc).toBe(
     '/draft-player-cover.png',
   );
-  expect(items.find((item) => item.id === 'BB-COVER001')?.coverCharacterImageSrcs).toEqual([
-    '/draft-player-cover.png',
-    '/draft-opponent-cover.png',
-  ]);
+  expect(
+    items.find((item) => item.id === 'BB-COVER001')?.coverCharacterImageSrcs,
+  ).toEqual(['/draft-player-cover.png', '/draft-opponent-cover.png']);
   expect(items.find((item) => item.id === 'BB-COVER002')?.coverImageSrc).toBe(
     '/creation-type-references/bark-battle.webp',
   );
@@ -457,14 +458,76 @@ test('buildCreationWorkShelfItems restores persisted generation state for puzzle
     ],
   });
 
-  expect(items.find((item) => item.kind === 'puzzle')?.isGenerating).toBe(
-    true,
-  );
+  expect(items.find((item) => item.kind === 'puzzle')?.isGenerating).toBe(true);
   expect(items.find((item) => item.kind === 'match3d')?.isGenerating).toBe(
     true,
   );
 });
 
+test('buildCreationWorkShelfItems lets failure notice override persisted generating copy', () => {
+  const items = buildCreationWorkShelfItems({
+    rpgItems: [],
+    bigFishItems: [],
+    puzzleItems: [
+      {
+        workId: 'puzzle:failed-generating',
+        profileId: 'puzzle-profile-failed-generating',
+        ownerUserId: 'user-1',
+        sourceSessionId: 'puzzle-session-failed-generating',
+        authorDisplayName: '测试作者',
+        levelName: '失败拼图',
+        summary: '正在生成拼图草稿。',
+        themeTags: [],
+        coverImageSrc: null,
+        publicationStatus: 'draft',
+        updatedAt: '2026-05-08T00:00:00.000Z',
+        publishedAt: null,
+        publishReady: false,
+        generationStatus: 'generating',
+      },
+    ],
+    getItemState: (item) =>
+      item.kind === 'puzzle'
+        ? {
+            isGenerating: false,
+            suppressPersistedGenerating: true,
+            summaryOverride: '拼图草稿生成失败，可重新打开处理。',
+          }
+        : null,
+  });
+
+  expect(items[0]?.isGenerating).toBe(false);
+  expect(items[0]?.summary).toBe('拼图草稿生成失败，可重新打开处理。');
+});
+
+test('persisted failed puzzle draft is not treated as generating', () => {
+  const items = buildCreationWorkShelfItems({
+    rpgItems: [],
+    bigFishItems: [],
+    puzzleItems: [
+      {
+        workId: 'puzzle:failed',
+        profileId: 'puzzle-profile-failed',
+        ownerUserId: 'user-1',
+        sourceSessionId: 'puzzle-session-failed',
+        authorDisplayName: '测试作者',
+        levelName: '失败拼图',
+        summary: '服务端已回写失败。',
+        themeTags: [],
+        coverImageSrc: null,
+        publicationStatus: 'draft',
+        updatedAt: '2026-05-08T00:00:00.000Z',
+        publishedAt: null,
+        publishReady: false,
+        generationStatus: 'failed',
+      },
+    ],
+  });
+
+  expect(items[0]?.isGenerating).toBeFalsy();
+  expect(items[0]?.summary).toBe('服务端已回写失败。');
+});
+
 test('buildCreationWorkShelfItems maps baby object match local drafts', () => {
   const onOpenBabyObjectMatchDetail = vi.fn();
   const onDeleteBabyObjectMatch = vi.fn();
@@ -1088,7 +1151,6 @@ test('bark battle draft generating state only follows pending assets', () => {
   ).toBe(false);
 });
 
-
 test('CustomWorldWorkCard hides author on shelf draft and published cards', () => {
   const buildItem = (
     status: CreationWorkShelfItem['status'],
@@ -1110,7 +1172,11 @@ test('CustomWorldWorkCard hides author on shelf draft and published cards', () =
     canDelete: false,
     canShare: false,
     badges: [
-      { id: 'status', label: status === 'draft' ? '草稿' : '已发布', tone: 'neutral' },
+      {
+        id: 'status',
+        label: status === 'draft' ? '草稿' : '已发布',
+        tone: 'neutral',
+      },
       { id: 'type', label: '汪汪', tone: 'neutral' },
     ],
     metrics: [],