xiaozhang/guoyu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
1a2826bfcc
guoyu/log/考核模块接口文档.md

8.6 KiB
Raw Blame History

考核模块接口文档

1. 考试管理接口

1.1 查询考试列表

  • 接口URL: /study/exam/list
  • 请求方式: GET
  • 权限要求: study:exam:list
  • 请求参数: 
    {
  "pageNum": 1,
  "pageSize": 10,
  "examName": "考试名称（可选）",
  "subjectId": "科目ID（可选）",
  "status": "状态（0-草稿，1-已发布，2-已结束，可选）"
}
  • 响应示例: 
    {
  "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
  • 响应示例: 
    {
  "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
  • 权限要求: 无（学生端）
  • 响应示例: 
    {
  "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
  • 请求参数: 
    {
  "examName": "数学期中考试",
  "subjectId": 1,
  "duration": 120,
  "totalScore": 100.0
}
  • 响应示例: 
    {
  "code": 200,
  "msg": "操作成功"
}

1.5 修改考试

  • 接口URL: /study/exam
  • 请求方式: PUT
  • 权限要求: study:exam:edit
  • 请求参数: 同新增考试

1.6 删除考试

  • 接口URL: /study/exam/{ids}
  • 请求方式: DELETE
  • 权限要求: study:exam:remove
  • 响应示例: 
    {
  "code": 200,
  "msg": "操作成功"
}

1.7 发布考试

  • 接口URL: /study/exam/publish/{id}
  • 请求方式: PUT
  • 权限要求: study:exam:edit
  • 响应示例: 
    {
  "code": 200,
  "msg": "操作成功"
}

1.8 AI生成题目

  • 接口URL: /study/exam/ai/generate-questions
  • 请求方式: POST
  • 权限要求: study:exam:edit
  • 请求参数: 
    {
  "subjectId": 1,
  "questionCounts": {
    "single": 10,
    "multiple": 5,
    "judge": 5,
    "fill": 3,
    "essay": 2
  }
}
  • 响应示例: 
    {
  "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
  • 请求参数: 
    [
  {
    "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
  • 请求参数: 
    {
  "pageNum": 1,
  "pageSize": 10,
  "examId": "考试ID（可选）",
  "studentId": "学生ID（可选）",
  "status": "状态（可选）"
}
  • 响应示例: 
    {
  "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
  • 权限要求: 无
  • 响应示例: 
    {
  "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
  • 权限要求: 无（学生端）
  • 请求参数: 
    {
  "examId": 1,
  "answers": [
    {
      "questionId": 1,
      "answer": "2"
    },
    {
      "questionId": 2,
      "answer": "A,B"
    }
  ],
  "duration": 115
}
  • 响应示例: 
    {
  "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()
  • 函数签名: 
    public AjaxResult generateQuestionsByAI(@RequestBody Map<String, Object> params)
  • 参数说明:
    • subjectId: 科目ID（Long）
    • questionCounts: 各题型题量（Map<String, Integer>）
      • 键：题型（single/multiple/judge/fill/essay）
      • 值：题量
  • 返回值: 题目列表（List）
  • 接入方式: 替换TODO注释处的代码，调用实际AI API

3.2 AI自动打分API

  • 位置: StudyScoreController.submitAnswer()
  • 函数签名: 
    public AjaxResult submitAnswer(@RequestBody Map<String, Object> params)
  • 参数说明:
    • examId: 考试ID（Long）
    • studentAnswers: 学生答题数据（List）
  • 返回值: 打分结果（Map<String, Object>） 
    {
  "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: 已评分