# 文件管理 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. 硬删除会永久删除文件记录，请谨慎使用