fix(auth): clarify flarum login failures

src/modules/backendApi.ts

@@ -1,4 +1,5 @@
-import axios from "axios";
+import axios, { type AxiosResponse } from "axios";
+import pino from "pino";
 
 import { SPARK_BACKEND_BASE_URL } from "@/global/storeConfig";
 import type {
@@ -19,9 +20,42 @@ const backend = axios.create({
   baseURL: SPARK_BACKEND_BASE_URL,
   timeout: 10000,
 });
+const logger = pino({ name: "backendApi" });
 
 type ApiRecord = Record<string, unknown>;
 
+const normalizeBackendAuthError = (error: unknown): Error => {
+  if (!axios.isAxiosError(error)) {
+    return error instanceof Error ? error : new Error("登录失败，请稍后重试。");
+  }
+
+  logger.error(
+    {
+      code: error.code,
+      message: error.message,
+      status: error.response?.status,
+    },
+    "Spark backend auth exchange failed",
+  );
+
+  if (!error.response) {
+    return new Error("无法连接星火账号服务，请确认后端服务已启动或稍后重试。");
+  }
+
+  const status = error.response.status;
+  if (status === 401) {
+    return new Error("论坛登录失败，请检查账号和密码。");
+  }
+  if (status === 503) {
+    return new Error("星火账号服务暂时无法连接论坛，请稍后重试。");
+  }
+  if (status === 500) {
+    return new Error("星火账号服务异常，请确认后端数据库迁移已执行后重试。");
+  }
+
+  return new Error(`星火账号服务返回异常 (${status})，请稍后重试。`);
+};
+
 const asApiRecord = (value: unknown): ApiRecord => {
   if (value && typeof value === "object" && !Array.isArray(value)) {
     return value as ApiRecord;
@@ -145,10 +179,15 @@ export const exchangeFlarumToken = async (payload: {
   flarumUserId: string;
   flarumToken: string;
 }): Promise<AuthSession> => {
-  const response = await backend.post("/auth/flarum", {
-    flarum_user_id: payload.flarumUserId,
-    flarum_token: payload.flarumToken,
-  });
+  let response: AxiosResponse;
+  try {
+    response = await backend.post("/auth/flarum", {
+      flarum_user_id: payload.flarumUserId,
+      flarum_token: payload.flarumToken,
+    });
+  } catch (error) {
+    throw normalizeBackendAuthError(error);
+  }
   const data = asApiRecord(response.data);
 
   return {

src/modules/flarumAuth.ts

@@ -12,15 +12,49 @@ const asRecord = (value: unknown): Record<string, unknown> => {
   return {};
 };
 
+const knownLoginErrorMessages = [
+  "无法连接星火论坛，请检查网络后重试。",
+  "论坛登录失败，请检查账号和密码。",
+  "论坛登录响应异常，请稍后重试。",
+  "登录信息格式不正确，请重新输入。",
+];
+
+const normalizeIpcError = (error: unknown): Error => {
+  if (!(error instanceof Error)) {
+    return new Error("登录失败，请稍后重试");
+  }
+
+  const knownMessage = knownLoginErrorMessages.find((message) =>
+    error.message.includes(message),
+  );
+  return knownMessage ? new Error(knownMessage) : error;
+};
+
 export const requestFlarumToken = async (
   payload: FlarumLoginPayload,
 ): Promise<FlarumTokenResponse> => {
-  const data = asRecord(
-    await window.ipcRenderer.invoke("request-flarum-token", payload),
-  );
+  let data: Record<string, unknown>;
+  try {
+    data = asRecord(
+      await window.ipcRenderer.invoke("request-flarum-token", payload),
+    );
+  } catch (error) {
+    throw normalizeIpcError(error);
+  }
+
+  const token = data.token;
+  const userId = data.userId ?? data.user_id;
+  if (
+    typeof token !== "string" ||
+    !token ||
+    userId === undefined ||
+    userId === null
+  ) {
+    throw new Error("论坛登录响应异常，请稍后重试。");
+  }
 
   return {
-    token: String(data.token || ""),
-    userId: String(data.userId || data.user_id || ""),
+    token,
+    userId: String(userId),
   };
 };