API接口目录
👨‍🎓 学生端API
15个接口
👨‍🏫 教师端API
35个接口
⚙️ 管理端API
8个接口
🔐 认证API
4个接口
📦 公共API
6个接口
API设计规范

基础信息

  • Base URL: https://api.reading-platform.com/v1
  • 认证方式: JWT Bearer Token
  • 请求格式: JSON
  • 响应格式: JSON
  • 字符编码: UTF-8

学生端API特点

  • 不返回具体分数，只返回等级和进度
  • 极简响应数据，减少学生认知负担
  • 错误提示友好，适合儿童理解
  • 所有接口需要学生权限
👨‍🎓
学生端API（15个接口）
极简设计，无分数显示，专注阅读体验
学生端API设计原则：
  • 所有响应数据不包含分数、百分比等量化指标
  • 使用等级（Level 1-8）和进度条（progress: 0.7）代替分数
  • 正确率转换为星级（⭐⭐⭐⭐⭐）或简单等级（Excellent/Good/Try Again）
  • 积分系统用于激励，但不在学生端显示排名
方法 端点 页面 功能说明 操作
GET /api/student/profileJWT 学生首页 获取学生个人信息、当前等级、积分总数
请求参数：无
响应示例：
{ "studentId": "STU001", "name": "张小明", "grade": "3", "currentLevel": 3, "levelName": "Emerging Reader", "totalPoints": 245, "avatar": "avatar_001.png", "progress": 0.75 }
GET /api/student/statsJWT 学生首页 获取学习统计数据（已完成书籍数、本月活动等）
响应示例：
{ "booksCompleted": 12, "quizzesTaken": 15, "currentStreak": 7, "monthActivity": "⭐⭐⭐⭐" }
GET /api/content/searchJWT 图书搜索 搜索图书和文章内容（支持中文分词）
请求参数：
keyword string 搜索关键词（支持IK中文分词）
level number 内容等级（1-8）
type string 类型：fiction/nonfiction
page number 页码（默认1）
size number 每页数量（默认20）
响应示例：
{ "total": 156, "page": 1, "size": 20, "items": [ { "id": "CONTENT001", "title": "小猫钓鱼", "level": 2, "type": "fiction", "author": "未知", "coverImage": "cover_001.jpg", "wordCount": 500, "avgRating": 4.5 } ] }
GET /api/content/listJWT 图书搜索 获取推荐内容列表（按等级、分类筛选）
GET /api/content/{id}JWT 图书搜索 获取内容详情（标题、正文、作者、等级等）
GET /api/audio/{contentId}JWT 选择练习方式 获取音频文件URL（听故事模式）
GET /api/quiz/typesJWT 选择练习方式 获取支持的测验类型（听故事、阅读理解、词汇练习）
GET /api/quiz/{quizId}/questionsJWT 测验答题 获取测验题目列表（不返回正确答案）
POST /api/quiz/session/startJWT 测验答题 开始测验会话，返回sessionId
请求参数：
{ "contentId": "CONTENT001", "quizType": "listening", "studentId": "STU001" }
响应示例：
{ "sessionId": "SESSION20240101001", "startTime": "2024-01-01T10:00:00Z", "totalQuestions": 10, "estimatedTime": 15 }
POST /api/quiz/session/answerJWT 测验答题 提交单个题目答案
POST /api/quiz/session/submitJWT 测验答题 提交整个测验，返回结果摘要（无分数）
响应示例（学生端，无分数）：
{ "sessionId": "SESSION20240101001", "result": "Good", "stars": 4, "pointsEarned": 15, "correctCount": 8, "totalCount": 10, "message": "做得很好！继续加油！" }
注意：学生端API不返回correctRate、percentage等量化指标，只返回result等级和星星数
POST /api/rating/createJWT 书籍评分 为书籍评分（1-5星）
POST /api/comment/createJWT 书籍评分 添加书籍评论
GET /api/quiz/session/{sessionId}/resultJWT 测验结果 获取测验结果摘要（不显示分数）
GET /api/quiz/session/{sessionId}/detailsJWT 测验结果 获取答题详情回顾
GET /api/student/levelJWT 我的进度 获取学生当前等级信息
响应示例：
{ "currentLevel": 3, "levelName": "Emerging Reader", "nextLevel": 4, "nextLevelName": "Developing Reader", "progress": 0.75, "pointsToNextLevel": 55 }
GET /api/student/progressJWT 我的进度 获取学习进度条（不显示百分比）
GET /api/student/historyJWT 我的进度 获取完成的书籍历史列表
👨‍🏫
教师端API（35个接口）
完整的班级管理、内容管理、报表分析功能
教师端API权限：需要教师或管理员权限，所有请求需携带有效的JWT Token。教师只能访问自己班级的数据，管理员可以访问全校数据。

班级管理API（5个）

方法 端点 页面 功能说明 操作
GET /api/teacher/classesJWT 记录书首页 获取教师管理的班级列表
GET /api/class/{classId}/studentsJWT 记录书首页 获取班级学生列表
GET /api/class/{classId}/goalsJWT 记录书首页 获取班级阅读目标
GET /api/class/{classId}/quizzesJWT 记录书首页 获取班级测验记录列表
GET /api/class/{classId}/certificationsJWT 记录书首页 获取班级证书进度列表

目标设定API（6个）

方法 端点 页面 功能说明 操作
GET /api/goals/modelsJWT 阅读目标设定 获取可用目标模型（K-2徽章制/3-5积分制/6+综合制）
响应示例：
{ "models": [ { "id": "K-2", "name": "K-2徽章制", "description": "适合K-2年级，以徽章激励为主", "features": ["badges", "stars", "rewards"] }, { "id": "3-5", "name": "3-5积分制", "description": "适合3-5年级，设置正确率和积分目标", "features": ["accuracy", "points", "range"] }, { "id": "6+", "name": "6+综合制", "description": "适合6年级以上，综合目标体系", "features": ["accuracy", "points", "range", "certificates"] } ] }
GET /api/class/{classId}/goals/currentJWT 阅读目标设定 获取班级当前阅读目标
POST /api/class/{classId}/goals/createJWT 阅读目标设定 创建班级阅读目标
请求参数：
{ "modelId": "3-5", "targetAccuracy": 85, "targetPoints": 50, "readingRange": { "minLevel": 2, "maxLevel": 5 }, "semester": "2024-Spring" }
PUT /api/class/{classId}/goals/updateJWT 阅读目标设定 更新班级阅读目标
GET /api/certifications/listJWT 证书目标设定 获取证书等级列表（Ready Reader到Honors Reader）
GET /api/student/{studentId}/certificationJWT 证书目标设定 获取学生当前证书进度
POST /api/student/certification/setJWT 证书目标设定 为学生设定证书目标
PUT /api/student/certification/updateJWT 证书目标设定 更新学生证书目标

内容管理API（8个）

方法 端点 页面 功能说明 操作
POST /api/content/createJWT 录入新内容 创建新内容（第一步：定义测验详情）
请求参数：
{ "title": "小猫钓鱼", "type": "fiction", "level": 2, "category": "story", "language": "zh-CN", "wordCount": 500, "content": "从前有一只小猫..." }
POST /api/content/quiz/createJWT 录入新内容 创建测验（第二步：编写题目）
POST /api/content/question/createJWT 录入新内容 添加单个题目到测验
POST /api/content/submit-reviewJWT 录入新内容 提交内容审核（第三步：提交审核）
POST /api/content/audio/uploadJWT 录入新内容 上传音频文件（听故事模式）
GET /api/teacher/content/listJWT 管理内容列表 获取教师创建的内容列表
GET /api/content/{id}/statusJWT 管理内容列表 获取内容审核状态
PUT /api/content/{id}/updateJWT 管理内容列表 更新内容信息
DELETE /api/content/{id}JWT 管理内容列表 删除内容
PUT /api/content/{id}/withdrawJWT 管理内容列表 下架内容

报表API（11个）

方法 端点 页面 功能说明 操作
GET /api/report/class/overviewJWT 报表中心 获取班级概况数据
GET /api/report/content/statsJWT 报表中心 获取内容统计数据
GET /api/report/level/progressJWT 报表中心 获取等级进度数据
POST /api/report/diagnostic/generateJWT 综合诊断报告 生成综合诊断报告
请求参数：
{ "classId": "CLASS001", "grade": "3", "dateRange": { "start": "2024-01-01", "end": "2024-12-31" } }
响应示例：
{ "grade": "3", "totalStudents": 28, "below85Percent": "14%", "avgCorrectRate": "87%", "avgDifficultyLevel": 3.2, "totalPoints": 1450, "summary": "三年级整体表现良好..." }
GET /api/report/diagnostic/dataJWT 综合诊断报告 获取已生成的诊断报告数据
POST /api/report/student-performance/generateJWT 学生表现记录 生成学生表现记录报告
GET /api/student/{studentId}/quiz-historyJWT 学生表现记录 获取学生测验历史记录
POST /api/report/schoolwide/generateJWT 学校综合报告 生成学校综合报告
GET /api/report/schoolwide/dataJWT 学校综合报告 获取学校综合报告数据
POST /api/report/twi/generateJWT TWI报告 生成TWI（Read To/With/Independently）报告
GET /api/report/twi/dataJWT TWI报告 获取TWI报告数据
POST /api/report/marking-period/generateJWT 学期进度报告 生成学期进度报告
GET /api/report/marking-period/dataJWT 学期进度报告 获取学期进度报告数据

实时监控API（4个）

方法 端点 页面 功能说明 操作
GET /api/monitor/class/{classId}/realtimeJWT 实时监控 获取班级实时状态（WebSocket实时推送）
GET /api/monitor/class/{classId}/warningsJWT 实时监控 获取预警学生列表
GET /api/monitor/class/{classId}/heatmapJWT 实时监控 获取班级活动热力图数据
POST /api/monitor/alert/createJWT 实时监控 创建预警提醒
⚙️
管理端API（8个接口）
内容审核、教师管理、系统配置
管理端API权限：仅限管理员角色访问，所有请求需携带管理员JWT Token。管理员可以访问全校数据、审核内容、管理教师账号。
方法 端点 页面 功能说明 操作
GET /api/admin/statsJWT 管理首页 获取平台统计数据
GET /api/admin/content/pendingJWT 管理首页 获取待审核内容列表
GET /api/admin/teachers/listJWT 管理首页 获取教师列表
GET /api/admin/content/{id}JWT 内容审核 获取内容详情（审核用）
GET /api/admin/content/{id}/quizJWT 内容审核 获取内容关联的测验题目
POST /api/admin/content/{id}/approveJWT 内容审核 批准内容发布
POST /api/admin/content/{id}/rejectJWT 内容审核 拒绝内容发布
请求参数：
{ "reason": "内容不符合分级标准", "feedback": "建议调整难度等级至Level 3" }
POST /api/admin/teacher/createJWT 管理页面 创建教师账号
🔐
认证API（4个接口）
用户登录、注册、Token管理
方法 端点 页面 功能说明 操作
POST /api/auth/login 登录页 用户登录，返回JWT Token
请求参数：
{ "username": "student001", "password": "password123", "role": "student" }
响应示例：
{ "success": true, "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "refreshToken": "refresh_token_here", "expiresIn": 3600, "user": { "id": "STU001", "username": "student001", "role": "student", "name": "张小明" } }
POST /api/auth/register 注册页 用户注册（学生注册需教师邀请码）
POST /api/auth/refresh 全局 刷新JWT Token
POST /api/auth/logoutJWT 全局 用户登出
📦
公共API（6个接口）
无需认证或低权限接口
方法 端点 页面 功能说明 操作
GET /api/common/levels 全局 获取阅读等级列表
响应示例：
{ "levels": [ {"id": 1, "name": "Ready Reader", "description": "初级读者"}, {"id": 2, "name": "Emerging Reader", "description": "新兴读者"}, {"id": 3, "name": "Developing Reader", "description": "发展中读者"}, {"id": 4, "name": "Transitional Reader", "description": "过渡期读者"}, {"id": 5, "name": "Fluent Reader", "description": "流利读者"}, {"id": 6, "name": "Proficient Reader", "description": "熟练读者"}, {"id": 7, "name": "Advanced Reader", "description": "高级读者"}, {"id": 8, "name": "Honors Reader", "description": "荣誉读者"} ] }
GET /api/common/categories 全局 获取内容分类列表
GET /api/common/certifications 全局 获取证书等级列表
GET /api/common/content-types 全局 获取内容类型列表（fiction/nonfiction）
GET /api/common/quiz-types 全局 获取测验类型列表（listening/reading/vocabulary）
GET /api/health 系统监控 系统健康检查
HTTP状态码与错误码

HTTP状态码

  • 200 OK - 请求成功
  • 201 Created - 资源创建成功
  • 400 Bad Request - 请求参数错误
  • 401 Unauthorized - 未认证或Token失效
  • 403 Forbidden - 无权限访问
  • 404 Not Found - 资源不存在
  • 500 Internal Server Error - 服务器错误

业务错误码

  • 1001 - 用户不存在
  • 1002 - 密码错误
  • 1003 - Token已过期
  • 2001 - 内容不存在
  • 2002 - 内容未发布
  • 3001 - 测验未完成
  • 3002 - 测验已过期