@jiangood/open-admin 3.1.8 → 3.1.10

package/package.json

@@ -55,7 +55,7 @@
     "lint": "eslint src --max-warnings=0",
     "lint:fix": "eslint src --fix"
   },
-  "version": "3.1.8",
+  "version": "3.1.10",
   "overrides": {
     "zod-validation-error": "^4.0.2"
   }

package/src/framework/GlobalData.ts

@@ -7,7 +7,11 @@ const SITE_ARTICLES_KEY = "siteArticles";
 
 export interface SiteInfo {
     title?: string;
+    /** 系统简称，用于侧栏等空间受限处；未配置时前端回退到 title */
+    shortTitle?: string;
     waterMark?: boolean;
+    /** 登录失效（空闲超时/未登录）时全局弹窗的提示文案，对应 sys.login-expired-message */
+    loginExpiredMessage?: string;
     [key: string]: unknown;
 }
 

package/src/framework/biz/OrgTree.tsx

@@ -24,6 +24,10 @@ export class OrgTree extends React.Component<OrgTreeProps, OrgTreeState> {
     componentDidMount() {
         HttpClient.get('admin/sysOrg/tree', null).then(tree => {
             this.setState({treeData: tree.data, treeDataLoading: false})
+        }).catch(() => {
+            // 失败时结束 loading 并置空（组件会显示空状态提示），避免一直停留在骨架屏；
+            // 401 由 HttpClient 广播 loginExpired（全局弹窗提示），其余错误仍按 toastError 弹错
+            this.setState({treeData: [], treeDataLoading: false})
         })
     }
 

package/src/framework/biz/RoleTree.tsx

@@ -24,6 +24,10 @@ export class RoleTree extends React.Component<RoleTreeProps, RoleTreeState> {
     componentDidMount() {
         HttpClient.get('admin/sysRole/biz-tree', null).then(tree => {
             this.setState({treeData: tree.data, treeDataLoading: false})
+        }).catch(() => {
+            // 失败时结束 loading 并置空（组件会显示空状态提示），避免一直停留在骨架屏；
+            // 401 由 HttpClient 广播 loginExpired（全局弹窗提示），其余错误仍按 toastError 弹错
+            this.setState({treeData: [], treeDataLoading: false})
         })
     }
 

package/src/framework/components/DownloadModal/index.tsx

@@ -8,6 +8,7 @@ import {
 import axios from "axios";
 import qs from 'qs';
 import type {AxiosProgressEvent, AxiosRequestConfig, AxiosResponse} from "axios";
+import {EventBus} from "../../utils/EventBus";
 
 const axiosInstance = axios.create({
   baseURL: import.meta.env.VITE_SERVER_SERVLET_CONTEXT_PATH,
@@ -264,6 +265,12 @@ export class DownloadModal extends React.Component<DownloadModalProps, ModalStat
       if (error.message) {
         msg = error.message;
       }
+      // 登录失效：交由全局登录失效弹窗提示，避免在此显示「Request failed with status code 401」
+      if (axios.isAxiosError(error) && error.response?.status === 401) {
+        EventBus.emit('loginExpired');
+        this.setState({open: false, status: ''});
+        return;
+      }
       console.error('[DownloadModal] 下载失败:', msg);
       this.setState({
         status: 'failed',

package/src/framework/components/LogViewer/index.tsx

@@ -0,0 +1,249 @@
+import React from "react";
+import { Alert, Spin, Typography } from "antd";
+import { HttpClient } from "../../utils";
+import { getToken } from "../../config";
+
+/** 增量拉取时每次最多读取的字节数（与后端默认值一致） */
+const DEFAULT_LENGTH = 256 * 1024;
+
+/** 运行中日志的默认刷新间隔（毫秒） */
+const DEFAULT_POLL_INTERVAL = 1500;
+
+export interface LogViewerProps {
+    /** 日志 key，如 `job/{logId}`；与后端 `admin/sys/log/{*key}` 对应 */
+    logKey?: string;
+    /**
+     * 自定义读取地址，覆盖默认的 `admin/sys/log/{logKey}`。
+     * <p>
+     * 用于「带行级/数据权限、由业务模块自己提供读取接口」的场景：
+     * 只要接口返回同样的 `{content, nextOffset, eof}` 结构，就能复用本组件的增量跟随。
+     */
+    url?: string;
+    /** 任务是否仍在运行：为 true 时按 `pollInterval` 增量轮询，false 时只读一次 */
+    running?: boolean;
+    /** 运行中的轮询间隔（毫秒），默认 1500 */
+    pollInterval?: number;
+    /** 可视高度（像素），默认 500 */
+    height?: number;
+    /** 是否自动滚动到底部，默认 true；用户上滑查看历史后不再强制跟随 */
+    autoFollow?: boolean;
+    /** 内容为空时的提示 */
+    emptyText?: React.ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+}
+
+interface LogViewerState {
+    content: string;
+    nextOffset: number;
+    loading: boolean;
+    error: string | null;
+    eof: boolean;
+}
+
+/**
+ * 文件日志查看器：按字节偏移增量读取日志文件。
+ * <p>
+ * 运行中的任务（`running`）按 `pollInterval` 反复拉取新增内容并追加；任务结束后停止轮询，
+ * 且会补拉一次剩余内容。日志很长时也不会每次整文件重读。
+ * <p>
+ * 使用方式（定时任务日志）：
+ * ```tsx
+ * <LogViewer logKey={`job/${logId}`} running={isRunning} />
+ * ```
+ */
+export class LogViewer extends React.Component<LogViewerProps, LogViewerState> {
+
+    state: LogViewerState = {
+        content: "",
+        nextOffset: 0,
+        loading: false,
+        error: null,
+        eof: false,
+    };
+
+    private containerRef = React.createRef<HTMLPreElement>();
+    private timer: ReturnType<typeof setTimeout> | null = null;
+    private mounted = false;
+    /** 用户是否仍处于底部（跟随最新日志）；上滑后置为 false */
+    private follow = true;
+    /** 请求进行中标记，避免慢请求叠加 */
+    private fetching = false;
+    /** 请求进行中被跳过的拉取请求，结束后立即补一次 */
+    private pendingFetch = false;
+    /** 请求代号：切换 logKey / 重新加载后，丢弃旧请求的迟到响应 */
+    private generation = 0;
+
+    componentDidMount() {
+        this.mounted = true;
+        this.reload();
+    }
+
+    componentDidUpdate(prevProps: LogViewerProps) {
+        if (prevProps.logKey !== this.props.logKey || prevProps.url !== this.props.url) {
+            this.reload();
+            return;
+        }
+        // 运行状态变化（尤其运行中 -> 结束）时补拉一次，拿到最后一段日志
+        if (prevProps.running !== this.props.running) {
+            this.schedule(0);
+        }
+    }
+
+    componentWillUnmount() {
+        this.mounted = false;
+        this.clearTimer();
+    }
+
+    /** 从头重新加载 */
+    reload = () => {
+        this.clearTimer();
+        this.generation++;
+        this.pendingFetch = false;
+        this.follow = true;
+        this.setState({ content: "", nextOffset: 0, loading: true, error: null, eof: false },
+            () => this.fetchChunk(true));
+    };
+
+    private clearTimer() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+    }
+
+    private schedule(delay?: number) {
+        if (!this.mounted) {
+            return;
+        }
+        this.clearTimer();
+        const running = !!this.props.running;
+        // 未运行时只在需要时补拉（delay 显式传入），不做周期性轮询
+        if (!running && delay == null) {
+            return;
+        }
+        const interval = this.props.pollInterval ?? DEFAULT_POLL_INTERVAL;
+        this.timer = setTimeout(() => this.fetchChunk(false), delay ?? interval);
+    }
+
+    private fetchChunk(initial: boolean) {
+        const { logKey, url } = this.props;
+        // 业务模块自建接口（带行级权限）可通过 url 覆盖默认的通用日志接口
+        const requestUrl = url || (logKey ? `admin/sys/log/${logKey}` : null);
+        if (!requestUrl) {
+            return;
+        }
+        if (this.fetching) {
+            // 已有请求在途：打完标记，等它结束后立即补一次
+            this.pendingFetch = true;
+            return;
+        }
+        this.fetching = true;
+        const generation = this.generation;
+        const offset = initial ? 0 : this.state.nextOffset;
+
+        HttpClient.get<{ content: string; nextOffset: number; eof: boolean }>(
+            requestUrl,
+            { offset, length: DEFAULT_LENGTH },
+            { toastError: false }
+        ).then(rs => {
+            if (!this.mounted || generation !== this.generation) {
+                return;
+            }
+            const chunk = rs.data;
+            if (!chunk) {
+                this.setState({ loading: false, eof: true });
+                return;
+            }
+            this.setState(prev => ({
+                content: initial ? (chunk.content || "") : prev.content + (chunk.content || ""),
+                nextOffset: chunk.nextOffset,
+                eof: chunk.eof,
+                loading: false,
+                error: null,
+            }), () => {
+                this.scrollToBottom();
+                if (!chunk.eof) {
+                    // 还有剩余内容（超过单次读取上限）：立即续读
+                    this.schedule(0);
+                } else {
+                    // 已读到末尾：运行中按间隔等新内容，已结束则停止
+                    this.schedule();
+                }
+            });
+        }).catch(e => {
+            if (!this.mounted || generation !== this.generation) {
+                return;
+            }
+            this.setState({ loading: false, error: e?.message || "日志加载失败" });
+            // 运行中遇到临时错误（如文件尚未创建）继续重试
+            this.schedule();
+        }).finally(() => {
+            this.fetching = false;
+            if (this.pendingFetch) {
+                this.pendingFetch = false;
+                this.fetchChunk(false);
+            }
+        });
+    }
+
+    private scrollToBottom() {
+        const el = this.containerRef.current;
+        if (!el || !(this.props.autoFollow ?? true)) {
+            return;
+        }
+        if (!this.follow) {
+            return;
+        }
+        el.scrollTop = el.scrollHeight;
+    }
+
+    private handleScroll = () => {
+        const el = this.containerRef.current;
+        if (!el) {
+            return;
+        }
+        // 距底部 24px 内视为跟随
+        this.follow = el.scrollHeight - el.scrollTop - el.clientHeight < 24;
+    };
+
+    render() {
+        const { height = 500, emptyText = "暂无日志", className, style } = this.props;
+        const { content, loading, error } = this.state;
+        const token = getToken();
+
+        return <div className={className} style={{ height, position: "relative", ...style }}>
+            {error && content.length === 0
+                ? <Alert type="error" showIcon message={error}/>
+                : <>
+                    {loading && content.length === 0 && (
+                        <div style={{ position: "absolute", inset: 0, display: "flex", alignItems: "center", justifyContent: "center" }}>
+                            <Spin/>
+                        </div>
+                    )}
+                    {!loading && content.length === 0 && (
+                        <Typography.Text type="secondary">{emptyText}</Typography.Text>
+                    )}
+                    <pre
+                        ref={this.containerRef}
+                        onScroll={this.handleScroll}
+                        style={{
+                            margin: 0,
+                            height: "100%",
+                            overflow: "auto",
+                            whiteSpace: "pre-wrap",
+                            wordBreak: "break-all",
+                            fontSize: 12,
+                            lineHeight: 1.6,
+                            padding: 12,
+                            boxSizing: "border-box",
+                            backgroundColor: token.colorBgContainer,
+                            color: token.colorText,
+                            border: `1px solid ${token.colorBorderSecondary}`,
+                            borderRadius: token.borderRadius,
+                        }}
+                    >{content}</pre>
+                </>}
+        </div>;
+    }
+}

package/src/framework/components/Page/index.less

@@ -2,6 +2,8 @@
   width: 100%;
   height: 100%;
   overflow: auto;
+  /* 页面底色统一走变量：暗色由 darkColorBgLayout / antd 算法决定，业务可覆盖 */
+  background: var(--oa-color-bg-layout, #f5f5f5);
 
   .oa-page-header {
     margin-bottom: 16px;

package/src/framework/components/Page/index.tsx

@@ -1,7 +1,6 @@
 import React from "react";
 import { Space, Typography } from "antd";
 import './index.less'
-import {getToken} from "../../config";
 import { PermActions, type PermAction } from "../../biz/PermActions";
 import { PermUtils } from "../../utils";
 
@@ -17,6 +16,7 @@ function renderActionNodes(nodes: React.ReactNode) {
 
 interface PageProps {
     padding?: boolean;
+    /** @deprecated 页面底色已默认跟随布局底色，该参数不再产生差异；保留仅为兼容旧写法 */
     backgroundGray?: boolean;
     debug?: boolean;
     title?: React.ReactNode;
@@ -28,23 +28,17 @@ interface PageProps {
 
 export class Page extends React.Component<PageProps> {
     render() {
-        const { padding = true, backgroundGray = false, debug = false, title, description, actions, children } = this.props;
+        const { padding = true, debug = false, title, description, actions, children } = this.props;
         const hasHeader = title != null || description != null || actions != null;
         const style: React.CSSProperties = {};
 
         if (padding) {
             style.padding = 16;
         }
-        const token = getToken();
-        if (backgroundGray) {
-            style.backgroundColor = token.colorBgLayout;
-        }
+        // 页面底色由 .oa-page 统一使用 --oa-color-bg-layout，避免内联值脱离变量体系
         if (debug) {
             style.backgroundColor = 'rgba(255, 0, 0, 0.08)';
         }
-        if (!style.backgroundColor) {
-            style.backgroundColor = token.colorBgLayout;
-        }
 
         return <div className={'oa-page'} style={style}>
             {hasHeader && (

package/src/framework/components/index.ts

@@ -9,6 +9,7 @@ export * from './ContextMenu'
 export * from './DownloadModal'
 export * from './OrgSwitcher'
 export * from './ThemeSettings'
+export * from './LogViewer'
 export { default as ErrorBoundary } from './ErrorBoundary'
 export { default as FormModal } from './FormModal'
 export { default as FormDrawer } from './DrawerForm'

package/src/framework/config/themeConfig.ts

@@ -12,7 +12,13 @@ export interface ThemeColors {
     colorWarning?: string;
     colorError?: string;
     colorInfo?: string;
+    /** 页面底色（antd token），仅浅色模式生效；暗色模式请用 darkColorBgLayout */
     colorBgLayout?: string;
+    /**
+     * 暗色模式页面底色（框架自定义字段，非 antd token）。
+     * 不设置时由 antd 暗色算法推导（#000000）。
+     */
+    darkColorBgLayout?: string;
     /** 侧栏底色（深色系）；不设置时使用 antd 默认值 */
     siderBg?: string;
     /** 侧栏子菜单底色；缺省与 siderBg 相同 */
@@ -266,8 +272,22 @@ function getMergedColors(): ThemeColors {
     };
 }
 
-function hasExplicitBgLayout(): boolean {
-    return businessColors?.colorBgLayout != null || getActivePreset()?.colors.colorBgLayout != null;
+/** 页面底色：浅色用 colorBgLayout；暗色只认 darkColorBgLayout，未传则交给 antd 暗色算法推导 */
+function resolveBgLayout(mode: ThemeMode): string | undefined {
+    if (mode === 'dark') {
+        return businessColors?.darkColorBgLayout ?? getActivePreset()?.colors.darkColorBgLayout;
+    }
+    return getMergedColors().colorBgLayout;
+}
+
+let warnedBgLayoutIgnored = false;
+
+/** 暗色模式下浅色 colorBgLayout 被忽略时提示一次，避免业务配置静默失效 */
+function warnIfBgLayoutIgnored() {
+    if (warnedBgLayoutIgnored || currentMode !== 'dark') return;
+    if (businessColors?.colorBgLayout == null || businessColors.darkColorBgLayout != null) return;
+    warnedBgLayoutIgnored = true;
+    console.warn('[open-admin] 暗色模式下 colors.colorBgLayout 不生效，请改用 colors.darkColorBgLayout 指定暗色页面底色。');
 }
 
 function invalidate() {
@@ -295,10 +315,11 @@ function buildConfig(): ThemeConfig {
         colorError: merged.colorError,
         colorInfo: merged.colorInfo,
     };
-    // colorBgLayout 仅浅色模式默认覆盖；暗色模式交给算法推导，避免被强制成浅灰。
-    // 业务/预设显式传入 colorBgLayout 时两种模式都尊重。
-    if (currentMode === 'light' || hasExplicitBgLayout()) {
-        token.colorBgLayout = merged.colorBgLayout;
+    // 页面底色：浅色用 colorBgLayout；暗色只认 darkColorBgLayout，未传则交给算法推导，
+    // 避免业务按浅色习惯传入的浅灰把暗色页面染成浅底。
+    const bgLayout = resolveBgLayout(currentMode);
+    if (bgLayout != null) {
+        token.colorBgLayout = bgLayout;
     }
 
     const resolved = getDesignToken({ token, algorithm } as ThemeConfig);
@@ -377,6 +398,7 @@ function syncCssVars(token: Record<string, unknown>) {
     setVar(el, '--oa-color-text-secondary', token.colorTextSecondary);
     setVar(el, '--oa-color-text-tertiary', token.colorTextTertiary);
     setVar(el, '--oa-color-fill', token.colorFillTertiary);
+    setVar(el, '--oa-color-fill-quaternary', token.colorFillQuaternary);
     setVar(el, '--oa-color-primary-bg', token.colorPrimaryBg);
     setVar(el, '--oa-color-error', token.colorError);
     // 尺寸/圆角变量，供 less 复用，使自定义样式跟随密度与圆角预设
@@ -397,6 +419,7 @@ export function setThemeColors(colors?: Partial<ThemeColors>) {
     businessColors = colors || null;
     invalidate();
     syncCssVars(getToken());
+    warnIfBgLayoutIgnored();
 }
 
 export function getThemeConfig(): ThemeConfig {
@@ -487,6 +510,7 @@ export function setThemeMode(mode: ThemeMode) {
     }
     invalidate();
     syncCssVars(getToken());
+    warnIfBgLayoutIgnored();
     EventBus.emit('themeChange', mode);
 }
 

package/src/framework/fields/FieldTable/styles.less

@@ -4,9 +4,9 @@
     border-spacing: 0;
 
     th {
-      background-color: rgb(250, 250, 250);
-      padding: 16px;
-      color: rgba(0, 0, 0, 0.88);
+      /* 跟随明暗主题，禁止硬编码浅色 */
+      background-color: var(--oa-color-fill, #fafafa);
+      color: var(--oa-color-text, rgba(0, 0, 0, 0.88));
     }
 
 

package/src/framework/utils/HttpClient.ts

@@ -15,7 +15,8 @@ import {getMessageApi} from "./MessageApi";
  * - 失败默认自动 console.warn + message.error，并 reject(AjaxError)；传 {toastError: false} 可完全静默（仅 reject）
  * - 返回值被忽略也安全：内部已对返回的 Promise 挂 no-op catch，不会产生 unhandled rejection
  * - reject 的 AjaxError {code, message}：业务失败 code 为后端业务码，网络异常 code 为 HTTP 状态码，message 始终为人类可读提示
- * - HTTP 401 或业务 code=401 均广播 loginExpired（全局关注点），弹错仍按 toastError 决定
+ * - HTTP 401 或业务 code=401 均广播 loginExpired，载荷为 {message, reason}，交由全局登录失效弹窗统一提示（不再单独弹错）
+ * - 非 AjaxResult 响应体（如纯文本、HTML 错误页）一律按失败处理，不再当成功 resolve，避免掩盖登录失效
  *
  * 用法：
  * ```ts
@@ -48,6 +49,8 @@ import {getMessageApi} from "./MessageApi";
 export interface AjaxError {
     code?: number | string;
     message: string;
+    /** 登录失效原因（仅 code=401 时可能携带），见 LOGIN_EXPIRED_REASON_CONCURRENT_LOGIN */
+    loginExpiredReason?: string;
 }
 
 /** 后端统一响应结构 AjaxResult；putExtData 附加字段在顶层，data 为业务数据 */
@@ -57,9 +60,25 @@ export interface AjaxBody<T = unknown> {
     data: T;
     message?: string;
     traceId?: string;
+    /** 登录失效原因（框架在 401 响应中透传，如并发登录被顶下线） */
+    loginExpiredReason?: string;
     [key: string]: unknown;
 }
 
+/**
+ * 登录失效原因：同一账号并发登录被顶下线（后端扩展字段 loginExpiredReason 的取值之一）。
+ * 全局登录失效弹窗据此使用后端下发的定制文案，而非站点级默认文案。
+ */
+export const LOGIN_EXPIRED_REASON_CONCURRENT_LOGIN = 'CONCURRENT_LOGIN';
+
+/** loginExpired 事件载荷 */
+export interface LoginExpiredPayload {
+    /** 提示文案，来自后端 401 响应体的 message */
+    message?: string;
+    /** 原因标识，来自后端 401 响应体的扩展字段 loginExpiredReason */
+    reason?: string;
+}
+
 /** 请求选项：headers 自定义请求头；toastError=false 时失败不自动弹错（完全静默，仅 reject）；toastSuccess=false 时成功不自动弹后端 message */
 export interface RequestOptions {
     headers?: AxiosRequestConfig['headers'];
@@ -144,16 +163,13 @@ export class HttpClient {
             }).then((response) => {
                 const blob: Blob = response.data;
 
-                if (blob.type === 'application/json') {
+                if (blob.type.toLowerCase().startsWith('application/json')) {
                     const reader = new FileReader();
                     reader.onerror = () => HttpClient.fail(url, toastError, reject, {message: '读取下载数据失败'}, '下载失败');
                     reader.onload = () => {
                         try {
                             const rs = JSON.parse(reader.result as string);
-                            if (rs.code === 401) {
-                                EventBus.emit('loginExpired');
-                            }
-                            HttpClient.fail(url, toastError, reject, {code: rs.code, message: rs.message || '下载失败'}, '下载失败');
+                            HttpClient.fail(url, toastError, reject, rs, '下载失败', rs.code === 401 ? 401 : undefined);
                         } catch {
                             HttpClient.fail(url, toastError, reject, {message: '解析错误响应失败'}, '下载失败');
                         }
@@ -246,21 +262,29 @@ export class HttpClient {
 
         const promise = new Promise<AjaxBody<T>>((resolve, reject) => {
             axiosInstance(config).then((response) => {
-                const body = response.data as AjaxBody<T>;
-                const {success: ok, message} = body;
-                if (ok == undefined) {
-                    resolve(body);
+                const body = response.data as AjaxBody<T> | undefined;
+
+                // 非 AjaxResult 响应体（如被过滤器/Servlet 容器拦截返回的纯文本、HTML 错误页）
+                // 一律按失败处理：曾经被当成成功 resolve，会掩盖登录失效等错误
+                // （axios 默认对 4xx/5xx 直接 reject，这里主要覆盖 2xx 却是非 JSON 的响应；401 分支为自定义 validateStatus 等场景兜底）
+                if (body == null || typeof body !== 'object' || body.success === undefined) {
+                    HttpClient.fail(url, toastError, reject, {
+                        code: response.status,
+                        message: response.status === 401 ? '登录过期' : `响应格式错误（HTTP ${response.status}）`,
+                    }, '请求失败', response.status);
                     return;
                 }
-                if (!ok) {
-                    if (body.code === 401) {
-                        EventBus.emit('loginExpired');
-                    }
-                    HttpClient.fail(url, toastError, reject, {code: body.code, message: message || '操作失败'});
+
+                if (!body.success) {
+                    HttpClient.fail(url, toastError, reject, {
+                        code: body.code,
+                        message: body.message || '操作失败',
+                        loginExpiredReason: body.loginExpiredReason,
+                    }, '请求失败', body.code === 401 ? 401 : undefined);
                     return;
                 }
-                if (toastSuccess && message) {
-                    getMessageApi().success(message);
+                if (toastSuccess && body.message) {
+                    getMessageApi().success(body.message);
                 }
                 resolve(body);
             }).catch((e: unknown) => {
@@ -273,14 +297,28 @@ export class HttpClient {
         return promise;
     }
 
-    /** 统一的失败处理：HTTP 401 广播 loginExpired 并弹"登录过期"，其余提取可读消息后按 toastError 决定是否弹错，最终 reject(AjaxError) */
-    private static fail(url: string, toastError: boolean, reject: (reason?: unknown) => void, e: unknown, label = '请求失败'): void {
-        if (axios.isAxiosError(e) && e.response?.status === 401) {
-            EventBus.emit('loginExpired');
-            const err: AjaxError = {code: 401, message: '登录过期'};
-            if (toastError) {
-                getMessageApi().error('登录过期');
-            }
+    /** 从 axios 异常 / AjaxResult / AjaxError 中提取登录失效文案与原因 */
+    private static loginExpiredInfo(e: unknown): {message: string; loginExpiredReason?: string} {
+        const data = (axios.isAxiosError(e) ? e.response?.data : e) as AjaxError | undefined;
+        return {
+            message: typeof data?.message === 'string' && data.message ? data.message : '登录过期',
+            loginExpiredReason: typeof data?.loginExpiredReason === 'string' ? data.loginExpiredReason : undefined,
+        };
+    }
+
+    /**
+     * 统一的失败处理：
+     * - HTTP 401 / 业务 code=401：广播 loginExpired（载荷含后端文案与原因），由全局登录失效弹窗统一提示，
+     *   不再单独弹错，避免与弹窗重复；最终 reject(AjaxError)
+     * - 其余：提取可读消息后按 toastError 决定是否弹错，最终 reject(AjaxError)
+     */
+    private static fail(url: string, toastError: boolean, reject: (reason?: unknown) => void, e: unknown, label = '请求失败', httpStatus?: number): void {
+        const status = httpStatus ?? (axios.isAxiosError(e) ? e.response?.status : undefined);
+        if (status === 401) {
+            const {message, loginExpiredReason} = HttpClient.loginExpiredInfo(e);
+            const payload: LoginExpiredPayload = {message, reason: loginExpiredReason};
+            EventBus.emit('loginExpired', payload);
+            const err: AjaxError = {code: 401, message, loginExpiredReason};
             reject(err);
             return;
         }