359 lines
6.3 KiB
Markdown
359 lines
6.3 KiB
Markdown
# 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 |
|