sionrui/yudao-module-tik/DESIGN.md

# 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**

- ✅ 架构清晰，分层合理
- ✅ 路径设计合理，支持多租户
- ✅ 配额管理完善
- ⚠️ 物理删除功能缺失
- ⚠️ 预览图功能未实现
- ⚠️ 部分字段未充分利用