402 lines
9.2 KiB
Markdown
402 lines
9.2 KiB
Markdown
# 文件管理接口文档
|
||
|
||
## 1. 接口概述
|
||
|
||
本文档描述文件管理模块的后端接口，用于前端展示和管理数据库中的文件信息。
|
||
|
||
### 基础路径
|
||
|
||
```
|
||
/api/file
|
||
```
|
||
|
||
### 认证方式
|
||
|
||
所有接口需要在请求头中携带 Authorization 令牌：
|
||
|
||
```http
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 接口列表
|
||
|
||
### 2.1 分页查询文件列表
|
||
|
||
**接口地址**：`GET /api/file/page`
|
||
|
||
**功能描述**：根据条件分页查询文件列表，支持文件名搜索
|
||
|
||
**请求参数**：
|
||
|
||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| `pageNum` | Integer | 否 | 1 | 页码 |
|
||
| `pageSize` | Integer | 否 | 10 | 每页大小 |
|
||
| `fileName` | String | 否 | - | 文件名（模糊搜索） |
|
||
|
||
**请求示例**：
|
||
|
||
```http
|
||
GET /api/file/page?pageNum=1&pageSize=10&fileName=文档
|
||
```
|
||
|
||
**成功响应**（HTTP 200）：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"total": 44,
|
||
"list": [
|
||
{
|
||
"id": 21,
|
||
"fileName": "1.docx",
|
||
"filePath": "resources/rule/总公司/南京分公司/公共部门/1/v1/1.docx",
|
||
"fileSize": 483352,
|
||
"fileType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
|
||
"extension": ".docx",
|
||
"uploadUserId": 1,
|
||
"uploadUserName": "admin",
|
||
"deptId": 7,
|
||
"deptName": "公共部门",
|
||
"isPublic": 1,
|
||
"fileCategory": "rule",
|
||
"status": 1,
|
||
"auditStatus": 1,
|
||
"processStatus": "INDEXED",
|
||
"examStatus": "GENERATED",
|
||
"processStepStatus": "COMPLETED",
|
||
"processStepMessage": "全部流程完成",
|
||
"processMessage": "生成成功，共10道题",
|
||
"createTime": "2026-05-07 11:00:23",
|
||
"updateTime": "2026-05-28 17:07:53"
|
||
}
|
||
],
|
||
"pageNum": 1,
|
||
"pageSize": 10
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2.2 查询单个文件详情
|
||
|
||
**接口地址**：`GET /api/file/{id}`
|
||
|
||
**功能描述**：根据文件ID查询文件详细信息
|
||
|
||
**路径参数**：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| `id` | Long | 是 | 文件ID |
|
||
|
||
**请求示例**：
|
||
|
||
```http
|
||
GET /api/file/21
|
||
```
|
||
|
||
**成功响应**（HTTP 200）：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"id": 21,
|
||
"fileName": "1.docx",
|
||
"filePath": "resources/rule/总公司/南京分公司/公共部门/1/v1/1.docx",
|
||
"fileSize": 483352,
|
||
"fileType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
|
||
"extension": ".docx",
|
||
"uploadUserId": 1,
|
||
"uploadUserName": "admin",
|
||
"deptId": 7,
|
||
"deptName": "公共部门",
|
||
"isPublic": 1,
|
||
"fileCategory": "rule",
|
||
"status": 1,
|
||
"auditStatus": 1,
|
||
"processStatus": "INDEXED",
|
||
"examStatus": "GENERATED",
|
||
"processStepStatus": "COMPLETED",
|
||
"processStepMessage": "全部流程完成",
|
||
"processMessage": "生成成功，共10道题",
|
||
"createTime": "2026-05-07 11:00:23",
|
||
"updateTime": "2026-05-28 17:07:53"
|
||
}
|
||
}
|
||
```
|
||
|
||
**失败响应**（HTTP 404）：
|
||
|
||
```json
|
||
{
|
||
"code": 404,
|
||
"message": "文件不存在",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2.3 上传文件
|
||
|
||
**接口地址**：`POST /api/file/upload`
|
||
|
||
**功能描述**：上传文件到服务器，支持个人文件和部门制度文件
|
||
|
||
**Content-Type**：`multipart/form-data`
|
||
|
||
**请求参数**：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| `file` | MultipartFile | 是 | 文件对象 |
|
||
| `targetDeptId` | Long | 否 | 目标部门ID（上传到指定部门） |
|
||
| `isPublic` | Boolean | 否 | 是否公开（默认true） |
|
||
|
||
**请求示例**：
|
||
|
||
```http
|
||
POST /api/file/upload
|
||
Content-Type: multipart/form-data
|
||
|
||
file: <文件二进制数据>
|
||
targetDeptId: 7
|
||
isPublic: true
|
||
```
|
||
|
||
**成功响应**（HTTP 200）：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"id": 45,
|
||
"fileName": "新建文档.docx",
|
||
"filePath": "resources/personal/user1/新建文档/v1/新建文档.docx",
|
||
"fileSize": 12288,
|
||
"extension": ".docx",
|
||
"uploadUserId": 1,
|
||
"uploadUserName": "admin",
|
||
"deptId": 1,
|
||
"deptName": "技术部",
|
||
"isPublic": 1,
|
||
"fileCategory": "personal",
|
||
"status": 1,
|
||
"auditStatus": 1,
|
||
"processStatus": "PENDING",
|
||
"examStatus": "UNGENERATED",
|
||
"processStepStatus": "UPLOADED",
|
||
"processStepMessage": "文件已上传",
|
||
"createTime": "2026-05-29 10:30:00",
|
||
"updateTime": "2026-05-29 10:30:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2.4 删除文件
|
||
|
||
**接口地址**：`DELETE /api/file/{id}`
|
||
|
||
**功能描述**：根据文件ID删除文件
|
||
|
||
**路径参数**：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| `id` | Long | 是 | 文件ID |
|
||
|
||
**请求示例**：
|
||
|
||
```http
|
||
DELETE /api/file/45
|
||
```
|
||
|
||
**成功响应**（HTTP 200）：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "删除成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 响应字段说明
|
||
|
||
### 3.1 FileVO 字段详情
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
| :--- | :--- | :--- |
|
||
| `id` | Long | 文件唯一标识 |
|
||
| `fileName` | String | 文件名 |
|
||
| `filePath` | String | 文件存储路径 |
|
||
| `fileSize` | Long | 文件大小（字节） |
|
||
| `fileType` | String | MIME类型 |
|
||
| `extension` | String | 文件扩展名 |
|
||
| `uploadUserId` | Long | 上传用户ID |
|
||
| `uploadUserName` | String | 上传用户名 |
|
||
| `deptId` | Long | 所属部门ID |
|
||
| `deptName` | String | 所属部门名称 |
|
||
| `isPublic` | Integer | 是否公开（0-私有，1-公开） |
|
||
| `fileCategory` | String | 文件分类（personal-个人，rule-制度） |
|
||
| `status` | Integer | 文件状态（0-禁用，1-启用） |
|
||
| `auditStatus` | Integer | 审核状态（0-待审核，1-已通过） |
|
||
| `processStatus` | String | 向量化状态 |
|
||
| `examStatus` | String | 题目生成状态 |
|
||
| `processStepStatus` | String | **流程状态（新增）** |
|
||
| `processStepMessage` | String | **流程状态描述（新增）** |
|
||
| `processMessage` | String | 处理信息/错误消息 |
|
||
| `createTime` | String | 创建时间 |
|
||
| `updateTime` | String | 更新时间 |
|
||
|
||
---
|
||
|
||
## 4. 状态字段说明
|
||
|
||
### 4.1 processStepStatus（流程状态 - 新增）
|
||
|
||
| 值 | 说明 |
|
||
| :--- | :--- |
|
||
| `UPLOADED` | 文件已上传 |
|
||
| `VECTORIZING` | 正在向量化 |
|
||
| `VECTORIZED` | 向量化完成 |
|
||
| `VECTORIZE_FAILED` | 向量化失败 |
|
||
| `EXAM_GENERATING` | 正在生成题目 |
|
||
| `EXAM_GENERATED` | 题目生成完成 |
|
||
| `EXAM_GENERATE_FAILED` | 题目生成失败 |
|
||
| `COMPLETED` | 全部流程完成 |
|
||
|
||
### 4.2 processStatus（向量化状态）
|
||
|
||
| 值 | 说明 |
|
||
| :--- | :--- |
|
||
| `PENDING` | 未入库 |
|
||
| `INDEXED` | 已入库 |
|
||
| `VECTORIZING` | 正在向量化 |
|
||
| `FAILED` | 失败 |
|
||
|
||
### 4.3 examStatus（题目生成状态）
|
||
|
||
| 值 | 说明 |
|
||
| :--- | :--- |
|
||
| `UNGENERATED` | 未出题 |
|
||
| `GENERATING` | 出题中 |
|
||
| `GENERATED` | 已有题目 |
|
||
| `FAILED` | 出题失败 |
|
||
|
||
---
|
||
|
||
## 5. 状态流转图
|
||
|
||
```
|
||
文件上传
|
||
↓
|
||
UPLOADED (文件已上传)
|
||
↓
|
||
VECTORIZING (正在向量化)
|
||
↓
|
||
VECTORIZED (向量化完成)
|
||
↓
|
||
EXAM_GENERATING (正在生成题目)
|
||
↓
|
||
EXAM_GENERATED (题目生成完成)
|
||
↓
|
||
COMPLETED (全部流程完成) ✓
|
||
|
||
失败路径：
|
||
VECTORIZING → VECTORIZE_FAILED (向量化失败)
|
||
EXAM_GENERATING → EXAM_GENERATE_FAILED (题目生成失败)
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 前端展示建议
|
||
|
||
### 6.1 状态映射函数
|
||
|
||
```javascript
|
||
// 根据流程状态显示对应文案
|
||
function getStatusText(status) {
|
||
const statusMap = {
|
||
'UPLOADED': '文件已上传',
|
||
'VECTORIZING': '正在向量化...',
|
||
'VECTORIZED': '向量化完成',
|
||
'VECTORIZE_FAILED': '向量化失败',
|
||
'EXAM_GENERATING': '正在生成题目...',
|
||
'EXAM_GENERATED': '题目生成完成',
|
||
'EXAM_GENERATE_FAILED': '题目生成失败',
|
||
'COMPLETED': '已完成'
|
||
};
|
||
return statusMap[status] || '未知状态';
|
||
}
|
||
|
||
// 获取状态对应的颜色
|
||
function getStatusColor(status) {
|
||
const colorMap = {
|
||
'UPLOADED': '#6B7280',
|
||
'VECTORIZING': '#3B82F6',
|
||
'VECTORIZED': '#8B5CF6',
|
||
'VECTORIZE_FAILED': '#EF4444',
|
||
'EXAM_GENERATING': '#F59E0B',
|
||
'EXAM_GENERATED': '#10B981',
|
||
'EXAM_GENERATE_FAILED': '#EF4444',
|
||
'COMPLETED': '#10B981'
|
||
};
|
||
return colorMap[status] || '#6B7280';
|
||
}
|
||
```
|
||
|
||
### 6.2 展示示例
|
||
|
||
```html
|
||
<!-- 文件状态标签 -->
|
||
<span
|
||
class="status-tag"
|
||
:style="{ backgroundColor: getStatusColor(file.processStepStatus) }"
|
||
>
|
||
{{ getStatusText(file.processStepStatus) }}
|
||
</span>
|
||
|
||
<!-- 状态详情 -->
|
||
<div v-if="file.processStepMessage">
|
||
{{ file.processStepMessage }}
|
||
</div>
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 错误码说明
|
||
|
||
| 错误码 | 说明 |
|
||
| :--- | :--- |
|
||
| 401 | 用户未登录或Token无效 |
|
||
| 403 | 无权限访问该文件 |
|
||
| 404 | 文件不存在 |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
---
|
||
|
||
## 8. 接口实现位置
|
||
|
||
- **Controller**：[FileController.java](file:///C:/Users/35018/Desktop/demo/src/main/java/top/tqx/demo_1/controller/FileController.java)
|
||
- **Service**：[FileServiceImpl.java](file:///C:/Users/35018/Desktop/demo/src/main/java/top/tqx/demo_1/service/impl/FileServiceImpl.java)
|
||
- **实体类**：[File.java](file:///C:/Users/35018/Desktop/demo/src/main/java/top/tqx/demo_1/entity/File.java)
|
||
- **视图对象**：[FileVO.java](file:///C:/Users/35018/Desktop/demo/src/main/java/top/tqx/demo_1/vo/FileVO.java)
|
||
|
||
---
|
||
|
||
**版本**：V2.12.0
|
||
**生成时间**：2026-05-29 |