# 考核模块接口文档 ## 1. 考试管理接口 ### 1.1 查询考试列表 - **接口URL**: `/study/exam/list` - **请求方式**: `GET` - **权限要求**: `study:exam:list` - **请求参数**: ```json { "pageNum": 1, "pageSize": 10, "examName": "考试名称（可选）", "subjectId": "科目ID（可选）", "status": "状态（0-草稿，1-已发布，2-已结束，可选）" } ``` - **响应示例**: ```json { "code": 200, "msg": "操作成功", "rows": [ { "id": 1, "examName": "数学期中考试", "subjectId": 1, "subjectName": "数学", "questionCount": 20, "duration": 120, "totalScore": 100.0, "status": "1", "publishTime": "2024-01-01 10:00:00", "createTime": "2024-01-01 09:00:00" } ], "total": 1 } ``` ### 1.2 查询考试详情 - **接口URL**: `/study/exam/{id}` - **请求方式**: `GET` - **权限要求**: `study:exam:query` - **响应示例**: ```json { "code": 200, "msg": "操作成功", "data": { "id": 1, "examName": "数学期中考试", "subjectId": 1, "subjectName": "数学", "questionCount": 20, "duration": 120, "totalScore": 100.0, "status": "1", "questions": [ { "id": 1, "questionType": "single", "questionContent": "1+1等于多少？", "options": "[\"1\", \"2\", \"3\", \"4\"]", "correctAnswer": "2", "score": 5.0 } ] } } ``` ### 1.3 获取考试题目（学生端） - **接口URL**: `/study/exam/{id}/questions` - **请求方式**: `GET` - **权限要求**: 无（学生端） - **响应示例**: ```json { "code": 200, "msg": "操作成功", "data": { "exam": { "id": 1, "examName": "数学期中考试", "subjectName": "数学", "duration": 120, "totalScore": 100.0 }, "questions": [ { "id": 1, "questionType": "single", "questionContent": "1+1等于多少？", "options": "[\"1\", \"2\", \"3\", \"4\"]", "score": 5.0 } ] } } ``` - **说明**: 此接口不返回正确答案，仅用于学生答题 ### 1.4 新增考试 - **接口URL**: `/study/exam` - **请求方式**: `POST` - **权限要求**: `study:exam:add` - **请求参数**: ```json { "examName": "数学期中考试", "subjectId": 1, "duration": 120, "totalScore": 100.0 } ``` - **响应示例**: ```json { "code": 200, "msg": "操作成功" } ``` ### 1.5 修改考试 - **接口URL**: `/study/exam` - **请求方式**: `PUT` - **权限要求**: `study:exam:edit` - **请求参数**: 同新增考试 ### 1.6 删除考试 - **接口URL**: `/study/exam/{ids}` - **请求方式**: `DELETE` - **权限要求**: `study:exam:remove` - **响应示例**: ```json { "code": 200, "msg": "操作成功" } ``` ### 1.7 发布考试 - **接口URL**: `/study/exam/publish/{id}` - **请求方式**: `PUT` - **权限要求**: `study:exam:edit` - **响应示例**: ```json { "code": 200, "msg": "操作成功" } ``` ### 1.8 AI生成题目 - **接口URL**: `/study/exam/ai/generate-questions` - **请求方式**: `POST` - **权限要求**: `study:exam:edit` - **请求参数**: ```json { "subjectId": 1, "questionCounts": { "single": 10, "multiple": 5, "judge": 5, "fill": 3, "essay": 2 } } ``` - **响应示例**: ```json { "code": 200, "msg": "操作成功", "data": [ { "questionType": "single", "questionContent": "1+1等于多少？", "options": "[\"1\", \"2\", \"3\", \"4\"]", "correctAnswer": "2", "score": 5.0 } ] } ``` - **说明**: 此处接入AI题目生成API，需要替换为实际API地址 ### 1.9 保存题目 - **接口URL**: `/study/exam/{examId}/questions` - **请求方式**: `POST` - **权限要求**: `study:exam:edit` - **请求参数**: ```json [ { "questionType": "single", "questionContent": "1+1等于多少？", "options": "[\"1\", \"2\", \"3\", \"4\"]", "correctAnswer": "2", "score": 5.0, "sortOrder": 1 } ] ``` ## 2. 成绩管理接口 ### 2.1 查询成绩列表 - **接口URL**: `/study/score/list` - **请求方式**: `GET` - **权限要求**: `study:score:list` - **请求参数**: ```json { "pageNum": 1, "pageSize": 10, "examId": "考试ID（可选）", "studentId": "学生ID（可选）", "status": "状态（可选）" } ``` - **响应示例**: ```json { "code": 200, "msg": "操作成功", "rows": [ { "id": 1, "examId": 1, "examName": "数学期中考试", "studentId": 100, "studentName": "张三", "studentNo": "2024001", "totalScore": 100.0, "obtainedScore": 85.0, "submitTime": "2024-01-01 12:00:00", "duration": 115, "status": "2" } ], "total": 1 } ``` ### 2.2 查询成绩详情 - **接口URL**: `/study/score/{id}` - **请求方式**: `GET` - **权限要求**: 无 - **响应示例**: ```json { "code": 200, "msg": "操作成功", "data": { "id": 1, "examId": 1, "examName": "数学期中考试", "studentId": 100, "studentName": "张三", "totalScore": 100.0, "obtainedScore": 85.0, "submitTime": "2024-01-01 12:00:00", "duration": 115, "status": "2", "answerDetails": [ { "id": 1, "questionId": 1, "questionContent": "1+1等于多少？", "studentAnswer": "2", "correctAnswer": "2", "isCorrect": "1", "score": 5.0, "questionScore": 5.0 } ] } } ``` ### 2.3 获取当前学生的成绩列表 - **接口URL**: `/study/score/my-scores` - **请求方式**: `GET` - **权限要求**: 无（学生端） - **响应示例**: 同查询成绩列表 ### 2.4 提交答题结果 - **接口URL**: `/study/score/submit` - **请求方式**: `POST` - **权限要求**: 无（学生端） - **请求参数**: ```json { "examId": 1, "answers": [ { "questionId": 1, "answer": "2" }, { "questionId": 2, "answer": "A,B" } ], "duration": 115 } ``` - **响应示例**: ```json { "code": 200, "msg": "操作成功", "data": { "totalScore": 100.0, "obtainedScore": 85.0, "answerDetails": [ { "questionId": 1, "isCorrect": "1", "score": 5.0 } ] } } ``` - **说明**: 此处接入AI自动打分API，需要替换为实际API地址 ## 3. AI API 接入点说明 ### 3.1 AI题目生成API - **位置**: `StudyExamController.generateQuestionsByAI()` - **函数签名**: ```java public AjaxResult generateQuestionsByAI(@RequestBody Map params) ``` - **参数说明**: - `subjectId`: 科目ID（Long） - `questionCounts`: 各题型题量（Map） - 键：题型（single/multiple/judge/fill/essay） - 值：题量 - **返回值**: 题目列表（List） - **接入方式**: 替换TODO注释处的代码，调用实际AI API ### 3.2 AI自动打分API - **位置**: `StudyScoreController.submitAnswer()` - **函数签名**: ```java public AjaxResult submitAnswer(@RequestBody Map params) ``` - **参数说明**: - `examId`: 考试ID（Long） - `studentAnswers`: 学生答题数据（List） - **返回值**: 打分结果（Map） ```json { "totalScore": 100.0, "obtainedScore": 85.0, "answerDetails": [ { "questionId": 1, "isCorrect": "1", "score": 5.0 } ] } ``` - **接入方式**: 替换TODO注释处的代码，调用实际AI API ## 4. 错误码说明 | 错误码 | 说明 | |--------|------| | 200 | 操作成功 | | 401 | 未登录或登录已过期 | | 403 | 无权限访问 | | 500 | 服务器内部错误 | ## 5. 题型说明 | 题型代码 | 说明 | 选项格式 | |---------|------|---------| | single | 单选题 | JSON数组，如：["选项A", "选项B", "选项C", "选项D"] | | multiple | 多选题 | JSON数组，答案用逗号分隔，如："A,B" | | judge | 判断题 | 答案："正确" 或 "错误" | | fill | 填空题 | 文本答案 | | essay | 简答题 | 文本答案 | ## 6. 状态说明 ### 考试状态 - `0`: 草稿 - `1`: 已发布 - `2`: 已结束 ### 成绩状态 - `0`: 未提交 - `1`: 已提交 - `2`: 已评分