@jiangood/open-admin 3.0.14 → 3.1.0

package/src/framework/fields/FieldTableSelect/index.tsx

@@ -2,14 +2,14 @@ import React from "react";
 import {Button, Select} from "antd";
 import type {TableColumnsType} from "antd";
 import {ProTable} from "../../components";
-import {HttpUtils} from "../../utils";
+import {HttpClient} from "../../utils";
 import type {FieldProps} from '../types';
 
 export interface FieldTableSelectProps extends FieldProps<string> {
     /** 数据加载地址 */
     url: string;
     /** 表格列配置（操作列由组件自动追加） */
-    columns: TableColumnsType<Record<string, any>>;
+    columns: TableColumnsType<Record<string, unknown>>;
     /** 占位文本，默认 请搜索选择 */
     placeholder?: string;
 }
@@ -26,7 +26,7 @@ interface FieldTableSelectState {
  */
 export class FieldTableSelect extends React.Component<FieldTableSelectProps, FieldTableSelectState> {
 
-    static defaultProps = {
+    static readonly defaultProps = {
         placeholder: '请搜索选择',
     };
 
@@ -62,13 +62,13 @@ export class FieldTableSelect extends React.Component<FieldTableSelectProps, Fie
                                 label: record.name,
                                 open: false
                             });
-                            this.props.onChange && this.props.onChange(record.id);
+                            this.props.onChange?.(record.id);
                         }}>选择</Button>;
                 }
             }]}
             request={(params) => {
                 params.selected = this.props.value;
-                return HttpUtils.get(this.props.url, params);
+                return HttpClient.get(this.props.url, params);
             }}>
         </ProTable>;
     };

package/src/framework/fields/FieldUploadFile/index.tsx

@@ -88,7 +88,7 @@ export class FieldUploadFile extends React.Component<FieldUploadFileProps, Field
                 if (f.response) { // 新上传的
                     const ajaxResult = f.response;
                     if (ajaxResult.success) {
-                        const {objectName, name} = ajaxResult.data;
+                        const {objectName} = ajaxResult.data;
                         f.objectName = objectName;
                         objectNames.push(objectName);
                     } else {
@@ -102,9 +102,9 @@ export class FieldUploadFile extends React.Component<FieldUploadFileProps, Field
         return objectNames;
     }
 
-    handleChange = ({fileList, event, file}: UploadChangeParam<SysUploadFile>) => {
+    handleChange = ({fileList, file}: UploadChangeParam<SysUploadFile>) => {
         const rs = file.response;
-        if (rs != null && rs.success === false) {
+        if (rs?.success === false) {
             this.setState({errorTitle: '上传失败', errorContent: rs.message});
             return;
         }

package/src/framework/fields/FieldUploadImage/index.tsx

@@ -4,9 +4,7 @@ import {DeleteOutlined, EyeOutlined, PlusOutlined} from "@ant-design/icons";
 import Compressor from "compressorjs";
 import Cropper from "cropperjs";
 import "cropperjs/dist/cropper.css";
-import {HttpUtils} from "../../utils";
-import {ObjectUtils} from "../../utils";
-import {UrlUtils} from "../../utils";
+import {HttpClient, ObjectUtils, UrlUtils} from "../../utils";
 import type {FieldProps} from '../types';
 
 export interface FieldUploadImageProps extends FieldProps<string> {
@@ -93,7 +91,7 @@ function readDims(url: string): Promise<Dims> {
 
 function compressToFile(source: Blob, options: {maxWidth?: number; maxHeight?: number; width?: number; height?: number; quality?: number}): Promise<File> {
     return new Promise((resolve, reject) => {
-        new Compressor(source, {
+        new Compressor(source, { // NOSONAR (typescript:S1848) — compressorjs 通过构造函数副作用异步压缩，回调内 resolve/reject，实例无需保留
             maxWidth: options.maxWidth,
             maxHeight: options.maxHeight,
             width: options.width,
@@ -141,9 +139,9 @@ async function compressToTarget(source: Blob, maxWidth: number | undefined, targ
     return best;
 }
 
-export class FieldUploadImage extends React.Component<FieldUploadImageProps, FieldUploadImageState> {
+export class FieldUploadImage extends React.Component<FieldUploadImageProps, FieldUploadImageState> { // NOSONAR: state 构造器中按 props 初始化，无法全部 readonly
 
-    state: FieldUploadImageState = {
+    state: FieldUploadImageState = { // NOSONAR: 构造器中按 props 初始化，无法 readonly
         // 传入的参数
         maxCount: 1,
         thumbWidth: 300,
@@ -169,10 +167,10 @@ export class FieldUploadImage extends React.Component<FieldUploadImageProps, Fie
     constructor(props: FieldUploadImageProps) {
         super(props);
         ObjectUtils.copyPropertyIfPresent(props, this.state);
-        if (this.props.value) this.state.objectNames = this.props.value.split(',');
+        if (props.value) this.state.objectNames = props.value.split(',');
     }
 
-    componentDidUpdate(prevProps: FieldUploadImageProps, prevState: FieldUploadImageState) {
+    componentDidUpdate(prevProps: FieldUploadImageProps, prevState: FieldUploadImageState) { // NOSONAR: 顺序同步多个 props 到 state，拆分反而更难读
         const next: Partial<FieldUploadImageState> = {};
         if (this.props.maxCount !== prevProps.maxCount) next.maxCount = this.props.maxCount;
         if (this.props.thumbWidth !== prevProps.thumbWidth) next.thumbWidth = this.props.thumbWidth;
@@ -199,7 +197,7 @@ export class FieldUploadImage extends React.Component<FieldUploadImageProps, Fie
         if (prevState.cropRatio !== this.state.cropRatio && this.cropperRef) {
             if (!this.state.cropRatio) {
                 const box = this.cropperRef.getCropBoxData();
-                this.cropperRef.setAspectRatio(NaN);
+                this.cropperRef.setAspectRatio(Number.NaN);
                 this.cropperRef.setCropBoxData(box);
             } else {
                 this.cropperRef.setAspectRatio(this.state.cropRatio.width / this.state.cropRatio.height);
@@ -229,7 +227,7 @@ export class FieldUploadImage extends React.Component<FieldUploadImageProps, Fie
         const init = () => {
             if (this.cropperRef) this.cropperRef.destroy();
             this.cropperRef = new Cropper(el, {
-                aspectRatio: this.state.cropRatio ? this.state.cropRatio.width / this.state.cropRatio.height : NaN,
+                aspectRatio: this.state.cropRatio ? this.state.cropRatio.width / this.state.cropRatio.height : Number.NaN,
                 viewMode: 1,
                 autoCropArea: 0.85,
                 dragMode: 'move',
@@ -293,7 +291,7 @@ export class FieldUploadImage extends React.Component<FieldUploadImageProps, Fie
             this.previewUrlsRef = [cUrl];
             this.setState({preview: {cUrl, cFile, cSize: cFile.size, cdims}, tool: undefined});
             message.success(`已压缩：${cdims.width} x ${cdims.height} / ${formatSize(cFile.size)}`);
-        } catch (e) {
+        } catch {
             message.error('压缩失败');
         }
     };
@@ -320,7 +318,7 @@ export class FieldUploadImage extends React.Component<FieldUploadImageProps, Fie
             this.setState({originalDims: dims});
             // 默认展示原图，不做压缩处理，用户可点击「压缩」按钮手动压缩
             await this.loadOriginalPreview(file, url, dims);
-        } catch (e) {
+        } catch {
             message.error('读取图片失败');
             this.closeModal();
             return;
@@ -365,22 +363,34 @@ export class FieldUploadImage extends React.Component<FieldUploadImageProps, Fie
             fd.append('file', this.state.preview.cFile);
             fd.append('thumb', tFile);
             fd.append('isPublic', String(this.state.isPublic));
-            const rs = await HttpUtils.post('admin/sysFile/uploadImage', fd);
-            const newNames = [...this.state.objectNames, rs.objectName];
-            this.setState({objectNames: newNames});
-            this.props.onChange?.(newNames.join(','));
+            const rs = await HttpClient.post('admin/sysFile/uploadImage', fd, null, {toastError: false});
+            this.setState(
+                (prevState) => ({objectNames: [...prevState.objectNames, rs.data.objectName]}),
+                () => this.props.onChange?.(this.state.objectNames.join(','))
+            );
             this.closeModal();
         } catch (e) {
-            message.error(HttpUtils.extractErrorMessage(e));
+            message.error(HttpClient.errToMsg(e));
         } finally {
             this.setState({uploading: false});
         }
     };
 
     private removeImage = (name: string) => {
-        const newNames = this.state.objectNames.filter((n) => n !== name);
-        this.setState({objectNames: newNames});
-        this.props.onChange?.(newNames.join(','));
+        this.setState(
+            (prevState) => ({objectNames: prevState.objectNames.filter((n) => n !== name)}),
+            () => this.props.onChange?.(this.state.objectNames.join(','))
+        );
+    };
+
+    private renderCanvas = (preview, canvasImg, originalUrl) => {
+        if (this.state.tool === 'crop') {
+            return <img key="crop-canvas" ref={this.imgRef} src={preview?.cUrl || originalUrl} style={{maxWidth: '100%', maxHeight: '100%'}} alt="待裁切"/>;
+        }
+        if (canvasImg?.url) {
+            return <img src={canvasImg.url} style={{maxWidth: '100%', maxHeight: '100%'}} alt="预览"/>;
+        }
+        return <div style={{color: '#999'}}>生成中...</div>;
     };
 
     render() {
@@ -479,13 +489,7 @@ export class FieldUploadImage extends React.Component<FieldUploadImageProps, Fie
                                 flex: 1, minHeight: 0, display: 'flex', alignItems: 'center', justifyContent: 'center',
                                 background: '#f5f5f5', borderRadius: 8, border: '1px dashed #d9d9d9', position: 'relative', overflow: 'hidden',
                             }}>
-                                {tool === 'crop' ? (
-                                    <img key="crop-canvas" ref={this.imgRef} src={preview?.cUrl || originalUrl} style={{maxWidth: '100%', maxHeight: '100%'}} alt="待裁切"/>
-                                ) : canvasImg?.url ? (
-                                    <img src={canvasImg.url} style={{maxWidth: '100%', maxHeight: '100%'}} alt="预览"/>
-                                ) : (
-                                    <div style={{color: '#999'}}>生成中...</div>
-                                )}
+                                {this.renderCanvas(preview, canvasImg, originalUrl)}
                             </div>
                         </div>
 
@@ -506,7 +510,6 @@ export class FieldUploadImage extends React.Component<FieldUploadImageProps, Fie
                                 {tool !== 'crop' && <Divider style={{margin: '0 0 12px'}}/>}
                                 <div style={{fontWeight: 600, marginBottom: 8}}>{tool === 'crop' ? '裁切信息' : '图片信息'}</div>
                                 {tool === 'crop' ? (
-                                    <>
                                         <Radio.Group
                                             value={cropRatio ? formatRatio(cropRatio.width, cropRatio.height) : 'free'}
                                             onChange={(e) => {
@@ -521,7 +524,6 @@ export class FieldUploadImage extends React.Component<FieldUploadImageProps, Fie
                                                 </Radio>
                                             ))}
                                         </Radio.Group>
-                                    </>
                                 ) : (
                                     <>
                                         {canvasImg && (

package/src/framework/fields/types.ts

@@ -1,5 +1,3 @@
-import React from 'react';
-
 /**
  * 通用字段组件属性接口
  * @template T - value 的类型

package/src/framework/router/PageFrame.tsx

@@ -10,7 +10,7 @@ interface PageFrameProps {
 }
 
 export class PageFrame extends React.Component<PageFrameProps> {
-    componentRef = React.createRef<any>();
+    componentRef = React.createRef<{onShow?: () => void}>();
 
     componentDidMount() {
         this.callOnShowIfActive();

package/src/framework/router/matcher.ts

@@ -6,7 +6,7 @@ function safeDecodeURIComponent(s: string): string {
 
 export interface RouteDef {
     path: string;
-    component: ComponentType<any>;
+    component: ComponentType<unknown>;
 }
 
 interface InternalRoute extends RouteDef {
@@ -14,7 +14,7 @@ interface InternalRoute extends RouteDef {
 }
 
 export interface MatchResult {
-    component: ComponentType<any>;
+    component: ComponentType<unknown>;
     params: Record<string, string>;
 }
 

package/src/framework/utils/ArrayUtils.ts

@@ -1,6 +1,6 @@
 export class ArrayUtils {
     static contains<T>(arr: T[], item: T): boolean {
-        return arr.indexOf(item) !== -1;
+        return arr.includes(item);
     }
 
     static containsAny<T>(arr: T[], ...items: T[]): boolean {
@@ -10,7 +10,7 @@ export class ArrayUtils {
         return false;
     }
 
-    static maxBy<T extends Record<K, any>, K extends keyof T>(arr: T[], key: K): T | undefined {
+    static maxBy<T extends Record<K, unknown>, K extends keyof T>(arr: T[], key: K): T | undefined {
         if (arr == null || arr.length === 0) return undefined;
         let maxElement: T | undefined = undefined;
         let maxValue = -Infinity;

package/src/framework/utils/DateUtils.ts

@@ -62,7 +62,7 @@ export class DateUtils {
     static friendlyTotalTime(time: number | string | null): string | null {
         if (time == null || time === '-') return null;
         let seconds: number;
-        if (typeof time === 'string') seconds = parseInt(time, 10) / 1000;
+        if (typeof time === 'string') seconds = Number.parseInt(time, 10) / 1000;
         else seconds = time / 1000;
         seconds = Math.floor(seconds);
         if (seconds < 60) return seconds + '秒';

package/src/framework/utils/{system/DictUtils.ts → DictUtils.ts}

@@ -1,4 +1,4 @@
-import {GlobalData} from '../../GlobalData';
+import {GlobalData} from '../GlobalData';
 import {Tag} from 'antd';
 import React from 'react';
 

package/src/framework/utils/EventBus.ts

@@ -1,14 +1,14 @@
-type EventCallback = (...args: any[]) => void;
+type EventCallback = (...args: unknown[]) => void;
 
 interface EventEntry {
     fn: EventCallback & { __callback?: EventCallback };
-    ctx?: any;
+    ctx?: unknown;
 }
 
 export class EventBus {
     private static __stack: Record<string, EventEntry[]> = {};
 
-    static on<T extends any[] = []>(name: string, callback: (...args: T) => void, ctx?: any): () => void {
+    static on<T extends unknown[] = []>(name: string, callback: (...args: T) => void, ctx?: unknown): () => void {
         if (!EventBus.__stack[name]) {
             EventBus.__stack[name] = [];
         }
@@ -16,9 +16,9 @@ export class EventBus {
         return () => EventBus.off(name, callback);
     }
 
-    static once<T extends any[] = []>(name: string, callback: (...args: T) => void, ctx?: any): () => void {
+    static once<T extends unknown[] = []>(name: string, callback: (...args: T) => void, ctx?: unknown): () => void {
         const unsubscribe = () => EventBus.off(name, callback);
-        const listener: EventEntry['fn'] = (...args: any[]) => {
+        const listener: EventEntry['fn'] = (...args: unknown[]) => {
             EventBus.off(name, listener);
             callback.apply(ctx, args);
         };
@@ -28,7 +28,7 @@ export class EventBus {
         return unsubscribe;
     }
 
-    static emit<T extends any[] = []>(name: string, ...args: T): void {
+    static emit<T extends unknown[] = []>(name: string, ...args: T): void {
         const list = EventBus.__stack[name];
         if (list !== undefined) {
             list.slice(0).forEach(entry => {
@@ -37,7 +37,7 @@ export class EventBus {
         }
     }
 
-    static off<T extends any[] = []>(name: string, callback?: (...args: T) => void): void {
+    static off<T extends unknown[] = []>(name: string, callback?: (...args: T) => void): void {
         const list = EventBus.__stack[name];
         if (list === undefined) return;
         if (callback === undefined) {

package/src/framework/utils/HttpClient.ts

@@ -0,0 +1,283 @@
+import axios from "axios";
+import type {AxiosProgressEvent, AxiosRequestConfig} from "axios";
+import qs from 'qs';
+import {message as messageApi} from "antd";
+import {EventBus} from "./EventBus";
+
+/**
+ * 单一 Promise 风格 HTTP 工具类（所有请求方法均返回 Promise，无 success/error 回调）
+ *
+ * 核心规则：
+ * - 请求方法返回 Promise<AjaxBody<T>>：成功 resolve 整个 AjaxResult 响应体，失败 reject(AjaxError {code, message})
+ * - 成功 resolve 的是原始响应体 {success, code, data, message, traceId, ...}（extData 等附加字段在顶层），
+ *   业务取数据用 rs.data，取提示文案用 rs.message
+ * - 成功且后端返回了 message 时自动 message.success(body.message)，传 {toastSuccess: false} 可关闭
+ * - 失败默认自动 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 决定
+ *
+ * 用法：
+ * ```ts
+ * // 提交：成功自动弹后端 message（如"更新成功"），失败自动弹错并 reject（可用 await 感知结果，如 FormModal 提交失败保持弹窗）
+ * await HttpClient.post('admin/sysUser/create', values);
+ *
+ * // 取返回数据与后端提示文案
+ * const {data, message} = await HttpClient.post('admin/sysUser/create', values);
+ *
+ * // 成功自控提示（关闭自动弹后由业务决定）
+ * await HttpClient.post('admin/sysUser/delete', {id}, null, {toastSuccess: false});
+ * messageApi.success('删除成功');
+ * reload();
+ *
+ * // 失败由调用方接管，不弹错（静默探测）
+ * HttpClient.get('admin/public/site-info', null, {toastError: false})
+ *     .then(({data}) => render(data))
+ *     .catch((e) => myHandle(e));
+ *
+ * // $.ajax 形态
+ * HttpClient.ajax({url: 'admin/sysUser/page', method: 'GET', params}).then((rs) => render(rs.data));
+ *
+ * // 下载（返回 Promise<Blob>，成功已触发浏览器保存）
+ * HttpClient.download({url: 'admin/sysUser/export', method: 'POST', data: {deptId: 1},
+ *     onDownloadProgress: ({loaded, total}) => console.log(loaded, total)})
+ *     .catch(() => {});
+ * ```
+ */
+/** 统一的错误数据格式：业务失败与网络异常都包装成此结构传给 reject 的 error */
+export interface AjaxError {
+    code?: number | string;
+    message: string;
+}
+
+/** 后端统一响应结构 AjaxResult；putExtData 附加字段在顶层，data 为业务数据 */
+export interface AjaxBody<T = unknown> {
+    success: boolean;
+    code: number;
+    data: T;
+    message?: string;
+    traceId?: string;
+    [key: string]: unknown;
+}
+
+/** 请求选项：headers 自定义请求头；toastError=false 时失败不自动弹错（完全静默，仅 reject）；toastSuccess=false 时成功不自动弹后端 message */
+export interface RequestOptions {
+    headers?: AxiosRequestConfig['headers'];
+    toastError?: boolean;
+    toastSuccess?: boolean;
+}
+
+interface AjaxSettings {
+    url: string;
+    method?: 'GET' | 'POST';
+    params?: unknown;
+    data?: unknown;
+    headers?: AxiosRequestConfig['headers'];
+    toastError?: boolean;
+    toastSuccess?: boolean;
+}
+
+interface DownloadSettings {
+    url: string;
+    method?: 'GET' | 'POST';
+    params?: unknown;
+    data?: unknown;
+    fileName?: string;
+    onDownloadProgress?: (progress: {loaded: number; total: number}) => void;
+    toastError?: boolean;
+}
+
+const axiosInstance = axios.create({
+    baseURL: import.meta.env.VITE_SERVER_SERVLET_CONTEXT_PATH,
+    withCredentials: true,
+    headers: {'Content-Type': 'application/json'},
+    paramsSerializer: (params: Record<string, unknown>) => qs.stringify(params, {indices: false})
+});
+
+export class HttpClient {
+    static ajax<T = unknown>(settings: AjaxSettings): Promise<AjaxBody<T>> {
+        const {url, method = 'GET', params, data, headers, toastError, toastSuccess} = settings;
+        return HttpClient.coreRequest<T>({
+            url, method, params, data, headers, toastError, toastSuccess
+        });
+    }
+
+    static get<T = unknown>(url: string, params: unknown = null, opts?: RequestOptions): Promise<AjaxBody<T>> {
+        return HttpClient.ajax<T>({url, method: 'GET', params, ...opts});
+    }
+
+    static post<T = unknown>(url: string, data: unknown = null, params: unknown = null, opts?: RequestOptions): Promise<AjaxBody<T>> {
+        return HttpClient.ajax<T>({url, method: 'POST', data, params, ...opts});
+    }
+
+    static postForm<T = unknown>(url: string, data: unknown, opts?: RequestOptions): Promise<AjaxBody<T>> {
+        return HttpClient.ajax<T>({
+            url,
+            method: 'POST',
+            data: qs.stringify(data),
+            headers: {'Content-Type': 'application/x-www-form-urlencoded'},
+            ...opts
+        });
+    }
+
+    /**
+     * 下载文件（responseType: blob），返回 Promise<Blob>。
+     * 成功即触发浏览器保存并 resolve(blob)；JSON 错误响应自动识别为失败并 reject；
+     * 文件名优先 settings.fileName，否则从 Content-Disposition 解析。
+     * 失败默认自动弹错，传 {toastError: false} 可静默（仅 reject）。
+     */
+    static download(settings: DownloadSettings): Promise<Blob> {
+        const {url, method = 'GET', params, data, fileName, onDownloadProgress, toastError = true} = settings;
+
+        return new Promise<Blob>((resolve, reject) => {
+            axiosInstance({
+                url: HttpClient.prefixUrl(url),
+                method,
+                params,
+                data,
+                responseType: 'blob',
+                onDownloadProgress: (progressEvent: AxiosProgressEvent) => {
+                    if (onDownloadProgress) {
+                        onDownloadProgress({loaded: progressEvent.loaded, total: progressEvent.total});
+                    }
+                }
+            }).then((response) => {
+                const blob: Blob = response.data;
+
+                if (blob.type === '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 || '下载失败'}, '下载失败');
+                        } catch {
+                            HttpClient.fail(url, toastError, reject, {message: '解析错误响应失败'}, '下载失败');
+                        }
+                    };
+                    reader.readAsText(blob, 'utf-8');
+                    return;
+                }
+
+                let filename = fileName;
+                if (!filename) {
+                    const contentDisposition = response.headers['content-disposition'] || response.headers['Content-Disposition'];
+                    if (contentDisposition) {
+                        const match = /filename\*?=(?:['"]?)(?:UTF-8''|)(.+?)(?:['"]?$|;)/i.exec(contentDisposition);
+                        let parsedName = match?.[1] ? match[1].trim() : 'download.file';
+                        try {
+                            parsedName = decodeURIComponent(parsedName.replaceAll('"', ''));
+                        } catch {
+                            parsedName = parsedName.replaceAll('"', '');
+                        }
+                        filename = parsedName;
+                    }
+                }
+
+                const objectUrl = window.URL.createObjectURL(new Blob([blob]));
+                const link = document.createElement('a');
+                link.style.display = 'none';
+                link.href = objectUrl;
+                link.download = filename || 'download.file';
+                document.body.appendChild(link);
+                link.click();
+                link.remove();
+                window.URL.revokeObjectURL(objectUrl);
+                resolve(blob);
+            }).catch((e: unknown) => {
+                HttpClient.fail(url, toastError, reject, e, '下载失败');
+            });
+        });
+    }
+
+    /**
+     * 从 axios 异常/Error/AjaxError 中提取人类可读错误消息。
+     * catch 收到的已是 AjaxError，直接取 e.message 即可；此方法供传原始异常的场景兜底。
+     */
+    static errToMsg(e: unknown, defaultMsg = '操作失败'): string {
+        if (axios.isAxiosError(e)) {
+            const responseData = e.response?.data;
+            const status = e.response?.status;
+            if (status === 504) return '504 请求后端服务失败';
+            if (responseData?.message) return responseData.message;
+            if (e.message) return e.message;
+            return defaultMsg;
+        }
+        if (e instanceof Error) return e.message || defaultMsg;
+        if (e && typeof e === 'object' && (e as {message?: unknown}).message) return (e as {message: string}).message;
+        return defaultMsg;
+    }
+
+    /** 把任意异常（AxiosError / Error / AjaxError / 业务消息）统一包装成 AjaxError */
+    private static toAjaxError(e: unknown, defaultMsg = '操作失败'): AjaxError {
+        if (e && typeof e === 'object' && typeof (e as {message?: unknown}).message === 'string') {
+            const ajaxErr = e as {code?: number | string; message: string};
+            return {code: ajaxErr.code, message: ajaxErr.message};
+        }
+        return {message: HttpClient.errToMsg(e, defaultMsg)};
+    }
+
+    private static prefixUrl(url: string): string {
+        return url.startsWith('admin') ? '/' + url : url;
+    }
+
+    private static coreRequest<T = unknown>(settings: AjaxSettings): Promise<AjaxBody<T>> {
+        const {url, method, params, data, headers, toastError = true, toastSuccess = true} = settings;
+        const config: AxiosRequestConfig = {url: HttpClient.prefixUrl(url), method, params, data, headers};
+
+        // FormData 请求交由浏览器自动生成带 boundary 的 multipart Content-Type
+        if (typeof FormData !== 'undefined' && data instanceof FormData) {
+            config.headers = {...config.headers, 'Content-Type': undefined};
+        }
+
+        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);
+                    return;
+                }
+                if (!ok) {
+                    if (body.code === 401) {
+                        EventBus.emit('loginExpired');
+                    }
+                    HttpClient.fail(url, toastError, reject, {code: body.code, message: message || '操作失败'});
+                    return;
+                }
+                if (toastSuccess && message) {
+                    messageApi.success(message);
+                }
+                resolve(body);
+            }).catch((e: unknown) => {
+                HttpClient.fail(url, toastError, reject, e);
+            });
+        });
+
+        // 调用方忽略返回值时兜底，避免 unhandled rejection；await 的调用方仍能正常收到 reject
+        promise.catch(() => {});
+        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) {
+                messageApi.error('登录过期');
+            }
+            reject(err);
+            return;
+        }
+        const err = HttpClient.toAjaxError(e);
+        if (toastError) {
+            console.warn(`[HttpClient] ${label}: ${url}`, err.message);
+            messageApi.error(err.message);
+        }
+        reject(err);
+    }
+}

package/src/framework/utils/{system/PageUtils.ts → PageUtils.ts}

@@ -1,7 +1,7 @@
-import {history} from '../../router';
-import {StringUtils} from "../StringUtils";
-import {UrlUtils} from "../UrlUtils";
-import {EventBus} from "../EventBus";
+import {history} from '../router';
+import {StringUtils} from "./StringUtils";
+import {UrlUtils} from "./UrlUtils";
+import {EventBus} from "./EventBus";
 
 export class PageUtils {
     static redirectToLogin(): void {

package/src/framework/utils/{system/PermUtils.ts → PermUtils.ts}

@@ -1,5 +1,5 @@
-import {GlobalData} from '../../GlobalData';
-import {ArrayUtils} from '../ArrayUtils';
+import {GlobalData} from '../GlobalData';
+import {ArrayUtils} from './ArrayUtils';
 
 export class PermUtils {
     static getPermissions(): string[] {
@@ -13,7 +13,7 @@ export class PermUtils {
         const permissions = PermUtils.getPermissions();
         if (permissions.length === 0) return false;
         if (ArrayUtils.contains(permissions, "*")) return true;
-        return permissions.indexOf(perm) > -1;
+        return permissions.includes(perm);
     }
 
     static isPermitted(p: string | null | undefined): boolean {