Merge pull request 'fix: keep draft form on mud-point failure' (#33) from codex/mud-point-modal-keep-form into master

Reviewed-on: #33

.hermes/shared-memory/pitfalls.md

@@ -23,6 +23,21 @@
 - 验证：点拼图 / 抓大鹅 / 汪汪声浪卡片后，应看到各自既有工作台内容，例如测试中的 `拼图工作区：missing-session`、`抓大鹅工作区：missing-session` 或 `汪汪声浪配置表单`，并且不再出现“X 创作入口”空白页。
 - 关联：`src/components/platform-entry/platformEntryTypes.ts`、`src/routing/appPageRoutes.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`。
 
+## 泥点不足提示不要把用户退回创作入口
+
+- 现象：拼图 / 抓大鹅 / 汪汪声浪等创作表单点击生成时，如果泥点不足，页面直接回到创作 Tab 玩法模板列表，刚填的表单内容随工作台卸载全部丢失。
+- 原因：`PlatformEntryFlowShellImpl.tsx` 的 `ensureEnoughDraftGenerationPointsFromServer(...)` 曾在余额不足或余额读取失败时调用 `enterCreateTab()` 并 `setSelectionStage('platform')`，把前置校验失败当作离开工作台处理。
+- 处理：泥点前置校验失败只更新独立 `UnifiedModal` 提示，不切换 stage，不清表单；余额读取失败也走同一弹窗口径。需要提示玩法内错误时可以保留局部错误位，但不得因此退出工作台。
+- 验证：`npm test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "puzzle form checks mud points before creating a draft|match3d form checks mud points before creating a draft|bark battle form checks mud points before creating image assets"` 应断言弹窗出现、对应工作台仍在、玩法模板分类不再出现。
+- 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 玩法入口分类字段缺失要前端兜底
+
+- 现象：平台创作入口初始化时，`platformEntryCreationTypes.ts` 直接对 `creationTypes[].categoryId` / `categoryLabel` 调 `trim()`，一旦后端旧数据、局部 mock 或异常返回里缺字段，整个创作页会在 `derivePlatformCreationTypes(...)` 里直接炸掉。
+- 处理：`normalizeCategoryId(...)` 和 `normalizeCategoryLabel(...)` 必须接收可空值，并分别回退到 `recent` / `最近创作`。前端这里是展示派生层，不能要求所有历史配置都先补齐字段。
+- 验证：`npm test -- src/components/platform-entry/platformEntryCreationTypes.test.ts`，再打开本地创作页确认能正常进入创作 Tab。
+- 关联：`src/components/platform-entry/platformEntryCreationTypes.ts`、`src/components/platform-entry/platformEntryCreationTypes.test.ts`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
 ## 草稿页未读点不要继续用红色 literal
 
 - 现象：草稿页底部 Tab 和作品架的未读点视觉上仍像红点，或 glow 仍带红色阴影，和平台暖棕体系不一致。

docs/【玩法创作】平台入口与玩法链路-2026-05-15.md

@@ -8,8 +8,12 @@
 
 当前创作 Tab 只承载赛事 banner、玩法模板分类和两列模板卡；点击模板卡后直接进入对应玩法已有的入口创作表单 stage，不再经过空白占位页，也不把旧表单嵌进创作 Tab 首屏。移动端创作 Tab 顶栏在 `陶泥儿` 品牌同一行显示真实账户泥点数，数据来自 `profileDashboard.walletBalance`，不得再把活动奖池当作账号余额展示。首屏 banner 结构按参考图拆成横向可滑动赛事卡、主体宣传图文区、奖池胶囊、开始 / 结束时间条和卡片内分页点；轮播只保留 `拼图主题创作赛` 和 `抓大鹅主题创作赛`，两个主题赛事奖池均为 `1000` 泥点数。玩法列表不再套外部边框卡片，移动端需要压缩横向边距和两列间距；玩法卡统一按“上图、左上状态标签（仅非开放态显示）、封面右下 `10-20泥点数`、下方白底标题/描述”结构展示，卡片高度保持紧凑但标题、描述和预估消耗点数都必须可见。创作 Tab 根容器不再使用 `platform-page-stage` 这类全局内容卡片壳，但继续保留 `platform-remap-surface` 作为主题和输入框样式命中钩子。创作首屏字号需要对齐平台普通 UI 档位：顶栏泥点组件、banner 正文、分类 Tab 和玩法卡标题 / 副标题 / 消耗说明优先使用 `11px` 到 `14px`，不使用 `text-lg`、`text-xl` 或更大的展示级字号。草稿 Tab 继续承接作品架。RPG、RPG 之外的各玩法入口分别落到既有的 `agent-workspace`、`big-fish-agent-workspace`、`match3d-agent-workspace`、`square-hole-agent-workspace`、`jump-hop-workspace`、`wooden-fish-workspace`、`puzzle-agent-workspace`、`bark-battle-workspace`、`visual-novel-agent-workspace`、`baby-object-match-workspace`，这些入口继续承接各玩法自己的表单、草稿恢复和后续编排，不作为创作 Tab 首屏内容。
 
+创作表单提交前的泥点余额前置校验只允许用独立弹窗提示失败原因，不得把用户退回创作入口或玩法模板列表，也不得清空当前表单状态。当前适用拼图、抓大鹅和汪汪声浪等会在前端提交前校验泥点的生成入口；余额不足、余额读取失败都应停留在当前工作台，由用户关闭提示后继续编辑或自行补足泥点。
+
 `PlatformEntryFlowShellImpl.tsx` 仍是平台入口编排壳，后续维护时应优先把独立 UI 片段、公开作品映射、草稿生成 notice 和运行态状态 helper 拆到 `src/components/platform-entry/PlatformEntryFlowShellImpl/` 或同目录紧邻 helper 文件。拆分只允许改变文件组织，不改变入口配置事实源、默认导出、props、页面阶段、UI 文案或现有交互；其中拼图首访 onboarding 已拆为 `PlatformEntryFlowShellImpl/PuzzleOnboardingView.tsx`。
 
+`platformEntryCreationTypes.ts` 只做前端展示派生，分组时必须把后端 `creationTypes` 里的 `categoryId` / `categoryLabel` 当作可缺失字段处理，空值统一回退到 `recent` / `最近创作`，避免旧数据、局部 mock 或异常返回把创作入口初始化直接打崩。
+
 移动端底部一级导航是全局平台样式，不按单一玩法分叉。当前视觉统一为米白浮动胶囊底座、浅棕分隔线、棕色线性图标、橘色选中态和底部短下划线；中间 `创作` 入口保持凸起圆形主按钮，但凸起位移只能作用在按钮内容层，不能移动承载分隔线的 Tab 按钮容器，确保创作左右分隔线与其他分隔线垂直位置一致。Tab 名称和可见性仍由现有 `PlatformHomeTab` / 登录态规则决定，样式调整不得改写 Tab 文案或导航状态。
 
 ## 新增玩法创作工具平台 SOP

src/components/platform-entry/PlatformEntryFlowShellImpl.tsx

@@ -2715,6 +2715,10 @@ export function PlatformEntryFlowShellImpl({
       ? 'platform-theme--dark'
       : 'platform-theme--light';
   const [showCreationTypeModal, setShowCreationTypeModal] = useState(false);
+  const [draftGenerationPointNotice, setDraftGenerationPointNotice] = useState<{
+    title: string;
+    message: string;
+  } | null>(null);
   const [selectedDetailEntry, setSelectedDetailEntry] =
     useState<CustomWorldLibraryEntry<CustomWorldProfile> | null>(null);
   const [selectedPublicWorkDetail, setSelectedPublicWorkDetail] =
@@ -3299,7 +3303,7 @@ export function PlatformEntryFlowShellImpl({
     [draftGenerationNotices],
   );
   const ensureEnoughDraftGenerationPointsFromServer = useCallback(
-    async (pointsCost: number, setError: (message: string | null) => void) => {
+    async (pointsCost: number) => {
       try {
         const latestDashboard = await getPlatformProfileDashboard(
           RECOMMEND_RUNTIME_BACKGROUND_AUTH_OPTIONS,
@@ -3307,25 +3311,26 @@ export function PlatformEntryFlowShellImpl({
         platformBootstrap.setProfileDashboard(latestDashboard);
         const walletBalance = resolveProfileWalletBalance(latestDashboard);
         if (walletBalance >= pointsCost) {
+          setDraftGenerationPointNotice(null);
           return true;
         }
 
-        setError(
-          `泥点不足，本次需要 ${pointsCost} 泥点，当前 ${walletBalance} 泥点。`,
+        setDraftGenerationPointNotice(
+          {
+            title: '泥点不足',
+            message: `本次需要 ${pointsCost} 泥点，当前 ${walletBalance} 泥点。`,
+          },
         );
-        enterCreateTab();
-        selectionStageRef.current = 'platform';
-        setSelectionStage('platform');
         return false;
       } catch {
-        setError('读取泥点余额失败，请稍后重试。');
-        enterCreateTab();
-        selectionStageRef.current = 'platform';
-        setSelectionStage('platform');
+        setDraftGenerationPointNotice({
+          title: '读取泥点余额失败',
+          message: '请稍后重试。',
+        });
         return false;
       }
     },
-    [enterCreateTab, platformBootstrap, setSelectionStage],
+    [platformBootstrap],
   );
 
   const resolveBigFishErrorMessage = useCallback(
@@ -5274,30 +5279,27 @@ export function PlatformEntryFlowShellImpl({
     setPuzzleError(null);
     return ensureEnoughDraftGenerationPointsFromServer(
       PUZZLE_DRAFT_GENERATION_POINT_COST,
-      (message) => {
-        setPuzzleCreationError(message);
-        setPuzzleError(message);
-      },
     );
   }, [
     ensureEnoughDraftGenerationPointsFromServer,
-    setPuzzleCreationError,
-    setPuzzleError,
   ]);
   const preflightMatch3DDraftGeneration = useCallback(async () => {
     setMatch3DError(null);
     return ensureEnoughDraftGenerationPointsFromServer(
       MATCH3D_DRAFT_GENERATION_POINT_COST,
-      setMatch3DError,
     );
-  }, [ensureEnoughDraftGenerationPointsFromServer, setMatch3DError]);
+  }, [ensureEnoughDraftGenerationPointsFromServer]);
   const preflightBarkBattleDraftGeneration = useCallback(async () => {
     setBarkBattleError(null);
     return ensureEnoughDraftGenerationPointsFromServer(
       BARK_BATTLE_DRAFT_GENERATION_POINT_COST,
-      setBarkBattleError,
     );
   }, [ensureEnoughDraftGenerationPointsFromServer]);
+  const draftGenerationPointNoticeDescription = draftGenerationPointNotice
+    ? draftGenerationPointNotice.title === '读取泥点余额失败'
+      ? '当前表单不会丢失，关闭后可继续编辑，稍后再试。'
+      : '当前表单不会丢失，关闭后可继续编辑或补足泥点再继续。'
+    : undefined;
   const recoverCompletedPuzzleDraftGeneration = useCallback(
     async ({
       sessionId,
@@ -15687,6 +15689,29 @@ export function PlatformEntryFlowShellImpl({
           }}
         />
       ) : null}
+      <UnifiedModal
+        open={Boolean(draftGenerationPointNotice)}
+        title={draftGenerationPointNotice?.title ?? '泥点提示'}
+        description={draftGenerationPointNoticeDescription}
+        onClose={() => setDraftGenerationPointNotice(null)}
+        closeOnBackdrop
+        size="sm"
+        overlayClassName={`platform-theme ${platformThemeClass} !items-center`}
+        panelClassName="platform-remap-surface rounded-[1.75rem]"
+        footer={
+          <button
+            type="button"
+            onClick={() => setDraftGenerationPointNotice(null)}
+            className="platform-button platform-button--primary min-h-0 rounded-full px-4 py-2 text-sm"
+          >
+            知道了
+          </button>
+        }
+      >
+        <div className="text-sm leading-6 text-[var(--platform-text-base)]">
+          {draftGenerationPointNotice?.message}
+        </div>
+      </UnifiedModal>
       <PublishShareModal
         open={Boolean(publishSharePayload)}
         payload={publishSharePayload}

src/components/platform-entry/platformEntryCreationTypes.test.ts

@@ -315,3 +315,36 @@ test('groups visible platform creation types by backend category metadata', () =
   ]);
   expect(groups[1]?.items.map((item) => item.id)).toEqual(['visual-novel']);
 });
+
+test('falls back when backend creation type category metadata is missing', () => {
+  const cards = derivePlatformCreationTypes([
+    {
+      id: 'legacy-entry',
+      title: '历史入口',
+      subtitle: '旧数据缺少分类字段',
+      badge: '可创建',
+      imageSrc: '/creation-type-references/puzzle.webp',
+      visible: true,
+      open: true,
+      sortOrder: 10,
+      categoryId: undefined as unknown as string,
+      categoryLabel: undefined as unknown as string,
+      categorySortOrder: 0,
+      updatedAtMicros: 1,
+    },
+  ]);
+
+  expect(cards[0]).toEqual(
+    expect.objectContaining({
+      id: 'legacy-entry',
+      categoryId: 'recent',
+      categoryLabel: '最近创作',
+    }),
+  );
+  expect(groupVisiblePlatformCreationTypes(cards)).toEqual([
+    expect.objectContaining({
+      id: 'recent',
+      label: '最近创作',
+    }),
+  ]);
+});

src/components/platform-entry/platformEntryCreationTypes.ts

@@ -55,13 +55,13 @@ export function isPlatformCreationTypeOpen(
   );
 }
 
-function normalizeCategoryId(value: string) {
-  const normalized = value.trim();
+function normalizeCategoryId(value: string | null | undefined) {
+  const normalized = typeof value === 'string' ? value.trim() : '';
   return normalized || FALLBACK_CREATION_CATEGORY_ID;
 }
 
-function normalizeCategoryLabel(value: string) {
-  const normalized = value.trim();
+function normalizeCategoryLabel(value: string | null | undefined) {
+  const normalized = typeof value === 'string' ? value.trim() : '';
   return normalized || FALLBACK_CREATION_CATEGORY_LABEL;
 }
 

src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx

@@ -1085,6 +1085,10 @@ vi.mock('../bark-battle-creation/BarkBattleConfigEditor', () => ({
   }) => (
     <div className="bark-battle-config-editor-mock">
       <div>汪汪声浪配置表单</div>
+      <label>
+        作品标题
+        <input aria-label="汪汪作品标题" defaultValue="汪汪测试杯" />
+      </label>
       <div data-testid="bark-battle-editor-back-state">
         {showBackButton ? 'back-visible' : 'back-hidden'}
       </div>
@@ -3581,11 +3585,20 @@ test('bark battle form checks mud points before creating image assets', async ()
 
   await openCreateTemplateHub(user);
   await user.click(await findCreationTypeButton('汪汪声浪'));
+  const titleInput = await screen.findByLabelText('汪汪作品标题');
+  await user.clear(titleInput);
+  await user.type(titleInput, '自定义声浪杯');
   await user.click(await screen.findByRole('button', { name: '生成草稿' }));
 
+  const noticeDialog = await screen.findByRole('dialog', { name: '泥点不足' });
   expect(
-    await screen.findByText('泥点不足，本次需要 3 泥点，当前 2 泥点。'),
+    within(noticeDialog).getByText('本次需要 3 泥点，当前 2 泥点。'),
   ).toBeTruthy();
+  expect(screen.getByText('汪汪声浪配置表单')).toBeTruthy();
+  expect(screen.queryByRole('tablist', { name: '玩法模板分类' })).toBeNull();
+  expect((screen.getByLabelText('汪汪作品标题') as HTMLInputElement).value).toBe(
+    '自定义声浪杯',
+  );
   expect(createBarkBattleDraft).not.toHaveBeenCalled();
   expect(generateAllBarkBattleImageAssets).not.toHaveBeenCalled();
 });
@@ -4302,11 +4315,15 @@ test('puzzle form checks mud points before creating a draft', async () => {
   render(<TestWrapper withAuth />);
 
   await openCreateTemplateHub(user);
+  await user.click(await findCreationTypeButton('拼图'));
   await user.click(await screen.findByRole('button', { name: '生成草稿' }));
 
+  const noticeDialog = await screen.findByRole('dialog', { name: '泥点不足' });
   expect(
-    await screen.findByText('泥点不足，本次需要 2 泥点，当前 1 泥点。'),
+    within(noticeDialog).getByText('本次需要 2 泥点，当前 1 泥点。'),
   ).toBeTruthy();
+  expect(screen.getByText('拼图工作区：missing-session')).toBeTruthy();
+  expect(screen.queryByRole('tablist', { name: '玩法模板分类' })).toBeNull();
   expect(createPuzzleAgentSession).not.toHaveBeenCalled();
   expect(executePuzzleAgentAction).not.toHaveBeenCalled();
 });
@@ -4323,14 +4340,17 @@ test('match3d form checks mud points before creating a draft', async () => {
   render(<TestWrapper withAuth />);
 
   await openCreateTemplateHub(user);
-  await user.click(screen.getByRole('tab', { name: '抓大鹅' }));
+  await user.click(await findCreationTypeButton('抓大鹅'));
   await user.click(
     await screen.findByRole('button', { name: '生成抓大鹅草稿' }),
   );
 
+  const noticeDialog = await screen.findByRole('dialog', { name: '泥点不足' });
   expect(
-    await screen.findByText('泥点不足，本次需要 10 泥点，当前 9 泥点。'),
+    within(noticeDialog).getByText('本次需要 10 泥点，当前 9 泥点。'),
   ).toBeTruthy();
+  expect(screen.getByText('抓大鹅工作区：missing-session')).toBeTruthy();
+  expect(screen.queryByRole('tablist', { name: '玩法模板分类' })).toBeNull();
   expect(match3dCreationClient.createSession).not.toHaveBeenCalled();
   expect(match3dCreationClient.executeAction).not.toHaveBeenCalled();
 });