180 lines
7.7 KiB
Markdown
180 lines
7.7 KiB
Markdown
# 题目管理 API 文档
|
||
|
||
## 1. 上传文件并生成题目
|
||
|
||
**接口说明：** 上传文档文件，调用 AI 自动生成题目
|
||
|
||
**请求方式：** `POST`
|
||
|
||
**接口地址：** `/question/upload`
|
||
|
||
**Content-Type：** `multipart/form-data`
|
||
|
||
### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| -------------- | ------ | ---- | --------------------------------------- |
|
||
| file | File | 是 | 文档文件（支持 doc, docx, pdf, txt 等） |
|
||
| customFileName | String | 否 | 自定义文件名（可选） |
|
||
|
||
### 响应示例
|
||
|
||
json { "code": 200, "message": "操作成功", "data": "=== AI 处理结果 ===\n用户: admin\n文件路径: /path/to/file.docx\n\nAI 处理状态: 成功\n说明: 这是占位返回，请替换为实际的 AI 接口调用", "timestamp": "2026-04-23 08:30:00", "success": true }
|
||
|
||
> **注意：** 目前 `callAIInterface` 方法是占位符，需要对接 Dify 工作流才能实现真正的题目生成功能。
|
||
|
||
---
|
||
|
||
## 2. 分页查询题目
|
||
|
||
**接口说明：** 根据条件分页查询题目列表
|
||
|
||
**请求方式：** `GET`
|
||
|
||
**接口地址：** `/question/page`
|
||
|
||
### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||
| ------------ | ------- | ---- | ------ | ------------------------------------------------------------ |
|
||
| pageNum | Integer | 否 | 1 | 页码 |
|
||
| pageSize | Integer | 否 | 10 | 每页大小 |
|
||
| questionType | String | 否 | - | 题目类型：single_choice/multiple_choice/fill_blank/true_false/subjective |
|
||
| difficulty | Integer | 否 | - | 难度等级（1-5） |
|
||
| status | String | 否 | - | 审核状态：pending/approved/rejected |
|
||
|
||
### 响应示例
|
||
|
||
json { "code": 200, "message": "操作成功", "data": { "records": [ { "id": 21, "questionId": "q-001-sc-uuid-20260418", "questionType": "single_choice", "difficulty": 2, "tags": ["公司历史", "基本信息"], "score": 10.00, "version": "1.0", "documentId": "doc-001", "documentName": "公司介绍手册", "sourceContext": "根据文档第一段描述...", "pageNumbers": [1], "content": { "stem": "根据文档，公司成立的年份是？", "answer": "B", "explanation": "在文档第一页明确提到...", "data": { "options": [ {"key": "A", "content": "1998年"}, {"key": "B", "content": "2005年"}, {"key": "C", "content": "2010年"}, {"key": "D", "content": "2015年"} ] } }, "status": "pending", "reviewerComment": null, "createdAt": "2026-04-18 08:00:00", "updatedAt": "2026-04-18 00:49:27" } ], "total": 25, "size": 10, "current": 1, "pages": 3 }, "timestamp": "2026-04-23 08:30:00", "success": true }
|
||
|
||
---
|
||
|
||
## 3. 获取题目详情
|
||
|
||
**接口说明：** 根据题目 ID 获取详细信息
|
||
|
||
**请求方式：** `GET`
|
||
|
||
**接口地址：** `/question/{id}`
|
||
|
||
### 路径参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| ------ | ---- | ---- | ----------- |
|
||
| id | Long | 是 | 题目自增 ID |
|
||
|
||
### 响应示例
|
||
|
||
json { "code": 200, "message": "操作成功", "data": { "id": 21, "questionId": "q-001-sc-uuid-20260418", "questionType": "single_choice", "difficulty": 2, "tags": ["公司历史", "基本信息"], "score": 10.00, "version": "1.0", "documentId": "doc-001", "documentName": "公司介绍手册", "sourceContext": "根据文档第一段描述...", "pageNumbers": [1], "content": {...}, "status": "pending", "reviewerComment": null, "createdAt": "2026-04-18 08:00:00", "updatedAt": "2026-04-18 00:49:27" }, "timestamp": "2026-04-23 08:30:00", "success": true }---
|
||
|
||
## 4. 获取待审核题目列表
|
||
|
||
**接口说明：** 获取所有待审核的题目
|
||
|
||
**请求方式：** `GET`
|
||
|
||
**接口地址：** `/question/pending`
|
||
|
||
### 响应示例
|
||
|
||
json { "code": 200, "message": "操作成功", "data": [ { "id": 21, "questionId": "q-001-sc-uuid-20260418", "questionType": "single_choice", "status": "pending", ... } ], "timestamp": "2026-04-23 08:30:00", "success": true }
|
||
|
||
---
|
||
|
||
## 5. 审核题目
|
||
|
||
**接口说明：** 审核通过或拒绝题目
|
||
|
||
**请求方式：** `PUT`
|
||
|
||
**接口地址：** `/question/review/{questionId}`
|
||
|
||
### 路径参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| ---------- | ------ | ---- | --------- |
|
||
| questionId | String | 是 | 题目 UUID |
|
||
|
||
### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --------------- | ------ | ---- | -------------------------------------------- |
|
||
| status | String | 是 | 审核状态：approved（通过）/ rejected（拒绝） |
|
||
| reviewerComment | String | 否 | 审核评论/意见 |
|
||
|
||
### 请求示例
|
||
|
||
PUT /question/review/q-001-sc-uuid-20260418?status=approved&reviewerComment=题目质量良好
|
||
|
||
### 响应示例
|
||
|
||
json { "code": 200, "message": "操作成功", "data": null, "timestamp": "2026-04-23 08:30:00", "success": true }
|
||
|
||
---
|
||
|
||
## 6. 按题型获取题目列表
|
||
|
||
**接口说明：** 获取指定题型的所有已审核通过的题目
|
||
|
||
**请求方式：** `GET`
|
||
|
||
**接口地址：** `/question/type/{questionType}`
|
||
|
||
### 路径参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| ------------ | ------ | ---- | ------------------------------------------------------------ |
|
||
| questionType | String | 是 | 题目类型：single_choice/multiple_choice/fill_blank/true_false/subjective |
|
||
|
||
### 响应示例
|
||
|
||
json { "code": 200, "message": "操作成功", "data": [ { "id": 21, "questionId": "q-001-sc-uuid-20260418", "questionType": "single_choice", "status": "approved", ... } ], "timestamp": "2026-04-23 08:30:00", "success": true }
|
||
|
||
---
|
||
|
||
## 7. 获取所有题型列表
|
||
|
||
**接口说明：** 获取系统支持的所有题目类型
|
||
|
||
**请求方式：** `GET`
|
||
|
||
**接口地址：** `/question/types`
|
||
|
||
### 响应示例
|
||
|
||
json { "code": 200, "message": "操作成功", "data": [ "single_choice", "multiple_choice", "fill_blank", "true_false", "subjective" ], "timestamp": "2026-04-23 08:30:00", "success": true }
|
||
|
||
---
|
||
|
||
## 附录
|
||
|
||
### 题目类型说明
|
||
|
||
| 类型值 | 中文名称 | 说明 |
|
||
| --------------- | -------- | ------------- |
|
||
| single_choice | 选择题 | 单选题 |
|
||
| multiple_choice | 多选题 | 多项选择题 |
|
||
| fill_blank | 填空题 | 填空题目 |
|
||
| true_false | 判断题 | 判断对错 |
|
||
| subjective | 简答题 | 主观题/问答题 |
|
||
|
||
### 审核状态说明
|
||
|
||
| 状态值 | 中文名称 | 说明 |
|
||
| -------- | -------- | -------------------- |
|
||
| pending | 待审核 | AI 生成后的初始状态 |
|
||
| approved | 已通过 | 审核通过，可对外展示 |
|
||
| rejected | 已拒绝 | 审核不通过 |
|
||
|
||
### 注意事项
|
||
|
||
1. **题目生成接口目前未完全实现**，`uploadAndProcessFile` 方法中的 `callAIInterface` 是占位符，需要对接 Dify 工作流 API
|
||
2. **按题型查询只返回已通过的题目**（status = "approved"），如需查看所有状态的题目，请使用分页查询接口并指定 status 参数
|
||
3. **时间格式统一为** `yyyy-MM-dd HH:mm:ss`
|
||
|
||
# AIChat模块流式接口
|
||
POST 'http://localhost:8080/api/ai/chat/stream' \
|
||
-H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc3NzAwODgxOCwiZXhwIjoxNzc3MDE2MDE4fQ.mrvapro3L_vzYPxRtZPcEDQFAE2kuvpeMBV1vWhI9ho7lJZq0CnBrL1ZkhwOnDiXOZltLjor6vvFkuEb-pGEtg' \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"message": "三峡船闸是什么", "chat_history": []}' \
|
||
-H 'Accept: text/event-stream' |