Initial commit: AI Interview System
This commit is contained in:
111
358
docs/api/endpoints.md
Normal file
358
docs/api/endpoints.md
Normal file
@@ -0,0 +1,358 @@
|
||||
# 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 |
|
||||
Reference in New Issue
Block a user