# 文件管理系统 API 接口文档

## 基础信息

- **Base URL**: `http://localhost:8080/api`
- **认证方式**: Bearer Token (在请求头中添加 `Authorization: Bearer {token}`)
- **响应格式**: JSON

## 通用响应结构

### 成功响应json { "code": 200, "message": "success", "data": {} }

***

## 1. 认证模块 (/auth)

### 1.1 用户登录

**接口地址**: `POST /auth/login`

**请求体**:json { "username": "string", "password": "string" }

**响应数据**:json { "code": 200, "message": "success", "data": { "token": "string", "refreshToken": "string", "expiresIn": 86400000, "userInfo": { "id": 1, "username": "string", "realName": "string", "email": "string", "phone": "string", "avatar": "string" } } }

***

### 1.2 用户登出

**接口地址**: `POST /auth/logout`

**请求头**:Authorization: Bearer {token}

**响应数据**:json { "code": 200, "message": "success", "data": null }

***

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

**接口地址**: `GET /auth/user/info`

**请求头**:Authorization: Bearer {token}

**响应数据**:json { "code": 200, "message": "success", "data": { "id": 1, "username": "string", "realName": "string", "email": "string", "phone": "string", "avatar": "string" } }

***

### 1.4 获取当前用户角色列表

**接口地址**: `GET /auth/user/roles`

**请求头**:Authorization: Bearer {token}

**响应数据**:json { "code": 200, "message": "success", "data": \["admin", "user"] }

***

### 1.5 获取当前用户主要角色

**接口地址**: `GET /auth/user/main-role`

**请求头**:Authorization: Bearer {token}

**响应数据**:json { "code": 200, "message": "success", "data": { "roleName": "admin" } }

***

## 2. 用户管理模块 (/api/users)

### 2.1 分页查询用户列表

**接口地址**: `GET /api/users`

**请求头**:Authorization: Bearer {token}

**查询参数**:

| 参数名      | 类型      | 必填 | 说明         |
| -------- | ------- | -- | ---------- |
| current  | Integer | 否  | 当前页码，默认1   |
| size     | Integer | 否  | 每页条数，默认10  |
| username | String  | 否  | 用户名（模糊查询）  |
| realName | String  | 否  | 真实姓名（模糊查询） |

**响应数据**:json { "code": 200, "message": "success", "data": { "records": \[ { "id": 1, "username": "string", "realName": "string", "email": "string", "phone": "string", "avatar": "string", "status": 1, "deptId": 1, "deptName": "string", "roles": \[ { "id": 1, "roleName": "string", "roleCode": "string" } ], "createTime": "2024-01-01T00:00:00", "updateTime": "2024-01-01T00:00:00" } ], "total": 100, "size": 10, "current": 1, "pages": 10 } }

***

### 2.2 创建用户

**接口地址**: `POST /api/users`

**请求头**:Authorization: Bearer {token}

**请求体**:json { "username": "string", "password": "string", "realName": "string", "email": "string", "phone": "string", "deptId": 1, "roleIds": \[1, 2] }

**响应数据**:json { "code": 200, "message": "success", "data": null }

***

### 2.3 更新用户

**接口地址**: `PUT /api/users/{id}`

**请求头**:Authorization: Bearer {token}

**路径参数**:

| 参数名 | 类型   | 必填 | 说明   |
| --- | ---- | -- | ---- |
| id  | Long | 是  | 用户ID |

**请求体**:json { "realName": "string", "email": "string", "phone": "string", "deptId": 1, "status": 1 }

**响应数据**:json { "code": 200, "message": "success", "data": null }

***

### 2.4 删除用户

**接口地址**: `DELETE /api/users/{id}`

**请求头**:Authorization: Bearer {token}

**路径参数**:

| 参数名 | 类型   | 必填 | 说明   |
| --- | ---- | -- | ---- |
| id  | Long | 是  | 用户ID |

**响应数据**:json { "code": 200, "message": "success", "data": null }

***

### 2.5 分配用户角色

**接口地址**: `PUT /api/users/{id}/roles`

**请求头**:Authorization: Bearer {token}

**路径参数**:

| 参数名 | 类型   | 必填 | 说明   |
| --- | ---- | -- | ---- |
| id  | Long | 是  | 用户ID |

**请求体**:json \[1, 2, 3]

**响应数据**:json { "code": 200, "message": "success", "data": null }

***

### 2.6 获取用户权限列表

**接口地址**: `GET /api/users/{id}/permissions`

**请求头**:Authorization: Bearer {token}

**路径参数**:

| 参数名 | 类型   | 必填 | 说明   |
| --- | ---- | -- | ---- |
| id  | Long | 是  | 用户ID |

**响应数据**:json { "code": 200, "message": "success", "data": \["file:read", "file:write", "user:manage"] }

***

## 3. 角色管理模块 (/api/roles)

### 3.1 获取所有角色列表

**接口地址**: `GET /api/roles`

**请求头**:Authorization: Bearer {token}

**响应数据**:json { "code": 200, "message": "success", "data": \[ { "id": 1, "roleName": "管理员", "roleCode": "admin", "description": "系统管理员", "status": 1, "createTime": "2024-01-01T00:00:00", "updateTime": "2024-01-01T00:00:00" } ] }

### 3.2 创建角色

**接口地址**: `POST /api/roles`

**请求头**:Authorization: Bearer {token}

**请求体**:json { "roleName": "string", "roleCode": "string", "description": "string", "status": 1 }

**响应数据**:json { "code": 200, "message": "success", "data": null }

***

### 3.3 更新角色

**接口地址**: `PUT /api/roles/{id}`

**请求头**:Authorization: Bearer {token}

**路径参数**:

| 参数名 | 类型   | 必填 | 说明   |
| --- | ---- | -- | ---- |
| id  | Long | 是  | 角色ID |

**请求体**:json { "roleName": "string", "roleCode": "string", "description": "string", "status": 1 }

**响应数据**:json { "code": 200, "message": "success", "data": null }

***

### 3.4 删除角色

**接口地址**: `DELETE /api/roles/{id}`

**请求头**:Authorization: Bearer {token}

**路径参数**:

| 参数名 | 类型   | 必填 | 说明   |
| --- | ---- | -- | ---- |
| id  | Long | 是  | 角色ID |

**响应数据**:json { "code": 200, "message": "success", "data": null }

***

### 3.5 分配角色权限

**接口地址**: `PUT /api/roles/{id}/permissions`

**请求头**:Authorization: Bearer {token}

**路径参数**:

| 参数名 | 类型   | 必填 | 说明   |
| --- | ---- | -- | ---- |
| id  | Long | 是  | 角色ID |

**请求体**:json \[1, 2, 3]

**响应数据**:json { "code": 200, "message": "success", "data": null }

***

### 3.6 获取角色权限列表

**接口地址**: `GET /api/roles/{id}/permissions`

**请求头**:**路径参数**:

| 参数名 | 类型   | 必填 | 说明   |
| --- | ---- | -- | ---- |
| id  | Long | 是  | 角色ID |

**响应数据**:json { "code": 200, "message": "success", "data": \[ { "id": 1, "permissionName": "文件读取", "permissionCode": "file:read", "permissionType": "menu", "parentId": 0, "path": "/files", "icon": "file", "sortOrder": 1 } ] }

***

## 4. 部门管理模块 (/api/departments)

### 4.1 获取部门列表

**接口地址**: `GET /api/departments`

**请求头**:Authorization: Bearer {token}

**响应数据**:json { "code": 200, "message": "success", "data": \[ { "id": 1, "deptName": "技术部", "deptCode": "tech", "parentId": 0, "managerId": 1, "managerName": "张三", "description": "技术研发部门", "sortOrder": 1, "status": 1, "createTime": "2024-01-01T00:00:00", "updateTime": "2024-01-01T00:00:00" } ] }

***

### 4.2 创建部门

**接口地址**: `POST /api/departments`

**请求头**:Authorization: Bearer {token}

**请求体**:json { "deptName": "string", "deptCode": "string", "parentId": 0, "managerId": 1, "description": "string", "sortOrder": 1 }

**响应数据**:json { "code": 200, "message": "success", "data": null }

***

### 4.3 更新部门

**接口地址**: `PUT /api/departments/{id}`

**请求头**:Authorization: Bearer {token}

**路径参数**:

| 参数名 | 类型   | 必填 | 说明   |
| --- | ---- | -- | ---- |
| id  | Long | 是  | 部门ID |

**请求体**:json { "deptName": "string", "deptCode": "string", "parentId": 0, "managerId": 1, "description": "string", "sortOrder": 1, "status": 1 }

**响应数据**:json { "code": 200, "message": "success", "data": null }

***

### 4.4 删除部门

**接口地址**: `DELETE /api/departments/{id}`

**请求头**:Authorization: Bearer {token}

**路径参数**:

| 参数名 | 类型   | 必填 | 说明   |
| --- | ---- | -- | ---- |
| id  | Long | 是  | 部门ID |

**响应数据**:json { "code": 200, "message": "success", "data": null }

***

### 4.5 设置部门负责人

**接口地址**: `PUT /api/departments/{id}/manager`

**请求头**:Authorization: Bearer {token}

**路径参数**:

| 参数名 | 类型   | 必填 | 说明   |
| --- | ---- | -- | ---- |
| id  | Long | 是  | 部门ID |

**请求体**:json { "userId": 1 }

**响应数据**:json { "code": 200, "message": "success", "data": null }

***

### 4.6 获取部门用户列表

**接口地址**: `GET /api/departments/{id}/users`

**请求头**:Authorization: Bearer {token}

**路径参数**:

| 参数名 | 类型   | 必填 | 说明   |
| --- | ---- | -- | ---- |
| id  | Long | 是  | 部门ID |

**响应数据**:json { "code": 200, "message": "success", "data": \[ { "id": 1, "username": "string", "realName": "string", "email": "string", "phone": "string", "avatar": "string", "status": 1 } ] }

***

## 5. 文件管理模块 (/api/files)

### 5.1 上传文件

**接口地址**: `POST /api/files/upload`

**请求头**:Authorization: Bearer {token} 	Content-Type: multipart/form-data

**表单参数**:

| 参数名  | 类型   | 必填 | 说明     |
| ---- | ---- | -- | ------ |
| file | File | 是  | 要上传的文件 |

**响应数据**:json { "code": 200, "message": "文件上传成功", "data": { "id": 1, "fileName": "example.pdf", "fileSize": 1024000, "fileType": "application/pdf", "filePath": "/uploads/example.pdf", "fileHash": "abc123", "uploaderId": 1, "uploaderName": "张三", "deptId": 1, "deptName": "技术部", "description": "文件描述", "downloadCount": 0, "createTime": "2024-01-01T00:00:00", "updateTime": "2024-01-01T00:00:00" } }

***

### 5.2 分页查询文件列表

**接口地址**: `GET /api/files/list`

**请求头**:Authorization: Bearer {token}

**查询参数**:

| 参数名      | 类型      | 必填 | 说明        |
| -------- | ------- | -- | --------- |
| current  | Integer | 否  | 当前页码，默认1  |
| size     | Integer | 否  | 每页条数，默认10 |
| fileName | String  | 否  | 文件名（模糊查询） |
| deptId   | Long    | 否  | 部门ID      |

**响应数据**:json { "code": 200, "message": "success", "data": { "records": \[ { "id": 1, "fileName": "example.pdf", "fileSize": 1024000, "fileType": "application/pdf", "filePath": "/uploads/example.pdf", "fileHash": "abc123", "uploaderId": 1, "uploaderName": "张三", "deptId": 1, "deptName": "技术部", "description": "文件描述", "downloadCount": 0, "createTime": "2024-01-01T00:00:00", "updateTime": "2024-01-01T00:00:00" } ], "total": 100, "size": 10, "current": 1, "pages": 10 } }

***

### 5.3 获取文件详情

**接口地址**: `GET /api/files/{id}`

**请求头**:Authorization: Bearer {token}

**路径参数**:

| 参数名 | 类型   | 必填 | 说明   |
| --- | ---- | -- | ---- |
| id  | Long | 是  | 文件ID |

**响应数据**:json { "code": 200, "message": "success", "data": { "id": 1, "fileName": "example.pdf", "fileSize": 1024000, "fileType": "application/pdf", "filePath": "/uploads/example.pdf", "fileHash": "abc123", "uploaderId": 1, "uploaderName": "张三", "deptId": 1, "deptName": "技术部", "description": "文件描述", "downloadCount": 0, "createTime": "2024-01-01T00:00:00", "updateTime": "2024-01-01T00:00:00" } }

***

### 5.4 下载文件

**接口地址**: `GET /api/files/{id}/download`

**请求头**:Authorization: Bearer {token}

**路径参数**:

| 参数名 | 类型   | 必填 | 说明   |
| --- | ---- | -- | ---- |
| id  | Long | 是  | 文件ID |

**响应**: 文件流（二进制数据）

***

### 5.5 更新文件信息

**接口地址**: `PUT /api/files/{id}`

**请求头**:Authorization: Bearer {token}

**路径参数**:

| 参数名 | 类型   | 必填 | 说明   |
| --- | ---- | -- | ---- |
| id  | Long | 是  | 文件ID |

**请求体**:json { "fileName": "new-name.pdf", "description": "新的文件描述", "deptId": 1 }

**响应数据**:json { "code": 200, "message": "success", "data": null }

***

### 5.6 删除文件

**接口地址**: `DELETE /api/files/{id}`

**请求头**:Authorization: Bearer {token}

**路径参数**:

| 参数名 | 类型   | 必填 | 说明   |
| --- | ---- | -- | ---- |
| id  | Long | 是  | 文件ID |

**响应数据**:json { "code": 200, "message": "success", "data": null }

***

### 5.7 搜索文件

**接口地址**: `GET /api/files/search`

**请求头**:Authorization: Bearer {token}

**查询参数**:

| 参数名     | 类型     | 必填 | 说明    |
| ------- | ------ | -- | ----- |
| keyword | String | 是  | 搜索关键词 |

**响应数据**:json { "code": 200, "message": "success", "data": \[ { "id": 1, "fileName": "example.pdf", "fileSize": 1024000, "fileType": "application/pdf", "filePath": "/uploads/example.pdf", "fileHash": "abc123", "uploaderId": 1, "uploaderName": "张三", "deptId": 1, "deptName": "技术部", "description": "文件描述", "downloadCount": 0, "createTime": "2024-01-01T00:00:00", "updateTime": "2024-01-01T00:00:00" } ] }

***

### 5.8 获取我上传的文件

**接口地址**: `GET /api/files/my-uploads`

**请求头**:Authorization: Bearer {token}

**响应数据**:json { "code": 200, "message": "success", "data": \[ { "id": 1, "fileName": "example.pdf", "fileSize": 1024000, "fileType": "application/pdf", "filePath": "/uploads/example.pdf", "fileHash": "abc123", "uploaderId": 1, "uploaderName": "张三", "deptId": 1, "deptName": "技术部", "description": "文件描述", "downloadCount": 0, "createTime": "2024-01-01T00:00:00", "updateTime": "2024-01-01T00:00:00" } ] }

***

## 6. 文件权限模块 (/api/file-permissions)

### 6.1 授予文件权限

**接口地址**: `POST /api/file-permissions`

**请求头**:Authorization: Bearer {token}

**请求体**:json { "fileId": 1, "userId": 2, "permissionType": 1, "expireTime": "2024-12-31T23:59:59" }

**字段说明**:

- `permissionType`: 1-只读，2-读写
- `expireTime`: 过期时间（可选）

**响应数据**:json { "code": 200, "message": "success", "data": null }

***

### 6.2 撤销文件权限

**接口地址**: `DELETE /api/file-permissions/{id}`

**请求头**:Authorization: Bearer {token}

**路径参数**:

| 参数名 | 类型   | 必填 | 说明   |
| --- | ---- | -- | ---- |
| id  | Long | 是  | 权限ID |

**响应数据**:json { "code": 200, "message": "success", "data": null }

***

### 6.3 获取文件权限列表

**接口地址**: `GET /api/file-permissions/file/{fileId}`

**请求头**:Authorization: Bearer {token}

**路径参数**:

| 参数名    | 类型   | 必填 | 说明   |
| ------ | ---- | -- | ---- |
| fileId | Long | 是  | 文件ID |

**响应数据**:json { "code": 200, "message": "success", "data": \[ { "id": 1, "fileId": 1, "userId": 2, "userName": "李四", "permissionType": 1, "permissionTypeName": "只读", "grantUserId": 1, "grantUserName": "张三", "expireTime": "2024-12-31T23:59:59", "createTime": "2024-01-01T00:00:00" } ] }

***

### 6.4 更新权限过期时间

**接口地址**: `PUT /api/file-permissions/{id}/expire`

**请求头**:Authorization: Bearer {token}

**路径参数**:

| 参数名 | 类型   | 必填 | 说明   |
| --- | ---- | -- | ---- |
| id  | Long | 是  | 权限ID |

**请求体**:json { "expireTime": "2024-12-31T23:59:59" }

**响应数据**:json { "code": 200, "message": "success", "data": null }

***

## 7. 操作日志模块 (/api/logs)

### 7.1 分页查询操作日志

**接口地址**: `GET /api/logs`

**请求头**:Authorization: Bearer {token}

**查询参数**:

| 参数名           | 类型      | 必填 | 说明        |
| ------------- | ------- | -- | --------- |
| current       | Integer | 否  | 当前页码，默认1  |
| size          | Integer | 否  | 每页条数，默认10 |
| operationType | String  | 否  | 操作类型      |

**响应数据**:json { "code": 200, "message": "success", "data": { "records": \[ { "id": 1, "userId": 1, "userName": "张三", "operationType": "UPLOAD", "operationDesc": "上传文件 example.pdf", "fileId": 1, "fileName": "example.pdf", "ipAddress": "192.168.1.1", "userAgent": "Mozilla/5.0...", "createTime": "2024-01-01T00:00:00" } ], "total": 100, "size": 10, "current": 1, "pages": 10 } }

***

### 7.2 获取用户操作日志

**接口地址**: `GET /api/logs/user/{userId}`

**请求头**:Authorization: Bearer {token}

**路径参数**:

| 参数名    | 类型   | 必填 | 说明   |
| ------ | ---- | -- | ---- |
| userId | Long | 是  | 用户ID |

**响应数据**:json { "code": 200, "message": "success", "data": \[ { "id": 1, "userId": 1, "userName": "张三", "operationType": "UPLOAD", "operationDesc": "上传文件 example.pdf", "fileId": 1, "fileName": "example.pdf", "ipAddress": "192.168.1.1", "userAgent": "Mozilla/5.0...", "createTime": "2024-01-01T00:00:00" } ] }

***

### 7.3 获取文件操作日志

**接口地址**: `GET /api/logs/file/{fileId}`

**请求头**:Authorization: Bearer {token}

**路径参数**:

| 参数名    | 类型   | 必填 | 说明   |
| ------ | ---- | -- | ---- |
| fileId | Long | 是  | 文件ID |

**响应数据**:json { "code": 200, "message": "success", "data": \[ { "id": 1, "userId": 1, "userName": "张三", "operationType": "UPLOAD", "operationDesc": "上传文件 example.pdf", "fileId": 1, "fileName": "example.pdf", "ipAddress": "192.168.1.1", "userAgent": "Mozilla/5.0...", "createTime": "2024-01-01T00:00:00" } ] }

***

## 8. 问题处理模块 (/api/questions)

### 8.1 上传并处理文件（AI处理）

**接口地址**: `POST /api/questions/upload`

**请求头**:Content-Type: multipart/form-data

**表单参数**:

| 参数名   | 类型      | 必填 | 说明       |
| ----- | ------- | -- | -------- |
| files | File\[] | 是  | 要上传的多个文件 |

**响应数据**:json { "code": 200, "message": "文件上传并处理成功", "data": { "fileCount": 2, "aiResult": "AI处理结果字符串" } }

***

## 错误码说明

| 错误码 | 说明              |
| --- | --------------- |
| 200 | 成功              |
| 400 | 请求参数错误          |
| 401 | 未授权（Token无效或过期） |
| 403 | 权限不足            |
| 404 | 资源不存在           |
| 500 | 服务器内部错误         |

***

## 注意事项

1. 所有需要认证的接口都需要在请求头中携带 `Authorization: Bearer {token}`
2. 文件上传接口使用 `multipart/form-data` 格式
3. 分页查询默认返回第1页，每页10条记录
4. 时间格式统一使用 ISO 8601 格式：`yyyy-MM-ddTHH:mm:ss`
5. 文件大小限制和允许的文件类型由后端配置决定