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

13 KiB
Raw Permalink Blame History

考试信息API使用文档

接口概述

/aiol/aiolExam/getExamInfo 接口用于获取教师名下的考试信息列表。

接口定义

请求方式

  • 方法: GET
  • 路径: /aiol/aiolExam/getExamInfo
  • 参数: userId (查询参数)

请求参数

参数名 类型 必选 说明
userId string 教师用户ID

响应格式

{
  "success": boolean,
  "message": string,
  "code": number,
  "result": ExamInfo[],
  "timestamp": number
}

ExamInfo 数据结构

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模块中调用

import { ExamApi } from '@/api/modules/exam'

// 获取教师考试信息
const response = await ExamApi.getExamInfo('teacher_user_id')
console.log('考试信息:', response.data)

2. 在Vue组件中使用

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. 在试卷管理页面中使用

// 在 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
  }
}

数据映射说明

状态映射

const statusMap: { [key: number]: string } = {
  0: '未发布',
  1: '发布中',
  2: '已结束'
}

类型映射

const categoryMap: { [key: number]: string } = {
  0: '练习',
  1: '考试'
}

难度映射

const difficultyMap: { [key: number]: string } = {
  0: '易',
  1: '中',
  2: '难'
}

错误处理

接口可能返回以下错误:

  1. 401 Unauthorized: 用户未登录或token过期
  2. 403 Forbidden: 没有权限访问
  3. 500 Internal Server Error: 服务器内部错误

建议在调用时添加适当的错误处理:

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=需要

响应格式

{
  "success": boolean,
  "message": string,
  "code": number,
  "result": string, // 试卷ID
  "timestamp": number
}

使用示例

1. 在API模块中调用

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组件中使用

// 在 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. 不同组卷模式示例

// 固定试卷组
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数组

响应格式

单个删除响应:

{
  "success": boolean,
  "message": string,
  "code": number,
  "result": string,
  "timestamp": number
}

批量删除响应:

{
  "success": boolean,
  "message": string,
  "code": number,
  "result": {
    "success": number,    // 成功删除的数量
    "failed": number,     // 失败删除的数量
    "total": number,      // 总数量
    "errors": string[]    // 错误信息数组
  },
  "timestamp": number
}

使用示例

1. 删除单个试卷

import { ExamApi } from '@/api/modules/exam'

// 删除单个试卷
const response = await ExamApi.deleteExamPaper('1962379646322384897')
console.log('删除结果:', response.data)

2. 批量删除试卷

// 批量删除试卷
const paperIds = ['1962379646322384897', '1966450638717292545']
const response = await ExamApi.batchDeleteExamPapers(paperIds)
console.log('批量删除结果:', response.data)

3. 在Vue组件中使用使用 Naive UI 对话框组件)

// 在 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. 错误处理

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