# 题目管理 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'