feat: 补充注释

server/api/auth/login.post.ts

@@ -1,4 +1,4 @@
-// server/api/auth/login.post.ts
+// server/api/auth/login.post.ts - 登录接口：代理 NewAPI 登录、保存 httpOnly 登录态并返回基础用户信息。
 import type { IUserLoginData, IUserLoginRequest } from "#shared/types";
 import {
   clearNewApiAuthCookies,
@@ -40,6 +40,13 @@ const LOGIN_FIELDS = ["username", "password"] as const satisfies ReadonlyArray<
 
 /**
  * POST /api/auth/login
+ *
+ * 流程：
+ * 1. 只接收 JSON 对象，并按 LOGIN_FIELDS 白名单组装上游登录参数。
+ * 2. 使用 raw fetch 调用 NewAPI 登录接口，保留 Set-Cookie 响应头。
+ * 3. 兼容上游直接返回用户对象或包装响应，提取基础用户信息。
+ * 4. 将 NewAPI session 和 userId 写入本站 httpOnly cookie，前端不接触 session 明文。
+ * 5. 异步 upsert 用户快照到数据库，失败只记日志，不影响登录成功。
  */
 export default defineEventHandler(async (event) => {
   const logger = createApiLogger("auth.login");
@@ -98,7 +105,7 @@ export default defineEventHandler(async (event) => {
       logger.warn("登录业务失败", {
         upstreamMessage: normalized.message
       });
-      return createErrorResponse(1, normalized.message, result._data ?? null);
+      return createErrorResponse(1, "登录失败");
     }
 
     if (!session) {
@@ -132,7 +139,7 @@ export default defineEventHandler(async (event) => {
 
     return createSuccessResponse<IUserLoginData>(
       normalized.user,
-      normalized.message
+      "登录成功"
     );
   } catch (error) {
     clearNewApiAuthCookies(event);
@@ -162,7 +169,7 @@ const normalizeLoginResponse = (
   }
 
   const wrapped = response as INewApiWrappedLoginResponse;
-  const message = wrapped.message || (wrapped.success ? "登录成功" : "登录失败");
+  const message = wrapped.success ? "登录成功" : "登录失败";
 
   if (wrapped.success !== true || !isUser(wrapped.data)) {
     return {

server/api/auth/logout.get.ts

@@ -1,3 +1,4 @@
+// server/api/auth/logout.get.ts - 登出接口：尽量通知 NewAPI 销毁 session，并清理本地登录态。
 import type { IUserLogoutData } from "#shared/types";
 import {
   clearNewApiAuthCookies,
@@ -7,6 +8,14 @@ import {
   toSafeLogError
 } from "~~/server/utils";
 
+/**
+ * GET /api/auth/logout
+ *
+ * 流程：
+ * 1. 使用本站 httpOnly cookie 中的 NewAPI session 调用上游登出。
+ * 2. 无论上游登出是否成功，都清理本站保存的 session/userId cookie。
+ * 3. 返回统一成功响应，避免坏 session 残留影响后续登录。
+ */
 export default defineEventHandler(async (event) => {
   const logger = createApiLogger("auth.logout");
   logger.info("开始");

server/api/auth/me.get.ts

@@ -1,3 +1,4 @@
+// server/api/auth/me.get.ts - 当前用户接口：用 httpOnly 登录态恢复用户信息并刷新用户快照。
 import type { IUserMeData } from "#shared/types";
 import {
   clearNewApiAuthCookies,
@@ -25,6 +26,16 @@ interface INewApiSelfUserData extends IUserMeData {
   [key: string]: unknown;
 }
 
+/**
+ * GET /api/auth/me
+ *
+ * 流程：
+ * 1. 从本站 httpOnly cookie 读取 NewAPI session/userId。
+ * 2. 带 Cookie 与 New-Api-User 请求 NewAPI /api/user/self。
+ * 3. 裁剪上游 self 响应，只返回前端需要的基础用户字段。
+ * 4. 异步更新数据库里的用户快照。
+ * 5. cookie 缺失、过期或上游鉴权失败时清理本地登录态并返回 401。
+ */
 export default defineEventHandler(async (event) => {
   const logger = createApiLogger("auth.me");
   logger.info("开始");
@@ -46,7 +57,7 @@ export default defineEventHandler(async (event) => {
       logger.warn("登录状态无效", {
         upstreamMessage: normalized.message
       });
-      return createErrorResponse(401, normalized.message);
+      return createErrorResponse(401, "未登录");
     }
 
     upsertUserSnapshot(normalized.user).catch((error) => {
@@ -64,7 +75,7 @@ export default defineEventHandler(async (event) => {
 
     return createSuccessResponse<IUserMeData>(
       normalized.user,
-      normalized.message
+      "获取用户信息成功"
     );
   } catch (error) {
     // cookie 缺失或上游鉴权异常时统一视为未登录。
@@ -95,8 +106,7 @@ const normalizeUserResponse = (
   }
 
   const wrapped = response as INewApiWrappedUserResponse;
-  const message =
-    wrapped.message || (wrapped.success ? "获取用户信息成功" : "未登录");
+  const message = wrapped.success ? "获取用户信息成功" : "未登录";
 
   if (wrapped.success !== true || !isUser(wrapped.data)) {
     return {

server/api/auth/ready.get.ts

@@ -1,3 +1,4 @@
+// server/api/auth/ready.get.ts - 登录后环境准备接口：确保当前用户已有可用的 AIArtStudio Token。
 import type { IUserReadyData } from "#shared/types";
 import {
   clearNewApiAuthCookies,
@@ -10,6 +11,16 @@ import {
   toSafeLogError
 } from "~~/server/utils";
 
+/**
+ * GET /api/auth/ready
+ *
+ * 流程：
+ * 1. 读取当前登录用户的 NewAPI session。
+ * 2. 检查是否存在启用且未删除的 AIArtStudio Token。
+ * 3. 不存在时按固定参数创建 Token。
+ * 4. 只返回环境是否准备完成，不返回完整 key 或脱敏 key。
+ * 5. 登录态失效时清理本地 cookie 并返回 401。
+ */
 export default defineEventHandler(async (event) => {
   const logger = createApiLogger("auth.ready");
   logger.info("开始");

server/api/auth/register.post.ts

@@ -1,4 +1,4 @@
-// server/api/auth/register.post.ts
+// server/api/auth/register.post.ts - 注册接口：校验并代理 NewAPI 注册请求。
 import type { IUserRegisterData, IUserRegisterRequest } from "#shared/types";
 import {
   createApiLogger,
@@ -23,6 +23,11 @@ const REGISTER_FIELDS = [
 
 /**
  * POST /api/auth/register
+ *
+ * 流程：
+ * 1. 只接收 JSON 对象，并按 REGISTER_FIELDS 白名单透传注册字段。
+ * 2. 调用 NewAPI 注册接口。
+ * 3. 成功时返回统一成功响应；上游失败时转成统一错误响应。
  */
 export default defineEventHandler(async (event) => {
   const logger = createApiLogger("auth.register");
@@ -59,7 +64,7 @@ export default defineEventHandler(async (event) => {
   }
 
   try {
-    const result = await newApiFetch<IUserRegisterData>("/api/user/register", {
+    await newApiFetch<IUserRegisterData>("/api/user/register", {
       method: "POST",
       body: payload,
       headers: {
@@ -68,10 +73,10 @@ export default defineEventHandler(async (event) => {
     });
 
     logger.done("成功", {
-      hasResult: Boolean(result)
+      registered: true
     });
 
-    return createSuccessResponse(result, "注册成功");
+    return createSuccessResponse<IUserRegisterData>(null, "注册成功");
   } catch (error) {
     logger.error("失败", {
       error: toSafeLogError(error)

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

server/api/images/history.get.ts

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

server/api/images/history/[id].delete.ts

@@ -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({

server/api/images/history/[id].get.ts

@@ -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({

server/api/images/stats.get.ts

@@ -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("开始");