404 lines
8.6 KiB
Markdown
404 lines
8.6 KiB
Markdown
# 考核模块接口文档
|
||
|
||
## 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<String, Object> params)
|
||
```
|
||
- **参数说明**:
|
||
- `subjectId`: 科目ID（Long）
|
||
- `questionCounts`: 各题型题量（Map<String, Integer>）
|
||
- 键：题型（single/multiple/judge/fill/essay）
|
||
- 值：题量
|
||
- **返回值**: 题目列表（List<StudyQuestion>）
|
||
- **接入方式**: 替换TODO注释处的代码，调用实际AI API
|
||
|
||
### 3.2 AI自动打分API
|
||
- **位置**: `StudyScoreController.submitAnswer()`
|
||
- **函数签名**:
|
||
```java
|
||
public AjaxResult submitAnswer(@RequestBody Map<String, Object> params)
|
||
```
|
||
- **参数说明**:
|
||
- `examId`: 考试ID（Long）
|
||
- `studentAnswers`: 学生答题数据（List<StudyStudentAnswer>）
|
||
- **返回值**: 打分结果（Map<String, Object>）
|
||
```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`: 已评分
|
||
|