Frontend Request Skill

src/
├── api/                       # 前后端桥接层（frontend-request-skill 管理）
│   ├── request.ts             # 统一请求封装（核心）
│   ├── upload.ts              # 文件上传封装
│   ├── sse.ts                 # SSE 流式请求封装
│   ├── modules/               # 业务模块 API（auth / user / role / menu / ...）
│   ├── _mocks_/               # Mock 数据字典
│   │   ├── index.ts           # MOCK_MAP + MockEntry
│   │   └── *.mock.ts          # 各模块 Mock
│   └── types/                 # 接口请求/响应类型
├── services/
│   └── auth.service.ts        # 鉴权服务：login / logout / handleUnauthorized
├── config/
│   ├── api.config.ts          # BASE_URL / 超时 / Mock / 成功码 / 鉴权失败码 / 重试
│   └── error.config.ts        # 错误码映射（与 api-contract.md 错误码表对齐）
├── utils/
│   ├── auth.ts                # getToken / setToken
│   ├── toast.ts               # 错误提示工具
│   └── error.ts               # 错误信息提取
└── composables/
    ├── useAuth.ts             # 游客判断 Hook
    └── useTypewriter.ts       # 打字机效果 Hook

export interface ApiResponse<T = any> {
  code: number;    // 业务状态码
  message: string; // 提示信息
  data: T;         // 业务数据
}

export const ERROR_CODE_MAP: Record<string, string> = {
  // HTTP 状态异常（请求层）
  UNAUTHORIZED: '登录已过期，请重新登录',
  FORBIDDEN: '权限不足',
  TIMEOUT: '请求超时，请检查网络',
  NETWORK_ERROR: '网络异常，请稍后重试',

  // 业务异常示例（按 code < 0 约定，需与后端契约保持一致）
  '-1001': '参数校验错误',
  '-1002': '未登录或 Token 无效',
  '-1003': '无权限',
  '-1004': '资源不存在',
  '-1005': '资源冲突',
  '-1006': '请求过于频繁',
  '-2000': '系统繁忙，请稍后再试',
};

export interface PageResponse<T> {
  list: T[];       // 数据列表
  total: number;   // 总条数
  page: number;    // 当前页码
  pageSize: number; // 每页条数
}

export interface TokenResponse {
  accessToken: string;   // 访问令牌（Java 后端 camelCase，Python 后端 snake_case 兼容）
  refreshToken: string;  // 刷新令牌
  tokenType: string;     // 固定 "Bearer"
  expiresIn: number;     // 过期时间（秒）
}

// src/api/request.ts
export interface RequestOptions {
  url: string;
  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'OPTIONS' | 'HEAD';
  data?: any;                // 请求体：通常为 plain object
  header?: Record<string, string>;
  timeout?: number;
  needAuth?: boolean;        // 是否需要 Token，默认 true
  showError?: boolean;       // 是否在请求层弹出错误 Toast；默认 false（自动弹）。true 时不弹，调用方自行处理
  skipDebounce?: boolean;    // 是否跳过防抖，默认 false
  skipAuthHandler?: boolean; // 是否跳过 401 处理，默认 false
  prefix?: string;           // API 前缀，默认 DEFAULT_PREFIX
  authMode?: 'bearer' | 'customer-token'; // Token 头格式
  retry?: number;            // 失败重试次数，默认 REQUEST_RETRY_COUNT
}

export interface RequestPromise<T> extends Promise<ApiResponse<T>> {
  __abort?: () => void;
}

export interface ApiResponse<T = any> {
  code: number;
  message: string;
  data: T;
}

export interface UploadOptions {
  url: string;
  file: File | string;       // 通用前端用 File；uniapp 用文件路径 string
  name?: string;
  formData?: Record<string, any>;
  header?: Record<string, string>;
  timeout?: number;
  onProgress?: (progress: number) => void; // 0-100
}

export function request<T = any>(options: RequestOptions): RequestPromise<T>;
export function get<T = any>(
  url: string,
  data?: any,
  options?: Omit<RequestOptions, 'url' | 'method' | 'data'>
): RequestPromise<T>;
export function post<T = any>(
  url: string,
  data?: any,
  options?: Omit<RequestOptions, 'url' | 'method' | 'data'>
): RequestPromise<T>;
export function put<T = any>(
  url: string,
  data?: any,
  options?: Omit<RequestOptions, 'url' | 'method' | 'data'>
): RequestPromise<T>;
export function del<T = any>(
  url: string,
  data?: any,
  options?: Omit<RequestOptions, 'url' | 'method' | 'data'>
): RequestPromise<T>;
export function upload<T = any>(options: UploadOptions): Promise<T>; // 直接返回业务 data，不包 ApiResponse