# 【需求编号】功能名称——前端接口对接文档

> 文档状态：设计中 / 待评审 / 联调中 / 已发布
> 编制日期：【YYYY-MM-DD】
> 最后更新：【YYYY-MM-DD】
> 后端负责人：【姓名】
> 前端负责人：【姓名】
> 测试负责人：【姓名】
> 关联需求：【需求或原型链接】
> 关联技术方案：【技术方案链接】
> 适用版本：【版本或迭代编号】

使用说明：复制本文档后，将所有「【请填写】」内容替换为真实信息，删除不适用的可选章节。提交评审前，应确认接口总览、请求示例、字段表、状态说明完全一致。

## 接口约定

### 1.1 基础信息

| 项目 | 说明 |
|-|-|
| 服务名称 | 【请填写】 |
| 接口前缀 | `/api/v1/【模块名】` |
| 通信协议 | HTTPS |
| 数据格式 | `application/json; charset=UTF-8` |
| 鉴权方式 | `Authorization: Bearer <token>` / 无需鉴权 |
| 时间格式 | `yyyy-MM-dd HH:mm:ss`，时区：`Asia/Shanghai` |
| 金额单位 | 分；如使用元，必须在具体字段中明确 |

通用请求头：

```HTTP
Authorization: Bearer <token>
Content-Type: application/json
```

补充约定：

- `GET` 请求没有请求体时，无需传 `Content-Type`；
- 前端不得传入可由登录态或服务端上下文确定的用户 ID、企业 ID 等归属字段；
- 前端只访问本服务，不直接调用内部依赖服务；
- 所有受保护接口必须校验用户、企业和业务数据归属。

### 1.2 统一响应格式

成功响应：

```JSON
{
  "code": 0,
  "message": "success",
  "data": {}
}
```

失败响应：

```JSON
{
  "code": 500,
  "message": "服务暂时不可用，请稍后重试",
  "data": null
}
```

前端应同时判断 HTTP 状态码和响应体 `code`。仅当 HTTP 请求成功且 `code === 0` 时读取 `data`。

如果项目采用字符串业务码，可将 `code` 统一调整为 `UNAUTHORIZED`、`INTERNAL_ERROR` 等稳定编码，但同一组接口不得混用整数码和字符串码。

### 1.3 通用数据约定

| 约定 | 说明 |
|-|-|
| 可空对象 | 无数据时返回 `null`，不返回空对象；特殊情况在字段定义中说明。 |
| 数组 | 无数据时返回 `[]`，不返回 `null`。 |
| 布尔值 | 使用 `true` / `false`，不使用 `0` / `1` 代替。 |
| 枚举 | 前端按编码处理逻辑；展示文案优先使用服务端返回的 `*Text` 字段。 |
| 时间 | 使用统一格式并明确时区，不返回含义不明的时间戳。 |
| 金额 | 字段说明必须标明单位，禁止同一接口混用「元」和「分」。 |
| 分页 | 明确页码起点、默认值和最大 `pageSize`。 |
| 未知字段 | 前端应忽略未识别字段，以支持接口向后兼容扩展。 |
| 敏感字段 | 手机号、证件号、银行卡号等必须脱敏，不返回密码、密钥或 Token。 |

## 本期接口总览

| 序号 | 方法 | 接口 | 用途 | 鉴权 | 是否新增 | 前端调用时机 |
|-|-|-|-|-|-|-|
| 1 | `GET` | `/api/v1/【模块】/【资源】` | 查询资源 | 是 | 是 | 页面首次加载及刷新 |
| 2 | `POST` | `/api/v1/【模块】/【资源】` | 创建资源 | 是 | 是 | 用户确认提交 |
| 3 | `POST` | `/api/v1/【模块】/【资源】/{id}/retry` | 重试处理 | 是 | 是 | 仅失败状态展示 |

## 接口一：查询资源

### 3.1 接口说明

**接口**：`GET /api/v1/【模块】/【资源】`

【说明接口用途、调用时机、查询范围、数据归属及关键约束，不要只重复接口名称。】

### 3.2 请求

请求示例：

```HTTP
GET /api/v1/【模块】/【资源】?page=1&pageSize=20
Authorization: Bearer <token>
```

路径参数：

| 参数 | 类型 | 必填 | 示例 | 说明 |
|-|-|-|-|-|
| `id` | string | 是 | `123456` | 资源唯一标识；必须校验当前用户的数据归属。 |

查询参数：

| 参数 | 类型 | 必填 | 默认值 | 示例 | 约束与说明 |
|-|-|-|-|-|-|
| `page` | integer | 否 | `1` | `1` | 从 1 开始。 |
| `pageSize` | integer | 否 | `20` | `20` | 最大值 100。 |
| `status` | string | 否 | — | `STATUS_A` | 可选值见状态编码。 |

请求体：无。

### 3.3 成功响应

```JSON
{
  "code": 0,
  "message": "success",
  "data": {
    "id": "123456",
    "status": "STATUS_A",
    "statusText": "处理中",
    "createdAt": "2026-01-01 10:00:00",
    "items": []
  }
}
```

响应字段：

| 字段 | 类型 | 必返 | 可空 | 示例 | 说明 |
|-|-|-|-|-|-|
| `data.id` | string | 是 | 否 | `123456` | 资源唯一标识。 |
| `data.status` | string | 是 | 否 | `STATUS_A` | 业务状态编码。 |
| `data.statusText` | string | 是 | 否 | `处理中` | 状态展示文案。 |
| `data.createdAt` | string | 是 | 否 | `2026-01-01 10:00:00` | 创建时间，时区为 `Asia/Shanghai`。 |
| `data.items` | array | 是 | 否 | `[]` | 无数据时返回空数组。 |

### 3.4 其他业务状态响应（可选）

业务上的空态、处理中和业务失败态，如果 HTTP 请求本身成功，应通过 `data.status` 等业务字段表达，不应误用 HTTP 500。

```JSON
{
  "code": 0,
  "message": "success",
  "data": {
    "status": "STATUS_C",
    "items": []
  }
}
```

| 业务状态 | 页面表现 | 是否轮询 | 主要操作 |
|-|-|-|-|
| `STATUS_A` | 处理中 | 是 | 刷新 |
| `STATUS_B` | 结果页 | 否 | 查看详情 |
| `STATUS_C` | 失败页 | 否 | 重试 |

## 接口二：创建或提交资源

### 4.1 接口说明

**接口**：`POST /api/v1/【模块】/【资源】`

【说明写操作的业务目的、前置状态、事务边界以及重复请求的处理方式。】

### 4.2 请求

```HTTP
POST /api/v1/【模块】/【资源】
Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: <唯一幂等号>
```

请求体：

```JSON
{
  "name": "示例名称",
  "type": "TYPE_A"
}
```

请求字段：

| 字段 | 类型 | 必填 | 可空 | 示例 | 校验规则与说明 |
|-|-|-|-|-|-|
| `name` | string | 是 | 否 | `示例名称` | 长度 1～100，提交前去除首尾空格。 |
| `type` | string | 是 | 否 | `TYPE_A` | 可选值见枚举定义。 |

### 4.3 成功响应

```JSON
{
  "code": 0,
  "message": "success",
  "data": {
    "id": "123456",
    "status": "STATUS_A"
  }
}
```

## 枚举与字段字典

### 5.1 类型枚举

| 编码 | 展示文案 | 说明 |
|-|-|-|
| `TYPE_A` | 类型 A | 【适用条件】 |
| `TYPE_B` | 类型 B | 【适用条件】 |

### 5.2 状态枚举

| 编码 | 展示文案 | 是否允许修改 | 可流转到 |
|-|-|-|-|
| `STATUS_A` | 处理中 | 否 | `STATUS_B`、`STATUS_C` |
| `STATUS_B` | 已完成 | 否 | — |
| `STATUS_C` | 失败 | 是 | `STATUS_A` |

## 变更记录

| 版本 | 日期 | 修改人 | 变更内容 | 影响范围 |
|-|-|-|-|-|
| `v0.1` | 【YYYY-MM-DD】 | 【姓名】 | 初稿 | 前后端评审 |
| `v1.0` | 【YYYY-MM-DD】 | 【姓名】 | 联调版本 | 正式接口 |