feat: 补充注释

2026-04-26 01:13:38 +08:00
parent e26e2f5491
commit 4c58f409e9
23 changed files with 206 additions and 95 deletions
@@ -1,27 +1,24 @@
+// server/api/images/generate.post.ts - 图片生成接口：创建记录、流式调用上游生图、归档图床并返回图片地址。
 import type {
  IImageGenerateData,
  IImageGenerateRequest
 } from "#shared/types/openai";
-import {
-  askImgStream,
-  clearNewApiAuthCookies,
-  createApiLogger,
-  createErrorResponse,
-  createRunningImageGeneration,
-  createSuccessResponse,
-  createUpstreamErrorResponse,
-  finishImageGenerationFailed,
-  finishImageGenerationSuccess,
-  getAiArtStudioTokenKey,
-  getNewApiUserIdFromCookie,
-  getUserArchiveIdentity,
-  isUnauthorizedError,
-  toSafeLogError,
-  uploadImageFromUrl
-} from "~~/server/utils";

 type ApiLogger = ReturnType<typeof createApiLogger>;

+/**
+ * POST /api/images/generate
+ *
+ * 流程：
+ * 1. 校验请求体和 prompt，空 prompt 不创建数据库记录。
+ * 2. 从 httpOnly cookie 读取当前 NewAPI 用户 ID。
+ * 3. 创建 RUNNING 生图记录，并递增全局请求/进行中统计。
+ * 4. 在服务端确保并读取 AIArtStudio 完整 key，完整 key 不返回前端。
+ * 5. 调用 Chat Completions 流式生图接口，累积 SSE delta content 并提取最终图片 URL。
+ * 6. 尝试把上游图片下载后上传到 Lsky 图床；图床失败不阻断本次生图成功。
+ * 7. 成功时写入上游 URL、图床 URL、完整上游响应、图床响应和耗时。
+ * 8. 失败时把记录标记为 FAILED；鉴权失败会清理本地登录态并返回 401。
+ */
 export default defineEventHandler(async (event) => {
  const logger = createApiLogger("images.generate");
  let stage = "read_body";
@@ -46,6 +43,7 @@ export default defineEventHandler(async (event) => {
    return createErrorResponse(400, "请输入图片描述");
  }

+  // 不记录完整 prompt，日志只保留长度，避免把用户输入或潜在敏感内容写进日志。
  logger.info("开始", {
    promptLength: prompt.length
  });
@@ -54,24 +52,28 @@ export default defineEventHandler(async (event) => {

  try {
    stage = "read_user_id";
+    // userId 来自服务端 httpOnly cookie，前端不能伪造请求体覆盖用户归属。
    const userId = getNewApiUserIdFromCookie(event);
    logger.info("读取用户成功", {
      userId
    });

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

    stage = "get_api_key";
+    // 完整 key 只在服务端内存中短暂使用，不写入响应、不写入日志。
    const apiKey = await getAiArtStudioTokenKey(event);
    logger.info("获取服务端 key 成功", {
      recordId: record.id.toString()
    });

    stage = "call_image_stream_api";
+    // 上游通过 SSE 分段返回进度和最终 Markdown 图片链接，这里同步等待流结束。
    const result = await askImgStream({
      apiKey,
      prompt
@@ -84,6 +86,7 @@ export default defineEventHandler(async (event) => {
    });

    stage = "upload_lsky";
+    // 归档图床用于长期保存；失败时仍继续返回 NewAPI 上游图片 URL。
    const archiveResult = await archiveGeneratedImage({
      imageUrl: result.imageUrl,
      userId,
@@ -129,14 +132,16 @@ export default defineEventHandler(async (event) => {
    });

    if (record) {
-      await finishImageGenerationFailed(record.id, record.startedAt, error).catch(
-        (recordError) => {
-          logger.error("更新失败记录失败", {
-            recordId: record?.id.toString() ?? null,
-            error: toSafeLogError(recordError)
-          });
-        }
-      );
+      await finishImageGenerationFailed(
+        record.id,
+        record.startedAt,
+        error
+      ).catch((recordError) => {
+        logger.error("更新失败记录失败", {
+          recordId: record?.id.toString() ?? null,
+          error: toSafeLogError(recordError)
+        });
+      });
    }

    if (isUnauthorizedError(error)) {
@@ -144,10 +149,12 @@ export default defineEventHandler(async (event) => {
      return createErrorResponse(401, "未登录");
    }

+    // 统一把上游错误包成前端约定的响应结构，避免泄露 key/cookie。
    return createUpstreamErrorResponse(error, "图片生成失败");
  }
 });

+/** 将生成图上传到 Lsky，返回图床地址；归档失败时降级为空结果 */
 const archiveGeneratedImage = async ({
  imageUrl,
  userId,
@@ -193,7 +200,7 @@ const archiveGeneratedImage = async ({
      hostedImageUrl: null,
      imageMimeType: null,
      hostedResponse: null,
-      errorMessage: "图片生成成功，但图床归档失败"
+      errorMessage: "图片生成成功，但图片归档失败"
    };
  }
 };
@@ -212,6 +219,7 @@ const getStreamContentLength = (upstreamResponse: unknown) => {
  return 0;
 };

+/** 判断流式上游响应里是否包含 usage，用于日志确认上游是否正常结束 */
 const hasStreamUsage = (upstreamResponse: unknown) => {
  return (
    upstreamResponse !== null &&
@@ -1,20 +1,19 @@
+// server/api/images/history.get.ts - 生图历史列表接口：分页返回当前用户未软删除的记录。
 import type { IImageHistoryListData } from "#shared/types/openai";
-import {
-  clearNewApiAuthCookies,
-  createApiLogger,
-  createErrorResponse,
-  createSuccessResponse,
-  createUpstreamErrorResponse,
-  getNewApiUserIdFromCookie,
-  isUnauthorizedError,
-  listImageGenerationHistory,
-  toSafeLogError
-} from "~~/server/utils";

 const DEFAULT_PAGE = 1;
 const DEFAULT_PAGE_SIZE = 10;
 const MAX_PAGE_SIZE = 50;

+/**
+ * GET /api/images/history
+ *
+ * 流程：
+ * 1. 从 httpOnly cookie 读取当前用户 ID。
+ * 2. 读取 page/size 查询参数，并限制最大 pageSize，避免一次查太多。
+ * 3. 只查询当前用户且未软删除的记录，按创建时间倒序返回。
+ * 4. 列表不返回完整上游响应或图床响应，详情接口再返回这些调试数据。
+ */
 export default defineEventHandler(async (event) => {
  const logger = createApiLogger("images.history.list");
  logger.info("开始");
@@ -68,6 +67,7 @@ export default defineEventHandler(async (event) => {
  }
 });

+/** 将 query 参数归一化为正整数，非法值回退到默认值 */
 const normalizePositiveInt = (
  value: unknown,
  fallbackValue: number
@@ -1,3 +1,4 @@
+// server/api/images/history/[id].delete.ts - 生图历史删除接口：软删除当前用户的单条记录。
 import {
  clearNewApiAuthCookies,
  createApiLogger,
@@ -10,6 +11,15 @@ import {
  toSafeLogError
 } from "~~/server/utils";

+/**
+ * DELETE /api/images/history/:id
+ *
+ * 流程：
+ * 1. 从 httpOnly cookie 读取当前用户 ID。
+ * 2. 校验路由参数 id 必须是数字。
+ * 3. 只软删除当前用户且未删除的记录，避免越权删除其他用户历史。
+ * 4. 找不到记录时返回 404，数据库中保留原始记录和 deletedAt。
+ */
 export default defineEventHandler(async (event) => {
  const logger = createApiLogger("images.history.delete");
  logger.info("开始");
@@ -55,6 +65,7 @@ export default defineEventHandler(async (event) => {
  }
 });

+/** 校验并解析路由里的生图记录 ID */
 const parseRecordId = (value: string | undefined): bigint => {
  if (!value || !/^\d+$/.test(value)) {
    throw createError({
@@ -1,3 +1,4 @@
+// server/api/images/history/[id].get.ts - 生图历史详情接口：返回当前用户单条记录和完整响应。
 import type { IImageHistoryDetail } from "#shared/types/openai";
 import {
  clearNewApiAuthCookies,
@@ -11,6 +12,15 @@ import {
  toSafeLogError
 } from "~~/server/utils";

+/**
+ * GET /api/images/history/:id
+ *
+ * 流程：
+ * 1. 从 httpOnly cookie 读取当前用户 ID。
+ * 2. 校验路由参数 id 必须是数字，并转成 BigInt 查询。
+ * 3. 只允许读取当前用户、未软删除的记录。
+ * 4. 返回详情时包含完整上游响应和 Lsky 响应，便于排查单次生图问题。
+ */
 export default defineEventHandler(async (event) => {
  const logger = createApiLogger("images.history.detail");
  logger.info("开始");
@@ -61,6 +71,7 @@ export default defineEventHandler(async (event) => {
  }
 });

+/** 校验并解析路由里的生图记录 ID */
 const parseRecordId = (value: string | undefined): bigint => {
  if (!value || !/^\d+$/.test(value)) {
    throw createError({
@@ -1,12 +1,14 @@
+// server/api/images/stats.get.ts - 生图统计接口：返回全局生图请求与成功失败统计。
 import type { IImageGenerationStatsData } from "#shared/types/openai";
-import {
-  createApiLogger,
-  createSuccessResponse,
-  createUpstreamErrorResponse,
-  getGenerationStats,
-  toSafeLogError
-} from "~~/server/utils";

+/**
+ * GET /api/images/stats
+ *
+ * 流程：
+ * 1. 读取 GenerationStats 的 global 单行统计。
+ * 2. 没有统计行时返回全 0，避免前端需要处理空状态。
+ * 3. 该接口返回全局统计，不包含用户输入、图片地址或上游响应。
+ */
 export default defineEventHandler(async () => {
  const logger = createApiLogger("images.stats");
  logger.info("开始");