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 {