011-ai-interview/docs/api/endpoints.md

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 响应格式

成功响应：

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

错误响应：

{
  "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

响应示例

{
  "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

请求参数

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

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

响应示例

{
  "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 参数）

响应示例

{
  "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

响应示例

{
  "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 参数）

响应示例

{
  "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