xiaozhang/guoyu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
2a816e4abf
guoyu/Test/备份/_已清理文件备份_周六 22512/md/考核模块接口文档.md

404 lines
8.6 KiB
Markdown
Raw Normal View History

修复app语音测评、图标、访问课程等问题
2025-12-10 13:15:26 +08:00
# 考核模块接口文档
## 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`: 已评分
Reference in New Issue Copy Permalink