---
name: project-api
description: 接口调用约定（axios 封装、apis/xt 模块、平台代管头、错误处理）。新增或修改接口调用时加载本技能。
---

# 接口调用

> ⚠️ **本仓库没有 Mock**：`mock/` 与 `vite-plugin-mock` 都已删除。
> `pnpm dev` 把 `/api` 代理到 `http://localhost:8080` → **后端不起着就没有数据**。
> （上一版这份 skill 以 Mock 为主线，那是 Gi 模板的写法，**已不适用**。）

## 契约

- 响应恒为 `{ code, msg, data }`；**业务错误也用 HTTP 200**，
  只有 `401` / `403` / `429` / `5xx` 用**真实状态码**（别在业务码里找 `40301`）。
- `code === 0` 是成功。

## 封装（`src/utils/http.ts`）

它替业务代码做掉三件事，所以页面里几乎不出现 `code`：

1. 成功时**直接 resolve `data`** → `const vo = await getTask(id)` 拿到的就是数据；
2. 失败时**弹一次提示**并 reject 一个带 `bizCode` 的错误（要按码分支也能拿到）；
3. 自动带 `Authorization: Bearer <token>` 与平台代管头 `X-Tenant-Id`。

## 写一个接口模块（`src/apis/xt/<域>.ts`）

```ts
import type { PageResult } from '@/apis/types'
import http from '@/utils/http'

export interface XxxVO { id: number, name: string, status: number }

/** 状态映射与接口同处一个文件（别处也要用，改动只有一处） */
export const XXX_STATUS: Record<number, { text: string, color: string }> = {
  0: { text: '停用', color: 'gray' },
  1: { text: '正常', color: 'green' }
}

export function list(params: { page: number, pageSize: number, keyword?: string }) {
  return http.get<PageResult<XxxVO>>('/xxx', { params })
}
```

- 新域就**新建一个文件**，并在 `src/apis/xt/index.ts` 里按需导出；
- 通用类型（`PageResult`、`BizError` 等）在 `src/apis/types.ts`；
- ⚠️ 展示映射里的 `color` 是**上一版 Arco 的色词**，给 `n-tag` 用之前必须过 `@/utils/tag.ts` 的 `tagOf()`。

## 平台代管（`X-Tenant-Id`）

平台运营的请求要带"当前学校"：值存在 `src/stores/acting-tenant.ts`，
由 `http.ts` 统一注入。**页面不要自己拼这个头**；不选学校时**不要发请求**（发了会把各租户数据混在一起）。

## 其它

- 下载类接口（导出包、整理结果）必须走 `fetch`/axios **取 blob**：接口要鉴权，
  直接 `window.open` 或 `<a href>` 会 401，用户看到的是"下载没反应"。
- 签名 URL（预览图片等）**每次现取**，不要缓存进本地状态或存库（有有效期）。