# API 接口文档

> 本项目 API 接口说明

---

## 一、接口概览

| 模块 | 接口 | 方法 | 说明 |
|------|------|------|------|
| 候选人 | `/api/candidates` | POST | 提交候选人信息（上传简历） |
| 房间 | `/api/rooms` | POST | 创建语音房间 |
| 管理 | `/api/candidates` | GET | 获取候选人列表 |
| 管理 | `/api/candidates/:id` | GET | 获取候选人详情 |
| 管理 | `/api/candidates/:id/export` | GET | 导出 PDF 报告 |

---

## 二、通用说明

### 2.1 基础 URL

```
开发环境：http://localhost:8000
生产环境：https://api.your-domain.com
```

### 2.2 响应格式

**成功响应**：
```json
{
  "code": 0,
  "message": "success",
  "data": { ... }
}
```

**错误响应**：
```json
{
  "code": 20001,
  "message": "参数错误",
  "data": null
}
```

### 2.3 错误码

| 范围 | 类型 |
|------|------|
| `0` | 成功 |
| `10000-19999` | 用户相关错误 |
| `20000-29999` | 业务逻辑错误 |
| `30000-39999` | 数据错误 |
| `40000-49999` | 系统错误 |
| `50000-59999` | 第三方服务错误 |

常用错误码：

| 错误码 | 说明 |
|--------|------|
| `20001` | 参数错误 |
| `20002` | 数据不存在 |
| `50001` | Coze API 调用失败 |
| `50002` | RTC 服务异常 |

---

## 三、用户端接口

### 3.1 提交候选人信息

提交候选人姓名和简历，创建面试会话。

**请求**

- **URL**: `POST /api/candidates`
- **Content-Type**: `multipart/form-data`

**请求参数**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | 候选人姓名，2-20字符 |
| resume | file | 是 | 简历文件，支持 PDF/DOC/DOCX，≤10MB |

**响应示例**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "sessionId": "SESS_1705737600_张三_abc123",
    "fileId": "file_xxx"
  }
}
```

**处理流程**

1. 校验参数
2. 上传简历到 Coze（`POST /v1/files/upload`）
3. 生成 sessionId
4. 返回结果

---

### 3.2 创建语音房间

创建 RTC 房间，让 Coze Bot 加入房间。

**请求**

- **URL**: `POST /api/rooms`
- **Content-Type**: `application/json`

**请求参数**

```json
{
  "sessionId": "SESS_1705737600_张三_abc123",
  "fileId": "file_xxx"
}
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| sessionId | string | 是 | 会话 ID |
| fileId | string | 是 | 简历文件 ID |

**响应示例**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "roomId": "room_xxx",
    "token": "rtc_token_xxx",
    "appId": "volcengine_app_id",
    "userId": "user_xxx"
  }
}
```

**处理流程**

1. 生成 roomId 和 userId
2. 调用 Coze API 让 Bot 加入房间（`POST /v1/audio/rooms`）
3. 生成 RTC Token
4. 返回房间信息

---

### 3.3 结束面试

通知后端面试已结束。

**请求**

- **URL**: `POST /api/interviews/:sessionId/end`
- **Content-Type**: `application/json`

**请求参数**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| sessionId | string | 是 | 会话 ID（URL 参数） |

**响应示例**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "success": true
  }
}
```

---

## 四、管理后台接口

### 4.1 获取候选人列表

分页获取候选人列表。

**请求**

- **URL**: `GET /api/candidates`
- **权限**: 需要登录

**请求参数**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | number | 否 | 页码，默认 1 |
| pageSize | number | 否 | 每页条数，默认 20 |
| keyword | string | 否 | 搜索关键词（姓名） |
| status | string | 否 | 状态筛选：pending/ongoing/completed |
| startDate | string | 否 | 开始日期，格式 YYYY-MM-DD |
| endDate | string | 否 | 结束日期，格式 YYYY-MM-DD |

**响应示例**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "list": [
      {
        "sessionId": "SESS_1705737600_张三_abc123",
        "name": "张三",
        "status": "completed",
        "score": 85,
        "createdAt": "2026-01-20T10:00:00+08:00"
      }
    ],
    "total": 100,
    "page": 1,
    "pageSize": 20
  }
}
```

---

### 4.2 获取候选人详情

获取候选人完整面试报告。

**请求**

- **URL**: `GET /api/candidates/:sessionId`
- **权限**: 需要登录

**请求参数**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| sessionId | string | 是 | 会话 ID（URL 参数） |

**响应示例**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "sessionId": "SESS_1705737600_张三_abc123",
    "name": "张三",
    "resume": "简历内容文本...",
    "status": "completed",
    "currentStage": 60,
    "scores": {
      "salesSkill": 85,
      "salesMindset": 80,
      "quality": 90,
      "motivation": 75
    },
    "analysis": "综合分析报告内容...",
    "interviewLog": "完整对话记录...",
    "createdAt": "2026-01-20T10:00:00+08:00",
    "completedAt": "2026-01-20T10:25:00+08:00"
  }
}
```

---

### 4.3 导出 PDF 报告

导出候选人面试报告为 PDF 文件。

**请求**

- **URL**: `GET /api/candidates/:sessionId/export`
- **权限**: 需要登录

**请求参数**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| sessionId | string | 是 | 会话 ID（URL 参数） |

**响应**

- **Content-Type**: `application/pdf`
- **Content-Disposition**: `attachment; filename="interview_report_张三.pdf"`

---

## 五、Coze API 调用说明

> 以下为后端调用 Coze API 的内部说明

### 5.1 文件上传

```
POST https://api.coze.cn/v1/files/upload
Authorization: Bearer {PAT_TOKEN}
Content-Type: multipart/form-data

Response:
{
  "data": {
    "id": "file_xxx"
  }
}
```

### 5.2 创建语音房间

```
POST https://api.coze.cn/v1/audio/rooms
Authorization: Bearer {PAT_TOKEN}
Content-Type: application/json

Body:
{
  "bot_id": "7595077233002840079",
  "room_id": "room_xxx",
  "user_id": "user_xxx",
  "voice_id": "voice_id_xxx",
  "config": {
    "input_file_id": "file_xxx"
  }
}
```

### 5.3 查询数据库

```
POST https://api.coze.cn/v1/database/query
Authorization: Bearer {PAT_TOKEN}
Content-Type: application/json

Body:
{
  "database_id": "7595077053909712922",
  "filter": {
    "session_id": "SESS_xxx"
  }
}
```

---

## 变更日志

| 日期 | 变更内容 | 操作人 |
|------|---------|--------|
| 2026-01-20 | 初始化 API 文档 | AI |