feat: 支持批量生图

Co-authored-by: Copilot <copilot@github.com>
2026-04-27 01:40:46 +08:00
parent 9a715dede8
commit 7f59b555c6
22 changed files with 1731 additions and 394 deletions
@@ -1,22 +1,26 @@
-// server/api/images/generate.post.ts - 图片生成接口：创建记录、流式调用上游生图并将图床归档交给数据库队列。
+// server/api/images/generate.post.ts - 图片批量生成接口：创建批次与图片子记录、并行调用上游生图并将图床归档交给数据库队列。
 import type {
  IImageGenerateData,
-  IImageGenerateRequest
+  IImageGenerateRequest,
+  IImageGenerateResultImage
 } from "#shared/types/openai";
 import { wakeImageArchiveWorker } from "~~/server/utils";

+const DEFAULT_BATCH_SIZE = 1;
+const DEFAULT_MAX_BATCH_SIZE = 3;
+
 /**
 * POST /api/images/generate
 *
 * 流程：
- * 1. 校验请求体和 prompt，空 prompt 不创建数据库记录。
+ * 1. 校验请求体、prompt 与 batch_size；空 prompt 和非法数量不创建数据库记录。
 * 2. 从 httpOnly cookie 读取当前 NewAPI 用户 ID。
- * 3. 创建 RUNNING 生图记录，并递增全局请求/进行中统计。
+ * 3. 创建 RUNNING 生图批次记录和对应数量的 RUNNING 图片子记录，并递增全局请求/进行中统计。
 * 4. 在服务端确保并读取 AIArtStudio 完整 key，完整 key 不返回前端。
- * 5. 调用 Chat Completions 流式生图接口，累积 SSE delta content 并提取最终图片 URL。
- * 6. 上游返回图片 URL 后立刻把生图结果落库为 SUCCEEDED，并把图床归档任务标记为待执行。
- * 7. 唤醒数据库归档队列 worker；归档失败只补写记录和日志，不影响本次响应。
- * 8. 主链路失败时把记录标记为 FAILED；鉴权失败会清理本地登录态并返回 401。
+ * 5. 对每张图片并行调用 Chat Completions 流式生图接口，每张图独立落库成功或失败。
+ * 6. 至少一张成功时批次记为 SUCCEEDED，并按成功图片数递增 totalImages；全部失败时批次记为 FAILED。
+ * 7. 成功图片进入图床归档队列；归档失败只补写图片子记录和日志，不影响本次响应。
+ * 8. 主链路鉴权失败会清理本地登录态并返回 401；接口不向前端暴露 key、token、上游响应或内部错误详情。
 */
 export default defineEventHandler(async (event) => {
  const logger = createApiLogger("images.generate");
@@ -42,12 +46,30 @@ export default defineEventHandler(async (event) => {
    return createErrorResponse(400, "请输入图片描述");
  }

-  // 不记录完整 prompt，日志只保留长度，避免把用户输入或潜在敏感内容写进日志。
+  const maxBatchSize = getMaxBatchSize();
+  const batchSizeResult = normalizeBatchSize(
+    requestBody?.batch_size,
+    maxBatchSize
+  );
+  if (!batchSizeResult.ok) {
+    logger.warn("生图数量参数错误", {
+      reason: batchSizeResult.reason,
+      maxBatchSize
+    });
+    return createErrorResponse(400, batchSizeResult.message);
+  }
+  const batchSize = batchSizeResult.value;
+
+  // 不记录完整 prompt，日志只保留长度和数量，避免把用户输入或潜在敏感内容写进日志。
  logger.info("开始", {
-    promptLength: prompt.length
+    promptLength: prompt.length,
+    batchSize,
+    maxBatchSize
  });

-  let record: { id: bigint; startedAt: Date } | null = null;
+  let record: Awaited<ReturnType<typeof createRunningImageGeneration>> | null =
+    null;
+  let batchFinished = false;

  try {
    stage = "read_user_id";
@@ -59,9 +81,10 @@ export default defineEventHandler(async (event) => {

    stage = "create_running_record";
    // 从这里开始才写数据库；参数错误和空 prompt 不会留下无效生图记录。
-    record = await createRunningImageGeneration(userId, prompt);
-    logger.info("创建生图记录成功", {
-      recordId: record.id.toString()
+    record = await createRunningImageGeneration(userId, prompt, batchSize);
+    logger.info("创建生图批次记录成功", {
+      recordId: record.id.toString(),
+      imageCount: record.images.length
    });

    stage = "get_api_key";
@@ -72,39 +95,67 @@ export default defineEventHandler(async (event) => {
    });

    stage = "call_image_stream_api";
-    // 上游通过 SSE 分段返回进度和最终 Markdown 图片链接，这里同步等待流结束。
-    const result = await askImgStream({
-      apiKey,
-      prompt
-    });
-    logger.info("上游流式生图成功", {
-      recordId: record.id.toString(),
-      hasImageUrl: Boolean(result.imageUrl),
-      contentLength: getStreamContentLength(result.upstreamResponse),
-      hasUsage: hasStreamUsage(result.upstreamResponse)
-    });
-
-    stage = "finish_success_record";
-    await finishImageGenerationSuccess(record.id, record.startedAt, {
-      imageUrl: result.imageUrl,
-      revisedPrompt: result.revisedPrompt,
-      upstreamResponse: result.upstreamResponse
-    });
-
-    logger.done("成功", {
-      recordId: record.id.toString(),
-      archiveScheduled: true
-    });
-
-    wakeImageArchiveWorker();
-
-    return createSuccessResponse<IImageGenerateData>(
-      {
-        imageUrl: result.imageUrl,
-        revisedPrompt: result.revisedPrompt
-      },
-      "图片生成成功"
+    const settledResults = await Promise.allSettled(
+      record.images.map((image) =>
+        generateOneImage({
+          apiKey,
+          prompt,
+          imageId: image.id,
+          index: image.index
+        })
+      )
    );
+
+    const images: IImageGenerateResultImage[] = [];
+    const errors: unknown[] = [];
+
+    for (const result of settledResults) {
+      if (result.status === "fulfilled") {
+        images.push(result.value);
+      } else {
+        errors.push(result.reason);
+      }
+    }
+
+    const successCount = images.length;
+    const failedCount = batchSize - successCount;
+
+    stage = "finish_batch_record";
+    await finishImageGenerationBatch({
+      recordId: record.id,
+      startedAt: record.startedAt,
+      successCount,
+      failedCount,
+      error: errors[0]
+    });
+    batchFinished = true;
+
+    logger.done(successCount > 0 ? "成功" : "全部失败", {
+      recordId: record.id.toString(),
+      successCount,
+      failedCount,
+      archiveScheduled: successCount > 0
+    });
+
+    if (successCount > 0) {
+      wakeImageArchiveWorker();
+      return createSuccessResponse<IImageGenerateData>(
+        {
+          recordId: record.id.toString(),
+          batchSize,
+          images: images.sort((left, right) => left.index - right.index),
+          failedCount
+        },
+        failedCount > 0 ? "图片生成完成，部分图片失败" : "图片生成成功"
+      );
+    }
+
+    if (isUnauthorizedError(errors[0])) {
+      clearNewApiAuthCookies(event);
+      return createErrorResponse(401, "未登录");
+    }
+
+    return createUpstreamErrorResponse(errors[0], "图片生成失败");
  } catch (error) {
    logger.error("失败", {
      stage,
@@ -112,13 +163,13 @@ export default defineEventHandler(async (event) => {
      error: toSafeLogError(error)
    });

-    if (record) {
+    if (record && !batchFinished) {
      await finishImageGenerationFailed(
        record.id,
        record.startedAt,
        error
      ).catch((recordError) => {
-        logger.error("更新失败记录失败", {
+        logger.error("更新失败批次记录失败", {
          recordId: record?.id.toString() ?? null,
          error: toSafeLogError(recordError)
        });
@@ -135,26 +186,100 @@ export default defineEventHandler(async (event) => {
  }
 });

-// 日志只读取流式聚合结果的元信息，不记录完整提示词、key 或图片内容。
-const getStreamContentLength = (upstreamResponse: unknown) => {
-  if (
-    upstreamResponse &&
-    typeof upstreamResponse === "object" &&
-    "content" in upstreamResponse &&
-    typeof upstreamResponse.content === "string"
-  ) {
-    return upstreamResponse.content.length;
+// 对单张图片发起上游生图调用，成功时落库并返回结果，失败时落库错误记录后向上抛出原始异常。
+// 落库操作自身的异常会被静默忽略，不会覆盖原始上游错误。
+const generateOneImage = async ({
+  apiKey,
+  prompt,
+  imageId,
+  index
+}: {
+  apiKey: string;
+  prompt: string;
+  imageId: bigint;
+  index: number;
+}): Promise<IImageGenerateResultImage> => {
+  try {
+    const result = await askImgStream({
+      apiKey,
+      prompt
+    });
+
+    await finishImageGenerationImageSuccess(imageId, {
+      imageUrl: result.imageUrl,
+      revisedPrompt: result.revisedPrompt,
+      upstreamResponse: result.upstreamResponse
+    });
+
+    return {
+      id: imageId.toString(),
+      index,
+      status: "SUCCEEDED",
+      imageUrl: result.imageUrl,
+      revisedPrompt: result.revisedPrompt
+    };
+  } catch (error) {
+    // 落库失败记录时忽略其自身异常，确保原始上游错误（含 401）能正确向上传递。
+    // 若不用 .catch() 包裹，finishImageGenerationImageFailed 抛出时 throw error 永远不会执行，
+    // 导致 Promise.allSettled 收到的是 DB 错误而非真正的上游错误，isUnauthorizedError 检查失效。
+    await finishImageGenerationImageFailed(imageId, error).catch(() => {});
+    throw error;
+  }
+};
+
+// normalizeBatchSize 的返回类型：discriminated union，ok=true 时携带合法数量，ok=false 时携带错误原因和面向用户的提示。
+type BatchSizeResult =
+  | {
+      ok: true;
+      value: number;
+    }
+  | {
+      ok: false;
+      reason: string; // 机器可读原因，用于日志
+      message: string; // 面向用户的提示，直接返回给前端
+    };
+
+// 校验并规范化 batch_size 参数：缺省时返回默认值 1，非正整数或超出上限时返回错误结构。
+// 使用 unknown 入参以安全处理来自请求体的任意值，不依赖调用方提前校验类型。
+const normalizeBatchSize = (
+  value: unknown,
+  maxBatchSize: number
+): BatchSizeResult => {
+  if (value === undefined || value === null) {
+    return {
+      ok: true,
+      value: DEFAULT_BATCH_SIZE
+    };
  }

-  return 0;
+  if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+    return {
+      ok: false,
+      reason: "not_positive_integer",
+      message: "生图数量必须是大于 0 的整数"
+    };
+  }
+
+  if (value > maxBatchSize) {
+    return {
+      ok: false,
+      reason: "exceeds_max_batch_size",
+      message: `生图数量不能超过 ${maxBatchSize} 张`
+    };
+  }
+
+  return {
+    ok: true,
+    value
+  };
 };

-/** 判断流式上游响应里是否包含 usage，用于日志确认上游是否正常结束 */
-const hasStreamUsage = (upstreamResponse: unknown) => {
-  return (
-    upstreamResponse !== null &&
-    typeof upstreamResponse === "object" &&
-    "usage" in upstreamResponse &&
-    Boolean(upstreamResponse.usage)
+// 从环境变量读取允许的最大批次大小；解析失败或未配置时回落到内置默认值，不抛出异常。
+const getMaxBatchSize = () => {
+  const value = Number.parseInt(
+    process.env.IMAGE_GENERATION_MAX_BATCH_SIZE ?? "",
+    10
  );
+
+  return Number.isInteger(value) && value > 0 ? value : DEFAULT_MAX_BATCH_SIZE;
 };
@@ -37,7 +37,7 @@ export default defineEventHandler(async (event) => {
      userId,
      recordId: recordId.toString(),
      status: result.status,
-      hasHostedImageUrl: Boolean(result.hostedImageUrl)
+      imageCount: result.images.length
    });

    return createSuccessResponse<IImageHistoryDetail>(
@@ -1,5 +1,8 @@
-// server/api/images/history/[id]/public.post.ts - 生图历史公开接口：将当前用户单条生图记录发布到广场。
-import type { IImagePublicStateData } from "#shared/types/openai";
+// server/api/images/history/[id]/public.post.ts - 生图历史公开接口：将当前用户单个批次中选定的图片发布到广场。
+import type {
+  IImagePublicStateData,
+  IImagePublicStateRequest
+} from "#shared/types/openai";
 import {
  clearNewApiAuthCookies,
  createApiLogger,
@@ -17,9 +20,10 @@ import {
 *
 * 流程：
 * 1. 从 httpOnly cookie 读取当前用户 ID。
- * 2. 只允许公开当前用户、未软删除的生图记录。
- * 3. 允许图片尚未归档时先创建公开记录；广场列表会等 hostedImageUrl 可用后再展示。
- * 4. 不返回上游响应、图床响应或内部错误详情。
+ * 2. 只允许公开当前用户、未软删除的生图批次记录。
+ * 3. 请求体可指定 imageIds 和 coverImageId；空 body 时兼容旧前端，默认公开全部成功图。
+ * 4. 允许图片尚未归档时先创建公开记录；广场列表会等封面 hostedImageUrl 可用后再展示。
+ * 5. 不返回上游响应、图床响应或内部错误详情。
 */
 export default defineEventHandler(async (event) => {
  const logger = createApiLogger("images.history.public.publish");
@@ -28,13 +32,32 @@ export default defineEventHandler(async (event) => {
  try {
    const userId = getNewApiUserIdFromCookie(event);
    const recordId = parseRecordId(getRouterParam(event, "id"));
+    const requestBody = await readBody<IImagePublicStateRequest | null>(event);
+
+    if (
+      requestBody === null ||
+      typeof requestBody !== "object" ||
+      Array.isArray(requestBody)
+    ) {
+      return createErrorResponse(400, "请求体必须是 JSON 对象");
+    }
+
+    const imageIds = parseImageIds(requestBody.imageIds);
+    const coverImageId = parseRecordId(requestBody.coverImageId);

    logger.info("公开参数", {
      userId,
-      recordId: recordId.toString()
+      recordId: recordId.toString(),
+      imageCount: imageIds.length,
+      coverImageId: coverImageId.toString()
    });

-    const result = await publishImageGenerationToPlaza(userId, recordId);
+    const result = await publishImageGenerationToPlaza({
+      userId,
+      recordId,
+      imageIds,
+      coverImageId
+    });

    if (!result) {
      logger.warn("记录不存在", {
@@ -52,9 +75,19 @@ export default defineEventHandler(async (event) => {
      return createErrorResponse(403, "图片已下架，无法公开");
    }

+    if (result === "INVALID_IMAGES") {
+      logger.warn("公开图片参数无效", {
+        userId,
+        recordId: recordId.toString()
+      });
+      return createErrorResponse(400, "请选择可公开的图片");
+    }
+
    logger.done("成功", {
      userId,
-      recordId: recordId.toString()
+      recordId: recordId.toString(),
+      imageCount: result.imageIds?.length ?? 0,
+      coverImageId: result.coverImageId
    });

    return createSuccessResponse<IImagePublicStateData>(result, "图片已公开");
@@ -68,7 +101,7 @@ export default defineEventHandler(async (event) => {
    }

    if (isBadRequestError(error)) {
-      return createErrorResponse(400, "生图记录 ID 不正确");
+      return createErrorResponse(400, getBadRequestMessage(error));
    }

    logger.error("失败", {
@@ -90,6 +123,17 @@ const parseRecordId = (value: string | undefined): bigint => {
  return BigInt(value);
 };

+const parseImageIds = (value: unknown): bigint[] => {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: "请选择可公开的图片"
+    });
+  }
+
+  return Array.from(new Set(value.map((item) => parseRecordId(String(item)))));
+};
+
 const isBadRequestError = (error: unknown): boolean => {
  return (
    typeof error === "object" &&
@@ -98,3 +142,17 @@ const isBadRequestError = (error: unknown): boolean => {
    error.statusCode === 400
  );
 };
+
+const getBadRequestMessage = (error: unknown) => {
+  if (
+    typeof error === "object" &&
+    error !== null &&
+    "statusMessage" in error &&
+    typeof error.statusMessage === "string" &&
+    error.statusMessage
+  ) {
+    return error.statusMessage;
+  }
+
+  return "生图记录 ID 不正确";
+};
@@ -0,0 +1,79 @@
+// server/api/images/plaza/[id].get.ts - 广场公开详情接口：返回单个公开批次中可展示的全部公开图片。
+import type { IPlazaPostDetail } from "#shared/types/openai";
+import {
+  createApiLogger,
+  createErrorResponse,
+  createSuccessResponse,
+  createUpstreamErrorResponse,
+  getPlazaPostDetail,
+  toSafeLogError
+} from "~~/server/utils";
+
+/**
+ * GET /api/images/plaza/:id
+ *
+ * 流程：
+ * 1. 校验路由参数 id 必须是数字。
+ * 2. 只返回 PUBLIC、批次未删除、图片已归档成功的公开详情。
+ * 3. 不返回上游响应、图床响应或内部错误详情。
+ */
+export default defineEventHandler(async (event) => {
+  const logger = createApiLogger("images.plaza.detail");
+  logger.info("开始");
+
+  try {
+    const postId = parseRecordId(getRouterParam(event, "id"));
+
+    logger.info("查询参数", {
+      postId: postId.toString()
+    });
+
+    const result = await getPlazaPostDetail(postId);
+    if (!result) {
+      logger.warn("公开记录不存在", {
+        postId: postId.toString()
+      });
+      return createErrorResponse(404, "公开记录不存在");
+    }
+
+    logger.done("成功", {
+      postId: postId.toString(),
+      imageCount: result.images.length
+    });
+
+    return createSuccessResponse<IPlazaPostDetail>(
+      result,
+      "获取广场图片详情成功"
+    );
+  } catch (error) {
+    if (isBadRequestError(error)) {
+      return createErrorResponse(400, "公开记录 ID 不正确");
+    }
+
+    logger.error("失败", {
+      error: toSafeLogError(error)
+    });
+    return createUpstreamErrorResponse(error, "获取广场图片详情失败");
+  }
+});
+
+/** 校验并解析路由里的记录 ID */
+const parseRecordId = (value: string | undefined): bigint => {
+  if (!value || !/^\d+$/.test(value)) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: "公开记录 ID 不正确"
+    });
+  }
+
+  return BigInt(value);
+};
+
+const isBadRequestError = (error: unknown): boolean => {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "statusCode" in error &&
+    error.statusCode === 400
+  );
+};
@@ -145,7 +145,8 @@ const runImageArchiveTask = (

    consola.info("[imageArchiveQueue] 归档开始", {
      workerId: workerState.workerId,
-      recordId: task.id.toString(),
+      recordId: task.recordId.toString(),
+      imageId: task.imageId.toString(),
      attempt: task.archiveAttempts
    });

@@ -156,12 +157,13 @@ const runImageArchiveTask = (
        imageUrl: task.imageUrl,
        userId: task.userId,
        username: identity.username,
-        recordId: task.id,
-        createdAt: task.startedAt
+        recordId: task.recordId,
+        imageId: task.imageId,
+        createdAt: task.createdAt
      });

      // 成功后补写 hosted 字段；前端仍通过历史接口读取归档结果，不暴露图床完整响应。
-      await finishImageGenerationArchiveSuccess(task.id, {
+      await finishImageGenerationArchiveSuccess(task.imageId, {
        hostedImageUrl: uploaded.publicUrl,
        imageMimeType: uploaded.mimetype,
        hostedResponse: uploaded.response
@@ -169,7 +171,8 @@ const runImageArchiveTask = (

      consola.info("[imageArchiveQueue] 归档成功", {
        workerId: workerState.workerId,
-        recordId: task.id.toString(),
+        recordId: task.recordId.toString(),
+        imageId: task.imageId.toString(),
        mimeType: uploaded.mimetype,
        byteLength: uploaded.byteLength,
        elapsedMs: Date.now() - startedAt
@@ -197,7 +200,8 @@ const handleImageArchiveFailure = async (
  // 归档日志只保留排查摘要，不记录 token、图片二进制、完整图床响应或完整上游响应。
  consola.error("[imageArchiveQueue] 归档失败", {
    workerId: workerState.workerId,
-    recordId: task.id.toString(),
+    recordId: task.recordId.toString(),
+    imageId: task.imageId.toString(),
    attempt: task.archiveAttempts,
    terminal: shouldStop,
    error: safeError
@@ -205,13 +209,13 @@ const handleImageArchiveFailure = async (

  if (shouldStop) {
    // 最终失败只影响归档字段，生图状态保持 SUCCEEDED，前端看到的是本地化“图片归档失败”。
-    await finishImageGenerationArchiveFailed(task.id, errorMessage);
+    await finishImageGenerationArchiveFailed(task.imageId, errorMessage);
    return;
  }

  // 可重试失败会清掉本次锁并设置下一次执行时间，期间历史记录仍表现为归档中。
  await scheduleImageGenerationArchiveRetry({
-    recordId: task.id,
+    imageId: task.imageId,
    nextRunAt: new Date(Date.now() + getRetryDelayMs(task.archiveAttempts)),
    errorMessage
  });
@@ -1,8 +1,9 @@
-// server/utils/imageGenerationRecords.ts - 生图相关数据库操作：用户快照、生成记录、历史查询和统计。
+// server/utils/imageGenerationRecords.ts - 生图相关数据库操作：用户快照、批次记录、图片子记录、历史查询和统计。
 import type { IUserBasicData } from "#shared/types";
 import type {
  IImageGenerationStatsData,
  IImageHistoryDetail,
+  IImageHistoryImageItem,
  IImageHistoryItem,
  IImageHistoryListData
 } from "#shared/types/openai";
@@ -18,16 +19,16 @@ import { prisma } from "~~/server/utils/prisma";
 const GLOBAL_STATS_ID = "global";
 const DEFAULT_IMAGE_MODEL = "gpt-image-2";

-interface IFinishImageGenerationSuccessInput {
+interface IFinishImageGenerationImageSuccessInput {
  /** NewAPI 上游返回的生成图片 URL */
  imageUrl: string;
  /** 上游返回的修订提示词，流式生图通常为空 */
  revisedPrompt?: string | null;
-  /** 完整上游响应，当前为 chat completions 流式聚合对象 */
+  /** 完整上游响应，仅服务端内部保存 */
  upstreamResponse: unknown;
 }

-interface IFinishImageGenerationArchiveSuccessInput {
+interface IFinishImageGenerationImageArchiveSuccessInput {
  /** Lsky 图床归档后的图片 URL */
  hostedImageUrl: string;
  /** 图片 MIME 类型，优先来自图床上传结果 */
@@ -37,14 +38,16 @@ interface IFinishImageGenerationArchiveSuccessInput {
 }

 export interface IImageArchiveTask {
-  /** 生图记录 ID */
-  id: bigint;
+  /** 生图图片子记录 ID */
+  imageId: bigint;
+  /** 所属生图批次记录 ID */
+  recordId: bigint;
  /** NewAPI 用户 ID */
  userId: number;
  /** 上游生成图片 URL */
  imageUrl: string;
-  /** 记录创建时间，用于构造图床文件名 */
-  startedAt: Date;
+  /** 图片子记录创建时间，用于构造图床文件名 */
+  createdAt: Date;
  /** 当前这次归档是第几次尝试 */
  archiveAttempts: number;
 }
@@ -103,10 +106,11 @@ export const getUserArchiveIdentity = async (userId: number) => {
  };
 };

-/** 创建进行中的生图记录，并递增全局请求与进行中统计 */
+/** 创建进行中的生图批次和图片子记录，并递增全局请求/进行中统计 */
 export const createRunningImageGeneration = async (
  userId: number,
-  prompt: string
+  prompt: string,
+  batchSize: number
 ) => {
  await ensureUserRecord(userId);

@@ -115,7 +119,26 @@ export const createRunningImageGeneration = async (
      userId,
      prompt,
      status: ImageGenerationStatus.RUNNING,
-      model: DEFAULT_IMAGE_MODEL
+      model: DEFAULT_IMAGE_MODEL,
+      batchSize,
+      images: {
+        create: Array.from({ length: batchSize }, (_, index) => ({
+          userId,
+          index,
+          status: ImageGenerationStatus.RUNNING
+        }))
+      }
+    },
+    include: {
+      images: {
+        orderBy: {
+          index: "asc"
+        },
+        select: {
+          id: true,
+          index: true
+        }
+      }
    }
  });

@@ -131,22 +154,17 @@ export const createRunningImageGeneration = async (
  return record;
 };

-/** 将生图记录标记为成功，并先写入上游结果；图床字段稍后由后台归档补写 */
-export const finishImageGenerationSuccess = async (
-  recordId: bigint,
-  startedAt: Date,
-  input: IFinishImageGenerationSuccessInput
+/** 将单张图片子记录标记为成功，并先写入上游结果；图床字段稍后由后台归档补写 */
+export const finishImageGenerationImageSuccess = async (
+  imageId: bigint,
+  input: IFinishImageGenerationImageSuccessInput
 ) => {
-  const endedAt = new Date();
-
-  await prisma.imageGeneration.update({
+  await prisma.imageGenerationImage.update({
    where: {
-      id: recordId
+      id: imageId
    },
    data: {
      status: ImageGenerationStatus.SUCCEEDED,
-      endedAt,
-      durationMs: getDurationMs(startedAt, endedAt),
      imageUrl: input.imageUrl,
      hostedImageUrl: null,
      imageMimeType: null,
@@ -162,48 +180,115 @@ export const finishImageGenerationSuccess = async (
      archiveLastError: null
    }
  });
+};

-  await safeUpsertGenerationStats({
-    successRequests: {
-      increment: 1
+/** 将单张图片子记录标记为失败，只保留服务端可排查摘要 */
+export const finishImageGenerationImageFailed = async (
+  imageId: bigint,
+  error: unknown
+) => {
+  await prisma.imageGenerationImage.update({
+    where: {
+      id: imageId
    },
-    runningRequests: {
-      decrement: 1
-    },
-    totalImages: {
-      increment: 1
+    data: {
+      status: ImageGenerationStatus.FAILED,
+      errorMessage: getSafeErrorMessage(error),
+      archiveStatus: ImageArchiveStatus.NOT_REQUIRED
    }
  });
 };

-/** 将生图记录标记为失败，并保存失败原因和耗时 */
-export const finishImageGenerationFailed = async (
-  recordId: bigint,
-  startedAt: Date,
-  error: unknown
-) => {
+/** 批次内所有图片都结束后，汇总批次状态与全局统计 */
+export const finishImageGenerationBatch = async ({
+  recordId,
+  startedAt,
+  successCount,
+  failedCount,
+  error
+}: {
+  recordId: bigint;
+  startedAt: Date;
+  successCount: number;
+  failedCount: number;
+  error?: unknown;
+}) => {
  const endedAt = new Date();
+  const hasSuccess = successCount > 0;

  await prisma.imageGeneration.update({
    where: {
      id: recordId
    },
    data: {
-      status: ImageGenerationStatus.FAILED,
+      status: hasSuccess
+        ? ImageGenerationStatus.SUCCEEDED
+        : ImageGenerationStatus.FAILED,
      endedAt,
      durationMs: getDurationMs(startedAt, endedAt),
-      errorMessage: getSafeErrorMessage(error)
+      successCount,
+      failedCount,
+      errorMessage: hasSuccess ? null : getSafeErrorMessage(error)
    }
  });

  await safeUpsertGenerationStats({
-    failedRequests: {
-      increment: 1
-    },
+    successRequests: hasSuccess
+      ? {
+          increment: 1
+        }
+      : undefined,
+    failedRequests: hasSuccess
+      ? undefined
+      : {
+          increment: 1
+        },
    runningRequests: {
      decrement: 1
+    },
+    totalImages:
+      successCount > 0
+        ? {
+            increment: successCount
+          }
+        : undefined
+  });
+};
+
+/** 兼容旧调用：主链路异常且尚未逐图结算时，把整个批次标记为失败 */
+export const finishImageGenerationFailed = async (
+  recordId: bigint,
+  startedAt: Date,
+  error: unknown
+) => {
+  const record = await prisma.imageGeneration.findUnique({
+    where: {
+      id: recordId
+    },
+    select: {
+      batchSize: true
    }
  });
+
+  await prisma.imageGenerationImage.updateMany({
+    where: {
+      imageGenerationId: recordId,
+      status: ImageGenerationStatus.RUNNING
+    },
+    data: {
+      status: ImageGenerationStatus.FAILED,
+      errorMessage: getSafeErrorMessage(error),
+      archiveStatus: ImageArchiveStatus.NOT_REQUIRED
+    }
+  });
+
+  await finishImageGenerationBatch({
+    recordId,
+    startedAt,
+    successCount: 0,
+    failedCount: record?.batchSize ?? 1,
+    error
+  });
 };

 /** 领取可执行的图床归档任务；通过 updateMany 条件锁避免多实例重复处理 */
@@ -221,7 +306,7 @@ export const claimRunnableImageArchiveTasks = async ({
  const now = new Date();
  const staleBefore = new Date(now.getTime() - lockTtlMs);
  const runnableWhere = buildRunnableArchiveWhere(now, staleBefore);
-  const candidates = await prisma.imageGeneration.findMany({
+  const candidates = await prisma.imageGenerationImage.findMany({
    where: runnableWhere,
    select: {
      id: true
@@ -241,7 +326,7 @@ export const claimRunnableImageArchiveTasks = async ({
  for (const candidate of candidates) {
    if (tasks.length >= limit) break;

-    const claimed = await prisma.imageGeneration.updateMany({
+    const claimed = await prisma.imageGenerationImage.updateMany({
      where: {
        id: candidate.id,
        ...runnableWhere
@@ -259,25 +344,27 @@ export const claimRunnableImageArchiveTasks = async ({

    if (claimed.count !== 1) continue;

-    const task = await prisma.imageGeneration.findUnique({
+    const task = await prisma.imageGenerationImage.findUnique({
      where: {
        id: candidate.id
      },
      select: {
        id: true,
+        imageGenerationId: true,
        userId: true,
        imageUrl: true,
-        startedAt: true,
+        createdAt: true,
        archiveAttempts: true
      }
    });

    if (task?.imageUrl) {
      tasks.push({
-        id: task.id,
+        imageId: task.id,
+        recordId: task.imageGenerationId,
        userId: task.userId,
        imageUrl: task.imageUrl,
-        startedAt: task.startedAt,
+        createdAt: task.createdAt,
        archiveAttempts: task.archiveAttempts
      });
    }
@@ -288,12 +375,12 @@ export const claimRunnableImageArchiveTasks = async ({

 /** 后台归档成功后回写图床地址、MIME 和图床响应 */
 export const finishImageGenerationArchiveSuccess = async (
-  recordId: bigint,
-  input: IFinishImageGenerationArchiveSuccessInput
+  imageId: bigint,
+  input: IFinishImageGenerationImageArchiveSuccessInput
 ) => {
-  await prisma.imageGeneration.update({
+  await prisma.imageGenerationImage.update({
    where: {
-      id: recordId
+      id: imageId
    },
    data: {
      hostedImageUrl: input.hostedImageUrl,
@@ -311,17 +398,17 @@ export const finishImageGenerationArchiveSuccess = async (

 /** 归档可重试失败时释放任务锁并安排下一次执行，前端仍显示归档中 */
 export const scheduleImageGenerationArchiveRetry = async ({
-  recordId,
+  imageId,
  nextRunAt,
  errorMessage
 }: {
-  recordId: bigint;
+  imageId: bigint;
  nextRunAt: Date;
  errorMessage: string;
 }) => {
-  await prisma.imageGeneration.update({
+  await prisma.imageGenerationImage.update({
    where: {
-      id: recordId
+      id: imageId
    },
    data: {
      archiveStatus: ImageArchiveStatus.PENDING,
@@ -336,12 +423,12 @@ export const scheduleImageGenerationArchiveRetry = async ({

 /** 后台归档最终失败时仅补写本地错误文案，不影响已成功的生图状态 */
 export const finishImageGenerationArchiveFailed = async (
-  recordId: bigint,
+  imageId: bigint,
  errorMessage: string = "图片归档失败"
 ) => {
-  await prisma.imageGeneration.update({
+  await prisma.imageGenerationImage.update({
    where: {
-      id: recordId
+      id: imageId
    },
    data: {
      archiveStatus: ImageArchiveStatus.FAILED,
@@ -354,7 +441,7 @@ export const finishImageGenerationArchiveFailed = async (
  });
 };

-/** 查询当前用户未删除的生图历史列表，不返回完整上游/图床响应 */
+/** 查询当前用户未删除的生图批次历史列表，不返回完整上游/图床响应 */
 export const listImageGenerationHistory = async ({
  userId,
  page,
@@ -373,13 +460,7 @@ export const listImageGenerationHistory = async ({
    prisma.imageGeneration.count({ where }),
    prisma.imageGeneration.findMany({
      where,
-      include: {
-        plazaPost: {
-          select: {
-            status: true
-          }
-        }
-      },
+      include: historyInclude,
      orderBy: {
        createdAt: "desc"
      },
@@ -396,7 +477,7 @@ export const listImageGenerationHistory = async ({
  };
 };

-/** 查询当前用户单条生图历史详情，内部响应字段固定隐藏为 null */
+/** 查询当前用户单条生图批次详情，内部响应字段固定隐藏为 null */
 export const getImageGenerationDetail = async (
  userId: number,
  recordId: bigint
@@ -407,26 +488,15 @@ export const getImageGenerationDetail = async (
      userId,
      deletedAt: null
    },
-    include: {
-      plazaPost: {
-        select: {
-          status: true
-        }
-      }
-    }
+    include: historyInclude
  });

  if (!record) return null;

-  return {
-    ...mapImageGenerationItem(record),
-    imageMimeType: record.imageMimeType,
-    upstreamResponse: null,
-    hostedResponse: null
-  };
+  return mapImageGenerationItem(record);
 };

-/** 软删除当前用户单条生图历史 */
+/** 软删除当前用户单条生图批次历史 */
 export const softDeleteImageGeneration = async (
  userId: number,
  recordId: bigint
@@ -482,8 +552,12 @@ const upsertGenerationStats = (update: Prisma.GenerationStatsUpdateInput) => {
 const safeUpsertGenerationStats = async (
  update: Prisma.GenerationStatsUpdateInput
 ) => {
+  const cleanUpdate = Object.fromEntries(
+    Object.entries(update).filter(([, value]) => value !== undefined)
+  ) as Prisma.GenerationStatsUpdateInput;
+
  try {
-    await upsertGenerationStats(update);
+    await upsertGenerationStats(cleanUpdate);
  } catch (error) {
    consola.error("[imageGenerationRecords] 更新生图统计失败", {
      message: error instanceof Error ? error.message : String(error)
@@ -503,14 +577,16 @@ const buildStatsCreateInput = (update: Prisma.GenerationStatsUpdateInput) => {
  };
 };

-/** 只领取成功生成、未删除、已到执行时间或锁超时的归档任务 */
+/** 只领取成功生成、所属批次未删除、已到执行时间或锁超时的归档任务 */
 const buildRunnableArchiveWhere = (now: Date, staleBefore: Date) => {
  return {
    status: ImageGenerationStatus.SUCCEEDED,
-    deletedAt: null,
    imageUrl: {
      not: null
    },
+    imageGeneration: {
+      deletedAt: null
+    },
    OR: [
      {
        archiveStatus: ImageArchiveStatus.PENDING,
@@ -532,7 +608,7 @@ const buildRunnableArchiveWhere = (now: Date, staleBefore: Date) => {
        }
      }
    ]
-  } satisfies Prisma.ImageGenerationWhereInput;
+  } satisfies Prisma.ImageGenerationImageWhereInput;
 };

 /** 从 Prisma increment 操作里取出增量；非 increment 操作在创建时按 0 处理 */
@@ -549,43 +625,97 @@ const getIncrementValue = (value: unknown): number => {
  return 0;
 };

-/** 将 Prisma 记录转换为前端类型，BigInt/Date 在这里统一序列化 */
-const mapImageGenerationItem = (record: {
-  id: bigint;
-  userId: number;
-  prompt: string;
-  status: ImageGenerationStatus;
-  model: string;
-  startedAt: Date;
-  endedAt: Date | null;
-  durationMs: number | null;
-  imageUrl: string | null;
-  hostedImageUrl: string | null;
-  revisedPrompt: string | null;
-  errorMessage: string | null;
-  createdAt: Date;
-  plazaPost?: {
-    status: PlazaPostStatus;
-  } | null;
-}): IImageHistoryItem => {
+const historyInclude = {
+  images: {
+    orderBy: {
+      index: "asc" as const
+    }
+  },
+  plazaPost: {
+    select: {
+      status: true,
+      coverImageId: true,
+      images: {
+        select: {
+          imageGenerationImageId: true
+        }
+      }
+    }
+  }
+};
+
+type ImageGenerationWithHistory = Prisma.ImageGenerationGetPayload<{
+  include: typeof historyInclude;
+}>;
+
+/** 将 Prisma 批次记录转换为前端类型，BigInt/Date 在这里统一序列化 */
+const mapImageGenerationItem = (
+  record: ImageGenerationWithHistory
+): IImageHistoryItem => {
+  const images = record.images.map((image) =>
+    mapImageGenerationImageItem(image, record.plazaPost)
+  );
+  const publicImageIds = getPublicImageIds(record.plazaPost);
+
  return {
    id: record.id.toString(),
    userId: record.userId,
    prompt: record.prompt,
    status: record.status,
    model: record.model,
+    batchSize: record.batchSize,
+    successCount: record.successCount,
+    failedCount: record.failedCount,
    startedAt: record.startedAt.toISOString(),
    endedAt: record.endedAt?.toISOString() ?? null,
    durationMs: record.durationMs,
-    imageUrl: record.imageUrl,
-    hostedImageUrl: record.hostedImageUrl,
-    revisedPrompt: record.revisedPrompt,
-    errorMessage: getPublicRecordMessage(record.status, record.errorMessage),
-    isPublic: record.plazaPost?.status === PlazaPostStatus.PUBLIC,
+    errorMessage: getPublicBatchMessage(record.status, record.errorMessage),
+    isPublic:
+      record.plazaPost?.status === PlazaPostStatus.PUBLIC &&
+      publicImageIds.size > 0,
+    coverImageId: record.plazaPost?.coverImageId?.toString() ?? null,
+    images,
    createdAt: record.createdAt.toISOString()
  };
 };

+const mapImageGenerationImageItem = (
+  image: ImageGenerationWithHistory["images"][number],
+  plazaPost: ImageGenerationWithHistory["plazaPost"]
+): IImageHistoryImageItem => {
+  const publicImageIds = getPublicImageIds(plazaPost);
+
+  return {
+    id: image.id.toString(),
+    index: image.index,
+    status: image.status,
+    imageUrl: image.imageUrl,
+    hostedImageUrl: image.hostedImageUrl,
+    imageMimeType: image.imageMimeType,
+    revisedPrompt: image.revisedPrompt,
+    errorMessage: getPublicImageMessage(image.status, image.errorMessage),
+    isPublic:
+      plazaPost?.status === PlazaPostStatus.PUBLIC && publicImageIds.has(image.id),
+    isCover:
+      plazaPost?.status === PlazaPostStatus.PUBLIC &&
+      plazaPost.coverImageId === image.id,
+    createdAt: image.createdAt.toISOString()
+  };
+};
+
+/** 展示图优先使用公开封面，其次使用第一张成功图，再兜底第一张子记录 */
+const getPublicImageIds = (
+  plazaPost: ImageGenerationWithHistory["plazaPost"]
+): Set<bigint> => {
+  if (!plazaPost || plazaPost.status !== PlazaPostStatus.PUBLIC) {
+    return new Set();
+  }
+
+  return new Set(
+    plazaPost.images.map((image) => image.imageGenerationImageId)
+  );
+};
+
 /** 计算耗时并兜底为非负数，避免系统时间抖动导致负值 */
 const getDurationMs = (startedAt: Date, endedAt: Date) => {
  return Math.max(0, endedAt.getTime() - startedAt.getTime());
@@ -598,8 +728,17 @@ const getSafeErrorMessage = (error: unknown): string => {
  return "图片生成失败";
 };

-/** 返回给前端的记录错误只保留本地泛化文案，具体内部错误留在数据库和服务端日志 */
-const getPublicRecordMessage = (
+/** 批次错误返回本地泛化文案，具体内部错误留在数据库和服务端日志 */
+const getPublicBatchMessage = (
+  status: ImageGenerationStatus,
+  errorMessage: string | null
+): string | null => {
+  if (!errorMessage) return null;
+  return status === ImageGenerationStatus.FAILED ? "图片生成失败" : null;
+};
+
+/** 图片错误返回本地泛化文案，归档失败和生成失败分开表达 */
+const getPublicImageMessage = (
  status: ImageGenerationStatus,
  errorMessage: string | null
 ): string | null => {
@@ -6,6 +6,7 @@ interface ILskyUploadInput {
  userId: number;
  username?: string | null;
  recordId: bigint;
+  imageId: bigint;
  createdAt: Date;
 }

@@ -55,6 +56,7 @@ export const uploadImageFromUrl = async (
    userId: input.userId,
    username: input.username,
    recordId: input.recordId,
+    imageId: input.imageId,
    createdAt: input.createdAt,
    extension
  });
@@ -69,9 +71,16 @@ export const uploadImageFromUrl = async (
  );
  formData.append("storage_id", String(config.storageId));
  formData.append("is_remove_exif", "true");
-  formData.append("intro", `AIArtStudio image generation ${input.recordId}`);
+  formData.append(
+    "intro",
+    `AIArtStudio image generation ${input.recordId} image ${input.imageId}`
+  );

-  for (const tag of buildArchiveTags(input.userId, input.recordId)) {
+  for (const tag of buildArchiveTags(
+    input.userId,
+    input.recordId,
+    input.imageId
+  )) {
    formData.append("tags[]", tag);
  }

@@ -231,26 +240,33 @@ const buildArchiveFilename = ({
  userId,
  username,
  recordId,
+  imageId,
  createdAt,
  extension
 }: {
  userId: number;
  username?: string | null;
  recordId: bigint;
+  imageId: bigint;
  createdAt: Date;
  extension: string;
 }) => {
  const safeUsername = sanitizeFilenamePart(username || "user");
  const timestamp = formatTimestamp(createdAt);
-  return `${userId}_${safeUsername}_${timestamp}_${recordId.toString()}.${extension}`;
+  return `${userId}_${safeUsername}_${timestamp}_${recordId.toString()}_${imageId.toString()}.${extension}`;
 };

 /** 给图片打固定标签，便于后续在图床里按项目、用户、记录和模型筛选 */
-const buildArchiveTags = (userId: number, recordId: bigint) => {
+const buildArchiveTags = (
+  userId: number,
+  recordId: bigint,
+  imageId: bigint
+) => {
  return [
    "AIArtStudio",
    `user:${userId}`,
    `record:${recordId.toString()}`,
+    `image:${imageId.toString()}`,
    "model:gpt-image-2"
  ];
 };
@@ -1,6 +1,6 @@
 // server/utils/openai.ts - OpenAI/NewAPI 调用工具：文本、视觉、Responses 流式和 Chat Completions 流式生图。
 import OpenAI from "openai";
-import type { BaseOptions, IImageGenerateData } from "#shared/types/openai";
+import type { BaseOptions } from "#shared/types/openai";

 /** 图像生成改走 Chat Completions 流式接口，通常能更快拿到中转平台返回的图片地址 */
 const CHAT_COMPLETIONS_URL = "https://api.qflink.xyz/v1/chat/completions";
@@ -36,7 +36,11 @@ interface IImageStreamUpstreamResponse {
  usage?: unknown;
 }

-export interface IAskImageResult extends IImageGenerateData {
+export interface IAskImageResult {
+  /** 上游返回的生成图片访问地址 */
+  imageUrl: string;
+  /** 上游返回的修订提示词，可能为空 */
+  revisedPrompt?: string | null;
  /** 完整上游生图接口返回结果，仅服务端内部保存 */
  upstreamResponse: unknown;
 }
@@ -251,8 +255,8 @@ const readChatCompletionStream = async (
      }

      finishReason =
-        chunk.choices?.find((choice) => choice.finish_reason)
-          ?.finish_reason ?? finishReason;
+        chunk.choices?.find((choice) => choice.finish_reason)?.finish_reason ??
+        finishReason;
    }
  }

@@ -1,8 +1,9 @@
-// server/utils/plazaPosts.ts - 广场发布记录数据库操作：公开、取消公开、广场列表查询。
-// 广场帖子与 ImageGeneration 一对一关联，状态流转：PUBLIC → HIDDEN（用户自主） / REMOVED（管理员下架，不可恢复）。
+// server/utils/plazaPosts.ts - 广场发布记录数据库操作：公开、取消公开、广场列表和公开详情查询。
+// 广场帖子与 ImageGeneration 批次一对一关联，帖子内通过 PlazaPostImage 关联用户选择公开的图片集合。
 // 本文件不向调用方暴露上游响应、图床响应或内部错误字段。
 import type {
  IImagePublicStateData,
+  IPlazaPostDetail,
  IPlazaPostItem,
  IPlazaPostListData
 } from "#shared/types/openai";
@@ -15,28 +16,50 @@ import { prisma } from "~~/server/utils/prisma";
 /** 作者未设置昵称时的展示兜底文案 */
 const ANONYMOUS_AUTHOR_NAME = "匿名用户";

-/** 发布操作的三种结果：成功返回公开状态、记录不存在返回 null、已被管理员下架返回 "REMOVED" */
-export type PublishPlazaPostResult = IImagePublicStateData | null | "REMOVED";
+/** 发布操作结果：成功返回公开状态，记录不存在返回 null，已下架或参数非法返回对应字面量 */
+export type PublishPlazaPostResult =
+  | IImagePublicStateData
+  | null
+  | "REMOVED"
+  | "INVALID_IMAGES";

 /**
- * 将指定生图记录发布到广场。
+ * 将指定生图批次发布到广场。
 * - 记录不存在或已软删除时返回 null。
 * - 记录已被管理员 REMOVED 时返回 "REMOVED"，调用方应提示用户无法重新发布。
- * - 其余情况 upsert 为 PUBLIC，允许重复调用（幂等）。
+ * - imageIds 和 coverImageId 必须由调用方显式传入，不再兼容空 body 默认公开全部。
+ * - coverImageId 必须属于公开图片集合；所有公开图片必须属于该批次且生成成功。
 */
-export const publishImageGenerationToPlaza = async (
-  userId: number,
-  recordId: bigint
-): Promise<PublishPlazaPostResult> => {
+export const publishImageGenerationToPlaza = async ({
+  userId,
+  recordId,
+  imageIds,
+  coverImageId
+}: {
+  userId: number;
+  recordId: bigint;
+  imageIds: bigint[];
+  coverImageId: bigint;
+}): Promise<PublishPlazaPostResult> => {
  const record = await prisma.imageGeneration.findFirst({
    where: {
      id: recordId,
      userId,
      deletedAt: null
    },
-    select: {
-      id: true,
-      userId: true,
+    include: {
+      images: {
+        where: {
+          status: ImageGenerationStatus.SUCCEEDED
+        },
+        orderBy: {
+          index: "asc"
+        },
+        select: {
+          id: true,
+          index: true
+        }
+      },
      plazaPost: {
        select: {
          status: true
@@ -48,29 +71,71 @@ export const publishImageGenerationToPlaza = async (
  if (!record) return null;
  if (record.plazaPost?.status === PlazaPostStatus.REMOVED) return "REMOVED";

-  await prisma.plazaPost.upsert({
-    where: {
-      imageGenerationId: record.id
-    },
-    create: {
-      imageGenerationId: record.id,
-      userId: record.userId,
-      status: PlazaPostStatus.PUBLIC
-    },
-    update: {
-      status: PlazaPostStatus.PUBLIC,
-      hiddenAt: null,
-      removedAt: null
-    }
+  const availableImageIds = new Set(record.images.map((image) => image.id));
+  const selectedImageIds = Array.from(new Set(imageIds));
+
+  if (selectedImageIds.length === 0) return "INVALID_IMAGES";
+  if (selectedImageIds.some((imageId) => !availableImageIds.has(imageId))) {
+    return "INVALID_IMAGES";
+  }
+
+  const selectedImageIdSet = new Set(selectedImageIds);
+  if (!selectedImageIdSet.has(coverImageId)) {
+    return "INVALID_IMAGES";
+  }
+
+  const sortedSelectedImages = record.images.filter((image) =>
+    selectedImageIdSet.has(image.id)
+  );
+
+  const result = await prisma.$transaction(async (tx) => {
+    const post = await tx.plazaPost.upsert({
+      where: {
+        imageGenerationId: record.id
+      },
+      create: {
+        imageGenerationId: record.id,
+        coverImageId,
+        userId: record.userId,
+        status: PlazaPostStatus.PUBLIC
+      },
+      update: {
+        coverImageId,
+        status: PlazaPostStatus.PUBLIC,
+        hiddenAt: null,
+        removedAt: null
+      }
+    });
+
+    await tx.plazaPostImage.deleteMany({
+      where: {
+        plazaPostId: post.id
+      }
+    });
+
+    await tx.plazaPostImage.createMany({
+      data: sortedSelectedImages.map((image, sortOrder) => ({
+        plazaPostId: post.id,
+        imageGenerationImageId: image.id,
+        sortOrder
+      }))
+    });
+
+    return {
+      post,
+      imageIds: sortedSelectedImages.map((image) => image.id.toString())
+    };
  });

  return {
-    isPublic: true
+    isPublic: true,
+    imageIds: result.imageIds,
+    coverImageId: result.post.coverImageId.toString()
  };
 };

 /**
- * 将指定生图记录从广场隐藏（用户主动操作）。
+ * 将指定生图批次从广场隐藏（用户主动操作）。
 * - 记录不存在或已软删除时返回 null。
 * - 帖子不存在或已被 REMOVED 时 updateMany count 为 0，同样返回 null。
 * - 不允许将 REMOVED 状态改为 HIDDEN，REMOVED 由管理员操作，不在此处处理。
@@ -116,10 +181,10 @@ export const hideImageGenerationFromPlaza = async (
 /**
 * 分页查询广场公开列表。
 * 只返回满足以下全部条件的记录：
- *   - PlazaPost.status = PUBLIC
- *   - 关联的 ImageGeneration.status = SUCCEEDED
- *   - 关联的 ImageGeneration 未软删除
- *   - 关联的 ImageGeneration.hostedImageUrl 不为 null（图床归档完成）
+ * - PlazaPost.status = PUBLIC
+ * - 关联的 ImageGeneration.status = SUCCEEDED
+ * - 关联的 ImageGeneration 未软删除
+ * - 关联的封面 ImageGenerationImage 已成功生成并完成图床归档
 *
 * count 与 findMany 并行执行以减少网络往返耗时。
 * 返回字段仅包含广场展示所需的公开信息，不含上游响应、图床响应或错误详情。
@@ -135,7 +200,10 @@ export const listPlazaPosts = async ({
    status: PlazaPostStatus.PUBLIC,
    imageGeneration: {
      status: ImageGenerationStatus.SUCCEEDED,
-      deletedAt: null,
+      deletedAt: null
+    },
+    coverImage: {
+      status: ImageGenerationStatus.SUCCEEDED,
      hostedImageUrl: {
        not: null
      }
@@ -150,10 +218,20 @@ export const listPlazaPosts = async ({
        imageGeneration: {
          select: {
            id: true,
-            prompt: true,
+            prompt: true
+          }
+        },
+        coverImage: {
+          select: {
+            id: true,
            hostedImageUrl: true
          }
        },
+        images: {
+          select: {
+            imageGenerationImageId: true
+          }
+        },
        user: {
          select: {
            displayName: true,
@@ -179,6 +257,87 @@ export const listPlazaPosts = async ({
  };
 };

+/**
+ * 查询广场公开详情。
+ * 只返回已归档成功且属于公开集合的图片；详情接口同样不暴露上游响应、图床响应或内部错误。
+ */
+export const getPlazaPostDetail = async (
+  postId: bigint
+): Promise<IPlazaPostDetail | null> => {
+  const post = await prisma.plazaPost.findFirst({
+    where: {
+      id: postId,
+      status: PlazaPostStatus.PUBLIC,
+      imageGeneration: {
+        status: ImageGenerationStatus.SUCCEEDED,
+        deletedAt: null
+      },
+      coverImage: {
+        status: ImageGenerationStatus.SUCCEEDED,
+        hostedImageUrl: {
+          not: null
+        }
+      }
+    },
+    include: {
+      imageGeneration: {
+        select: {
+          id: true,
+          prompt: true
+        }
+      },
+      coverImage: {
+        select: {
+          id: true,
+          hostedImageUrl: true
+        }
+      },
+      images: {
+        orderBy: {
+          sortOrder: "asc"
+        },
+        include: {
+          imageGenerationImage: {
+            select: {
+              id: true,
+              index: true,
+              hostedImageUrl: true,
+              imageMimeType: true,
+              status: true
+            }
+          }
+        }
+      },
+      user: {
+        select: {
+          displayName: true,
+          username: true
+        }
+      }
+    }
+  });
+
+  const item = post ? mapPlazaPostItem(post) : null;
+  if (!post || !item) return null;
+
+  return {
+    ...item,
+    images: post.images
+      .map((image) => image.imageGenerationImage)
+      .filter(
+        (image): image is typeof image & { hostedImageUrl: string } =>
+          image.status === ImageGenerationStatus.SUCCEEDED &&
+          Boolean(image.hostedImageUrl)
+      )
+      .map((image) => ({
+        id: image.id.toString(),
+        index: image.index,
+        hostedImageUrl: image.hostedImageUrl,
+        imageMimeType: image.imageMimeType
+      }))
+  };
+};
+
 /**
 * 将 Prisma 查询结果映射为广场展示条目。
 * hostedImageUrl 在 where 条件中已过滤，此处二次检查是为了满足类型收窄。
@@ -190,20 +349,28 @@ const mapPlazaPostItem = (post: {
  imageGeneration: {
    id: bigint;
    prompt: string;
+  };
+  coverImage: {
+    id: bigint;
    hostedImageUrl: string | null;
  };
+  images: Array<{
+    imageGenerationImageId: bigint;
+  }>;
  user: {
    displayName: string;
    username: string;
  };
 }): IPlazaPostItem | null => {
-  if (!post.imageGeneration.hostedImageUrl) return null;
+  if (!post.coverImage.hostedImageUrl) return null;

  return {
    id: post.id.toString(),
    imageGenerationId: post.imageGeneration.id.toString(),
+    coverImageId: post.coverImage.id.toString(),
    prompt: post.imageGeneration.prompt,
-    hostedImageUrl: post.imageGeneration.hostedImageUrl,
+    hostedImageUrl: post.coverImage.hostedImageUrl,
+    imageCount: post.images.length,
    authorDisplayName:
      post.user.displayName || post.user.username || ANONYMOUS_AUTHOR_NAME,
    publishedAt: post.publishedAt.toISOString()