# API 契约

**文档版本**: 1.0.0
**最后更新**: 2026-04-19

---

## 1. 通用规范

| 规范项 | 规则 |
|--------|------|
| **基础路径** | `/api/v1` |
| **协议** | HTTPS（所有接口强制 HTTPS） |
| **时间格式** | ISO 8601（示例：`2026-04-15T14:30:00Z`） |
| **字符编码** | UTF-8 |
| **分页参数** | `?page=1&per_page=50`（默认 50，最大 200） |

### 1.1 认证方式

| 接口类别 | 认证方式 | 说明 |
|----------|----------|------|
| <!-- 类别1 --> | <!-- 方式 --> | <!-- 说明 --> |
| <!-- 类别2 --> | <!-- 方式 --> | <!-- 说明 --> |

---

## 2. 通用响应格式

### 2.1 成功响应

```json
{
    "data": {
        "key": "value"
    },
    "meta": {
        "request_id": "550e8400-e29b-41d4-a716-446655440000"
    }
}
```

### 2.2 错误响应

```json
{
    "error": {
        "code": "ERROR_CODE",
        "message": "用户可读的错误描述"
    },
    "meta": {
        "request_id": "550e8400-e29b-41d4-a716-446655440000"
    }
}
```

### 2.3 分页响应

```json
{
    "data": [],
    "meta": {
        "total": 100,
        "page": 1,
        "per_page": 50,
        "request_id": "550e8400-e29b-41d4-a716-446655440000"
    }
}
```

---

## 3. HTTP 状态码

| 状态码 | 场景 |
|--------|------|
| 200 | 成功 |
| 201 | 创建成功 |
| 204 | 删除成功（无响应体） |
| 400 | 请求参数错误 |
| 401 | 未认证 |
| 403 | 未授权 |
| 404 | 资源不存在 |
| 409 | 冲突 |
| 429 | 请求过于频繁 |
| 500 | 服务端内部错误 |

---

## 4. 错误码规范

| 范围 | 错误码 | 说明 |
|------|--------|------|
| `AUTH_*` | <!-- 错误码 --> | 认证相关 |
| `VALIDATION_*` | <!-- 错误码 --> | 验证相关 |
| <!-- 范围 --> | <!-- 错误码 --> | <!-- 说明 --> |

---

## 5. 接口定义

<!-- 按以下模板为每个接口编写定义 -->

### 5.1 <!-- HTTP方法 --> <!-- 路径 --> -- <!-- 接口说明 -->

**请求：**

```json
{
    "field": "value"
}
```

**响应 <!-- 状态码 -->：**

```json
{
    "data": {},
    "meta": {
        "request_id": "550e8400-e29b-41d4-a716-446655440000"
    }
}
```

**错误响应：**

| 状态码 | 错误码 | 说明 |
|--------|--------|------|
| <!-- 状态码 --> | <!-- 错误码 --> | <!-- 说明 --> |

---

## 6. FR 映射表

| FR 编号 | 功能 | 对应 API 接口 |
|---------|------|---------------|
| FR-001 | <!-- 功能 --> | <!-- 接口 --> |
| FR-002 | <!-- 功能 --> | <!-- 接口 --> |

---

**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板