first commit

2025-10-27 23:13:08 +08:00
commit 476c5e7658
2968 changed files with 49547 additions and 0 deletions
@@ -0,0 +1,328 @@
+# 文件管理 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. 硬删除会永久删除文件记录，请谨慎使用