feat: 补充注释

server/api/images/generate.post.ts

@@ -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 &&