283 lines
7.5 KiB
Markdown
283 lines
7.5 KiB
Markdown
# Tik 文件管理模块设计文档
|
||
|
||
## 一、模块概述
|
||
|
||
Tik 文件管理模块负责用户文件的上传、存储、管理和分组功能，支持多种文件类型（视频、图片、音频等）和分类管理。
|
||
|
||
## 二、表结构设计
|
||
|
||
### 2.1 核心表
|
||
|
||
#### 1. `tik_user_file` - 用户文件表
|
||
**作用**：存储用户上传的文件元数据
|
||
|
||
**关键字段**：
|
||
- `file_path` (varchar(1024)): **完整OSS路径**，格式：`{手机号MD5}/{租户ID}/{分类}/{日期}/{文件名}_{时间戳}.ext`
|
||
- `file_url` (varchar(1024)): 文件访问URL（预签名URL或公开URL）
|
||
- `oss_root_path` (varchar(256)): OSS根路径，用于快速定位用户文件目录
|
||
- `file_category`: 文件分类（video/generate/audio/mix/voice）
|
||
- `file_id`: 关联 `infra_file.id`（可选，用于关联系统文件表）
|
||
|
||
**索引设计**：
|
||
- `idx_user_id`: 用户ID索引
|
||
- `idx_file_category`: 文件分类索引
|
||
- `idx_user_tenant`: 用户+租户联合索引
|
||
- `idx_create_time`: 创建时间索引
|
||
|
||
#### 2. `tik_user_oss_init` - OSS初始化记录表
|
||
**作用**：记录用户OSS目录初始化状态和路径信息
|
||
|
||
**关键字段**：
|
||
- `mobile_md5`: 手机号MD5值（用于生成OSS路径）
|
||
- `oss_root_path`: OSS根路径
|
||
- `video_path`, `generate_path`, `audio_path`, `mix_path`, `voice_path`: 各分类目录路径
|
||
- `init_status`: 初始化状态（0-未初始化，1-已初始化）
|
||
|
||
**设计要点**：
|
||
- 懒加载策略：首次上传时自动初始化
|
||
- 路径格式：`{手机号MD5}/{租户ID}/{分类}`
|
||
|
||
#### 3. `tik_file_group` - 文件分组表
|
||
**作用**：用户自定义文件分组（支持层级分组）
|
||
|
||
**关键字段**：
|
||
- `parent_id`: 父分组ID（0表示根分组）
|
||
- `sort`: 排序字段
|
||
|
||
#### 4. `tik_user_file_group` - 文件分组关联表
|
||
**作用**：文件与分组的关联关系（支持一个文件属于多个分组）
|
||
|
||
**设计要点**：
|
||
- 多对多关系
|
||
- 唯一索引：`uk_file_group` (file_id, group_id)
|
||
|
||
#### 5. `tik_user_quota` - 用户配额表
|
||
**作用**：管理用户存储配额和VIP等级
|
||
|
||
**关键字段**：
|
||
- `total_storage`: 总存储空间（字节）
|
||
- `used_storage`: 已使用存储空间（字节）
|
||
- `vip_level`: VIP等级
|
||
|
||
## 三、架构设计
|
||
|
||
### 3.1 分层架构
|
||
|
||
```
|
||
Controller 层 (AppTikUserFileController)
|
||
↓
|
||
Service 层 (TikUserFileService)
|
||
↓
|
||
Mapper 层 (TikUserFileMapper)
|
||
↓
|
||
DataObject 层 (TikUserFileDO)
|
||
```
|
||
|
||
### 3.2 核心服务
|
||
|
||
#### 1. TikUserFileService - 文件管理服务
|
||
**职责**：
|
||
- 文件上传（带配额校验）
|
||
- 文件查询（分页、筛选）
|
||
- 文件删除（逻辑删除 + 物理删除）
|
||
- 预签名URL生成
|
||
|
||
**关键流程**：
|
||
1. **上传流程**：
|
||
```
|
||
校验文件分类 → 校验配额 → 获取OSS目录 → 生成完整路径 → 上传到OSS → 保存元数据 → 更新配额
|
||
```
|
||
|
||
2. **删除流程**：
|
||
```
|
||
校验权限 → 物理删除OSS文件 → 逻辑删除记录 → 释放配额
|
||
```
|
||
|
||
#### 2. TikOssInitService - OSS初始化服务
|
||
**职责**：
|
||
- 初始化用户OSS目录结构
|
||
- 获取OSS路径信息
|
||
- 懒加载策略实现
|
||
|
||
**设计要点**：
|
||
- OSS目录是虚拟的，不需要显式创建
|
||
- 首次上传时自动初始化
|
||
- 路径格式：`{手机号MD5}/{租户ID}/{分类}`
|
||
|
||
#### 3. TikFileGroupService - 文件分组服务
|
||
**职责**：
|
||
- 分组CRUD
|
||
- 层级分组支持
|
||
|
||
#### 4. TikUserQuotaService - 配额管理服务
|
||
**职责**：
|
||
- 配额校验
|
||
- 配额更新
|
||
- VIP等级管理
|
||
|
||
## 四、路径设计
|
||
|
||
### 4.1 OSS路径结构
|
||
|
||
```
|
||
{手机号MD5}/{租户ID}/{分类}/{日期}/{文件名}_{时间戳}.ext
|
||
```
|
||
|
||
**示例**：
|
||
```
|
||
abc123def45678901234567890123456/1/video/20250101/my_video_1234567890123.mp4
|
||
```
|
||
|
||
**路径组成部分**：
|
||
1. **手机号MD5** (32字符): 用户唯一标识，保护隐私
|
||
2. **租户ID**: 多租户隔离
|
||
3. **分类** (video/generate/audio/mix/voice): 文件分类
|
||
4. **日期** (yyyyMMdd): 按日期分目录，便于管理
|
||
5. **文件名+时间戳**: 保证唯一性，避免覆盖
|
||
|
||
### 4.2 路径存储策略
|
||
|
||
- **file_path**: 存储完整OSS路径（用于物理删除）
|
||
- **file_url**: 存储访问URL（用于前端展示）
|
||
- **oss_root_path**: 存储根路径（用于快速定位）
|
||
|
||
## 五、设计亮点
|
||
|
||
### 5.1 优点
|
||
|
||
1. **分层清晰**：Controller → Service → Mapper → DO，职责明确
|
||
2. **配额管理**：上传前校验，删除后释放
|
||
3. **多租户支持**：通过 tenant_id 隔离
|
||
4. **懒加载策略**：OSS目录按需初始化
|
||
5. **路径设计合理**：包含用户、租户、分类、日期等信息
|
||
6. **分组功能**：支持多分组、层级分组
|
||
|
||
### 5.2 需要改进的地方
|
||
|
||
1. **物理删除OSS文件**：
|
||
- 当前只做了逻辑删除，OSS文件未删除
|
||
- 建议：删除时调用 FileService 或 FileClient 删除OSS文件
|
||
- 或者：定期清理已逻辑删除的文件
|
||
|
||
2. **file_path 字段长度**：
|
||
- 当前：varchar(512)
|
||
- 建议：varchar(1024) 更安全
|
||
|
||
3. **文件关联 infra_file 表**：
|
||
- `file_id` 字段存在但未充分利用
|
||
- 建议：上传时关联 infra_file 表，便于统一管理
|
||
|
||
4. **预览图生成**：
|
||
- 视频封面和图片缩略图功能未实现
|
||
- 建议：异步生成预览图
|
||
|
||
5. **批量操作优化**：
|
||
- 删除文件时逐个删除OSS文件，可能较慢
|
||
- 建议：批量删除或异步删除
|
||
|
||
## 六、数据流
|
||
|
||
### 6.1 上传流程
|
||
|
||
```
|
||
前端上传文件
|
||
↓
|
||
Controller 接收
|
||
↓
|
||
Service 校验（分类、配额）
|
||
↓
|
||
获取OSS目录（懒加载初始化）
|
||
↓
|
||
生成完整路径
|
||
↓
|
||
上传到OSS（FileApi）
|
||
↓
|
||
保存元数据到 tik_user_file
|
||
↓
|
||
更新配额（tik_user_quota）
|
||
↓
|
||
返回文件ID
|
||
```
|
||
|
||
### 6.2 查询流程
|
||
|
||
```
|
||
前端请求文件列表
|
||
↓
|
||
Controller 接收查询参数
|
||
↓
|
||
Service 查询数据库（分页、筛选）
|
||
↓
|
||
转换为VO（生成预览URL）
|
||
↓
|
||
返回分页结果
|
||
```
|
||
|
||
### 6.3 删除流程
|
||
|
||
```
|
||
前端请求删除
|
||
↓
|
||
Controller 接收文件ID列表
|
||
↓
|
||
Service 校验权限
|
||
↓
|
||
物理删除OSS文件（TODO）
|
||
↓
|
||
逻辑删除数据库记录
|
||
↓
|
||
释放配额
|
||
↓
|
||
返回成功
|
||
```
|
||
|
||
## 七、API设计
|
||
|
||
### 7.1 文件管理API
|
||
|
||
- `POST /api/tik/file/upload` - 上传文件
|
||
- `GET /api/tik/file/page` - 分页查询
|
||
- `DELETE /api/tik/file/delete-batch` - 批量删除
|
||
- `GET /api/tik/file/video/play-url` - 获取视频播放URL
|
||
- `GET /api/tik/file/audio/play-url` - 获取音频播放URL
|
||
- `GET /api/tik/file/preview-url` - 获取预览URL
|
||
|
||
### 7.2 分组管理API
|
||
|
||
- `POST /api/tik/file/group/create` - 创建分组
|
||
- `PUT /api/tik/file/group/update` - 更新分组
|
||
- `DELETE /api/tik/file/group/delete` - 删除分组
|
||
- `GET /api/tik/file/group/list` - 查询分组列表
|
||
- `POST /api/tik/file/group/add-files` - 添加文件到分组
|
||
- `POST /api/tik/file/group/remove-files` - 从分组移除文件
|
||
|
||
## 八、总结
|
||
|
||
### 8.1 表结构建议
|
||
|
||
1. **必须修改**：
|
||
- `file_path` 字段长度：512 → 1024
|
||
|
||
2. **可选优化**：
|
||
- 添加 `file_path` 索引（如果经常按路径查询）
|
||
- 添加 `file_id` 索引（如果关联 infra_file 表）
|
||
|
||
### 8.2 功能完善建议
|
||
|
||
1. **物理删除OSS文件**：删除时调用 FileService 删除OSS文件
|
||
2. **预览图生成**：实现视频封面和图片缩略图异步生成
|
||
3. **文件关联**：充分利用 `file_id` 关联 infra_file 表
|
||
4. **批量操作优化**：优化批量删除性能
|
||
|
||
### 8.3 整体评价
|
||
|
||
**设计评分：8.5/10**
|
||
|
||
- ✅ 架构清晰，分层合理
|
||
- ✅ 路径设计合理，支持多租户
|
||
- ✅ 配额管理完善
|
||
- ⚠️ 物理删除功能缺失
|
||
- ⚠️ 预览图功能未实现
|
||
- ⚠️ 部分字段未充分利用
|
||
|