refactor(api-server): narrow puzzle state surface

src/components/puzzle-agent/PuzzleAgentWorkspace.tsx

@@ -16,9 +16,11 @@ import { getPuzzleHistoryAssetReferenceLabel } from '../../services/puzzle-works
 import {
   cropPuzzleReferenceImageDataUrl,
   isPuzzleReferenceImageSquare,
+  puzzleReferenceImageDataUrlToFile,
   readPuzzleReferenceImageAsDataUrl,
   readPuzzleReferenceImageForUpload,
 } from '../../services/puzzleReferenceImage';
+import { puzzleAssetClient } from '../../services/puzzle-works/puzzleAssetClient';
 import {
   CreativeImageInputPanel,
   type CreativeImageInputReferenceImage,
@@ -54,6 +56,7 @@ type PuzzleAgentWorkspaceProps = {
 type PuzzleFormState = {
   pictureDescription: string;
   referenceImageSrc: string;
+  referenceImageAssetObjectId: string;
   referenceImageLabel: string;
   referenceImageSrcs: CreativeImageInputReferenceImage[];
   imageModel: PuzzleImageModelId;
@@ -63,6 +66,7 @@ type PuzzleFormState = {
 const EMPTY_FORM_STATE: PuzzleFormState = {
   pictureDescription: '',
   referenceImageSrc: '',
+  referenceImageAssetObjectId: '',
   referenceImageLabel: '',
   referenceImageSrcs: [],
   imageModel: PUZZLE_IMAGE_MODEL_GPT_IMAGE_2,
@@ -74,6 +78,7 @@ const PUZZLE_PROMPT_REFERENCE_IMAGE_LIMIT = 5;
 type PuzzleImageCropState = {
   source: string;
   label: string;
+  fileName: string;
   imageSize: { width: number; height: number };
   cropRect: SquareImageCropRect;
   error: string | null;
@@ -97,11 +102,14 @@ function resolveInitialFormState(
     return {
       pictureDescription: formDraft.pictureDescription ?? '',
       referenceImageSrc: initialFormPayload?.referenceImageSrc ?? '',
+      referenceImageAssetObjectId:
+        initialFormPayload?.referenceImageAssetObjectId ?? '',
       referenceImageLabel: initialFormPayload?.referenceImageSrc
         ? '已选择拼图图片'
         : '',
       referenceImageSrcs: createPuzzlePromptReferenceImagesFromSources(
         initialFormPayload?.referenceImageSrcs,
+        initialFormPayload?.referenceImageAssetObjectIds,
       ),
       imageModel: normalizePuzzleImageModel(initialFormPayload?.imageModel),
       aiRedraw: initialFormPayload?.aiRedraw ?? true,
@@ -115,11 +123,14 @@ function resolveInitialFormState(
         initialFormPayload.seedText ??
         '',
       referenceImageSrc: initialFormPayload.referenceImageSrc ?? '',
+      referenceImageAssetObjectId:
+        initialFormPayload.referenceImageAssetObjectId ?? '',
       referenceImageLabel: initialFormPayload.referenceImageSrc
         ? '已选择拼图图片'
         : '',
       referenceImageSrcs: createPuzzlePromptReferenceImagesFromSources(
         initialFormPayload.referenceImageSrcs,
+        initialFormPayload.referenceImageAssetObjectIds,
       ),
       imageModel: normalizePuzzleImageModel(initialFormPayload.imageModel),
       aiRedraw: initialFormPayload.aiRedraw ?? true,
@@ -138,6 +149,7 @@ function resolveInitialFormState(
       session.seedText ||
       '',
     referenceImageSrc: '',
+    referenceImageAssetObjectId: '',
     referenceImageLabel: '',
     referenceImageSrcs: [],
     imageModel: PUZZLE_IMAGE_MODEL_GPT_IMAGE_2,
@@ -166,14 +178,46 @@ function normalizePuzzlePromptReferenceSources(
 
 function createPuzzlePromptReferenceImagesFromSources(
   sources: readonly string[] | null | undefined,
+  assetObjectIds: readonly string[] | null | undefined = [],
 ): CreativeImageInputReferenceImage[] {
-  return normalizePuzzlePromptReferenceSources(sources).map(
+  const assetIds = normalizePuzzleAssetObjectIds(assetObjectIds);
+  const sourceImages = normalizePuzzlePromptReferenceSources(sources).map(
     (imageSrc, index) => ({
       id: `restored:${index}:${imageSrc}`,
       label: `参考图 ${index + 1}`,
       imageSrc,
+      assetObjectId: assetIds[index] ?? null,
     }),
   );
+  if (sourceImages.length > 0) {
+    return sourceImages;
+  }
+
+  return assetIds.map((assetObjectId, index) => ({
+    id: `restored-asset:${index}:${assetObjectId}`,
+    label: `参考图 ${index + 1}`,
+    imageSrc: '',
+    assetObjectId,
+  }));
+}
+
+function normalizePuzzleAssetObjectIds(
+  assetObjectIds: readonly (string | null | undefined)[] | null | undefined,
+) {
+  const normalizedIds: string[] = [];
+  for (const assetObjectId of assetObjectIds ?? []) {
+    const normalized = assetObjectId?.trim() ?? '';
+    if (
+      normalized &&
+      !normalizedIds.some((current) => current === normalized)
+    ) {
+      normalizedIds.push(normalized);
+    }
+    if (normalizedIds.length >= PUZZLE_PROMPT_REFERENCE_IMAGE_LIMIT) {
+      break;
+    }
+  }
+  return normalizedIds;
 }
 
 function addPuzzlePromptReferenceImage(
@@ -256,6 +300,21 @@ export function PuzzleAgentWorkspace({
       ),
     [formState.referenceImageSrc, formState.referenceImageSrcs],
   );
+  const promptReferenceAssetObjectIds = useMemo(
+    () =>
+      formState.referenceImageSrc
+        ? []
+        : normalizePuzzleAssetObjectIds(
+            formState.referenceImageSrcs.map((image) => image.assetObjectId),
+          ),
+    [formState.referenceImageSrc, formState.referenceImageSrcs],
+  );
+  const mainReferenceImageSrcForPayload =
+    formState.referenceImageAssetObjectId && formState.aiRedraw
+      ? null
+      : formState.referenceImageSrc || null;
+  const promptReferenceImageSrcsForPayload =
+    promptReferenceAssetObjectIds.length > 0 ? [] : promptReferenceImageSrcs;
   const canSubmit = formState.aiRedraw
     ? Boolean(pictureDescription) && !isBusy
     : Boolean(formState.referenceImageSrc) && !isBusy;
@@ -263,16 +322,21 @@ export function PuzzleAgentWorkspace({
     () => ({
       seedText: pictureDescription,
       pictureDescription,
-      referenceImageSrc: formState.referenceImageSrc || null,
-      referenceImageSrcs: promptReferenceImageSrcs,
+      referenceImageSrc: mainReferenceImageSrcForPayload,
+      referenceImageSrcs: promptReferenceImageSrcsForPayload,
+      referenceImageAssetObjectId:
+        formState.referenceImageAssetObjectId || null,
+      referenceImageAssetObjectIds: promptReferenceAssetObjectIds,
       imageModel: formState.imageModel,
       aiRedraw: formState.aiRedraw,
     }),
     [
       formState.aiRedraw,
-      formState.referenceImageSrc,
+      formState.referenceImageAssetObjectId,
       formState.imageModel,
-      promptReferenceImageSrcs,
+      mainReferenceImageSrcForPayload,
+      promptReferenceAssetObjectIds,
+      promptReferenceImageSrcsForPayload,
       pictureDescription,
     ],
   );
@@ -280,6 +344,8 @@ export function PuzzleAgentWorkspace({
     autosavePayload.pictureDescription,
     autosavePayload.referenceImageSrc,
     autosavePayload.referenceImageSrcs,
+    autosavePayload.referenceImageAssetObjectId,
+    autosavePayload.referenceImageAssetObjectIds,
     autosavePayload.aiRedraw,
     autosavePayload.imageModel,
   ]);
@@ -333,6 +399,7 @@ export function PuzzleAgentWorkspace({
         setCropState({
           source: uploadImage.dataUrl,
           label: file.name.trim() || '本地拼图图片',
+          fileName: file.name.trim() || 'puzzle-reference.jpg',
           imageSize,
           cropRect: buildCenteredSquareImageCropRect(imageSize),
           error: null,
@@ -342,9 +409,11 @@ export function PuzzleAgentWorkspace({
         return;
       }
 
+      const asset = await puzzleAssetClient.uploadReferenceImage({ file });
       setFormState((current) => ({
         ...current,
-        referenceImageSrc: uploadImage.dataUrl,
+        referenceImageSrc: asset.imageSrc || uploadImage.dataUrl,
+        referenceImageAssetObjectId: asset.assetObjectId,
         referenceImageLabel: file.name.trim() || '本地拼图图片',
       }));
       setReferenceImageError(null);
@@ -372,11 +441,18 @@ export function PuzzleAgentWorkspace({
 
     try {
       const images = await Promise.all(
-        files.slice(0, remainingSlots).map(async (file, index) => ({
-          id: `prompt-upload:${Date.now()}:${index}:${file.name}`,
-          label: file.name.trim() || `参考图 ${index + 1}`,
-          imageSrc: await readPuzzleReferenceImageAsDataUrl(file),
-        })),
+        files.slice(0, remainingSlots).map(async (file, index) => {
+          const [imageSrc, asset] = await Promise.all([
+            readPuzzleReferenceImageAsDataUrl(file),
+            puzzleAssetClient.uploadReferenceImage({ file }),
+          ]);
+          return {
+            id: `prompt-upload:${Date.now()}:${index}:${file.name}`,
+            label: file.name.trim() || `参考图 ${index + 1}`,
+            imageSrc: asset.imageSrc || imageSrc,
+            assetObjectId: asset.assetObjectId,
+          };
+        }),
       );
       setFormState((current) => ({
         ...current,
@@ -439,9 +515,15 @@ export function PuzzleAgentWorkspace({
         cropY: currentCropState.cropRect.y,
         cropSize: currentCropState.cropRect.size,
       });
+      const file = puzzleReferenceImageDataUrlToFile(
+        dataUrl,
+        currentCropState.fileName,
+      );
+      const asset = await puzzleAssetClient.uploadReferenceImage({ file });
       setFormState((current) => ({
         ...current,
-        referenceImageSrc: dataUrl,
+        referenceImageSrc: asset.imageSrc || dataUrl,
+        referenceImageAssetObjectId: asset.assetObjectId,
         referenceImageLabel: currentCropState.label,
       }));
       setCropState(null);
@@ -482,8 +564,11 @@ export function PuzzleAgentWorkspace({
     const payload = {
       seedText: payloadPictureDescription,
       pictureDescription: payloadPictureDescription,
-      referenceImageSrc: formState.referenceImageSrc || null,
-      referenceImageSrcs: promptReferenceImageSrcs,
+      referenceImageSrc: mainReferenceImageSrcForPayload,
+      referenceImageSrcs: promptReferenceImageSrcsForPayload,
+      referenceImageAssetObjectId:
+        formState.referenceImageAssetObjectId || null,
+      referenceImageAssetObjectIds: promptReferenceAssetObjectIds,
       imageModel: formState.imageModel,
       aiRedraw: formState.aiRedraw,
     };
@@ -499,8 +584,11 @@ export function PuzzleAgentWorkspace({
       action: 'compile_puzzle_draft',
       promptText: payloadPictureDescription,
       pictureDescription: payloadPictureDescription,
-      referenceImageSrc: formState.referenceImageSrc || null,
-      referenceImageSrcs: promptReferenceImageSrcs,
+      referenceImageSrc: mainReferenceImageSrcForPayload,
+      referenceImageSrcs: promptReferenceImageSrcsForPayload,
+      referenceImageAssetObjectId:
+        formState.referenceImageAssetObjectId || null,
+      referenceImageAssetObjectIds: promptReferenceAssetObjectIds,
       imageModel: formState.imageModel,
       aiRedraw: formState.aiRedraw,
       candidateCount: 1,
@@ -510,6 +598,7 @@ export function PuzzleAgentWorkspace({
     setFormState((current) => ({
       ...current,
       referenceImageSrc: '',
+      referenceImageAssetObjectId: '',
       referenceImageLabel: '',
       aiRedraw: true,
     }));
@@ -645,6 +734,7 @@ export function PuzzleAgentWorkspace({
             setFormState((current) => ({
               ...current,
               referenceImageSrc: asset.imageSrc,
+              referenceImageAssetObjectId: asset.assetObjectId,
               referenceImageLabel: getPuzzleHistoryAssetReferenceLabel(
                 asset.imageSrc,
               ),