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)