feat: add puzzle onboarding and match3d entry updates

src/services/puzzle-onboarding/index.ts

@@ -0,0 +1,5 @@
+export {
+  generatePuzzleOnboardingWork,
+  puzzleOnboardingClient,
+  savePuzzleOnboardingWork,
+} from './puzzleOnboardingClient';

src/services/puzzle-onboarding/puzzleOnboardingClient.ts

@@ -0,0 +1,62 @@
+import type {
+  PuzzleOnboardingGenerateRequest,
+  PuzzleOnboardingGenerateResponse,
+  PuzzleOnboardingSaveRequest,
+} from '../../../packages/shared/src/contracts/puzzleOnboarding';
+import type { PuzzleWorkMutationResponse } from '../../../packages/shared/src/contracts/puzzleWorkSummary';
+import { type ApiRetryOptions, requestJson } from '../apiClient';
+
+const PUZZLE_ONBOARDING_API_BASE = '/api/runtime/puzzle/onboarding';
+const PUZZLE_ONBOARDING_WRITE_RETRY: ApiRetryOptions = {
+  maxRetries: 1,
+  baseDelayMs: 120,
+  maxDelayMs: 360,
+  retryUnsafeMethods: true,
+};
+
+/**
+ * 未登录首次访问生成的临时 1 关拼图，不写入用户作品库。
+ */
+export async function generatePuzzleOnboardingWork(
+  payload: PuzzleOnboardingGenerateRequest,
+) {
+  return requestJson<PuzzleOnboardingGenerateResponse>(
+    `${PUZZLE_ONBOARDING_API_BASE}/generate`,
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+    },
+    '生成新手引导拼图失败',
+    {
+      retry: PUZZLE_ONBOARDING_WRITE_RETRY,
+      skipAuth: true,
+      skipRefresh: true,
+    },
+  );
+}
+
+/**
+ * 登录后把临时拼图保存成当前用户的草稿作品。
+ */
+export async function savePuzzleOnboardingWork(
+  payload: PuzzleOnboardingSaveRequest,
+) {
+  return requestJson<PuzzleWorkMutationResponse>(
+    `${PUZZLE_ONBOARDING_API_BASE}/save`,
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+    },
+    '保存新手引导拼图失败',
+    {
+      retry: PUZZLE_ONBOARDING_WRITE_RETRY,
+    },
+  );
+}
+
+export const puzzleOnboardingClient = {
+  generate: generatePuzzleOnboardingWork,
+  save: savePuzzleOnboardingWork,
+};