feat: 补充注释

CLAUDE.md

@@ -9,6 +9,7 @@
 - 默认最小改动，优先复用现有工具函数、类型和目录结构。
 - 保持单一入口和单一职责，避免同一业务暴露多套路由或重复实现。
 - 前端不接触 NewAPI session、完整 API Key、Lsky token 等敏感信息。
+- 所有返回给前端的 `msg` 必须使用本地业务表达，不提及“上游”“NewAPI”“Lsky”“供应商”“token”“key”等内部来源；内部异常统一返回“服务器内部错误”。
 - 注释和日志要解释意图、边界和排查信息，不输出密码、cookie、完整 key、token、图片二进制或完整 prompt。
 - 已存在的说明性注释不要随意删除，尤其是 `server/utils/openai.ts` 里的模型调用、视觉输入、流式解析等上下文注释。
 
@@ -60,7 +61,7 @@
 
 - `POST /api/images/generate` 当前同步等待生图完成后返回，不向前端透传流式进度。
 - 生图成功后返回：
-  - `imageUrl`：NewAPI 上游返回的图片 URL，前端当前优先展示。
+  - `imageUrl`：生成图片访问地址，前端当前优先展示。
   - `hostedImageUrl`：Lsky 图床归档后的 URL，归档失败时为 `null`。
   - `revisedPrompt`：流式 chat completions 当前没有等价字段，通常为空。
 - Lsky 归档逻辑集中在 `server/utils/lsky.ts`：
@@ -68,9 +69,9 @@
   - 上传时先下载上游图片，再用 `multipart/form-data` 调 Lsky `/upload`。
   - 文件名格式为 `userId_username_timestamp_recordId.ext`。
   - tags 固定包含 `AIArtStudio`、`user:{userId}`、`record:{recordId}`、`model:gpt-image-2`。
-- 图床上传失败不影响本次生图成功：接口仍返回上游 `imageUrl`，数据库记录归档失败提示。
+- 图床上传失败不影响本次生图成功：接口仍返回 `imageUrl`，数据库记录归档失败提示；前端可见文案只能说“图片归档失败”等本地描述。
 - 数据库不保存图片 base64；不要恢复 `image_base64` 或类似大文本存图方案。
-- 历史列表不返回大体积数据；详情可返回完整上游响应和 Lsky 上传响应。
+- 历史列表和详情都不向前端返回完整上游响应、图床响应或内部错误详情；这些内容可以入库供服务端排查，但 API 响应应固定隐藏或置空。
 
 ## 数据库与 Prisma
 
@@ -92,6 +93,7 @@
 
 - API handler 使用 `server/utils/logging.ts` 的 `createApiLogger` 和 `toSafeLogError`。
 - 日志必须包含足够排查信息，例如 `requestId`、阶段、`userId`、`recordId`、分页、耗时、状态。
+- 上游错误、内部响应、图床响应、数据库异常等细节只允许写入服务端日志或数据库排查字段，不允许通过接口 `msg`、`data`、历史详情等返回给前端。
 - 生图日志阶段建议保持清晰：
   - `read_body`
   - `read_user_id`
@@ -108,7 +110,10 @@
 - 所有 JSON 接口先校验请求体：只接受 JSON 对象或 `null`，数组、字符串等无效 body 直接返回 400。
 - 对上游透传字段必须使用白名单数组过滤，只透传类型正确且文档声明的字段。
 - 统一使用 `createSuccessResponse`、`createErrorResponse` 返回结构。
-- 上游异常统一通过 `createUpstreamErrorResponse` 转换。
+- `createSuccessResponse` 的 `msg` 只写本地业务结果，例如“登录成功”“生图完成”“环境已准备”。
+- `createErrorResponse` 的 `msg` 只写本地业务错误，例如“未登录”“请求体必须是 JSON 对象”“生图记录不存在”。
+- 上游或内部异常统一通过 `createUpstreamErrorResponse` 转换，并固定对前端返回“服务器内部错误”；具体异常必须在调用前写入服务端日志。
+- 不把上游 `message`、`statusMessage`、响应体、错误 data、完整响应对象、图床错误信息、数据库错误信息透出给前端。
 - 401 或登录态失效时统一清理本地 auth cookie。
 - 不在 handler 内重复实现复杂错误解析，通用判断放到 `server/utils`。
 
@@ -133,6 +138,8 @@
 - TypeScript 严格类型优先，避免 `any` 扩散。
 - 新增通用逻辑优先抽到 `server/utils`，handler 只负责入参校验、调用和统一响应。
 - 修改优先小步快改，不重构无关代码。
+- `server/` 下每个文件顶部必须有 `// server/... - 用途说明` 注释。
+- 复杂 `defineEventHandler` 上方必须写清楚接口流程、鉴权边界、数据是否入库、哪些信息不会返回前端。
 - 注释使用中文，描述意图与边界，不写机械解释。
 - 不删除已有有价值注释；确需重写文件时，要保留或迁移原注释表达的信息。
 
@@ -145,8 +152,9 @@
 3. 在 handler 中完成请求体校验、白名单过滤、鉴权和日志。
 4. 将可复用业务逻辑抽到 `server/utils`。
 5. 涉及数据库时同步修改 Prisma schema、migration、`create_tables.sql`。
-6. 确认敏感信息不进入前端响应、日志或数据库不该保存的字段。
-7. 运行 `pnpm typecheck`；涉及 Prisma schema 时运行 `prisma generate`，必要时同步数据库。
+6. 确认前端响应中的 `msg`、`data`、历史详情不包含上游/internal 细节；内部错误统一显示“服务器内部错误”。
+7. 确认敏感信息不进入前端响应、日志或数据库不该保存的字段。
+8. 运行 `pnpm typecheck`；涉及 Prisma schema 时运行 `prisma generate`，必要时同步数据库。
 
 ## 非目标
 

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) => {
+      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("开始");

server/middleware/log.ts

@@ -1,3 +1,4 @@
+// server/middleware/log.ts - 全局请求日志中间件：记录 method、path、status 和耗时。
 import { consola } from "consola";
 
 /**

server/utils/createApiResponse.ts

@@ -1,5 +1,8 @@
+// server/utils/createApiResponse.ts - 统一封装后端接口成功/失败响应，并把内部异常转换为安全前端文案。
 import type { ICommonResponse } from "#shared/types";
 
+const INTERNAL_SERVER_ERROR_MESSAGE = "服务器内部错误";
+
 /**
  * 构造统一成功响应。
  *
@@ -39,37 +42,17 @@ export const createErrorResponse = (
 };
 
 /**
- * 将上游请求错误转换为统一响应。
+ * 将上游或内部异常转换为统一响应。
  *
- * @param error           ofetch 抛出的错误对象
- * @param fallbackMessage 当上游没有提供可用错误信息时的兜底提示
- * @returns               符合 ICommonResponse 格式的错误响应
+ * 调用方必须先在服务端日志中记录 error。这里永远不把上游 message、响应体、
+ * statusMessage 或 data 返回给前端，避免暴露内部服务、供应商、token 使用细节。
  */
 export const createUpstreamErrorResponse = (
   error: unknown,
-  fallbackMessage: string = "请求失败"
+  _fallbackMessage: string = INTERNAL_SERVER_ERROR_MESSAGE
 ): ICommonResponse => {
-  const fetchError = error as {
-    data?: unknown;
-    message?: string;
-    response?: {
-      _data?: unknown;
-      status?: number;
-    };
-    statusCode?: number;
-  };
-
-  const errorData = fetchError.data ?? fetchError.response?._data ?? null;
-  const errorMessage =
-    typeof errorData === "string"
-      ? errorData
-      : fetchError.message || fallbackMessage;
-
-  return createErrorResponse(
-    fetchError.statusCode ?? fetchError.response?.status ?? 500,
-    errorMessage,
-    errorData
-  );
+  void error;
+  return createErrorResponse(500, INTERNAL_SERVER_ERROR_MESSAGE);
 };
 
 /** 判断上游或本地鉴权错误是否为 401，用于统一清理失效登录态 */

server/utils/fetch.ts

@@ -1,3 +1,4 @@
+// server/utils/fetch.ts - NewAPI 请求封装：集中维护 baseURL、raw fetch 和服务端鉴权请求。
 import type { H3Event } from "h3";
 import { createError, getCookie } from "h3";
 import {

server/utils/imageGenerationRecords.ts

@@ -1,3 +1,4 @@
+// server/utils/imageGenerationRecords.ts - 生图相关数据库操作：用户快照、生成记录、历史查询和统计。
 import type { IUserBasicData } from "#shared/types";
 import type {
   IImageGenerationStatsData,
@@ -238,8 +239,8 @@ export const getImageGenerationDetail = async (
   return {
     ...mapImageGenerationItem(record),
     imageMimeType: record.imageMimeType,
-    upstreamResponse: record.upstreamResponse,
-    hostedResponse: record.hostedResponse
+    upstreamResponse: null,
+    hostedResponse: null
   };
 };
 
@@ -295,6 +296,7 @@ const upsertGenerationStats = (update: Prisma.GenerationStatsUpdateInput) => {
   });
 };
 
+/** 更新统计失败不能影响主链路，避免统计表问题导致生图接口失败 */
 const safeUpsertGenerationStats = async (
   update: Prisma.GenerationStatsUpdateInput
 ) => {
@@ -307,6 +309,7 @@ const safeUpsertGenerationStats = async (
   }
 };
 
+/** upsert 创建统计行时，把本次 increment 转换为初始计数 */
 const buildStatsCreateInput = (update: Prisma.GenerationStatsUpdateInput) => {
   return {
     totalRequests: getIncrementValue(update.totalRequests),
@@ -318,6 +321,7 @@ const buildStatsCreateInput = (update: Prisma.GenerationStatsUpdateInput) => {
   };
 };
 
+/** 从 Prisma increment 操作里取出增量；非 increment 操作在创建时按 0 处理 */
 const getIncrementValue = (value: unknown): number => {
   if (
     value &&
@@ -331,6 +335,7 @@ const getIncrementValue = (value: unknown): number => {
   return 0;
 };
 
+/** 将 Prisma 记录转换为前端类型，BigInt/Date 在这里统一序列化 */
 const mapImageGenerationItem = (record: {
   id: bigint;
   userId: number;
@@ -360,17 +365,30 @@ const mapImageGenerationItem = (record: {
     imageUrl: record.imageUrl,
     hostedImageUrl: record.hostedImageUrl,
     revisedPrompt: record.revisedPrompt,
-    errorMessage: record.errorMessage,
+    errorMessage: getPublicRecordMessage(record.status, record.errorMessage),
     createdAt: record.createdAt.toISOString()
   };
 };
 
+/** 计算耗时并兜底为非负数，避免系统时间抖动导致负值 */
 const getDurationMs = (startedAt: Date, endedAt: Date) => {
   return Math.max(0, endedAt.getTime() - startedAt.getTime());
 };
 
+/** 保存到数据库的错误信息只保留可读摘要，不保存复杂错误对象 */
 const getSafeErrorMessage = (error: unknown): string => {
   if (error instanceof Error) return error.message;
   if (typeof error === "string") return error;
   return "图片生成失败";
 };
+
+/** 返回给前端的记录错误只保留本地泛化文案，具体内部错误留在数据库和服务端日志 */
+const getPublicRecordMessage = (
+  status: ImageGenerationStatus,
+  errorMessage: string | null
+): string | null => {
+  if (!errorMessage) return null;
+  return status === ImageGenerationStatus.SUCCEEDED
+    ? "图片归档失败"
+    : "图片生成失败";
+};

server/utils/index.ts

@@ -1,3 +1,4 @@
+// server/utils/index.ts - 服务端工具统一导出口，方便 API handler 从同一入口导入。
 export * from "./createApiResponse";
 export * from "./fetch";
 export * from "./imageGenerationRecords";

server/utils/logging.ts

@@ -1,8 +1,10 @@
+// server/utils/logging.ts - API 调试日志工具：为每次请求生成 requestId 并输出安全错误摘要。
 import { randomUUID } from "node:crypto";
 import { consola } from "consola";
 
 type LogMeta = Record<string, unknown>;
 
+/** 创建带 requestId、scope 和耗时统计的接口日志器 */
 export const createApiLogger = (scope: string) => {
   const requestId = randomUUID();
   const startedAt = Date.now();
@@ -36,6 +38,7 @@ export const createApiLogger = (scope: string) => {
   };
 };
 
+/** 将未知错误转换为可写入日志的安全摘要，避免把 cookie/key 等响应体细节打进日志 */
 export const toSafeLogError = (error: unknown) => {
   const maybeError = error as {
     message?: string;

server/utils/lsky.ts

@@ -1,3 +1,4 @@
+// server/utils/lsky.ts - Lsky 图床上传工具：下载上游图片、重命名、打标签并上传归档。
 import { createError } from "h3";
 
 interface ILskyUploadInput {
@@ -29,6 +30,14 @@ export interface ILskyUploadedImage {
   response: ILskyUploadResponse;
 }
 
+/**
+ * 从远程图片 URL 下载图片并上传到 Lsky。
+ *
+ * 注意：
+ * - Lsky 地址、Token、storage_id 都来自环境变量，代码不写死密钥。
+ * - 文件名包含 userId、username、时间戳、recordId，方便图床侧追踪来源。
+ * - 返回完整 Lsky 响应供数据库保存，但调用方不要把 token 写入日志。
+ */
 export const uploadImageFromUrl = async (
   input: ILskyUploadInput
 ): Promise<ILskyUploadedImage> => {
@@ -85,6 +94,7 @@ export const uploadImageFromUrl = async (
   };
 };
 
+/** 读取并校验 Lsky 环境变量配置 */
 const getLskyConfig = () => {
   const baseUrl = process.env.LSKY_BASE_URL?.replace(/\/+$/, "");
   const token = process.env.LSKY_TOKEN;
@@ -109,6 +119,7 @@ const getLskyConfig = () => {
   };
 };
 
+/** 下载上游图片二进制，保留 content-type 供上传和入库使用 */
 const downloadImage = async (imageUrl: string) => {
   const response = await fetch(imageUrl);
   if (!response.ok) {
@@ -121,6 +132,7 @@ const downloadImage = async (imageUrl: string) => {
   };
 };
 
+/** 构造图床文件名：userId_username_timestamp_recordId.ext */
 const buildArchiveFilename = ({
   userId,
   username,
@@ -139,6 +151,7 @@ const buildArchiveFilename = ({
   return `${userId}_${safeUsername}_${timestamp}_${recordId.toString()}.${extension}`;
 };
 
+/** 给图片打固定标签，便于后续在图床里按项目、用户、记录和模型筛选 */
 const buildArchiveTags = (userId: number, recordId: bigint) => {
   return [
     "AIArtStudio",
@@ -148,6 +161,7 @@ const buildArchiveTags = (userId: number, recordId: bigint) => {
   ];
 };
 
+/** 清理文件名片段，避免中文/英文/数字/下划线/短横线以外的字符影响上传 */
 const sanitizeFilenamePart = (value: string) => {
   const sanitized = value
     .trim()
@@ -158,10 +172,12 @@ const sanitizeFilenamePart = (value: string) => {
   return sanitized || "user";
 };
 
+/** 文件名使用紧凑 UTC 时间戳，避免冒号等字符影响跨平台兼容性 */
 const formatTimestamp = (date: Date) => {
   return date.toISOString().replace(/\D/g, "").slice(0, 14);
 };
 
+/** 优先按 MIME 推断扩展名，MIME 不认识时再从 URL 路径兜底 */
 const getImageExtension = (mimeType: string, imageUrl: string) => {
   const fromMimeType = mimeType.split(";")[0]?.trim().toLowerCase();
   if (fromMimeType === "image/jpeg") return "jpg";
@@ -174,6 +190,7 @@ const getImageExtension = (mimeType: string, imageUrl: string) => {
   return extension && /^[a-z0-9]+$/.test(extension) ? extension : "png";
 };
 
+/** 兼容 Lsky 可能返回的布尔或字符串成功状态 */
 const isSuccessStatus = (status: unknown) => {
   return status === true || status === "success" || status === "ok";
 };

server/utils/newApiAuthCookies.ts

@@ -1,3 +1,4 @@
+// server/utils/newApiAuthCookies.ts - NewAPI 登录态 cookie 工具：提取上游 session 并用 httpOnly 保存。
 import type { H3Event } from "h3";
 import { createError, deleteCookie, getCookie, setCookie } from "h3";
 

server/utils/newApiTokens.ts

@@ -1,3 +1,4 @@
+// server/utils/newApiTokens.ts - NewAPI Token 工具：准备 AIArtStudio Token 并在服务端读取完整 key。
 import type { H3Event } from "h3";
 import { createError } from "h3";
 import type { IUserReadyData } from "#shared/types";

server/utils/openai.ts

@@ -1,4 +1,4 @@
-// server/utils/openai.ts
+// server/utils/openai.ts - OpenAI/NewAPI 调用工具：文本、视觉、Responses 流式和 Chat Completions 流式生图。
 import OpenAI from "openai";
 import type { BaseOptions, IImageGenerateData } from "#shared/types/openai";
 

server/utils/prisma.ts

@@ -1,3 +1,4 @@
+// server/utils/prisma.ts - Prisma 客户端初始化：使用 MariaDB adapter 并在开发热更新中复用连接池。
 import { PrismaMariaDb } from "@prisma/adapter-mariadb";
 import { PrismaClient } from "~~/app/generated/prisma/client";
 
@@ -16,6 +17,7 @@ type MariaDbPoolConfig = Exclude<
   string
 >;
 
+/** 从 DATABASE_URL 查询参数读取连接池配置，非法值回退到默认值 */
 function getNumberParam(url: URL, name: string, fallback: number) {
   const value = url.searchParams.get(name);
   if (!value) {
@@ -26,6 +28,7 @@ function getNumberParam(url: URL, name: string, fallback: number) {
   return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
 }
 
+/** 将 DATABASE_URL 拆成 Prisma MariaDB adapter 需要的连接池配置 */
 function createMariaDbConfig(urlString: string): MariaDbPoolConfig {
   const url = new URL(urlString);
   const database = decodeURIComponent(url.pathname.replace(/^\//, ""));

shared/types/openai.ts

@@ -64,7 +64,7 @@ export interface IImageHistoryItem {
   hostedImageUrl: string | null;
   /** 上游返回的修订提示词，可能为空 */
   revisedPrompt: string | null;
-  /** 失败原因或图床归档提示 */
+  /** 面向前端的本地泛化错误提示，不包含上游或内部服务细节 */
   errorMessage: string | null;
   /** 记录创建时间，ISO 字符串 */
   createdAt: string;
@@ -76,9 +76,9 @@ export interface IImageHistoryItem {
 export interface IImageHistoryDetail extends IImageHistoryItem {
   /** 图片 MIME 类型，可能为空 */
   imageMimeType: string | null;
-  /** 完整上游生图接口返回结果 */
+  /** 内部响应不向前端透出，当前固定为 null */
   upstreamResponse: unknown;
-  /** 完整 Lsky 图床上传接口返回结果 */
+  /** 内部图床响应不向前端透出，当前固定为 null */
   hostedResponse: unknown;
 }