接口需求清单

1接口总览

模块	接口数	GET	POST	PUT	适用角色
用户认证	4	1	2	1	专家/学员/管理员
课程管理	6	3	2	1	专家/学员/管理员
学习进度	3	2	1	0	学员
在线答疑	4	2	2	0	专家/学员
作业管理	4	2	1	1	专家/学员
考试管理	4	2	2	0	专家/学员
认证管理	2	1	1	0	管理员/学员
管理员功能	3	1	1	1	管理员
文件与视频	2	0	2	0	专家/管理员
合计	32	14	14	4	—

通用约定

API 基础路径：https://api.cancer-training.gov.cn/api/v1
所有接口默认返回 JSON 格式，Content-Type: application/json
鉴权方式：Bearer Token（JWT），有效期 24 小时
分页参数：page（默认1）、page_size（默认20，最大100）
时间格式：ISO 8601（YYYY-MM-DDTHH:mm:ssZ）
语言：zh-CN

2用户认证模块

编号	接口名称	方法	路径	鉴权	角色	说明
API-001	用户登录	POST	/auth/login	否	全部	手机号+密码/验证码登录，返回 token 和用户信息
API-002	获取当前用户信息	GET	/auth/profile	是	全部	获取当前登录用户的详细信息（姓名、角色、所属基地、资质等）
API-003	更新个人信息	PUT	/auth/profile	是	全部	更新头像、联系方式、所属单位等个人信息
API-004	发送验证码	POST	/auth/sms-code	否	全部	向指定手机号发送短信验证码，用于登录或找回密码

API-001 用户登录 - 请求参数

phonestring 必填手机号，11位数字

passwordstring 可选密码（密码登录时必填），MD5加密

sms_codestring 可选短信验证码（验证码登录时必填）

login_typestring 必填登录类型：password / sms

rolestring 必填登录角色：expert / student / admin

API-001 用户登录 - 响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...（JWT Token）",
    "expires_in": 86400,
    "user": {
      "id": "u_100001",
      "name": "张医生",
      "phone": "138****5678",
      "role": "expert",
      "avatar": "https://cdn.../avatar.jpg",
      "hospital": "北京协和医院",
      "department": "肿瘤科",
      "title": "主任医师",
      "base_id": "base_001",
      "base_name": "国家级癌症早诊培训基地"
    }
  }
}

3课程管理模块

编号	接口名称	方法	路径	鉴权	角色	说明
API-005	获取课程列表	GET	/courses	是	全部	分页获取课程列表，支持按分类、难度、状态筛选
API-006	获取课程详情	GET	/courses/:id	是	全部	获取课程详细信息，包括章节列表、讲师信息、学习进度
API-007	创建课程	POST	/courses	是	专家管理员	专家创建新课程，包含基本信息、封面、章节结构
API-008	更新课程	PUT	/courses/:id	是	专家管理员	编辑课程基本信息、章节内容、上架/下架状态
API-009	获取直播课程列表	GET	/courses/live	是	全部	获取直播课程列表，包含直播状态、开播时间、观看人数
API-010	创建直播课	POST	/courses/live	是	专家	专家创建直播课程，设置时间、标题、简介、推流地址

API-005 获取课程列表 - 请求参数

categorystring 可选课程分类：lung / breast / gastric / colorectal / liver / cervical / general

difficultystring 可选难度等级：beginner / intermediate / advanced

statusstring 可选状态：draft / published / archived

keywordstring 可选搜索关键词（课程名称/讲师）

pageint 可选页码，默认 1

page_sizeint 可选每页数量，默认 20，最大 100

sortstring 可选排序方式：newest / popular / progress

4学习进度模块

编号	接口名称	方法	路径	鉴权	角色	说明
API-011	上报学习进度	POST	/learning/progress	是	学员	上报视频观看进度（每30秒上报一次），记录观看时长
API-012	获取我的学习进度	GET	/learning/progress	是	学员	获取当前学员所有课程的学习进度统计
API-013	获取单课学习详情	GET	/learning/progress/:course_id	是	学员	获取指定课程的章节级学习进度明细

API-011 上报学习进度 - 请求参数

course_idstring 必填课程ID

chapter_idstring 必填章节ID

video_idstring 必填视频ID

current_timefloat 必填当前播放位置（秒）

durationfloat 必填视频总时长（秒）

watch_durationint 必填本次累计观看时长（秒）

is_completedboolean 可选是否完成本章节学习，默认 false

5在线答疑模块

编号	接口名称	方法	路径	鉴权	角色	说明
API-014	提交文字提问	POST	/qa/questions	是	学员	学员提交文字问题，支持上传图片附件，关联课程/章节
API-015	获取答疑列表	GET	/qa/questions	是	专家学员	分页获取答疑记录，支持按状态、课程筛选
API-016	获取答疑详情	GET	/qa/questions/:id	是	专家学员	获取问题详情及回复记录（对话形式）
API-017	专家回复问题	POST	/qa/questions/:id/reply	是	专家	专家回复学员问题，支持图文回复，标记问题状态

6作业管理模块

编号	接口名称	方法	路径	鉴权	角色	说明
API-018	发布作业	POST	/assignments	是	专家	专家发布作业，设置题目、截止时间、提交方式（文件/文本）
API-019	获取作业列表	GET	/assignments	是	专家学员	分页获取作业列表，学员视角显示提交状态
API-020	提交作业	POST	/assignments/:id/submit	是	学员	学员提交作业答案，支持文件上传、文本作答
API-021	批改作业	PUT	/assignments/:id/grade	是	专家	专家批改作业，给出分数和评语，标记通过/不通过

7考试管理模块

编号	接口名称	方法	路径	鉴权	角色	说明
API-022	创建考试	POST	/exams	是	专家	专家创建考试，设置题库、时长、及格分数、考试时间
API-023	获取考试列表	GET	/exams	是	专家学员	获取考试列表，包含考试状态、成绩、排名等
API-024	开始考试	POST	/exams/:id/start	是	学员	学员开始考试，获取试题列表，记录开始时间
API-025	提交考试	POST	/exams/:id/submit	是	学员	学员提交答卷，系统自动判分，生成成绩记录

API-025 提交考试 - 响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "exam_id": "exam_001",
    "score": 87,
    "total_score": 100,
    "pass_score": 60,
    "is_passed": true,
    "rank": 23,
    "total_participants": 156,
    "used_time": 3240,
    "correct_count": 44,
    "total_questions": 50,
    "details": [
      {"question_id": "q_001", "is_correct": true, "user_answer": "B", "correct_answer": "B"}
    ]
  }
}

8认证管理模块

编号	接口名称	方法	路径	鉴权	角色	说明
API-026	申请认证证书	POST	/certifications/apply	是	学员	满足条件的学员申请认证证书，系统校验学习完成度和考试成绩
API-027	获取证书详情	GET	/certifications/:id	是	全部	获取认证证书详情，含证书编号、电子签章、验证链接

9管理员模块

编号	接口名称	方法	路径	鉴权	角色	说明
API-028	用户管理（专家/学员）	GET	/admin/users	是	管理员	分页获取用户列表，支持按角色、基地、状态筛选和搜索
API-029	审核专家入驻	POST	/admin/experts/:id/audit	是	管理员	管理员审核专家入驻申请，通过/拒绝并填写原因
API-030	培训基地管理	PUT	/admin/bases/:id	是	管理员	管理各级培训基地信息，增删改查基地配置和关联人员

10文件与视频模块

编号	接口名称	方法	路径	鉴权	角色	说明
API-031	文件上传	POST	/files/upload	是	专家管理员	上传图片/文档/作业附件，支持分片上传，返回文件URL和ID
API-032	视频上传初始化	POST	/videos/init-upload	是	专家	初始化视频上传，获取分片上传地址和上传凭证

API-032 视频上传初始化 - 响应示例

{
  "code": 0,
  "data": {
    "video_id": "vid_abc123",
    "upload_url": "https://vod.example.com/upload/vid_abc123",
    "chunk_size": 5242880,
    "total_chunks": 24,
    "upload_token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_at": "YYYY-MM-DDTHH:MM:SSZ"
  }
}

11WebSocket 事件

连接地址：wss://api.cancer-training.gov.cn/ws
鉴权方式：URL 参数携带 token，即 wss://.../ws?token={jwt_token}
心跳间隔：30秒

事件名称	方向	触发场景	数据结构	角色
live_qa_join	Client → Server	用户进入直播答疑房间	{ room_id, user_id, user_name, role }	专家学员
live_qa_message	Bidirectional	发送/接收实时答疑消息	{ room_id, user_id, user_name, role, content, type, timestamp }	专家学员
live_qa_status	Server → Client	直播状态变更（开始/结束/人数变更）	{ room_id, status, viewer_count, duration }	专家学员

消息类型 type 枚举

text纯文本消息

image图片消息，content 为图片 URL

system系统消息（如加入/离开提示）

question学员提问消息（带问题标识）

answer专家解答消息（带解答标识）

12标准错误码

错误码	HTTP状态	说明	处理建议
0	200	成功	正常处理响应数据
40001	400	参数错误	检查请求参数格式和必填项
40002	400	参数校验失败	根据返回的 field 信息修正参数
40101	401	未登录或 Token 无效	引导用户重新登录
40102	401	Token 已过期	使用 refresh_token 刷新或重新登录
40301	403	权限不足	当前角色无此操作权限
40302	403	账号已被禁用	联系管理员解封
40401	404	资源不存在	检查资源 ID 是否正确
40901	409	资源冲突	如重复提交、已存在等
42901	429	请求过于频繁	降低请求频率，遵守限流规则
50001	500	服务器内部错误	稍后重试，如持续请反馈
50002	500	第三方服务异常	如短信、视频服务等不可用
60001	200	验证码错误	重新获取并输入验证码
60002	200	用户名或密码错误	检查输入或找回密码
70001	200	考试已提交	不可重复提交
70002	200	考试时间已结束	考试超时自动提交
70003	200	不满足认证条件	检查学习进度和考试成绩
80001	200	文件格式不支持	检查文件格式是否在允许列表中
80002	200	文件大小超限	压缩文件后重新上传

统一响应格式

{
  "code": 0,           // 0=成功，非0=错误码
  "message": "success",  // 状态描述
  "data": {},           // 响应数据（成功时返回）
  "request_id": "xxx"   // 请求追踪ID，排错使用
}

目录