7.5 KiB
7.5 KiB
Tik 文件管理模块设计文档
一、模块概述
Tik 文件管理模块负责用户文件的上传、存储、管理和分组功能，支持多种文件类型（视频、图片、音频等）和分类管理。
二、表结构设计
2.1 核心表
1. tik_user_file - 用户文件表
作用：存储用户上传的文件元数据
关键字段：
file_path(varchar(1024)): 完整OSS路径，格式：{手机号MD5}/{租户ID}/{分类}/{日期}/{文件名}_{时间戳}.extfile_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生成
关键流程：
-
上传流程：
校验文件分类 → 校验配额 → 获取OSS目录 → 生成完整路径 → 上传到OSS → 保存元数据 → 更新配额 -
删除流程：
校验权限 → 物理删除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
路径组成部分：
- 手机号MD5 (32字符): 用户唯一标识，保护隐私
- 租户ID: 多租户隔离
- 分类 (video/generate/audio/mix/voice): 文件分类
- 日期 (yyyyMMdd): 按日期分目录，便于管理
- 文件名+时间戳: 保证唯一性，避免覆盖
4.2 路径存储策略
- file_path: 存储完整OSS路径（用于物理删除）
- file_url: 存储访问URL（用于前端展示）
- oss_root_path: 存储根路径（用于快速定位）
五、设计亮点
5.1 优点
- 分层清晰：Controller → Service → Mapper → DO，职责明确
- 配额管理：上传前校验，删除后释放
- 多租户支持：通过 tenant_id 隔离
- 懒加载策略：OSS目录按需初始化
- 路径设计合理：包含用户、租户、分类、日期等信息
- 分组功能：支持多分组、层级分组
5.2 需要改进的地方
-
物理删除OSS文件：
- 当前只做了逻辑删除，OSS文件未删除
- 建议：删除时调用 FileService 或 FileClient 删除OSS文件
- 或者：定期清理已逻辑删除的文件
-
file_path 字段长度：
- 当前：varchar(512)
- 建议：varchar(1024) 更安全
-
文件关联 infra_file 表：
file_id字段存在但未充分利用- 建议：上传时关联 infra_file 表，便于统一管理
-
预览图生成：
- 视频封面和图片缩略图功能未实现
- 建议：异步生成预览图
-
批量操作优化：
- 删除文件时逐个删除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- 获取视频播放URLGET /api/tik/file/audio/play-url- 获取音频播放URLGET /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 表结构建议
-
必须修改：
file_path字段长度：512 → 1024
-
可选优化：
- 添加
file_path索引（如果经常按路径查询） - 添加
file_id索引（如果关联 infra_file 表）
- 添加
8.2 功能完善建议
- 物理删除OSS文件：删除时调用 FileService 删除OSS文件
- 预览图生成：实现视频封面和图片缩略图异步生成
- 文件关联：充分利用
file_id关联 infra_file 表 - 批量操作优化：优化批量删除性能
8.3 整体评价
设计评分：8.5/10
- ✅ 架构清晰，分层合理
- ✅ 路径设计合理，支持多租户
- ✅ 配额管理完善
- ⚠️ 物理删除功能缺失
- ⚠️ 预览图功能未实现
- ⚠️ 部分字段未充分利用