---
name: new-api-module
description: 在本模板中新建一个接口模块（src/api/<模块>/index.ts + types/）。当需要对接新的后端接口时使用。
---

# 新建 API 模块

## 目录约定

```text
src/api/<模块>/
├── index.ts              # 接口函数
└── types/<模块>.ts        # 该模块的请求/响应类型
```

## index.ts 模板

```ts
import type * as Recharge from "./types/recharge"
import { request } from "@/utils/service"

/** 交易流水列表 */
export function getPayList(params: IApiTableRequestData) {
  return request<Recharge.GetPayListResponseData>({
    method: "get",
    url: "/api/fund/tx/list",
    params
  })
}

/** 新增交易 */
export function addPay(data: Recharge.IPaySaveRequestData) {
  return request<IRequestResult<null>>({
    method: "post",
    url: "/api/fund/tx/add",
    data
  })
}
```

## types/<模块>.ts 模板

```ts
/** 列表行 */
export interface IPayItem {
  txId: string
  amount: number
  status: string
}

/** 列表响应 */
export type GetPayListResponseData = IApiResponseData<{
  list: IPayItem[]
  total: number
}>

/** 新增/编辑入参 */
export interface IPaySaveRequestData {
  txType: string
  amount: number
}
```

## 约束

- 必须从 `@/utils/service` 引入 `request`，**不要自定义 axios 实例或 baseURL**（统一走 vite 代理 `/api`，401 刷新由库内 `RefreshManager` 处理）。
- 全局类型已声明，可直接用：`IRequestResult<T>`、`IApiResponseData<T>`、`IApiTableRequestData<T>`（见 `types/api.d.ts` / `src/api/type.d.ts`）。
- 接口函数加中文注释；类型用 `interface`/`type`，接口对象前缀 `I`。
- 风格遵守 `AGENTS.md`：双引号、无分号、无尾随逗号。改完跑 `npm run lint`。
