328 lines
7.1 KiB
Markdown
328 lines
7.1 KiB
Markdown
# 文件管理 API 文档
|
||
|
||
## 概述
|
||
|
||
文件管理模块提供对 `yz_files` 表的完整 CRUD 操作，支持文件信息的管理、搜索和统计功能。
|
||
|
||
## 数据库表结构
|
||
|
||
```sql
|
||
CREATE TABLE yz_files (
|
||
id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '文件ID',
|
||
tenant_id VARCHAR(64) NOT NULL COMMENT '租户ID',
|
||
|
||
-- 文件基础信息
|
||
file_name VARCHAR(255) NOT NULL COMMENT '文件名称',
|
||
original_name VARCHAR(255) NOT NULL COMMENT '原始文件名',
|
||
file_path VARCHAR(500) NOT NULL COMMENT '文件存储路径',
|
||
file_url VARCHAR(500) COMMENT '文件访问URL',
|
||
file_size BIGINT NOT NULL DEFAULT 0 COMMENT '文件大小(字节)',
|
||
file_type VARCHAR(50) NOT NULL COMMENT '文件类型',
|
||
file_ext VARCHAR(20) NOT NULL COMMENT '文件扩展名',
|
||
|
||
-- 分类信息
|
||
category VARCHAR(100) NOT NULL COMMENT '文件分类',
|
||
sub_category VARCHAR(100) COMMENT '子分类',
|
||
|
||
-- 状态信息
|
||
status TINYINT DEFAULT 1 COMMENT '状态(1:正常, 0:删除)',
|
||
is_public TINYINT DEFAULT 0 COMMENT '是否公开(1:是, 0:否)',
|
||
|
||
-- 上传信息
|
||
upload_by VARCHAR(100) NOT NULL COMMENT '上传人',
|
||
upload_time DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '上传时间',
|
||
|
||
-- 索引
|
||
INDEX idx_tenant (tenant_id),
|
||
INDEX idx_category (category),
|
||
INDEX idx_upload_time (upload_time),
|
||
INDEX idx_status (status)
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='文件表';
|
||
```
|
||
|
||
## API 接口列表
|
||
|
||
### 1. 获取所有文件信息
|
||
|
||
**GET** `/api/files`
|
||
|
||
**认证方式**: JWT认证
|
||
|
||
**参数**: 无
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "获取成功",
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"tenant_id": "default",
|
||
"user_id": 1,
|
||
"file_name": "example.pdf",
|
||
"original_name": "example.pdf",
|
||
"file_path": "/uploads/2024/01/01/example.pdf",
|
||
"file_url": "http://example.com/uploads/2024/01/01/example.pdf",
|
||
"file_size": 1024,
|
||
"file_type": "application/pdf",
|
||
"file_ext": "pdf",
|
||
"category": "文档",
|
||
"sub_category": "PDF",
|
||
"status": 1,
|
||
"is_public": 0,
|
||
"upload_by": "admin",
|
||
"upload_time": "2024-01-01T10:00:00Z"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 2. 获取当前用户的文件列表
|
||
|
||
**GET** `/api/files/my`
|
||
|
||
**认证方式**: JWT认证
|
||
|
||
**参数**: 无
|
||
|
||
**说明**: 通过JWT token自动获取当前登录用户的文件列表
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "获取成功",
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"tenant_id": "default",
|
||
"user_id": 1,
|
||
"file_name": "example.pdf",
|
||
"original_name": "example.pdf",
|
||
"file_path": "/uploads/2024/01/01/example.pdf",
|
||
"file_url": "http://example.com/uploads/2024/01/01/example.pdf",
|
||
"file_size": 1024,
|
||
"file_type": "application/pdf",
|
||
"file_ext": "pdf",
|
||
"category": "文档",
|
||
"sub_category": "PDF",
|
||
"status": 1,
|
||
"is_public": 0,
|
||
"upload_by": "admin",
|
||
"upload_time": "2024-01-01T10:00:00Z"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 2. 根据ID获取文件信息
|
||
|
||
**GET** `/api/files/:id`
|
||
|
||
**参数**:
|
||
- `id` (路径参数): 文件ID
|
||
|
||
**响应**: 同获取所有文件接口
|
||
|
||
### 3. 创建文件信息
|
||
|
||
**POST** `/api/files`
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"tenant_id": "tenant-001",
|
||
"file_name": "new-file.txt",
|
||
"original_name": "原始文件.txt",
|
||
"file_path": "/uploads/tenant-001/new-file.txt",
|
||
"file_url": "http://localhost:8080/uploads/tenant-001/new-file.txt",
|
||
"file_size": 1024,
|
||
"file_type": "text/plain",
|
||
"file_ext": "txt",
|
||
"category": "文本",
|
||
"sub_category": "TXT",
|
||
"status": 1,
|
||
"is_public": 0,
|
||
"upload_by": "admin"
|
||
}
|
||
```
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "创建文件成功",
|
||
"data": {
|
||
"id": 2,
|
||
... // 创建的文件信息
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 更新文件信息
|
||
|
||
**PUT** `/api/files/:id`
|
||
|
||
**参数**:
|
||
- `id` (路径参数): 文件ID
|
||
|
||
**请求体**: 同创建文件接口
|
||
|
||
**响应**: 同创建文件接口
|
||
|
||
### 5. 删除文件（软删除）
|
||
|
||
**DELETE** `/api/files/:id`
|
||
|
||
**参数**:
|
||
- `id` (路径参数): 文件ID
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "删除文件成功"
|
||
}
|
||
```
|
||
|
||
### 6. 硬删除文件
|
||
|
||
**DELETE** `/api/files/:id/hard`
|
||
|
||
**参数**:
|
||
- `id` (路径参数): 文件ID
|
||
|
||
**响应**: 同软删除接口
|
||
|
||
### 7. 根据租户ID获取文件
|
||
|
||
**GET** `/api/files/tenant?tenant_id=tenant-001`
|
||
|
||
**参数**:
|
||
- `tenant_id` (查询参数): 租户ID
|
||
|
||
**响应**: 同获取所有文件接口
|
||
|
||
### 8. 根据分类获取文件
|
||
|
||
**GET** `/api/files/category?category=文档`
|
||
|
||
**参数**:
|
||
- `category` (查询参数): 文件分类
|
||
|
||
**响应**: 同获取所有文件接口
|
||
|
||
### 9. 根据状态获取文件
|
||
|
||
**GET** `/api/files/status?status=1`
|
||
|
||
**参数**:
|
||
- `status` (查询参数): 文件状态 (1:正常, 0:删除)
|
||
|
||
**响应**: 同获取所有文件接口
|
||
|
||
### 10. 获取文件统计信息
|
||
|
||
**GET** `/api/files/statistics?tenant_id=tenant-001`
|
||
|
||
**参数**:
|
||
- `tenant_id` (查询参数): 租户ID
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "获取统计信息成功",
|
||
"data": {
|
||
"total_count": 10,
|
||
"total_size": 10485760,
|
||
"category_stats": [
|
||
{
|
||
"category": "文档",
|
||
"count": 5,
|
||
"size": 5242880
|
||
},
|
||
{
|
||
"category": "图片",
|
||
"count": 3,
|
||
"size": 3145728
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 11. 搜索文件
|
||
|
||
**GET** `/api/files/search?keyword=文档&tenant_id=tenant-001`
|
||
|
||
**参数**:
|
||
- `keyword` (查询参数): 搜索关键词
|
||
- `tenant_id` (查询参数): 租户ID
|
||
|
||
**响应**: 同获取所有文件接口
|
||
|
||
### 12. 公开接口（无需认证）
|
||
|
||
**GET** `/api/files/public`
|
||
|
||
**参数**: 无
|
||
|
||
**响应**: 同获取所有文件接口
|
||
|
||
## 错误响应
|
||
|
||
所有接口在发生错误时返回统一的错误格式：
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "错误描述",
|
||
"error": "详细错误信息"
|
||
}
|
||
```
|
||
|
||
## 状态码说明
|
||
|
||
- `200`: 请求成功
|
||
- `400`: 参数错误
|
||
- `404`: 资源不存在
|
||
- `500`: 服务器内部错误
|
||
|
||
## 使用示例
|
||
|
||
### 前端调用示例（JavaScript）
|
||
|
||
```javascript
|
||
// 获取所有文件
|
||
const response = await fetch('/api/files');
|
||
const result = await response.json();
|
||
|
||
// 创建文件
|
||
const newFile = {
|
||
tenant_id: "tenant-001",
|
||
file_name: "example.txt",
|
||
original_name: "示例文件.txt",
|
||
file_path: "/uploads/example.txt",
|
||
file_type: "text/plain",
|
||
file_ext: "txt",
|
||
category: "文档",
|
||
upload_by: "user123"
|
||
};
|
||
|
||
const createResponse = await fetch('/api/files', {
|
||
method: 'POST',
|
||
headers: {
|
||
'Content-Type': 'application/json'
|
||
},
|
||
body: JSON.stringify(newFile)
|
||
});
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. 所有需要认证的接口都需要在请求头中包含有效的 JWT Token
|
||
2. 文件上传功能需要配合文件存储服务实现
|
||
3. 软删除只是标记文件状态为删除，实际数据仍然保留
|
||
4. 硬删除会永久删除文件记录，请谨慎使用 |