# 文件管理接口文档

## 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