@moluoxixi/ajax-package 0.0.13 → 0.0.14-beta.1

package/es/BaseHttpClient.d.ts

@@ -1,6 +1,15 @@
 import { AxiosError, AxiosRequestConfig, AxiosResponse, InternalAxiosRequestConfig, default as axios } from 'axios';
 import { BaseHttpClientConfig } from './_types/index.ts';
 import { MessageInstance, NotificationInstance } from './_utils/index.ts';
+/**
+ * BaseHttpClient 基础类
+ * 提供最基础的 HTTP 请求功能，包括：
+ * - 创建 axios 实例
+ * - 自动添加 Token
+ * - 基础错误处理（401、超时等）
+ * - HTTP 方法（get、post、put、delete、all）
+ * - 文件上传
+ */
 export default class BaseHttpClient {
     protected baseURL: string;
     protected timeout: number;
@@ -10,22 +19,124 @@ export default class BaseHttpClient {
     instance: ReturnType<typeof axios.create>;
     protected messageInstance: MessageInstance;
     protected notificationInstance: NotificationInstance;
+    /**
+     * 创建 BaseHttpClient 实例
+     * @param config - HTTP 客户端配置对象
+     */
     constructor(config: BaseHttpClientConfig);
+    /**
+     * 处理请求配置，子类可重写此方法自定义请求配置
+     * @param config - 请求配置对象
+     * @returns 处理后的请求配置
+     */
     processRequestConfig(config: InternalAxiosRequestConfig): InternalAxiosRequestConfig<any>;
+    /**
+     * 处理响应配置，子类可重写此方法自定义响应处理
+     * 按照标准 HTTP 结构处理响应
+     * @param response - Axios 响应对象
+     * @returns 解析后的响应数据
+     */
     processResponseConfig(response: AxiosResponse): AxiosResponse['data'];
+    /**
+     * 处理 HTTP 状态码
+     * 子类可重写此方法来自定义 HTTP 状态码处理逻辑
+     * @param response - Axios 响应对象
+     */
     protected handleHttpStatus(response: AxiosResponse): void;
+    /**
+     * 处理成功响应
+     * 子类可重写此方法来自定义成功响应的处理逻辑
+     * @param response - Axios 响应对象
+     * @returns 解析后的响应数据
+     */
     protected handleSuccessResponse(response: AxiosResponse): AxiosResponse['data'];
+    /**
+     * 处理响应错误，子类可重写此方法自定义错误处理
+     * 按照标准 HTTP 错误结构处理错误
+     * @param error - Axios 错误对象
+     * @returns 处理后的错误对象
+     */
     processResponseError(error: AxiosError): Promise<AxiosError>;
+    /**
+     * 处理认证错误（401 - 未授权/登录失效）
+     * 子类可重写此方法来自定义认证错误处理逻辑
+     * @param error - Axios 错误对象
+     */
     protected handleAuthenticationError(error: AxiosError): void;
+    /**
+     * 处理超时错误
+     * 子类可重写此方法来自定义超时错误处理逻辑
+     * @param error - Axios 错误对象
+     */
     protected handleTimeoutError(error: AxiosError): void;
+    /**
+     * 处理网络错误（其他错误）
+     * 子类可重写此方法来自定义网络错误处理逻辑
+     * @param error - Axios 错误对象
+     */
     protected handleNetworkError(error: AxiosError): void;
+    /**
+     * 设置请求和响应拦截器
+     * 请求拦截器：自动添加 Token
+     * 响应拦截器：处理成功响应和错误响应（401、超时等）
+     */
     private setupInterceptors;
+    /**
+     * 发送 HTTP 请求，所有 HTTP 方法最终都调用此方法
+     * @param config - Axios 请求配置对象
+     * @returns 解析后的响应数据
+     */
     protected request<R>(config: AxiosRequestConfig): Promise<AxiosResponse['data']>;
+    /**
+     * 发送 GET 请求
+     * @param url - 请求 URL 路径
+     * @param params - 查询参数对象
+     * @param config - 额外的请求配置
+     * @returns 解析后的响应数据
+     */
     get<R>(url: string, params?: Record<string, any>, config?: AxiosRequestConfig): Promise<AxiosResponse['data']>;
+    /**
+     * 发送 POST 请求
+     * @param url - 请求 URL 路径
+     * @param data - 请求体数据
+     * @param config - 额外的请求配置
+     * @returns 解析后的响应数据
+     */
     post<R>(url: string, data?: Record<string, any>, config?: AxiosRequestConfig): Promise<AxiosResponse['data']>;
+    /**
+     * 发送 DELETE 请求
+     * @param url - 请求 URL 路径
+     * @param params - 查询参数对象
+     * @param config - 额外的请求配置
+     * @returns 解析后的响应数据
+     */
     delete<R>(url: string, params?: Record<string, any>, config?: AxiosRequestConfig): Promise<AxiosResponse['data']>;
+    /**
+     * 发送 PUT 请求
+     * @param url - 请求 URL 路径
+     * @param data - 请求体数据
+     * @param config - 额外的请求配置
+     * @returns 解析后的响应数据
+     */
     put<R>(url: string, data?: Record<string, any>, config?: AxiosRequestConfig): Promise<AxiosResponse['data']>;
+    /**
+     * 批量请求，并发发送多个请求
+     * @param requests - 请求配置数组或已发起的请求 Promise 数组
+     * @returns 所有请求的响应数据数组
+     */
     all<R>(requests: Array<AxiosRequestConfig | Promise<AxiosResponse<R>>>): Promise<AxiosResponse['data'][]>;
+    /**
+     * 文件上传，将文件包装为 FormData 发送
+     * @param url - 上传地址
+     * @param file - 文件对象
+     * @param config - 额外的请求配置
+     * @returns 解析后的响应数据
+     */
     uploadFile<R>(url: string, file: File | Blob, config?: AxiosRequestConfig): Promise<AxiosResponse['data']>;
+    /**
+     * 下载文件，将 Blob 对象下载到本地
+     * @param blob - Blob 对象
+     * @param filename - 文件名，如果不提供则使用时间戳
+     */
     downloadFile(blob: Blob, filename?: string): void;
 }

package/es/SystemErrorDialog.d.ts

@@ -1,3 +1,7 @@
+/**
+ * SystemErrorDialog 组件
+ * 使用 defineComponent 和 h 函数实现
+ */
 declare const _default: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
     title: {
         type: StringConstructor;

package/es/_types/api.d.ts

@@ -1,29 +1,65 @@
 import { App } from 'vue';
 import { MessageInstance } from '../_utils/index.ts';
 import { default as BaseApi } from '../class.ts';
+/**
+ * BaseHttpClient 基础配置接口，包含最基础的 HTTP 客户端配置
+ */
 export interface BaseHttpClientConfig {
+    /** API 基础地址 */
     baseURL?: string;
+    /** 请求超时时间（毫秒），默认 5000 */
     timeout?: number;
+    /** 请求超时回调函数，接收 messageInstance 用于显示消息提示 */
     onTimeout?: (messageInstance: MessageInstance) => void;
+    /** 获取 token 的函数，每次请求前自动调用 */
     getToken?: () => string | null;
+    /** 登录失效回调函数，当检测到 401 错误时调用，接收 messageInstance 用于显示消息提示 */
     onLoginRequired?: (messageInstance: MessageInstance) => void;
+    /** 允许其他任意配置项，会直接传递给 axios.create */
     [key: string]: any;
 }
+/**
+ * BaseApi 配置接口，用于配置 BaseApi 实例的所有选项
+ * 继承 BaseHttpClientConfig，添加响应字段映射和系统异常弹窗配置
+ */
 export interface BaseApiConfig extends BaseHttpClientConfig {
+    /** 响应字段映射配置 */
     responseFields?: {
+        /** 响应状态码字段名，默认 'Code' */
         code?: string;
+        /** 响应消息字段名，默认 'Message' */
         message?: string;
+        /** 响应数据字段名，默认 'data' */
         data?: string;
+        /** 错误数组字段名 */
         errors?: string;
+        /** 提示信息字段名 */
         tips?: string;
     };
+    /** 是否启用 code === -1 的系统异常弹窗，默认为 true */
     enableSystemErrorDialog?: boolean;
 }
+/**
+ * Vue Axios 插件配置选项
+ */
 export interface vueAxiosPluginOptionsType {
+    /** 默认 HTTP 服务配置 */
     default?: BaseApiConfig;
+    /** 是否在所有组件中通过 mixin 注入 $http，默认为 true */
     globalMixin?: boolean;
 }
+/**
+ * Vue HTTP 服务类型，在 Vue 应用中通过 this.$http 或 inject('$http') 获取
+ */
 export type vueHttpServiceType = BaseApi;
+/**
+ * Vue Axios 插件类型，定义了 Vue 插件的标准接口
+ */
 export interface vueAxiosPluginType {
+    /**
+     * 安装插件
+     * @param app - Vue 应用实例
+     * @param options - 插件配置选项
+     */
     install: (app: App, options?: vueAxiosPluginOptionsType) => void;
 }

package/es/_types/emits.d.ts

@@ -1,6 +1,13 @@
+/**
+ * SystemErrorDialog 组件的 Emits 类型定义
+ */
 export interface SystemErrorDialogEmitsType {
+    /** v-model 更新事件 */
     'update:modelValue': [val: boolean];
+    /** 关闭事件 */
     'close': [];
+    /** 确认事件 */
     'confirm': [data: any];
+    /** 上报事件 */
     'report': [];
 }

package/es/_types/props.d.ts

@@ -1,13 +1,27 @@
+/**
+ * SystemErrorDialog 组件的 Props 类型定义
+ */
 export interface SystemErrorDialogPropsType {
+    /** 对话框标题 */
     title?: string;
+    /** 对话框宽度 */
     width?: number | string;
+    /** 用户名 */
     userName?: string;
+    /** 用户ID */
     userId?: string;
+    /** 科室名称 */
     deptName?: string;
+    /** 科室ID */
     deptId?: string;
+    /** 客户端IP地址 */
     clientIp?: string;
+    /** 请求URL路径 */
     requestUrl?: string;
+    /** 链路追踪ID */
     traceId?: string;
+    /** 错误消息 */
     errorMessage?: string;
+    /** 错误代码 */
     errorCode?: number | string;
 }

package/es/_utils/messageWrapper.d.ts

@@ -1,3 +1,7 @@
+/**
+ * 创建消息实例的包装函数
+ * @returns 消息实例，支持 success、error、warning、info 方法
+ */
 export declare function createMessageWrapper(): (import('element-plus').MessageFn & {
     primary: import('element-plus').MessageTypedFn;
     success: import('element-plus').MessageTypedFn;

package/es/_utils/notificationWrapper.d.ts

@@ -1,3 +1,7 @@
+/**
+ * 创建通知实例的包装函数（用于 errors / tips 展示）
+ * @returns 通知实例，支持 success、error、warning、info 方法
+ */
 export declare function createNotificationWrapper(): ((import('element-plus').Notify & import('vue').Plugin) & {
     _context: import('vue').AppContext | null;
 }) | ((options: string | {

package/es/_utils/systemErrorInfo.d.ts

@@ -1,6 +1,27 @@
 import { AxiosResponse } from 'axios';
 import { SystemErrorDialogPropsType } from '../_types/index.ts';
+/**
+ * 规范化请求参数对象
+ * @param payload 请求参数
+ * @returns 规范化后的对象
+ */
 export declare function normalizePayload(payload: any): Record<string, any>;
+/**
+ * 解析响应头中的 TraceId
+ * @param headers 响应头
+ * @returns TraceId 字符串
+ */
 export declare function resolveTraceId(headers: AxiosResponse['headers'] | undefined): string;
+/**
+ * 从 localStorage 中读取 userInfo
+ * @returns userInfo 对象，如果不存在则返回空对象
+ */
 export declare function getUserInfoFromLocalStorage(): Record<string, any>;
+/**
+ * 从 AxiosResponse 中提取系统错误信息
+ * @param response Axios 响应对象
+ * @param code 错误代码
+ * @param message 错误消息
+ * @returns 提取的错误信息
+ */
 export declare function extractSystemErrorInfo(response: AxiosResponse, code: number, message: string): Omit<SystemErrorDialogPropsType, 'title' | 'width'>;

package/es/class.d.ts

@@ -1,34 +1,208 @@
-import { AxiosError, AxiosResponse, InternalAxiosRequestConfig } from 'axios';
+import { AxiosError, AxiosRequestConfig, AxiosResponse, InternalAxiosRequestConfig } from 'axios';
 import { BaseApiConfig } from './_types/index.ts';
 import { default as BaseHttpClient } from './BaseHttpClient.ts';
+/**
+ * BaseApi 类
+ * 继承 BaseHttpClient，提供增强的响应解析和错误处理功能
+ * 包括：响应字段映射、错误码处理、系统异常弹窗等
+ */
 export default class BaseApi extends BaseHttpClient {
     protected responseFields: Required<BaseApiConfig['responseFields']>;
     protected enableSystemErrorDialog: boolean;
+    /**
+     * 创建 BaseApi 实例
+     * @param config - API 配置对象
+     */
     constructor(config: BaseApiConfig);
+    /**
+     * 处理请求配置，子类可重写此方法自定义请求配置
+     * 显式声明以确保类型一致性，避免打包后的类型不兼容问题
+     * @param config - 请求配置对象
+     * @returns 处理后的请求配置
+     */
     processRequestConfig(config: InternalAxiosRequestConfig): InternalAxiosRequestConfig;
+    /**
+     * 处理响应配置，子类可重写此方法自定义响应处理
+     * 显式声明以确保类型一致性，避免打包后的类型不兼容问题
+     * @param response - Axios 响应对象
+     * @returns 解析后的响应数据
+     */
+    processResponseConfig(response: AxiosResponse): AxiosResponse['data'];
+    /**
+     * 处理响应错误，子类可重写此方法自定义错误处理
+     * 显式声明以确保类型一致性，避免打包后的类型不兼容问题
+     * @param error - Axios 错误对象
+     * @returns 处理后的错误对象
+     */
     processResponseError(error: AxiosError): Promise<AxiosError>;
+    /**
+     * 处理 HTTP 状态码
+     * 重写父类方法，确保子类可以重写此方法
+     * @param response - Axios 响应对象
+     */
     protected handleHttpStatus(response: AxiosResponse): void;
+    /**
+     * 处理认证错误（401 - 未授权/登录失效）
+     * 重写父类方法，处理 HTTP 401 错误
+     * 子类可重写此方法来自定义 HTTP 认证错误处理逻辑
+     * @param error - Axios 错误对象
+     */
     protected handleAuthenticationError(error: AxiosError): void;
+    /**
+     * 处理超时错误
+     * 重写父类方法，确保子类可以重写此方法
+     * @param error - Axios 错误对象
+     */
     protected handleTimeoutError(error: AxiosError): void;
+    /**
+     * 处理网络错误（其他错误）
+     * 重写父类方法，确保子类可以重写此方法
+     * @param error - Axios 错误对象
+     */
     protected handleNetworkError(error: AxiosError): void;
+    /**
+     * 处理成功响应
+     * 重写父类方法，在标准 HTTP 成功响应基础上，处理业务特定的响应结构
+     * 支持嵌套路径解析，自动处理业务层的登录失效、系统异常等错误
+     * 注意：HTTP 层的错误（如 HTTP 401、超时等）由父类 BaseHttpClient 处理
+     * @param response - Axios 响应对象
+     * @returns 解析后的响应数据
+     */
     protected handleSuccessResponse(response: AxiosResponse): AxiosResponse['data'];
+    /**
+     * 解析响应字段，支持嵌套路径解析
+     * 子类可重写此方法来自定义字段解析逻辑
+     * @param data - 响应数据对象
+     * @returns 解析后的字段值对象
+     */
     protected parseResponseFields(data: any): {
         code: any;
         message: any;
         responseData: any;
     };
+    /**
+     * 处理系统异常错误（-1 - 系统异常）
+     * 子类可重写此方法来自定义系统异常处理逻辑
+     * @param response - Axios 响应对象
+     * @param code - 响应状态码
+     * @param message - 错误消息
+     * @param responseData - 响应数据
+     */
     protected handleSystemError(response: AxiosResponse, code: any, message: any, responseData: any): void;
+    /**
+     * 处理业务错误（其他非200错误码）
+     * 子类可重写此方法来自定义业务错误处理逻辑
+     * @param code - 响应状态码
+     * @param message - 错误消息
+     */
     protected handleBusinessError(code: any, message: any): void;
+    /**
+     * 处理错误数组 errors（如果有配置）
+     * 子类可重写此方法来自定义错误数组处理逻辑
+     * @param responseData - 响应数据
+     */
     protected handleErrorArray(responseData: any): void;
+    /**
+     * 显示错误数组通知
+     * 子类可重写此方法来自定义错误数组通知显示方式
+     * @param errors - 错误数组
+     */
     protected showErrorArrayNotification(errors: Array<{
         code: string;
         message: string;
     }>): void;
+    /**
+     * 处理提示信息 tips（如果有配置）
+     * 子类可重写此方法来自定义提示信息处理逻辑
+     * @param responseData - 响应数据
+     */
     protected handleTips(responseData: any): void;
+    /**
+     * 显示提示信息通知
+     * 子类可重写此方法来自定义提示信息通知显示方式
+     * @param tips - 提示信息数组
+     */
     protected showTipsNotification(tips: Array<{
         code: string;
         message: string;
     }>): void;
+    /**
+     * 显示系统异常对话框，当响应状态码为 -1 时调用
+     * @param response - Axios 响应对象
+     * @param responseData - 响应数据
+     * @param code - 错误状态码
+     * @param message - 错误消息
+     */
     private showSystemExceptionDialog;
+    /**
+     * 上报错误信息到服务器，默认实现仅显示提示，子类可重写实现真实上报
+     * @param errorInfo - 错误信息对象
+     */
     protected reportError(errorInfo: any): Promise<void>;
+    /**
+     * 发送 HTTP 请求，所有 HTTP 方法最终都调用此方法
+     * 显式声明以确保类型一致性，子类可重写此方法
+     * @param config - Axios 请求配置对象
+     * @returns 解析后的响应数据
+     */
+    protected request<R>(config: AxiosRequestConfig): Promise<AxiosResponse['data']>;
+    /**
+     * 发送 GET 请求
+     * 显式声明以确保类型一致性，子类可重写此方法
+     * @param url - 请求 URL 路径
+     * @param params - 查询参数对象
+     * @param config - 额外的请求配置
+     * @returns 解析后的响应数据
+     */
+    get<R>(url: string, params?: Record<string, any>, config?: AxiosRequestConfig): Promise<AxiosResponse['data']>;
+    /**
+     * 发送 POST 请求
+     * 显式声明以确保类型一致性，子类可重写此方法
+     * @param url - 请求 URL 路径
+     * @param data - 请求体数据
+     * @param config - 额外的请求配置
+     * @returns 解析后的响应数据
+     */
+    post<R>(url: string, data?: Record<string, any>, config?: AxiosRequestConfig): Promise<AxiosResponse['data']>;
+    /**
+     * 发送 DELETE 请求
+     * 显式声明以确保类型一致性，子类可重写此方法
+     * @param url - 请求 URL 路径
+     * @param params - 查询参数对象
+     * @param config - 额外的请求配置
+     * @returns 解析后的响应数据
+     */
+    delete<R>(url: string, params?: Record<string, any>, config?: AxiosRequestConfig): Promise<AxiosResponse['data']>;
+    /**
+     * 发送 PUT 请求
+     * 显式声明以确保类型一致性，子类可重写此方法
+     * @param url - 请求 URL 路径
+     * @param data - 请求体数据
+     * @param config - 额外的请求配置
+     * @returns 解析后的响应数据
+     */
+    put<R>(url: string, data?: Record<string, any>, config?: AxiosRequestConfig): Promise<AxiosResponse['data']>;
+    /**
+     * 批量请求，并发发送多个请求
+     * 显式声明以确保类型一致性，子类可重写此方法
+     * @param requests - 请求配置数组或已发起的请求 Promise 数组
+     * @returns 所有请求的响应数据数组
+     */
+    all<R>(requests: Array<AxiosRequestConfig | Promise<AxiosResponse<R>>>): Promise<AxiosResponse['data'][]>;
+    /**
+     * 文件上传，将文件包装为 FormData 发送
+     * 显式声明以确保类型一致性，子类可重写此方法
+     * @param url - 上传地址
+     * @param file - 文件对象
+     * @param config - 额外的请求配置
+     * @returns 解析后的响应数据
+     */
+    uploadFile<R>(url: string, file: File | Blob, config?: AxiosRequestConfig): Promise<AxiosResponse['data']>;
+    /**
+     * 下载文件，将 Blob 对象下载到本地
+     * 显式声明以确保类型一致性，子类可重写此方法
+     * @param blob - Blob 对象
+     * @param filename - 文件名，如果不提供则使用时间戳
+     */
+    downloadFile(blob: Blob, filename?: string): void;
 }

package/es/index.d.ts

@@ -2,4 +2,5 @@ import { default as BaseHttpClient } from './BaseHttpClient.ts';
 import { default as BaseApi } from './class.ts';
 import { default as VueAxiosPlugin, createHttpService, getHttpService } from './netseriver.ts';
 export { BaseApi, BaseHttpClient, createHttpService, getHttpService, VueAxiosPlugin, };
+export type { BaseApiConfig, BaseHttpClientConfig, vueAxiosPluginOptionsType, vueAxiosPluginType, vueHttpServiceType, } from './_types/index.ts';
 export default getHttpService;

package/es/index.mjs

@@ -2,9 +2,9 @@
   "use strict";
   try {
     if (typeof document !== "undefined") {
-      if (!document.getElementById("065a78da-34dc-4a45-874d-4fb480012cd9")) {
+      if (!document.getElementById("ffe3dd99-bf7e-4730-8936-fd7b509c3c02")) {
         var elementStyle = document.createElement("style");
-        elementStyle.id = "065a78da-34dc-4a45-874d-4fb480012cd9";
+        elementStyle.id = "ffe3dd99-bf7e-4730-8936-fd7b509c3c02";
         elementStyle.appendChild(document.createTextNode("._root_11p33_1 .el-dialog__header {\n  padding: 0 12px 12px;\n}\n\n._root_11p33_1 .el-dialog__body {\n  border-top: 1px solid #e5e7eb;\n  border-bottom: 1px solid #e5e7eb;\n  padding: 0 12px;\n}\n\n._root_11p33_1 .el-dialog__footer {\n  padding: 0 12px;\n}"));
         document.head.appendChild(elementStyle);
       }
@@ -12183,6 +12183,10 @@ function defaultGetToken() {
   return typeof localStorage !== "undefined" ? localStorage.getItem("token") || "" : "";
 }
 class BaseHttpClient {
+  /**
+   * 创建 BaseHttpClient 实例
+   * @param config - HTTP 客户端配置对象
+   */
   constructor(config) {
     __publicField(this, "baseURL", "");
     __publicField(this, "timeout", 5e3);
@@ -12212,42 +12216,86 @@ class BaseHttpClient {
       baseURL: this.baseURL,
       timeout: this.timeout,
       ...axiosConfig
+      // 将所有剩余参数传给axios.create
     });
     this.setupInterceptors();
   }
+  /**
+   * 处理请求配置，子类可重写此方法自定义请求配置
+   * @param config - 请求配置对象
+   * @returns 处理后的请求配置
+   */
   processRequestConfig(config) {
     return config;
   }
+  /**
+   * 处理响应配置，子类可重写此方法自定义响应处理
+   * 按照标准 HTTP 结构处理响应
+   * @param response - Axios 响应对象
+   * @returns 解析后的响应数据
+   */
   processResponseConfig(response) {
     this.handleHttpStatus(response);
     return this.handleSuccessResponse(response);
   }
+  /**
+   * 处理 HTTP 状态码
+   * 子类可重写此方法来自定义 HTTP 状态码处理逻辑
+   * @param response - Axios 响应对象
+   */
   handleHttpStatus(response) {
     var _a2;
     if (response.status !== 200) {
       throw new Error(((_a2 = response.data) == null ? void 0 : _a2.message) || `HTTP Error: ${response.status}`);
     }
   }
+  /**
+   * 处理成功响应
+   * 子类可重写此方法来自定义成功响应的处理逻辑
+   * @param response - Axios 响应对象
+   * @returns 解析后的响应数据
+   */
   handleSuccessResponse(response) {
     return response.data;
   }
+  /**
+   * 处理响应错误，子类可重写此方法自定义错误处理
+   * 按照标准 HTTP 错误结构处理错误
+   * @param error - Axios 错误对象
+   * @returns 处理后的错误对象
+   */
   async processResponseError(error) {
     this.handleAuthenticationError(error);
     this.handleTimeoutError(error);
     this.handleNetworkError(error);
     return error;
   }
+  /**
+   * 处理认证错误（401 - 未授权/登录失效）
+   * 子类可重写此方法来自定义认证错误处理逻辑
+   * @param error - Axios 错误对象
+   */
   handleAuthenticationError(error) {
     var _a2, _b;
     if (((_a2 = error.response) == null ? void 0 : _a2.status) === 401) {
       (_b = this.onLoginRequired) == null ? void 0 : _b.call(this, this.messageInstance);
     }
   }
+  /**
+   * 处理超时错误
+   * 子类可重写此方法来自定义超时错误处理逻辑
+   * @param error - Axios 错误对象
+   */
   handleTimeoutError(error) {
     if (error.code === "ECONNABORTED" && error.message.includes("timeout")) {
       this.onTimeout(this.messageInstance);
     }
   }
+  /**
+   * 处理网络错误（其他错误）
+   * 子类可重写此方法来自定义网络错误处理逻辑
+   * @param error - Axios 错误对象
+   */
   handleNetworkError(error) {
     var _a2, _b, _c;
     if (((_a2 = error.response) == null ? void 0 : _a2.status) !== 401 && error.code !== "ECONNABORTED") {
@@ -12258,6 +12306,11 @@ class BaseHttpClient {
       });
     }
   }
+  /**
+   * 设置请求和响应拦截器
+   * 请求拦截器：自动添加 Token
+   * 响应拦截器：处理成功响应和错误响应（401、超时等）
+   */
   setupInterceptors() {
     this.instance.interceptors.request.use(
       (config) => {
@@ -12284,21 +12337,59 @@ class BaseHttpClient {
       }
     );
   }
+  /**
+   * 发送 HTTP 请求，所有 HTTP 方法最终都调用此方法
+   * @param config - Axios 请求配置对象
+   * @returns 解析后的响应数据
+   */
   async request(config) {
     return this.instance.request(config);
   }
+  /**
+   * 发送 GET 请求
+   * @param url - 请求 URL 路径
+   * @param params - 查询参数对象
+   * @param config - 额外的请求配置
+   * @returns 解析后的响应数据
+   */
   async get(url, params, config) {
     return this.request({ ...config, url, method: "get", params });
   }
+  /**
+   * 发送 POST 请求
+   * @param url - 请求 URL 路径
+   * @param data - 请求体数据
+   * @param config - 额外的请求配置
+   * @returns 解析后的响应数据
+   */
   async post(url, data, config) {
     return this.request({ ...config, url, method: "post", data });
   }
+  /**
+   * 发送 DELETE 请求
+   * @param url - 请求 URL 路径
+   * @param params - 查询参数对象
+   * @param config - 额外的请求配置
+   * @returns 解析后的响应数据
+   */
   async delete(url, params, config) {
     return this.request({ ...config, url, method: "delete", params });
   }
+  /**
+   * 发送 PUT 请求
+   * @param url - 请求 URL 路径
+   * @param data - 请求体数据
+   * @param config - 额外的请求配置
+   * @returns 解析后的响应数据
+   */
   async put(url, data, config) {
     return this.request({ ...config, url, method: "put", data });
   }
+  /**
+   * 批量请求，并发发送多个请求
+   * @param requests - 请求配置数组或已发起的请求 Promise 数组
+   * @returns 所有请求的响应数据数组
+   */
   async all(requests) {
     if (!requests.length)
       return [];
@@ -12311,6 +12402,13 @@ class BaseHttpClient {
     const promises = requests.map((config) => this.request(config));
     return await Promise.all(promises);
   }
+  /**
+   * 文件上传，将文件包装为 FormData 发送
+   * @param url - 上传地址
+   * @param file - 文件对象
+   * @param config - 额外的请求配置
+   * @returns 解析后的响应数据
+   */
   async uploadFile(url, file, config) {
     const formData = new FormData();
     formData.append("file", file);
@@ -12322,6 +12420,11 @@ class BaseHttpClient {
       }
     });
   }
+  /**
+   * 下载文件，将 Blob 对象下载到本地
+   * @param blob - Blob 对象
+   * @param filename - 文件名，如果不提供则使用时间戳
+   */
   downloadFile(blob, filename) {
     if (typeof window === "undefined") {
       console.warn("downloadFile: 非浏览器环境，无法下载文件");
@@ -12333,7 +12436,7 @@ class BaseHttpClient {
     link.download = filename || `download-${Date.now()}`;
     document.body.appendChild(link);
     link.click();
-    document.body.removeChild(link);
+    link.remove();
     window.URL.revokeObjectURL(url);
   }
 }
@@ -12437,10 +12540,12 @@ function createApiDialog(DialogComponent) {
               cleanup();
             }
           },
+          // 监听关闭事件
           onClose: () => {
             reject(new Error("对话框已关闭"));
             cleanup();
           },
+          // 监听确认事件（如有）
           onConfirm: (data) => {
             resolve(data);
             cleanup();
@@ -12491,6 +12596,10 @@ function createApiDialog(DialogComponent) {
 const hasDocument = typeof document !== "undefined";
 let systemErrorDialogInstance = null;
 class BaseApi extends BaseHttpClient {
+  /**
+   * 创建 BaseApi 实例
+   * @param config - API 配置对象
+   */
   constructor(config) {
     const {
       responseFields,
@@ -12510,24 +12619,74 @@ class BaseApi extends BaseHttpClient {
     };
     this.enableSystemErrorDialog = enableSystemErrorDialog;
   }
+  /**
+   * 处理请求配置，子类可重写此方法自定义请求配置
+   * 显式声明以确保类型一致性，避免打包后的类型不兼容问题
+   * @param config - 请求配置对象
+   * @returns 处理后的请求配置
+   */
   processRequestConfig(config) {
     return super.processRequestConfig(config);
   }
+  /**
+   * 处理响应配置，子类可重写此方法自定义响应处理
+   * 显式声明以确保类型一致性，避免打包后的类型不兼容问题
+   * @param response - Axios 响应对象
+   * @returns 解析后的响应数据
+   */
+  processResponseConfig(response) {
+    return super.processResponseConfig(response);
+  }
+  /**
+   * 处理响应错误，子类可重写此方法自定义错误处理
+   * 显式声明以确保类型一致性，避免打包后的类型不兼容问题
+   * @param error - Axios 错误对象
+   * @returns 处理后的错误对象
+   */
   async processResponseError(error) {
     return super.processResponseError(error);
   }
+  /**
+   * 处理 HTTP 状态码
+   * 重写父类方法，确保子类可以重写此方法
+   * @param response - Axios 响应对象
+   */
   handleHttpStatus(response) {
     return super.handleHttpStatus(response);
   }
+  /**
+   * 处理认证错误（401 - 未授权/登录失效）
+   * 重写父类方法，处理 HTTP 401 错误
+   * 子类可重写此方法来自定义 HTTP 认证错误处理逻辑
+   * @param error - Axios 错误对象
+   */
   handleAuthenticationError(error) {
     super.handleAuthenticationError(error);
   }
+  /**
+   * 处理超时错误
+   * 重写父类方法，确保子类可以重写此方法
+   * @param error - Axios 错误对象
+   */
   handleTimeoutError(error) {
     return super.handleTimeoutError(error);
   }
+  /**
+   * 处理网络错误（其他错误）
+   * 重写父类方法，确保子类可以重写此方法
+   * @param error - Axios 错误对象
+   */
   handleNetworkError(error) {
     return super.handleNetworkError(error);
   }
+  /**
+   * 处理成功响应
+   * 重写父类方法，在标准 HTTP 成功响应基础上，处理业务特定的响应结构
+   * 支持嵌套路径解析，自动处理业务层的登录失效、系统异常等错误
+   * 注意：HTTP 层的错误（如 HTTP 401、超时等）由父类 BaseHttpClient 处理
+   * @param response - Axios 响应对象
+   * @returns 解析后的响应数据
+   */
   handleSuccessResponse(response) {
     const httpData = super.handleSuccessResponse(response);
     const parsedFields = this.parseResponseFields(httpData);
@@ -12538,6 +12697,12 @@ class BaseApi extends BaseHttpClient {
     this.handleTips(responseData);
     return responseData;
   }
+  /**
+   * 解析响应字段，支持嵌套路径解析
+   * 子类可重写此方法来自定义字段解析逻辑
+   * @param data - 响应数据对象
+   * @returns 解析后的字段值对象
+   */
   parseResponseFields(data) {
     var _a2, _b, _c;
     const getValueByPath = (obj, path) => {
@@ -12559,6 +12724,14 @@ class BaseApi extends BaseHttpClient {
     const responseData = getValueByPath(data, (_c = this.responseFields) == null ? void 0 : _c.data);
     return { code, message: message2, responseData };
   }
+  /**
+   * 处理系统异常错误（-1 - 系统异常）
+   * 子类可重写此方法来自定义系统异常处理逻辑
+   * @param response - Axios 响应对象
+   * @param code - 响应状态码
+   * @param message - 错误消息
+   * @param responseData - 响应数据
+   */
   handleSystemError(response, code, message2, responseData) {
     if (code === -1) {
       if (this.enableSystemErrorDialog) {
@@ -12569,6 +12742,12 @@ class BaseApi extends BaseHttpClient {
       throw new Error(message2 || "系统异常");
     }
   }
+  /**
+   * 处理业务错误（其他非200错误码）
+   * 子类可重写此方法来自定义业务错误处理逻辑
+   * @param code - 响应状态码
+   * @param message - 错误消息
+   */
   handleBusinessError(code, message2) {
     var _a2;
     if (code && code !== 200) {
@@ -12579,6 +12758,11 @@ class BaseApi extends BaseHttpClient {
       throw new Error(message2 || "请求失败");
     }
   }
+  /**
+   * 处理错误数组 errors（如果有配置）
+   * 子类可重写此方法来自定义错误数组处理逻辑
+   * @param responseData - 响应数据
+   */
   handleErrorArray(responseData) {
     var _a2;
     const errorsField = (_a2 = this.responseFields) == null ? void 0 : _a2.errors;
@@ -12590,6 +12774,11 @@ class BaseApi extends BaseHttpClient {
       }
     }
   }
+  /**
+   * 显示错误数组通知
+   * 子类可重写此方法来自定义错误数组通知显示方式
+   * @param errors - 错误数组
+   */
   showErrorArrayNotification(errors) {
     var _a2, _b;
     const html = errors.map((item) => `<div style="font-size: 14px;color:red">${item.code}：${item.message}</div>`).join("");
@@ -12608,6 +12797,11 @@ class BaseApi extends BaseHttpClient {
       });
     }
   }
+  /**
+   * 处理提示信息 tips（如果有配置）
+   * 子类可重写此方法来自定义提示信息处理逻辑
+   * @param responseData - 响应数据
+   */
   handleTips(responseData) {
     var _a2;
     const tipsField = (_a2 = this.responseFields) == null ? void 0 : _a2.tips;
@@ -12618,6 +12812,11 @@ class BaseApi extends BaseHttpClient {
       }
     }
   }
+  /**
+   * 显示提示信息通知
+   * 子类可重写此方法来自定义提示信息通知显示方式
+   * @param tips - 提示信息数组
+   */
   showTipsNotification(tips) {
     var _a2, _b;
     const html = tips.map((item) => `<div style="font-size: 14px;color:#E6A23C">${item.code}：${item.message}</div>`).join("");
@@ -12636,6 +12835,13 @@ class BaseApi extends BaseHttpClient {
       });
     }
   }
+  /**
+   * 显示系统异常对话框，当响应状态码为 -1 时调用
+   * @param response - Axios 响应对象
+   * @param responseData - 响应数据
+   * @param code - 错误状态码
+   * @param message - 错误消息
+   */
   async showSystemExceptionDialog(response, responseData, code, message2) {
     if (!hasDocument) {
       console.error("系统异常信息：", responseData);
@@ -12674,6 +12880,10 @@ class BaseApi extends BaseHttpClient {
       console.error("系统异常信息：", responseData);
     }
   }
+  /**
+   * 上报错误信息到服务器，默认实现仅显示提示，子类可重写实现真实上报
+   * @param errorInfo - 错误信息对象
+   */
   async reportError(errorInfo) {
     var _a2, _b;
     try {
@@ -12691,11 +12901,98 @@ class BaseApi extends BaseHttpClient {
       });
     }
   }
+  /**
+   * 发送 HTTP 请求，所有 HTTP 方法最终都调用此方法
+   * 显式声明以确保类型一致性，子类可重写此方法
+   * @param config - Axios 请求配置对象
+   * @returns 解析后的响应数据
+   */
+  async request(config) {
+    return super.request(config);
+  }
+  /**
+   * 发送 GET 请求
+   * 显式声明以确保类型一致性，子类可重写此方法
+   * @param url - 请求 URL 路径
+   * @param params - 查询参数对象
+   * @param config - 额外的请求配置
+   * @returns 解析后的响应数据
+   */
+  async get(url, params, config) {
+    return super.get(url, params, config);
+  }
+  /**
+   * 发送 POST 请求
+   * 显式声明以确保类型一致性，子类可重写此方法
+   * @param url - 请求 URL 路径
+   * @param data - 请求体数据
+   * @param config - 额外的请求配置
+   * @returns 解析后的响应数据
+   */
+  async post(url, data, config) {
+    return super.post(url, data, config);
+  }
+  /**
+   * 发送 DELETE 请求
+   * 显式声明以确保类型一致性，子类可重写此方法
+   * @param url - 请求 URL 路径
+   * @param params - 查询参数对象
+   * @param config - 额外的请求配置
+   * @returns 解析后的响应数据
+   */
+  async delete(url, params, config) {
+    return super.delete(url, params, config);
+  }
+  /**
+   * 发送 PUT 请求
+   * 显式声明以确保类型一致性，子类可重写此方法
+   * @param url - 请求 URL 路径
+   * @param data - 请求体数据
+   * @param config - 额外的请求配置
+   * @returns 解析后的响应数据
+   */
+  async put(url, data, config) {
+    return super.put(url, data, config);
+  }
+  /**
+   * 批量请求，并发发送多个请求
+   * 显式声明以确保类型一致性，子类可重写此方法
+   * @param requests - 请求配置数组或已发起的请求 Promise 数组
+   * @returns 所有请求的响应数据数组
+   */
+  async all(requests) {
+    return super.all(requests);
+  }
+  /**
+   * 文件上传，将文件包装为 FormData 发送
+   * 显式声明以确保类型一致性，子类可重写此方法
+   * @param url - 上传地址
+   * @param file - 文件对象
+   * @param config - 额外的请求配置
+   * @returns 解析后的响应数据
+   */
+  async uploadFile(url, file, config) {
+    return super.uploadFile(url, file, config);
+  }
+  /**
+   * 下载文件，将 Blob 对象下载到本地
+   * 显式声明以确保类型一致性，子类可重写此方法
+   * @param blob - Blob 对象
+   * @param filename - 文件名，如果不提供则使用时间戳
+   */
+  downloadFile(blob, filename) {
+    return super.downloadFile(blob, filename);
+  }
 }
 function createHttpService(options = {}) {
   return new BaseApi(options);
 }
 const VueAxiosPlugin = {
+  /**
+   * 安装插件
+   * @param app - Vue 应用实例
+   * @param options - 插件配置选项
+   */
   install(app, options = {}) {
     const httpService = createHttpService(options.default ?? {});
     app.config.globalProperties.$http = httpService;
@@ -12876,10 +13173,12 @@ const SystemErrorDialog = defineComponent({
             h("span", { style: { fontWeight: "bold", fontSize: "16px" } }, props.title || "系统异常信息")
           ]),
           default: () => h("div", { style: { padding: 0, maxHeight: "500px", overflowY: "auto" } }, [
+            // 第一块：无法完成您的请求
             h("div", { style: { padding: "20px", borderBottom: "1px solid #ebeef5" } }, [
               h("h3", { style: { margin: "0 0 12px 0", fontSize: "16px", fontWeight: "bold", color: "#303133" } }, "无法完成您的请求"),
               h("p", { style: { margin: 0, color: "#606266", lineHeight: 1.5 } }, "系统在处理您的请求时遇到了问题，可能是由于服务暂时不可用。")
             ]),
+            // 第二块：技术摘要（可展开）
             h("div", { style: { borderBottom: "1px solid #ebeef5" } }, [
               h(
                 "div",
@@ -12941,6 +13240,7 @@ const SystemErrorDialog = defineComponent({
                 )
               ) : null
             ]),
+            // SkyWalking 按钮
             h("div", { style: { padding: "16px 20px", borderBottom: "1px solid #ebeef5" } }, [
               h(
                 ElButton,
@@ -12952,6 +13252,7 @@ const SystemErrorDialog = defineComponent({
                 { default: () => "📊 在SkyWalking中查看详情" }
               )
             ]),
+            // 黑色错误信息区域
             h("div", { style: { backgroundColor: "#2c3e50", color: "#fff", padding: "16px 20px", fontFamily: 'Monaco, Consolas, "Courier New", monospace', fontSize: "12px", lineHeight: 1.5, maxHeight: "200px", overflowY: "auto" } }, [
               h("div", { style: { marginBottom: "8px", color: "#ecf0f1" } }, `Trace ID: ${props.traceId || "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8"}`),
               h("div", { style: { color: "#e74c3c", fontWeight: "bold" } }, `Error: ${props.errorMessage || "Connection timeout after 5000ms"}`)

package/es/netseriver.d.ts

@@ -5,8 +5,22 @@ declare global {
         $http?: vueHttpServiceType;
     }
 }
+/**
+ * 创建 HTTP 服务实例
+ * @param options - API 配置对象
+ * @returns BaseApi 实例
+ */
 declare function createHttpService(options?: BaseApiConfig): BaseApi;
+/**
+ * Vue Axios 插件，用于在 Vue 应用中全局注册 HTTP 服务
+ * 提供 this.$http、inject('$http') 和 window.$http 三种使用方式
+ */
 declare const VueAxiosPlugin: vueAxiosPluginType;
+/**
+ * 获取 HTTP 服务实例，与 createHttpService 功能相同
+ * @param options - API 配置对象
+ * @returns BaseApi 实例
+ */
 declare function getHttpService(options?: BaseApiConfig): BaseApi;
 export default VueAxiosPlugin;
 export { createHttpService, getHttpService };

package/es/test/utils/BaseRequestApi.d.ts

@@ -0,0 +1,9 @@
+import { AxiosResponse, InternalAxiosRequestConfig } from 'axios';
+import { BaseApi, BaseApiConfig } from '@moluoxixi/ajax-package';
+export default class BaseRequestApi extends BaseApi {
+    constructor(config?: Partial<BaseApiConfig>);
+    processRequestConfig(config: InternalAxiosRequestConfig): InternalAxiosRequestConfig;
+    protected handleSuccessResponse(response: AxiosResponse): AxiosResponse['data'];
+    protected handleHttpStatus(response: AxiosResponse): void;
+    protected handleBusinessError(code: any, message: any): void;
+}

package/es/test/utils/DownloadApi.d.ts

@@ -0,0 +1,21 @@
+import { AxiosError, AxiosRequestConfig, AxiosResponse, InternalAxiosRequestConfig } from 'axios';
+import { default as BaseRequestApi } from './BaseRequestApi.ts';
+export default class DownloadApi extends BaseRequestApi {
+    private downloadingFiles;
+    constructor();
+    processRequestConfig(config: InternalAxiosRequestConfig): InternalAxiosRequestConfig;
+    processResponseError(error: AxiosError): Promise<AxiosError>;
+    protected handleSuccessResponse(response: AxiosResponse): AxiosResponse['data'];
+    downloadFileFromUrl(url: string, filename?: string, params?: Record<string, any>, data?: Record<string, any>, method?: 'get' | 'post', config?: AxiosRequestConfig): Promise<boolean>;
+    private getFilenameFromUrl;
+    downloadMultipleFiles(files: Array<{
+        url: string;
+        filename?: string;
+        params?: Record<string, any>;
+        data?: Record<string, any>;
+        method?: 'get' | 'post';
+    }>, onProgress?: (progress: number, currentFile: string) => void): Promise<{
+        success: number;
+        total: number;
+    }>;
+}

package/es/test/utils/RoleApi.d.ts

@@ -0,0 +1,4 @@
+import { BaseApi, BaseApiConfig } from '@moluoxixi/ajax-package';
+export default class RoleApi extends BaseApi {
+    constructor(config?: Partial<BaseApiConfig>);
+}

package/es/test/utils/UserApi.d.ts

@@ -0,0 +1,4 @@
+import { BaseApi, BaseApiConfig } from '@moluoxixi/ajax-package';
+export default class UserApi extends BaseApi {
+    constructor(config?: Partial<BaseApiConfig>);
+}

package/es/test/utils/index.d.ts

@@ -0,0 +1,9 @@
+import { default as DownloadApi } from './DownloadApi.ts';
+import { default as BaseRequestApi } from './BaseRequestApi.ts';
+import { default as UserApi } from './UserApi.ts';
+import { default as RoleApi } from './RoleApi.ts';
+export declare const downloadRequest: DownloadApi;
+export declare const userRequest: any;
+export declare const baseRequest: any;
+export declare const roleRequest: any;
+export { DownloadApi, BaseRequestApi, UserApi, RoleApi, };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moluoxixi/ajax-package",
-  "version": "0.0.13",
+  "version": "0.0.14-beta.1",
   "description": "AjaxPackage 组件",
   "sideEffects": [
     "*.css",