OL-LearnPlatform-Frontend/docs/ExamInfo-API-Usage.md

524 lines
13 KiB
Markdown
Raw Normal View History

# 考试信息API使用文档
## 接口概述
`/aiol/aiolExam/getExamInfo` 接口用于获取教师名下的考试信息列表。
## 接口定义
### 请求方式
- **方法**: GET
- **路径**: `/aiol/aiolExam/getExamInfo`
- **参数**: `userId` (查询参数)
### 请求参数
| 参数名 | 类型 | 必选 | 说明 |
|--------|------|------|------|
| userId | string | 是 | 教师用户ID |
### 响应格式
```typescript
{
"success": boolean,
"message": string,
"code": number,
"result": ExamInfo[],
"timestamp": number
}
```
### ExamInfo 数据结构
```typescript
interface ExamInfo {
id: string // 考试ID
name: string // 考试名称
paperId: string // 试卷ID
startTime: string // 开始时间
endTime: string // 结束时间
totalTime: number // 考试时长(分钟)
type: number // 考试类型0=练习1=考试
status: number // 状态0=未发布1=发布中2=已结束
createBy: string // 创建人
createTime: string // 创建时间
updateBy: string // 更新人
updateTime: string // 更新时间
}
```
## 使用示例
### 1. 在API模块中调用
```typescript
import { ExamApi } from '@/api/modules/exam'
// 获取教师考试信息
const response = await ExamApi.getExamInfo('teacher_user_id')
console.log('考试信息:', response.data)
```
### 2. 在Vue组件中使用
```typescript
import { ExamApi } from '@/api/modules/exam'
import { useUserStore } from '@/stores/user'
export default {
setup() {
const userStore = useUserStore()
const loadExamInfo = async () => {
if (!userStore.user?.id) {
console.error('请先登录')
return
}
try {
const response = await ExamApi.getExamInfo(userStore.user.id.toString())
return response.data || []
} catch (error) {
console.error('加载考试信息失败:', error)
return []
}
}
return {
loadExamInfo
}
}
}
```
### 3. 在试卷管理页面中使用
```typescript
// 在 ExamLibrary.vue 中
import { ExamApi } from '@/api/modules/exam'
import { useUserStore } from '@/stores/user'
import type { ExamInfo } from '@/api/types'
const userStore = useUserStore()
const loadExamInfo = async () => {
loading.value = true
try {
const currentUser = userStore.user
if (!currentUser?.id) {
message.error('请先登录')
return
}
const response = await ExamApi.getExamInfo(currentUser.id.toString())
if (response.data && Array.isArray(response.data)) {
// 数据映射和显示逻辑
const mappedList = response.data.map((item: ExamInfo) => {
// 映射逻辑...
return {
id: item.id,
name: item.name,
// ... 其他字段映射
}
})
examData.value = mappedList
}
} catch (error) {
console.error('加载考试信息失败:', error)
message.error('加载考试信息失败')
} finally {
loading.value = false
}
}
```
## 数据映射说明
### 状态映射
```typescript
const statusMap: { [key: number]: string } = {
0: '未发布',
1: '发布中',
2: '已结束'
}
```
### 类型映射
```typescript
const categoryMap: { [key: number]: string } = {
0: '练习',
1: '考试'
}
```
### 难度映射
```typescript
const difficultyMap: { [key: number]: string } = {
0: '易',
1: '中',
2: '难'
}
```
## 错误处理
接口可能返回以下错误:
1. **401 Unauthorized**: 用户未登录或token过期
2. **403 Forbidden**: 没有权限访问
3. **500 Internal Server Error**: 服务器内部错误
建议在调用时添加适当的错误处理:
```typescript
try {
const response = await ExamApi.getExamInfo(userId)
// 处理成功响应
} catch (error) {
if (error.response?.status === 401) {
// 处理认证错误
console.error('登录已过期,请重新登录')
} else {
// 处理其他错误
console.error('获取考试信息失败:', error.message)
}
}
```
## 注意事项
1. 调用此接口前需要确保用户已登录
2. 只有教师用户才能调用此接口
3. 返回的考试信息按创建时间倒序排列
4. 建议在组件挂载时调用此接口加载数据
5. 可以根据需要添加分页、搜索等参数(需要后端支持)
## 相关文件
- API实现: `src/api/modules/exam.ts`
- 类型定义: `src/api/types.ts`
- 使用示例: `src/api/examples/getExamInfo-example.ts`
- 页面实现: `src/views/teacher/ExamPages/ExamLibrary.vue`
---
# 创建试卷API使用文档
## 接口概述
`POST /aiol/aiolPaper/add` 接口用于创建新的试卷。
## 接口定义
### 请求方式
- **方法**: POST
- **路径**: `/aiol/aiolPaper/add`
- **Content-Type**: `application/json`
### 请求参数
| 参数名 | 类型 | 必选 | 说明 |
|--------|------|------|------|
| title | string | 是 | 试卷标题 |
| generateMode | number | 否 | 组卷模式0=固定试卷组1=随机抽题组卷 |
| rules | string | 否 | 组卷规则(随机抽题时使用) |
| repoId | string | 否 | 题库ID随机抽题时使用 |
| totalScore | number | 是 | 试卷总分 |
| passScore | number | 否 | 及格分数默认总分的60% |
| requireReview | number | 否 | 是否需要批阅0=不需要1=需要 |
### 响应格式
```typescript
{
"success": boolean,
"message": string,
"code": number,
"result": string, // 试卷ID
"timestamp": number
}
```
## 使用示例
### 1. 在API模块中调用
```typescript
import { ExamApi } from '@/api/modules/exam'
// 创建固定试卷组
const response = await ExamApi.createExamPaper({
title: '数学期末考试试卷',
generateMode: 0,
totalScore: 100,
passScore: 60,
requireReview: 0
})
console.log('试卷ID:', response.data)
```
### 2. 在Vue组件中使用
```typescript
// 在 AddExam.vue 中
const saveExam = async () => {
try {
const apiData = {
title: examForm.title,
generateMode: examForm.type === 1 ? 0 : 1,
rules: '',
repoId: '',
totalScore: examForm.totalScore,
passScore: examForm.passScore || Math.floor(examForm.totalScore * 0.6),
requireReview: examForm.useAIGrading ? 1 : 0
}
const response = await ExamApi.createExamPaper(apiData)
console.log('创建试卷成功:', response.data)
} catch (error) {
console.error('创建试卷失败:', error)
}
}
```
### 3. 不同组卷模式示例
```typescript
// 固定试卷组
const fixedPaper = {
title: '固定试卷组示例',
generateMode: 0,
rules: '',
repoId: '',
totalScore: 100,
passScore: 60,
requireReview: 0
}
// 随机抽题组卷
const randomPaper = {
title: '随机抽题组卷示例',
generateMode: 1,
rules: '{"difficulty": [1, 2, 3], "types": [0, 1, 2], "count": 20}',
repoId: 'repo_123',
totalScore: 100,
passScore: 60,
requireReview: 1
}
```
## 相关文件
- API实现: `src/api/modules/exam.ts`
- 页面实现: `src/views/teacher/ExamPages/AddExam.vue`
- 使用示例: `src/api/examples/createPaper-example.ts`
---
# 删除试卷API使用文档
## 接口概述
删除试卷相关的API接口包括单个删除和批量删除功能。
## 接口定义
### 1. 删除单个试卷
- **方法**: DELETE
- **路径**: `/aiol/aiolPaper/delete?id={paperId}`
- **参数**: `id` (查询参数) - 试卷ID
### 2. 批量删除试卷
- **实现方式**: 循环调用单个删除接口(因为后端可能不支持批量删除接口)
- **方法**: 内部调用多个 `DELETE /aiol/aiolPaper/delete?id={paperId}`
- **参数**: `ids: string[]` - 试卷ID数组
### 响应格式
**单个删除响应**:
```typescript
{
"success": boolean,
"message": string,
"code": number,
"result": string,
"timestamp": number
}
```
**批量删除响应**:
```typescript
{
"success": boolean,
"message": string,
"code": number,
"result": {
"success": number, // 成功删除的数量
"failed": number, // 失败删除的数量
"total": number, // 总数量
"errors": string[] // 错误信息数组
},
"timestamp": number
}
```
## 使用示例
### 1. 删除单个试卷
```typescript
import { ExamApi } from '@/api/modules/exam'
// 删除单个试卷
const response = await ExamApi.deleteExamPaper('1962379646322384897')
console.log('删除结果:', response.data)
```
### 2. 批量删除试卷
```typescript
// 批量删除试卷
const paperIds = ['1962379646322384897', '1966450638717292545']
const response = await ExamApi.batchDeleteExamPapers(paperIds)
console.log('批量删除结果:', response.data)
```
### 3. 在Vue组件中使用使用 Naive UI 对话框组件)
```typescript
// 在 ExamLibrary.vue 中
import { useDialog, useMessage } from 'naive-ui'
const dialog = useDialog()
const message = useMessage()
const handleDeletePaper = async (row: any) => {
try {
// 使用 Naive UI 对话框组件
dialog.warning({
title: '确认删除',
content: `确定要删除试卷"${row.name}"吗?此操作不可撤销。`,
positiveText: '确定删除',
negativeText: '取消',
onPositiveClick: async () => {
try {
// 调用删除API
const response = await ExamApi.deleteExamPaper(row.id)
// 显示成功消息
message.success('试卷删除成功!')
// 重新加载试卷列表
await loadExamPaperList()
} catch (error) {
console.error('删除试卷失败:', error)
message.error('删除试卷失败,请重试')
}
}
})
} catch (error) {
console.error('删除试卷失败:', error)
message.error('删除试卷失败,请重试')
}
}
// 批量删除示例
const handleBatchDelete = async () => {
if (checkedRowKeys.value.length === 0) {
message.warning('请先选择要删除的试卷')
return
}
try {
// 使用 Naive UI 对话框组件
dialog.error({
title: '确认批量删除',
content: `确定要删除选中的 ${checkedRowKeys.value.length} 个试卷吗?此操作不可撤销。`,
positiveText: '确定删除',
negativeText: '取消',
onPositiveClick: async () => {
try {
// 调用批量删除API
const response = await ExamApi.batchDeleteExamPapers(checkedRowKeys.value as string[])
// 显示成功消息
message.success(`成功删除 ${checkedRowKeys.value.length} 个试卷!`)
// 清空选中状态
checkedRowKeys.value = []
// 重新加载试卷列表
await loadExamPaperList()
} catch (error) {
console.error('批量删除试卷失败:', error)
message.error('批量删除试卷失败,请重试')
}
}
})
} catch (error) {
console.error('批量删除试卷失败:', error)
message.error('批量删除试卷失败,请重试')
}
}
```
### 4. 错误处理
```typescript
const deletePaperWithErrorHandling = async (paperId: string) => {
try {
const response = await ExamApi.deleteExamPaper(paperId)
if (response.data === 'success') {
return { success: true, message: '删除成功' }
} else {
return { success: false, message: '删除失败,请重试' }
}
} catch (error: any) {
if (error.response?.status === 404) {
return { success: false, message: '试卷不存在' }
} else if (error.response?.status === 403) {
return { success: false, message: '没有权限删除此试卷' }
}
return { success: false, message: '删除失败,请检查网络连接' }
}
}
```
## 功能特性
### 单个删除
- 支持删除单个试卷
- 使用 Naive UI 警告对话框组件
- 删除成功后自动刷新列表
- 完整的错误处理
### 批量删除
- 支持同时删除多个试卷
- 循环调用单个删除接口(避免后端接口不存在的问题)
- 逐个删除,避免对服务器造成过大压力
- 详细的删除结果反馈(成功/失败数量)
- 使用 Naive UI 错误对话框组件(更醒目的警告)
- 删除后清空选中状态
### 用户体验
- **美观的确认对话框**: 使用 Naive UI 组件,样式统一美观
- **不同类型的对话框**: 单个删除使用 warning批量删除使用 error
- **成功/失败消息提示**: 使用 Naive UI 的 message 组件
- **按钮状态管理**: 批量删除按钮在未选中时禁用
- **实时更新选中数量显示**: 动态显示选中的试卷数量
- **异步操作处理**: 在对话框确认后才执行删除操作
## 相关文件
- API实现: `src/api/modules/exam.ts`
- 页面实现: `src/views/teacher/ExamPages/ExamLibrary.vue`
- 使用示例: `src/api/examples/deletePaper-example.ts`