my-springboot-project/docs/完整curl测试手册.md

# 知识库管理系统 - 完整CURL测试手册

## 文档信息

| 项目          | 内容                      |
| ----------- | ----------------------- |
| **文档名称**    | 完整CURL测试文档              |
| **版本号**     | V2.15.0                 |
| **生成日期**    | 2026-05-29              |
| **基础URL**   | <http://localhost:8080> |
| **RAG服务地址** | <http://localhost:5001> |

***

## 一、使用说明

### 1.1 认证Token获取

首先需要通过登录接口获取JWT Token：

```bash
curl -X POST "http://localhost:8080/api/auth/login" \
     -H "Content-Type: application/json" \
     -d '{"username":"admin","password":"123456"}'
```

### 1.2 Token说明

本文档中所有curl命令均已预置Token，可直接复制使用。

### 1.3 通用请求头

所有需要认证的接口都需要添加以下请求头：

```bash
-H "Authorization: Bearer <your_token>" \
-H "Content-Type: application/json"
```

***

## 二、认证接口

### 2.1 登录

```bash
curl -X POST "http://localhost:8080/api/auth/login" \
     -H "Content-Type: application/json" \
     -d '{"username":"admin","password":"123456"}'
```

### 2.2 获取当前用户信息

```bash
curl -X GET "http://localhost:8080/api/auth/me" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

***

## 三、用户管理接口

### 3.1 获取用户列表

```bash
curl -X GET "http://localhost:8080/api/user/list" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 3.2 获取用户详情

```bash
curl -X GET "http://localhost:8080/api/user/1" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 3.3 创建用户

```bash
curl -X POST "http://localhost:8080/api/user" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
     -d '{
       "username": "testuser",
       "password": "123456",
       "email": "test@example.com",
       "deptId": 1,
       "userType": 3
     }'
```

### 3.4 更新用户

```bash
curl -X PUT "http://localhost:8080/api/user/1" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
     -d '{"email": "newemail@example.com"}'
```

### 3.5 删除用户

```bash
curl -X DELETE "http://localhost:8080/api/user/1" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 3.6 获取部门列表

```bash
curl -X GET "http://localhost:8080/api/department/list" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

***

## 四、向量库管理接口

### 4.1 获取向量库列表

```bash
curl -X GET "http://localhost:8080/api/collection" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 4.2 创建向量库

```bash
curl -X POST "http://localhost:8080/api/collection?name=dept_hr&displayName=人力资源知识库&departmentId=1&description=人力资源部专用知识库" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 4.3 修改向量库

```bash
curl -X PUT "http://localhost:8080/api/collection/dept_hr?displayName=人力资源知识库V2&description=更新后的描述" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 4.4 删除向量库

```bash
curl -X DELETE "http://localhost:8080/api/collection/dept_hr" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 4.5 文件向量化（单文件）

```bash
curl -X POST "http://localhost:8080/api/collection/public_kb/vectorize?fileId=36" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 4.6 批量文件向量化

```bash
curl -X POST "http://localhost:8080/api/collection/public_kb/vectorize/batch?fileIds=1&fileIds=2&fileIds=3" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 4.7 获取文档列表

```bash
curl -X GET "http://localhost:8080/api/collection/public_kb/documents" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 4.8 删除文档

```bash
# 推荐：使用 fileId 精确删除（避免同名文件删除错误）
curl -X DELETE "http://localhost:8080/api/collection/public_kb/documents/test_document.pdf?fileId=56" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"

# 兼容旧版本：仅使用文件名（存在同名文件风险）
curl -X DELETE "http://localhost:8080/api/collection/public_kb/documents/test_document.pdf" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 4.9 废止文档

```bash
curl -X POST "http://localhost:8080/api/collection/public_kb/documents/test_document.pdf/deprecate?reason=new_version" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 4.10 恢复已废止文档

```bash
curl -X POST "http://localhost:8080/api/collection/public_kb/documents/test_document_v2.pdf/restore" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 4.11 获取文档版本历史

```bash
curl -X GET "http://localhost:8080/api/collection/public_kb/documents/test_document.pdf/versions?limit=10" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 4.12 获取向量库切片列表

```bash
curl -X GET "http://localhost:8080/api/collection/public_kb/chunks?limit=100&offset=0" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 4.13 获取文档切片列表

```bash
curl -X GET "http://localhost:8080/api/collection/public_kb/documents/test_document.pdf/chunks?page=1&pageSize=20" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 4.14 新增切片

```bash
curl -X POST "http://localhost:8080/api/collection/public_kb/chunks?content=新的切片内容&section=第一章" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 4.15 修改切片

```bash
curl -X PUT "http://localhost:8080/api/collection/public_kb/chunks/chunk_001?content=更新后的内容&section=第一章" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 4.16 删除切片

```bash
curl -X DELETE "http://localhost:8080/api/collection/public_kb/chunks/chunk_001" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

***

## 四、知识库访问控制接口

### 4.1 分页查询知识库列表

```bash
curl -X GET "http://localhost:8080/api/collection-access/page?pageNum=1&pageSize=10" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
     -H "Content-Type: application/json"
```

### 4.2 获取知识库详情

```bash
curl -X GET "http://localhost:8080/api/collection-access/1" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
     -H "Content-Type: application/json"
```

### 4.3 获取用户可访问的知识库列表

```bash
curl -X GET "http://localhost:8080/api/collection-access/accessible" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
     -H "Content-Type: application/json"
```

***

## 五、AI流式问答接口

### 5.1 流式问答

```bash
curl -X POST "http://localhost:8080/api/ai/chat/stream" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
     -H "Content-Type: application/json" \
     -d '{
       "message": "市场权重计算公式",
       "session_id": ""
     }' \
     --no-buffer
```

### 5.2 中断AI流式问答

```bash
curl -X POST "http://localhost:8080/api/ai/chat/stop?sessionId=sess_1777600000000_abc123" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 5.3 获取用户会话列表

```bash
curl -X GET "http://localhost:8080/api/ai/sessions?page=1&pageSize=10" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 5.4 获取会话详情

```bash
curl -X GET "http://localhost:8080/api/ai/session/sess_123456789" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 5.5 获取消息文件来源列表

```bash
curl -X GET "http://localhost:8080/api/ai/message/1/sources" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 5.6 获取消息引用信息

```bash
curl -X GET "http://localhost:8080/api/ai/message/1/references" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 5.7 获取会话引用信息

```bash
curl -X GET "http://localhost:8080/api/ai/session/sess_123456789/references" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 5.8 删除单个会话

```bash
curl -X DELETE "http://localhost:8080/api/ai/session/sess_123456789" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 5.9 批量删除会话

```bash
curl -X DELETE "http://localhost:8080/api/ai/sessions" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
     -d '["sess_001", "sess_002", "sess_003"]'
```

***

## 六、反馈管理接口

### 6.1 提交反馈

```bash
curl -X POST "http://localhost:8080/api/feedback" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
  -d '{
    "sessionId": "sess_test_001",
    "query": "出差补助标准是什么？",
    "answer": "根据公司规定，国内出差补助标准为每天200元。",
    "rating": 1,
    "reason": "回答准确详细",
    "sources": ["出差报销制度.pdf"]
  }'
```

### 6.2 获取反馈列表

```bash
curl -X GET "http://localhost:8080/api/feedback/list?page=1&page_size=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 6.3 获取反馈统计

```bash
curl -X GET "http://localhost:8080/api/feedback/stats" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 6.4 获取差评案例

```bash
curl -X GET "http://localhost:8080/api/feedback/bad-cases" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

***

## 七、FAQ管理接口

### 7.1 获取FAQ列表

```bash
curl -X GET "http://localhost:8080/api/faq?page=1&page_size=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 7.2 获取FAQ建议列表

```bash
curl -X GET "http://localhost:8080/api/faq/suggestions?page=1&page_size=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 7.3 批准FAQ建议

```bash
curl -X POST "http://localhost:8080/api/faq/suggestions/1/approve" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
  -d '{"answer": "修改后的标准答案内容"}'
```

### 7.4 拒绝FAQ建议

```bash
curl -X POST "http://localhost:8080/api/faq/suggestions/1/reject" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

***

## 八、图片管理接口

### 8.0 图片完整处理流程测试

#### 8.0.1 整体流程说明

本系统实现了完整的AI图片处理流程：

```
用户提问 → RAG服务返回 → 图片提取 → 下载保存 → 数据库存储 → API访问 → 前端展示
```

#### 8.0.2 步骤1：AI流式问答（包含图片）

```bash
curl -X POST "http://localhost:8080/api/ai/chat/stream" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
  -d '{
    "message": "2003—2022 年，三峡电站累计发电量是多少？最好带图片说明",
    "session_id": ""
  }' \
  --no-buffer
```

**预期返回的 finish 事件包含 images 数组：**

```json
{
  "type": "finish",
  "images": [
    {
      "id": "ab77281e7913.jpg",
      "score": 7.8,
      "type": "chart",
      "source": "三峡公报_1-15页.pdf",
      "page": 12,
      "description": "这是一张柱状图...",
      "full_description": "这是一张柱状图，展示了...",
      "url": "/images/ab77281e7913.jpg"
    }
  ]
}
```

#### 8.0.3 步骤2：获取图片数据（二进制）

```bash
curl -X GET "http://localhost:8080/api/image/ab77281e7913.jpg/data" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
  -o downloaded_image.jpg
```

**验证下载的文件：**

```bash
# 查看文件信息
ls -lh downloaded_image.jpg

# 查看文件类型
file downloaded_image.jpg

# 查看文件大小
wc -c downloaded_image.jpg
```

**预期输出：**

```
-rw-r--r-- 1 root root 79827 May 19 15:37 downloaded_image.jpg
downloaded_image.jpg: JPEG image data, ...
79827 downloaded_image.jpg
```

#### 8.0.4 步骤3：获取图片详情（JSON）

```bash
curl -X GET "http://localhost:8080/api/image/1" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

**预期返回：**

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "id": 1,
    "imageId": "ab77281e7913.jpg",
    "filename": "ab77281e7913.jpg",
    "path": "/img/ab77281e7913.jpg",
    "sizeBytes": 79827,
    "format": "JPEG",
    "source": "三峡公报_1-15页.pdf",
    "page": 12,
    "type": "chart",
    "description": "这是一张柱状图，展示了2003年至2022年发电量的变化趋势...",
    "fullDescription": "这是一张柱状图，展示了2003年至2022年发电量（单位：亿千瓦时）的变化趋势...",
    "score": 7.8
  }
}
```

#### 8.0.5 步骤4：查看数据库中的图片记录

```bash
mysql -h localhost -u root -p knowledge_management_system -e "SELECT id, image_id, path, format, size_bytes, source, page, type, score FROM context_image LIMIT 5;"
```

**预期输出：**

```
+----+-------------------------+--------------------------+--------+-------------+-------------------------------+------+-------+-------+
| id | image_id                | path                     | format | size_bytes  | source                        | page | type  | score |
+----+-------------------------+--------------------------+--------+-------------+-------------------------------+------+-------+-------+
|  1 | ab77281e7913.jpg       | /img/ab77281e7913.jpg    | JPEG   |       79827 | 三峡公报_1-15页.pdf          |   12 | chart |  7.80 |
+----+-------------------------+--------------------------+--------+-------------+-------------------------------+------+-------+-------+
```

### 8.1 获取图片列表

```bash
curl -X GET "http://localhost:8080/api/image/list?limit=10&offset=0" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 8.2 获取单张图片

```bash
curl -X GET "http://localhost:8080/api/image/img_001" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
  -o downloaded_image.jpg
```

### 8.3 获取图片统计

```bash
curl -X GET "http://localhost:8080/api/image/stats" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

***

## 九、报告管理接口

### 9.1 获取周报

```bash
curl -X GET "http://localhost:8080/api/report/weekly" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 9.2 获取月报

```bash
curl -X GET "http://localhost:8080/api/report/monthly" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

***

## 十、知识检索接口

### 10.1 混合检索

```bash
curl -X POST "http://localhost:8080/api/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
  -d '{
    "query": "出差补助标准",
    "topK": 5,
    "collections": ["public_kb", "dept"]
  }'
```

***

## 十一、知识库路由接口

### 11.1 测试知识库路由

```bash
curl -X POST "http://localhost:8080/api/kb-route" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
  -d '{
    "query": "财务部的报销流程是什么"
  }'
```

***

## 十二、模拟考接口 🔵 模拟考

### 12.1 生成试卷（按权限范围）

```bash
curl -X POST "http://localhost:8080/api/exam/paper/generate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
  -d '{
    "single_choice_count": 5,
    "multiple_choice_count": 3,
    "true_false_count": 2,
    "fill_blank_count": 2,
    "subjective_count": 1,
    "difficulty": 3,
    "include_personal": false
  }'
```

### 12.2 生成试卷（指定文件）

```bash
curl -X POST "http://localhost:8080/api/exam/paper/generate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
  -d '{
    "single_choice_count": 5,
    "multiple_choice_count": 3,
    "true_false_count": 2,
    "fill_blank_count": 2,
    "subjective_count": 1,
    "difficulty": 3,
    "file_ids": [1, 2, 3]
  }'
```

### 12.3 生成题目

**重要说明**：此接口为异步接口，请求后立即返回任务提交状态，实际生成在后台执行。需通过 `GET /api/file/{fileId}` 接口轮询查询生成进度和结果。

**测试用例1：智能生成模式（推荐）**

不提供 `question_types` 参数，AI 会根据文档内容自动判断题型和数量：

```bash
curl -X POST "http://localhost:8080/api/exam/generate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
  -d '{
    "file_id": 74,
    "difficulty": 3,
    "request_id": "gen_req_smart_001"
  }'
```

**测试用例2：指定题型模式 - 通过 file\_id 指定文件**

> **注意**：系统会自动查询该文件已有的题目题干（`exclude_stems`），在调用AI时传入进行去重，避免生成重复题目。

```bash
curl -X POST "http://localhost:8080/api/exam/generate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
  -d '{
    "file_id": 69,
    "question_types": {
      "single_choice": 3,
      "multiple_choice": 2,
      "true_false": 2,
      "fill_blank": 2,
      "subjective": 1
    },
    "difficulty": 3,
    "request_id": "gen_req_001"
  }'
```

**默认分数配置：**

| 题型                | 默认分数 |
| ----------------- | ---- |
| `single_choice`   | 2分   |
| `multiple_choice` | 4分   |
| `true_false`      | 1分   |
| `fill_blank`      | 2分   |
| `subjective`      | 10分  |

**预期响应：**

```json
{
  "code": 200,
  "message": "收到请求",
  "data": {
    "requestId": "gen_req_001",
    "fileId": 21,
    "fileMatchStatus": "success",
    "matchedCollection": "test1",
    "matchedFilePath": "test1/1.docx",
    "documentName": "1.docx",
    "collectionFilled": true,
    "collectionFillSource": "直接使用",
    "asyncTaskStarted": true,
    "nextStep": "请通过文件状态接口查询生成进度",
    "status": "success"
  }
}
```

> **生成完成后**，通过 `GET /api/file/{fileId}` 接口可查询到生成结果，`processMessage` 字段会包含题型统计信息：
>
> ```
> 生成成功，共15道题
>
> 【题型统计】
> 请求题型: {单选题: 10道, 填空题: 5道}
> 实际生成: {单选题: 10道, 填空题: 3道}
>
> 【短缺警告】
> - fill_blank: 请求5道，实际生成3道
> ```

**测试用例3：通过 file\_path 指定文件**

```bash
curl -X POST "http://localhost:8080/api/exam/generate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
  -d '{
    "file_path": "test1/1.docx",
    "collection": "test1",
    "question_types": {
      "single_choice": 3,
      "multiple_choice": 2,
      "true_false": 2,
      "fill_blank": 2,
      "subjective": 1
    },
    "difficulty": 3,
    "request_id": "gen_req_002"
  }'
```

**测试用例4：自定义题型分数**

```bash
curl -X POST "http://localhost:8080/api/exam/generate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
  -d '{
    "file_id": 21,
    "question_types": {
      "single_choice": 5,
      "multiple_choice": 3
    },
    "question_scores": {
      "single_choice": 4.00,
      "multiple_choice": 8.00
    },
    "difficulty": 3,
    "request_id": "gen_req_003"
  }'
```

**测试用例5：查询生成进度**

提交请求后，通过文件状态查询接口轮询生成进度：

```bash
curl -X GET "http://localhost:8080/api/file/21" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

**预期响应（生成中）：**

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "id": 21,
    "fileName": "1.docx",
    "filePath": "test1/1.docx",
    "processStatus": "INDEXED",
    "examStatus": "GENERATING",
    "processMessage": "正在生成题目，请稍后...",
    "createTime": "2026-05-28T10:00:00",
    "updateTime": "2026-05-28T10:00:01"
  }
}
```

**预期响应（生成成功）：**

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "id": 21,
    "fileName": "1.docx",
    "filePath": "test1/1.docx",
    "processStatus": "INDEXED",
    "examStatus": "GENERATED",
    "processMessage": "生成成功，共5道题\n\n【AI分析结果】\n{\"summary\":\"文档摘要...\",\"questionDistribution\":{\"single_choice\":3,\"multiple_choice\":2}}",
    "createTime": "2026-05-28T10:00:00",
    "updateTime": "2026-05-28T10:00:03"
  }
}
```

**AI生成题目状态说明：**

| 状态值           | 说明   |
| ------------- | ---- |
| `UNGENERATED` | 未生成  |
| `GENERATING`  | 正在生成 |
| `GENERATED`   | 已生成  |
| `FAILED`      | 生成失败 |

**轮询策略建议：**

- 初始轮询间隔：2-3秒
- 超时时间：建议设置为 5-10 分钟
- 停止条件：`examStatus` 变为 `GENERATED` 或 `FAILED`

**默认分值说明：**

| 题型                     | 默认分值 |
| ---------------------- | ---- |
| 单选题 (single\_choice)   | 2分   |
| 多选题 (multiple\_choice) | 4分   |
| 判断题 (true\_false)      | 1分   |
| 填空题 (fill\_blank)      | 2分   |
| 简答题 (subjective)       | 6分   |

### 12.4 批改答案（日常练习）

**测试用例1：单选题**

```bash
curl -X POST "http://localhost:8080/api/exam/grade" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
  -d '{
    "type": "practice",
    "request_id": "grade_req_single_001",
    "answers": [
      {
        "question_id": "q_single_001",
        "question_type": "single_choice",
        "question_content": {
          "stem": "请假制度中，事假的最长申请天数为？",
          "data": {
            "options": [
              {"key": "A", "content": "3天"},
              {"key": "B", "content": "7天"},
              {"key": "C", "content": "15天"},
              {"key": "D", "content": "30天"}
            ]
          },
          "answer": "B"
        },
        "student_answer": "B",
        "max_score": 2.0
      }
    ]
  }'
```

**测试用例2：多选题**

```bash
curl -X POST "http://localhost:8080/api/exam/grade" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
  -d '{
    "type": "practice",
    "request_id": "grade_req_multi_001",
    "answers": [
      {
        "question_id": "q_multi_001",
        "question_type": "multiple_choice",
        "question_content": {
          "stem": "以下哪些属于公司福利？",
          "data": {
            "options": [
              {"key": "A", "content": "五险一金"},
              {"key": "B", "content": "年终奖金"},
              {"key": "C", "content": "带薪年假"},
              {"key": "D", "content": "加班工资"}
            ]
          },
          "answer": "ABC"
        },
        "student_answer": "AB",
        "max_score": 4.0
      }
    ]
  }'
```

**测试用例3：判断题**

```bash
curl -X POST "http://localhost:8080/api/exam/grade" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
  -d '{
    "type": "practice",
    "request_id": "grade_req_tf_001",
    "answers": [
      {
        "question_id": "q_tf_001",
        "question_type": "true_false",
        "question_content": {
          "stem": "公式\"样本零售客户期末库存/月销量\"可以用来衡量客户对货源的依赖程度。",
          "data": {"options": [{"key": "T", "content": "正确"}, {"key": "F", "content": "错误"}]},
          "answer": "F"
        },
        "student_answer": "F",
        "max_score": 1.0
      }
    ]
  }'
```

**测试用例4：填空题**

```bash
curl -X POST "http://localhost:8080/api/exam/grade" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
  -d '{
    "type": "practice",
    "request_id": "grade_req_fill_001",
    "answers": [
      {
        "question_id": "q_fill_001",
        "question_type": "fill_blank",
        "question_content": {
          "stem": "三峡电站2020年发电量达到____亿千瓦时，为历年最高。",
          "data": {"blank_count": 1},
          "answer": ["1118.02"]
        },
        "student_answer": ["1118"],
        "max_score": 2.0
      }
    ]
  }'
```

**测试用例5：主观题**

```bash
curl -X POST "http://localhost:8080/api/exam/grade" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
  -d '{
    "type": "practice",
    "request_id": "grade_req_subjective_001",
    "answers": [
      {
        "question_id": "q_subjective_001",
        "question_type": "subjective",
        "question_content": {
          "stem": "请简述库存周转率的定义及其计算公式。",
          "data": {},
          "answer": "库存周转率是衡量库存管理效率的指标。公式：库存周转率 = 销售成本 / 平均库存"
        },
        "student_answer": "库存周转率是衡量库存管理效率的指标，反映了库存的周转速度。计算公式为：库存周转率 = 销售成本 / 平均库存",
        "max_score": 6.0
      }
    ]
  }'
```

**测试用例6：混合题型（完整试卷）**

```bash
curl -X POST "http://localhost:8080/api/exam/grade" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
  -d '{
    "type": "practice",
    "request_id": "grade_req_mixed_001",
    "answers": [
      {
        "question_id": "q_001",
        "question_type": "single_choice",
        "question_content": {
          "stem": "以下哪个不是公司的核心价值观？",
          "data": {
            "options": [
              {"key": "A", "content": "诚信"},
              {"key": "B", "content": "创新"},
              {"key": "C", "content": "利润"},
              {"key": "D", "content": "责任"}
            ]
          },
          "answer": "C"
        },
        "student_answer": "C",
        "max_score": 2.0
      },
      {
        "question_id": "q_002",
        "question_type": "multiple_choice",
        "question_content": {
          "stem": "以下哪些属于人力资源部的职责？",
          "data": {
            "options": [
              {"key": "A", "content": "招聘"},
              {"key": "B", "content": "培训"},
              {"key": "C", "content": "财务"},
              {"key": "D", "content": "绩效"}
            ]
          },
          "answer": "ABD"
        },
        "student_answer": "AB",
        "max_score": 4.0
      },
      {
        "question_id": "q_003",
        "question_type": "true_false",
        "question_content": {
          "stem": "员工请假需要提前一天申请。",
          "data": {"options": [{"key": "T", "content": "正确"}, {"key": "F", "content": "错误"}]},
          "answer": "T"
        },
        "student_answer": "T",
        "max_score": 1.0
      },
      {
        "question_id": "q_004",
        "question_type": "fill_blank",
        "question_content": {
          "stem": "公司成立于____年，总部位于____。",
          "data": {"blank_count": 2},
          "answer": ["2010", "北京"]
        },
        "student_answer": ["2010", "上海"],
        "max_score": 4.0
      },
      {
        "question_id": "q_005",
        "question_type": "subjective",
        "question_content": {
          "stem": "请简述绩效考核的目的和意义。",
          "data": {},
          "answer": "绩效考核的目的是评估员工工作表现，激励员工提升绩效，为薪酬调整和晋升提供依据。"
        },
        "student_answer": "绩效考核可以评估员工的工作表现，帮助发现问题并改进，同时作为薪酬和晋升的参考依据。",
        "max_score": 6.0
      }
    ]
  }'
```

### 12.5 获取考试记录

```bash
curl -X GET "http://localhost:8080/api/exam/my/papers" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 12.6 开始考试（获取题目）

```bash
curl -X POST "http://localhost:8080/api/exam/paper/paper_12345678-1234-1234-1234-123456789abc-start" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 12.7 获取考试结果

```bash
curl -X GET "http://localhost:8080/api/exam/record/record_12345678-1234-1234-1234-123456789abc/result" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 12.8 查询用户答题记录（按试卷）

```bash
curl -X POST "http://localhost:8080/api/exam/answers/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
  -d '{
    "paper_id": "paper_12345678-1234-1234-1234-123456789abc"
  }'
```

### 12.9 查询用户答题记录（按会话）

```bash
curl -X POST "http://localhost:8080/api/exam/answers/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
  -d '{
    "session_id": "sess_practice_001"
  }'
```

***

## 十三、题目管理接口

### 13.1 获取题目列表（按权限过滤）

```bash
curl -X GET "http://localhost:8080/api/question/list?questionType=&difficulty=&status=&documentName=&limit=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 13.2 创建题目

```bash
curl -X POST "http://localhost:8080/api/question" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
  -d '{
    "question_type": "single_choice",
    "difficulty": 3,
    "content": {
      "stem": "测试题目",
      "data": {
        "options": [
          {"key": "A", "content": "选项A"},
          {"key": "B", "content": "选项B"},
          {"key": "C", "content": "选项C"},
          {"key": "D", "content": "选项D"}
        ]
      },
      "answer": "B",
      "explanation": "测试解析"
    },
    "score": 5.0,
    "document_name": "public_kb/test.docx"
  }'
```

### 13.3 题目统计

```bash
curl -X POST "http://localhost:8080/api/question/stats" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
  -d '{
    "status": "approved",
    "question_types": ["single_choice", "multiple_choice"]
  }'
```

***

## 十四、正式考试接口 🟢 正式考

### 14.1 开始考试（获取题目）

```bash
curl -X POST "http://localhost:8080/api/formal-exam/paper/paper_12345678-1234-1234-1234-123456789abc/start" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

### 14.2 提交考试（通过 recordId 方式，推荐）

```bash
curl -X POST "http://localhost:8080/api/exam/record/record_12345678-1234-1234-1234-123456789abc/grade" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
  -d '{
    "answers": [
      {"questionId": "q_001", "questionType": "true_false", "answer": true},
      {"questionId": "q_002", "questionType": "subjective", "answer": "该指标用于衡量库存与销售的匹配程度。"},
      {"questionId": "q_003", "questionType": "fill_blank", "answer": ["散点图","销量"]},
      {"questionId": "q_004", "questionType": "single_choice", "answer": "B"},
      {"questionId": "q_005", "questionType": "multiple_choice", "answer": ["A","C","D"]}
    ]
  }'
```

### 14.3 提交考试（通过 /api/exam/grade 方式，支持完整题目信息）

```bash
curl -X POST "http://localhost:8080/api/exam/grade" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
  -d '{
    "type": "formal_exam",
    "record_id": "record_12345678-1234-1234-1234-123456789abc",
    "answers": [
      {
        "question_id": "q_001",
        "question_type": "true_false",
        "question_content": {
          "stem": "公式\"样本零售客户期末库存/月销量\"可以用来衡量客户对货源的依赖程度。",
          "data": {"options": [{"key": "T", "content": "正确"}, {"key": "F", "content": "错误"}]},
          "answer": "F"
        },
        "student_answer": true,
        "max_score": 3.0
      }
    ]
  }'
```

### 14.4 获取考试结果

```bash
curl -X GET "http://localhost:8080/api/formal-exam/record/record_12345678-1234-1234-1234-123456789abc/result" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A"
```

***

## 十五、正式考管理接口 🟢 正式考管理

### 15.1 预览试卷

```bash
curl -X POST "http://localhost:8080/api/admin/exam/paper/preview" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
  -d '{
    "single_choice_count": 1,
    "multiple_choice_count": 1,
    "true_false_count": 1,
    "fill_blank_count": 2,
    "subjective_count": 1,
    "difficulty": 3
  }'
```

### 15.2 保存试卷

```bash
curl -X POST "http://localhost:8080/api/admin/exam/paper/save" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
  -d '{
    "title": "月度考核试卷",
    "questionIds": [
      "q_001",
      "q_002",
      "q_003",
      "q_004",
      "q_005",
      "q_006"
    ]
  }'
```

### 15.3 发布试卷

```bash
curl -X POST "http://localhost:8080/api/admin/exam/paper/paper_12345678-1234-1234-1234-123456789abc/publish" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXNlcm5hbWUiOiJhZG1pbiIsImlhdCI6MTc4MDY0Njg2MSwiZXhwIjoxNzgwNjU0MDYxfQ.lNjvlKtxVRwjX9Ce2IO0M0NxB_Dm2vxkGlynBMUt6sjdUKr-R57nXhLcxHSM92gtaJYZHczYSU4l6eDWQ0a56A" \
  -d '{
    "exam_name": "月度考核",
    "start_time": "2026-06-01 09:00:00",
    "end_time": "2026-06-01 11:00:00",
    "duration_minutes": 120,
    "department_ids": ["dept_001", "dept_002"],
    "allow_retake": false
  }'
```