文件管理模块实现教程

// 修正点：文件/文件夹各自维护 keyset 游标，不再用单一 nextCursor 混比
result := &ListResult{
    Files:       files,
    Folders:     folders,
    FileCursor:  fileCursor,   // 数字 offset 或 created_at 时间戳，二选一并统一
    FolderCursor: folderCursor,
    HasMore:     len(files) >= pageSize || len(folders) >= pageSize,
}

// 修正点：单文件上传也必须净化文件名 + 拦截危险类型，与 SecUpload/InitUpload 一致
func (uc *FileUsecase) Upload(ctx context.Context, userID uint64, name, fileType string, parentID *uint64, data []byte) (*File, error) {
    fileSize := int64(len(data))
    name = sanitizeFileName(name)            // 修正点：补净化
    if isDangerousFileType(name) {           // 修正点：补危险类型拦截
        return nil, perrors.BadRequest("FILE_TYPE_FORBIDDEN", "不允许上传此类型的文件")
    }
    if uc.userUC != nil {
        if err := uc.userUC.CheckStorageAvailable(ctx, userID, fileSize); err != nil {
            return nil, err
        }
    }
    // ... 其余逻辑不变
}

// 修正点：增量更新必须带上限约束，防止并发通过前置检查后超配额
result := r.db.WithContext(ctx).Model(&model.User{}).
    Where("id = ? AND used_storage + ? <= total_storage", userID, delta).
    UpdateColumn("used_storage", gorm.Expr("used_storage + ?", delta))
// RowsAffected == 0 → 区分 用户不存在 / 空间不足（同减少分支）

// ListFiles 使用键集分页返回父目录下的文件和文件夹
func (uc *FileUsecase) ListFiles(ctx context.Context, userID uint64, parentID *uint64, cursor string, pageSize int, sortBy, sortOrder string) (*ListResult, error) {
    // 默认每页 20 条
    if pageSize <= 0 {
        pageSize = defaultPageSize
    }
    // 默认升序
    if sortOrder == "" {
        sortOrder = "asc"
    }

    // 仅第一页（cursor 为空）才查缓存，避免翻页时拿到过期数据
    cacheKey := ""
    if cursor == "" && uc.cache != nil {
        // 拼接缓存键：files:list:{userID}:{parentID}:{sortBy}:{sortOrder}
        parentStr := "root"
        if parentID != nil {
            parentStr = strconv.FormatUint(*parentID, 10)
        }
        cacheKey = fmt.Sprintf("files:list:%d:%s:%s:%s", userID, parentStr, sortBy, sortOrder)

        // 尝试缓存命中，命中则反序列化后直接返回
        cached, err := uc.cache.Get(ctx, cacheKey)
        if err == nil && cached != "" {
            var result ListResult
            if json.Unmarshal([]byte(cached), &result) == nil {
                return &result, nil
            }
        }
    }

    // 并行查询文件与文件夹（两者使用同一 cursor 与 limit）
    files, fileCursor, err := uc.fileRepo.ListByParent(ctx, userID, parentID, 0, cursor, pageSize, sortBy, sortOrder)
    if err != nil {
        return nil, err
    }
    folders, folderCursor, err := uc.folderRepo.ListByParent(ctx, userID, parentID, cursor, pageSize, sortBy, sortOrder)
    if err != nil {
        return nil, err
    }

    // 下一页游标取两者较大值，确保两边都翻到下一页
    // 修正点：fileCursor 是数字 offset、folderCursor 是时间戳，二者不可比较；
    // 商用版应改为分别返回 FileCursor / FolderCursor（见三.3）
    nextCursor := fileCursor
    if folderCursor > nextCursor {
        nextCursor = folderCursor
    }

    // 组装返回结果，HasMore 判断是否还有下一页
    result := &ListResult{
        Files:      files,
        Folders:    folders,
        NextCursor: nextCursor,
        HasMore:    len(files) >= pageSize || len(folders) >= pageSize,
    }

    // 第一页写入缓存，TTL = 42s + 随机 [0, 18)s，即 60s ±30% 抖动，防止缓存雪崩
    if cursor == "" && cacheKey != "" && uc.cache != nil {
        if data, err := json.Marshal(result); err == nil {
            ttl := 42*time.Second + time.Duration(time.Now().Nanosecond()%18)*time.Second
            uc.cache.Set(ctx, cacheKey, string(data), ttl)
        }
    }

    return result, nil
}

// ListByParent 使用键集分页返回给定父文件夹下的子文件夹
func (r *folderRepo) ListByParent(ctx context.Context, userID uint64, parentID *uint64, cursor string, limit int, sortBy, sortOrder string) ([]*biz.Folder, string, error) {
    // 基础查询条件：限定用户
    query := r.db.WithContext(ctx).Model(&model.Folder{}).
        Where("user_id = ?", userID)

    // 处理 parent_id：nil 表示根级别（parent_id IS NULL）
    if parentID == nil {
        query = query.Where("parent_id IS NULL")
    } else {
        query = query.Where("parent_id = ?", *parentID)
    }

    // keyset 分页核心：根据游标（上一页最后一条的 created_at）做范围查询
    // 降序查小于游标的，升序查大于游标的，避免 offset 深翻页性能问题
    if cursor != "" {
        if sortOrder == "desc" {
            query = query.Where("created_at < ?", cursor)
        } else {
            query = query.Where("created_at > ?", cursor)
        }
    }

    // 排序规则：按名称或按创建时间
    orderClause := "created_at ASC"
    if sortBy == "name" {
        orderClause = fmt.Sprintf("name %s", sortOrder)
    } else {
        if sortOrder == "desc" {
            orderClause = "created_at DESC"
        }
    }

    // 多查一条（limit + 1）用于判断是否还有下一页
    var pos []model.Folder
    if err := query.Order(orderClause).Limit(limit + 1).Find(&pos).Error; err != nil {
        return nil, "", err
    }

    // 截取前 limit 条，多余的用于 HasMore 判断
    hasMore := len(pos) > limit
    if hasMore {
        pos = pos[:limit]
    }

    // 下一页游标 = 当前页最后一条的 created_at（带毫秒精度）
    var nextCursor string
    if len(pos) > 0 {
        nextCursor = pos[len(pos)-1].CreatedAt.Format("2006-01-02 15:04:05.000")
    }

    // PO -> 领域对象转换
    folders := make([]*biz.Folder, len(pos))
    for i := range pos {
        folders[i] = toBizFolder(&pos[i])
    }
    return folders, nextCursor, nil
}

func (uc *FileUsecase) CreateFolder(ctx context.Context, userID uint64, name string, parentID *uint64) (*Folder, error) {
    // 净化文件夹名称：取 base 名、替换危险字符、限制长度
    name = sanitizeFileName(name)
    if name == "" {
        return nil, perrors.BadRequest("FOLDER_NAME_REQUIRED", "文件夹名称不能为空")
    }
    // 生成 UUID v4 作为文件夹唯一标识
    uuid, err := newUUID()
    if err != nil {
        return nil, err
    }
    // 构造领域对象：parentID 为 nil 表示根目录，非 nil 表示子目录（多级支持）
    folder := &Folder{
        UUID:     uuid,
        UserID:   userID,
        Name:     name,
        ParentID: parentID,
    }
    // 调用仓储写入数据库
    created, err := uc.folderRepo.Create(ctx, folder)
    if err != nil {
        return nil, err
    }

    // 失效当前目录的列表缓存（按 pattern 批量删除该目录所有排序组合）
    uc.invalidateFileListCache(ctx, userID, parentID)

    return created, nil
}

// ListAllSubDirectoryIDs 递归获取指定目录下的所有子目录 ID（不包含自身）
// 用于分类查询场景：查询某目录及其所有子目录下的文件
func (r *folderRepo) ListAllSubDirectoryIDs(ctx context.Context, userID uint64, parentID uint64) ([]uint64, error) {
    var ids []uint64
    // 查询直接子目录
    var children []model.Folder
    if err := r.db.WithContext(ctx).
        Where("user_id = ? AND parent_id = ?", userID, parentID).
        Find(&children).Error; err != nil {
        return nil, err
    }
    // 递归查询每个子目录的孙目录
    for _, c := range children {
        ids = append(ids, c.ID)
        subIDs, err := r.ListAllSubDirectoryIDs(ctx, userID, c.ID)
        if err != nil {
            return nil, err
        }
        ids = append(ids, subIDs...)
    }
    return ids, nil
}

func (uc *FileUsecase) SecUpload(ctx context.Context, userID uint64, hash, name string, parentID *uint64) (*File, bool, error) {
    // 安全校验：净化文件名 + 拦截危险文件类型
    name = sanitizeFileName(name)
    if isDangerousFileType(name) {
        return nil, false, perrors.BadRequest("FILE_TYPE_FORBIDDEN", "不允许上传此类型的文件")
    }

    // 核心步骤 1：按 user_id + hash 查询是否已有相同内容的文件
    existing, err := uc.fileRepo.FindByHash(ctx, userID, hash)
    if err != nil {
        // 未找到 -> 不存在同哈希文件，返回 exists=false 让客户端走正常上传
        if perrors.IsNotFound(err) {
            return nil, false, nil
        }
        return nil, false, err
    }

    // 核心步骤 2：校验存储空间是否充足（秒传也要占用用户配额）
    if uc.userUC != nil {
        if err := uc.userUC.CheckStorageAvailable(ctx, userID, existing.Size); err != nil {
            return nil, false, err
        }
    }

    // 生成新 UUID（每条 file 记录独立 UUID）
    uuid, err := newUUID()
    if err != nil {
        return nil, false, err
    }
    // 核心步骤 3：复用 existing.Path（物理存储路径相同），仅新建元数据记录
    // 大小、类型、哈希、路径全部复用，零字节传输
    file := &File{
        UUID:     uuid,
        UserID:   userID,
        Name:     name,
        Size:     existing.Size,
        Type:     existing.Type,
        Hash:     existing.Hash,
        Path:     existing.Path,
        ParentID: parentID,
        Status:   0,
    }
    created, err := uc.fileRepo.Create(ctx, file)
    if err != nil {
        return nil, false, err
    }

    // 累加用户已用存储空间（带分布式锁，原子更新）
    if uc.userUC != nil {
        if err := uc.userUC.AddUsedStorage(ctx, userID, existing.Size); err != nil {
            log.Error("file: failed to add used storage after copy upload", "userID", userID, "err", err)
        }
    }

    // 失效目录列表缓存
    uc.invalidateFileListCache(ctx, userID, parentID)

    // 返回 exists=true 表示秒传成功
    return created, true, nil
}

// FindByHash 根据特定用户的 SHA-256 哈希值检索文件
// 用于秒传：如果该用户存在相同哈希值的文件则返回
// 走 (user_id, hash) 联合索引，命中后 O(1) 返回
func (r *fileRepo) FindByHash(ctx context.Context, userID uint64, hash string) (*biz.File, error) {
    var po model.File
    if err := r.db.WithContext(ctx).
        Where("user_id = ? AND hash = ? AND status = ?", userID, hash, 0). // status=0 仅查正常文件
        First(&po).Error; err != nil {
        if errors.Is(err, gorm.ErrRecordNotFound) {
            return nil, biz.ErrFileNotFound
        }
        return nil, err
    }
    return toBizFile(&po), nil
}

func (uc *FileUsecase) Upload(ctx context.Context, userID uint64, name, fileType string, parentID *uint64, data []byte) (*File, error) {
    fileSize := int64(len(data))

    // 修正点：净化文件名 + 拦截危险类型（单文件上传此前漏做）
    name = sanitizeFileName(name)
    if isDangerousFileType(name) {
        return nil, perrors.BadRequest("FILE_TYPE_FORBIDDEN", "不允许上传此类型的文件")
    }

    // 校验存储空间是否充足
    if uc.userUC != nil {
        if err := uc.userUC.CheckStorageAvailable(ctx, userID, fileSize); err != nil {
            return nil, err
        }
    }

    // 生成 UUID 与存储文件名（UUID + 扩展名，避免冲突）
    uuid, err := newUUID()
    if err != nil {
        return nil, err
    }
    ext := extractExt(name)
    fileName := uuid + ext

    // 调用 Storage 接口写入物理文件，返回存储路径
    storagePath, err := uc.storage.Upload(ctx, fileName, bytesToReader(data))
    if err != nil {
        return nil, err
    }

    // 构造文件领域对象
    file := &File{
        UUID:     uuid,
        UserID:   userID,
        Name:     name,
        Size:     fileSize,
        Type:     fileType,
        Path:     storagePath,
        ParentID: parentID,
        Status:   0,
    }
    created, err := uc.fileRepo.Create(ctx, file)
    if err != nil {
        // 关键：数据库写入失败，回滚已上传的 Storage 文件，避免孤儿文件
        if delErr := uc.storage.Delete(ctx, storagePath); delErr != nil {
            log.Error("file: failed to rollback storage upload after db create failed", "storagePath", storagePath, "err", delErr)
        }
        return nil, err
    }

    // 累加用户已用存储（修正点：务必在分布式锁内做配额上限校验，见三.12）
    if uc.userUC != nil {
        if err := uc.userUC.AddUsedStorage(ctx, userID, fileSize); err != nil {
            log.Error("file: failed to add used storage after upload", "userID", userID, "err", err)
        }
    }

    // 失效目录列表缓存
    uc.invalidateFileListCache(ctx, userID, parentID)

    return created, nil
}

// getCachedFile 从缓存获取文件元数据，未命中则查数据库并写入缓存
// 缓存键：file:meta:{fileID}，TTL = 2 分钟
func (uc *FileUsecase) getCachedFile(ctx context.Context, fileID uint64) (*File, error) {
    cacheKey := fmt.Sprintf("file:meta:%d", fileID)
    // 尝试缓存命中
    if uc.cache != nil {
        if cached, err := uc.cache.Get(ctx, cacheKey); err == nil && cached != "" {
            var f File
            if json.Unmarshal([]byte(cached), &f) == nil {
                return &f, nil
            }
        }
    }

    // 缓存未命中，查询数据库
    file, err := uc.fileRepo.FindByID(ctx, fileID)
    if err != nil {
        return nil, err
    }

    // 写入缓存（失败不影响主流程）
    if uc.cache != nil {
        if data, err := json.Marshal(file); err == nil {
            _ = uc.cache.Set(ctx, cacheKey, string(data), fileMetaCacheTTL)
        }
    }
    return file, nil
}

func (uc *FileUsecase) Download(ctx context.Context, userID uint64, fileID uint64) (*File, []byte, string, error) {
    // 使用缓存获取文件元数据，减少 MySQL 查询
    file, err := uc.getCachedFile(ctx, fileID)
    if err != nil {
        return nil, nil, "", err
    }
    // 权限校验：仅文件所有者可下载（IDOR 防护）
    if file.UserID != userID {
        return nil, nil, "", ErrForbidden
    }
    // 状态校验：回收站/已删除文件不可下载
    if file.Status != 0 {
        return nil, nil, "", ErrFileNotFound
    }

    // 从 Storage 下载文件字节流
    reader, err := uc.storage.Download(ctx, file.Path)
    if err != nil {
        return nil, nil, "", err
    }
    defer reader.Close()

    // 读取全部字节（适合小文件；大文件走 service 层流式下载）
    data, err := ioReadAll(reader)
    if err != nil {
        return nil, nil, "", err
    }
    return file, data, file.Type, nil
}

// Download 服务端流式下载（仅 HTTP），按 64KB 分块发送，避免大文件全部加载到内存
func (s *FileService) Download(req *filev1.DownloadRequest, stream filev1.FileService_DownloadServer) error {
    userID := CtxUserID(stream.Context())
    if userID == 0 {
        return biz.ErrInvalidToken
    }
    // 使用流式读取，避免大文件全部加载到内存
    file, reader, _, err := s.uc.GetFileStream(stream.Context(), userID, req.FileId)
    if err != nil {
        return err
    }
    defer reader.Close()

    // 64KB 缓冲区分块发送
    buf := make([]byte, 64*1024)
    for {
        n, readErr := reader.Read(buf)
        if n > 0 {
            // 通过 gRPC 流发送当前分块（含文件名与总大小元信息）
            if err := stream.Send(&filev1.DownloadReply{
                Data: buf[:n],
                Name: file.Name,
                Size: file.Size,
            }); err != nil {
                return err
            }
        }
        if readErr != nil {
            break // EOF 或错误，结束循环
        }
    }
    return nil
}

func (uc *FileUsecase) InitUpload(ctx context.Context, userID uint64, fileName string, fileSize, chunkSize int64, parentID *uint64, hash string) (*UploadSession, error) {
    // 参数校验
    if fileSize <= 0 {
        return nil, perrors.BadRequest("INVALID_FILE_SIZE", "文件大小无效")
    }
    if chunkSize <= 0 {
        chunkSize = 5 * 1024 * 1024 // 默认 5MB 分片
    }

    // 修正点：客户端传入的 chunkSize 不可信任，钳制到合理区间，防止分片数爆炸
    const minChunk, maxChunk int64 = 1 << 20, 100 << 20 // 1MB ~ 100MB
    if chunkSize < minChunk || chunkSize > maxChunk {
        chunkSize = 5 * 1024 * 1024
    }

    // 安全校验：净化文件名 + 拦截危险文件类型
    fileName = sanitizeFileName(fileName)
    if isDangerousFileType(fileName) {
        return nil, perrors.BadRequest("FILE_TYPE_FORBIDDEN", "不允许上传此类型的文件")
    }

    // 校验存储空间
    if uc.userUC != nil {
        if err := uc.userUC.CheckStorageAvailable(ctx, userID, fileSize); err != nil {
            return nil, err
        }
    }

    if hash != "" {
        // 秒传检测：同哈希已有完成文件 -> 直接返回 status=1
        existing, _ := uc.fileRepo.FindByHash(ctx, userID, hash)
        if existing != nil && existing.Status == 0 {
            return &UploadSession{Status: 1}, nil
        }

        // 断点续传：查找同 user_id + hash + size 的进行中或已暂停会话
        if uc.uploadRepo != nil {
            resumed, _ := uc.uploadRepo.FindByHashAndSize(ctx, userID, hash, fileSize)
            if resumed != nil && (resumed.Status == 0 || resumed.Status == 3) {
                // 已暂停状态（status=3）先恢复为进行中（status=0）
                if resumed.Status == 3 {
                    _ = uc.uploadRepo.ResumeSession(ctx, resumed.UploadID)
                    resumed.Status = 0
                }
                return resumed, nil
            }
        }
    }

    // 计算分片总数：向上取整
    chunksTotal := int32((fileSize + chunkSize - 1) / chunkSize)
    // 生成 uploadID（upload_ + 随机 hex）
    uploadID := fmt.Sprintf("upload_%s", generateToken())

    // 使用 biz 层生成的 uploadID 初始化 storage 层分片目录，
    // 确保 biz 会话 ID 与 storage 目录名一致，避免孤儿空目录
    if err := uc.storage.InitMultipartUpload(ctx, uploadID, fileName); err != nil {
        return nil, err
    }

    // 构造上传会话领域对象
    session := &UploadSession{
        UploadID:    uploadID,
        UserID:      userID,
        FileName:    fileName,
        FileSize:    fileSize,
        FileHash:    hash,
        ChunkSize:   chunkSize,
        ChunksTotal: chunksTotal,
        Status:      0,
    }

    // 写入数据库；失败时取消 Storage 分片上传，避免孤儿空目录
    created, err := uc.uploadRepo.CreateSession(ctx, session)
    if err != nil {
        uc.storage.AbortMultipartUpload(ctx, uploadID)
        return nil, err
    }
    return created, nil
}

func (uc *FileUsecase) UploadPart(ctx context.Context, userID uint64, uploadID string, partNumber int, data []byte) (*UploadChunk, error) {
    // 校验会话存在且属于当前用户（IDOR 防护）
    session, err := uc.uploadRepo.FindSessionByUploadID(ctx, uploadID)
    if err != nil {
        return nil, err
    }
    if session.UserID != userID {
        return nil, ErrForbidden
    }
    // 仅进行中（status=0）的会话可上传分片
    if session.Status != 0 {
        return nil, ErrUploadSessionExpired
    }

    // 修正点：校验分片序号范围，防止越界/超大分片
    if partNumber < 1 || partNumber > int(session.ChunksTotal) {
        return nil, perrors.BadRequest("PART_OUT_OF_RANGE", "分片序号越界")
    }

    // 上传限流：信号量（容量 50）控制同时进行的分片写入数量
    semTimeout := 10 * time.Second
    select {
    case uc.uploadSemaphore <- struct{}{}: // 获取信号量
        defer func() { <-uc.uploadSemaphore }() // 函数结束时释放
    case <-time.After(semTimeout):
        return nil, ErrUploadBusy
    case <-ctx.Done():
        return nil, ctx.Err()
    }

    // 写入 Storage 分片目录
    _, err = uc.storage.UploadPart(ctx, uploadID, partNumber, bytesToReader(data))
    if err != nil {
        return nil, err
    }

    // 构造分片记录
    chunk := &UploadChunk{
        UploadSessionID: session.ID,
        ChunkIndex:      int32(partNumber),
        ChunkSize:       int64(len(data)),
    }

    // 写入 upload_chunks 表
    created, err := uc.uploadRepo.CreateChunk(ctx, chunk)
    if err != nil {
        return nil, err
    }
    // 原子递增会话的 chunks_received（用 gorm.Expr 避免 race condition）
    if err := uc.uploadRepo.IncrementChunks(ctx, uploadID); err != nil {
        return nil, err
    }
    return created, nil
}

// IncrementChunks 原子性地递增会话的已接收分片计数
// 使用 gorm.Expr("chunks_received + 1") 转换为 SQL: chunks_received = chunks_received + 1
// 数据库层保证原子性，避免并发 race condition
func (r *uploadRepo) IncrementChunks(ctx context.Context, uploadID string) error {
    return r.db.WithContext(ctx).
        Model(&model.UploadSession{}).
        Where("upload_id = ?", uploadID).
        UpdateColumn("chunks_received", gorm.Expr("chunks_received + 1")).Error
}

func (uc *FileUsecase) CheckParts(ctx context.Context, userID uint64, uploadID string) ([]int32, error) {
    // 校验会话归属
    session, err := uc.uploadRepo.FindSessionByUploadID(ctx, uploadID)
    if err != nil {
        return nil, err
    }
    if session.UserID != userID {
        return nil, ErrForbidden
    }
    // 返回已上传分片编号列表（按 chunk_index 升序），客户端据此跳过已传分片
    return uc.uploadRepo.ListReceivedPartNumbers(ctx, session.ID)
}

func (uc *FileUsecase) MergeParts(ctx context.Context, userID uint64, uploadID string, parentID *uint64) (*File, error) {
    // 校验会话归属与状态
    session, err := uc.uploadRepo.FindSessionByUploadID(ctx, uploadID)
    if err != nil {
        return nil, err
    }
    if session.UserID != userID {
        return nil, ErrForbidden
    }
    if session.Status != 0 {
        return nil, ErrUploadSessionExpired
    }

    // 读取所有已上传分片，按 chunk_index 升序
    chunks, err := uc.uploadRepo.ListChunksBySession(ctx, session.ID)
    if err != nil {
        return nil, err
    }
    // 修正点：用 != 校验分片完整，且应校验分片号连续落在 [1, ChunksTotal]
    if int32(len(chunks)) != session.ChunksTotal {
        return nil, ErrUploadIncomplete
    }

    // 构造 PartInfo 列表传给 Storage 合并
    parts := make([]PartInfo, len(chunks))
    for i, c := range chunks {
        parts[i] = PartInfo{
            PartNumber: int(c.ChunkIndex),
            Size:       c.ChunkSize,
        }
    }

    // 调用 Storage 合并分片，返回最终存储路径
    storagePath, err := uc.storage.CompleteMultipartUpload(ctx, uploadID, parts)
    if err != nil {
        // 合并失败，标记会话为失败状态
        uc.uploadRepo.FailSession(ctx, uploadID)
        return nil, err
    }

    // 标记会话为已完成
    if err := uc.uploadRepo.CompleteSession(ctx, uploadID); err != nil {
        log.Error("file: failed to complete upload session", "uploadID", uploadID, "err", err)
    }

    // 生成新文件 UUID
    uuid, err := newUUID()
    if err != nil {
        // UUID 生成失败，回滚已合并的 Storage 文件，避免孤儿
        if delErr := uc.storage.Delete(ctx, storagePath); delErr != nil {
            log.Error("file: failed to rollback storage after uuid gen failed", "storagePath", storagePath, "err", delErr)
        }
        return nil, err
    }

    // 根据文件名推断 MIME 类型
    fileType := detectMimeType(session.FileName)

    // 构造文件领域对象
    file := &File{
        UUID:     uuid,
        UserID:   userID,
        Name:     session.FileName,
        Size:     session.FileSize,
        Type:     fileType,
        Path:     storagePath,
        ParentID: parentID,
        Status:   0,
    }
    created, err := uc.fileRepo.Create(ctx, file)
    if err != nil {
        // 数据库写入失败，回滚已合并的 Storage 文件
        if delErr := uc.storage.Delete(ctx, storagePath); delErr != nil {
            log.Error("file: failed to rollback storage merge after db create failed", "storagePath", storagePath, "err", delErr)
        }
        return nil, err
    }

    // 修正点：AddUsedStorage 必须带配额上限校验，避免并发超配额（见三.12）
    if uc.userUC != nil {
        if err := uc.userUC.AddUsedStorage(ctx, userID, session.FileSize); err != nil {
            log.Error("file: failed to add used storage after merge parts", "userID", userID, "err", err)
        }
    }

    // 失效目录列表缓存
    uc.invalidateFileListCache(ctx, userID, parentID)

    // 发布上传完成事件（失败不影响主流程），供下游消费（生成缩略图、索引、病毒扫描）
    if uc.eventPublisher != nil {
        _ = uc.eventPublisher.Publish(ctx, EventUploadCompleted, &UploadCompletedPayload{
            UserID:   userID,
            FileID:   created.ID,
            FileName: created.Name,
            FileSize: created.Size,
            Hash:     session.FileHash,
        })
    }

    return created, nil
}

func (uc *FileUsecase) Move(ctx context.Context, userID uint64, fileIDs, folderIDs []uint64, targetParentID *uint64) error {
    // 用 map[*uint64]bool 显式区分 nil（根目录）与非 nil（子目录）
    sourceParentIDs := make(map[*uint64]bool)

    // 校验文件所有权并记录源目录 ID
    if len(fileIDs) > 0 {
        files, err := uc.fileRepo.FindByIDs(ctx, fileIDs)
        if err != nil {
            return err
        }
        for _, f := range files {
            if f.UserID != userID {
                return ErrForbidden // IDOR 防护
            }
            sourceParentIDs[f.ParentID] = true
        }
        // 批量更新 parent_id（一条 SQL）
        if err := uc.fileRepo.BatchMove(ctx, fileIDs, targetParentID); err != nil {
            return err
        }
    }
    // 校验文件夹所有权并记录源目录 ID
    if len(folderIDs) > 0 {
        for _, fid := range folderIDs {
            folder, err := uc.folderRepo.FindByID(ctx, fid)
            if err != nil {
                return err
            }
            if folder.UserID != userID {
                return ErrForbidden // IDOR 防护
            }
            sourceParentIDs[folder.ParentID] = true
        }
        if err := uc.folderRepo.BatchMove(ctx, folderIDs, targetParentID); err != nil {
            return err
        }
    }
    // 失效目标目录缓存
    uc.invalidateFileListCache(ctx, userID, targetParentID)
    // 失效所有源目录缓存（包括 nil 表示的根目录）
    for pid := range sourceParentIDs {
        uc.invalidateFileListCache(ctx, userID, pid)
    }
    // 失效被移动文件的元数据缓存（parent_id 已变更）
    for _, fid := range fileIDs {
        uc.InvalidateFileMetaCache(ctx, fid)
    }
    return nil
}

func (uc *FileUsecase) Copy(ctx context.Context, userID uint64, fileIDs, folderIDs []uint64, targetParentID *uint64) error {
    // 预加载目标目录下已有的文件和文件夹名称，用于重名检测
    existingNames := make(map[string]bool)
    existingFiles, _, err := uc.fileRepo.ListByParent(ctx, userID, targetParentID, 0, "", 1000, "", "")
    if err == nil {
        for _, f := range existingFiles {
            existingNames[f.Name] = true
        }
    }
    existingFolders, _, err := uc.folderRepo.ListByParent(ctx, userID, targetParentID, "", 1000, "", "")
    if err == nil {
        for _, f := range existingFolders {
            existingNames[f.Name] = true
        }
    }

    // 统计待复制文件总大小，用于存储空间校验
    var totalCopySize int64
    if len(fileIDs) > 0 {
        files, err := uc.fileRepo.FindByIDs(ctx, fileIDs)
        if err != nil {
            return err
        }
        for _, f := range files {
            if f.UserID != userID {
                return ErrForbidden // IDOR 防护
            }
            totalCopySize += f.Size
        }
    }
    // 校验存储空间
    if uc.userUC != nil && totalCopySize > 0 {
        if err := uc.userUC.CheckStorageAvailable(ctx, userID, totalCopySize); err != nil {
            return err
        }
    }

    // 逐个复制文件（共享 Path，新 UUID）
    for _, fid := range fileIDs {
        orig, err := uc.fileRepo.FindByID(ctx, fid)
        if err != nil {
            return err
        }
        if orig.UserID != userID {
            return ErrForbidden
        }
        uuid, err := newUUID()
        if err != nil {
            return err
        }
        // 重名检测：目标目录存在同名文件时自动添加 " (1)"、" (2)" 后缀
        copyName := uniqueName(orig.Name, existingNames)
        existingNames[copyName] = true
        copyFile := &File{
            UUID:     uuid,
            UserID:   userID,
            Name:     copyName,
            Size:     orig.Size,
            Type:     orig.Type,
            Hash:     orig.Hash,
            Path:     orig.Path, // 共享物理文件，不复制实际存储
            ParentID: targetParentID,
            Status:   0,
        }
        if _, err := uc.fileRepo.Create(ctx, copyFile); err != nil {
            return err
        }
        // 累加已用存储（修正点：同样需配额上限校验）
        if uc.userUC != nil {
            _ = uc.userUC.AddUsedStorage(ctx, userID, orig.Size)
        }
    }
    // 逐个复制文件夹（仅元数据，不递归复制子内容）
    for _, fid := range folderIDs {
        orig, err := uc.folderRepo.FindByID(ctx, fid)
        if err != nil {
            return err
        }
        if orig.UserID != userID {
            return ErrForbidden
        }
        uuid, err := newUUID()
        if err != nil {
            return err
        }
        copyName := uniqueName(orig.Name, existingNames)
        existingNames[copyName] = true
        copyFolder := &Folder{
            UUID:     uuid,
            UserID:   userID,
            Name:     copyName,
            ParentID: targetParentID,
        }
        if _, err := uc.folderRepo.Create(ctx, copyFolder); err != nil {
            return err
        }
    }
    // 失效目标目录缓存
    uc.invalidateFileListCache(ctx, userID, targetParentID)
    return nil
}

// uniqueName 在目标目录已有名称集合中生成不冲突的名称
// 若存在同名，则在新名称后添加 " (1)"、" (2)" 等后缀区分，不覆盖原有文件
func uniqueName(origName string, existing map[string]bool) string {
    if !existing[origName] {
        return origName
    }
    ext := extractExt(origName)
    base := origName[:len(origName)-len(ext)]
    for i := 1; ; i++ {
        candidate := fmt.Sprintf("%s (%d)%s", base, i, ext)
        if !existing[candidate] {
            return candidate
        }
    }
}

// BatchMove 将多个文件移动到新的父文件夹
// 一条 SQL 批量更新，避免循环单条更新
func (r *fileRepo) BatchMove(ctx context.Context, ids []uint64, newParentID *uint64) error {
    return r.db.WithContext(ctx).Model(&model.File{}).Where("id IN ?", ids).Update("parent_id", newParentID).Error
}

func (uc *FileUsecase) Preview(ctx context.Context, userID uint64, fileID uint64) (string, string, error) {
    file, err := uc.fileRepo.FindByID(ctx, fileID)
    if err != nil {
        return "", "", err
    }
    // 权限校验：仅文件所有者可预览（IDOR 防护）
    if file.UserID != userID {
        return "", "", ErrForbidden
    }
    // 修正点：补状态校验，回收站/已删除文件不可预览
    if file.Status != 0 {
        return "", "", ErrFileNotFound
    }

    // 根据 MIME 类型推断预览类型（image/video/audio/pdf/text/other）
    previewType := guessPreviewType(file.Type)
    // 获取预签名 URL（OSS）或本地路径（本地存储），有效期 1 小时
    url, err := uc.storage.GetFileURL(ctx, file.Path, 1*time.Hour)
    if err != nil {
        return "", "", err
    }
    return url, previewType, nil
}

// guessPreviewType 根据 MIME 类型返回前端预览分类
func guessPreviewType(mime string) string {
    switch {
    case mime == "":
        return "other"
    case len(mime) >= 5 && mime[:5] == "image": // image/jpeg, image/png 等
        return "image"
    case len(mime) >= 5 && mime[:5] == "video": // video/mp4 等
        return "video"
    case len(mime) >= 5 && mime[:5] == "audio": // audio/mpeg 等
        return "audio"
    case mime == "application/pdf":
        return "pdf"
    case len(mime) >= 4 && mime[:4] == "text": // text/plain 等
        return "text"
    default:
        return "other"
    }
}

// GetFileStream 获取文件流用于预览，返回文件对象、读取器和 MIME 类型
func (uc *FileUsecase) GetFileStream(ctx context.Context, userID uint64, fileID uint64) (*File, io.ReadCloser, string, error) {
    file, err := uc.fileRepo.FindByID(ctx, fileID)
    if err != nil {
        return nil, nil, "", err
    }
    if file.UserID != userID {
        return nil, nil, "", ErrForbidden
    }
    // 回收站文件禁止预览
    if file.Status != 0 {
        return nil, nil, "", ErrFileNotFound
    }

    // 从 Storage 获取读取器（流式，不加载全部到内存）
    reader, err := uc.storage.Download(ctx, file.Path)
    if err != nil {
        return nil, nil, "", err
    }

    return file, reader, file.Type, nil
}

// StreamPreview 流式返回文件内容用于预览（service 层）
func (s *FileService) StreamPreview(ctx context.Context, userID uint64, fileID uint64, w http.ResponseWriter) error {
    // 获取文件流
    file, reader, mimeType, err := s.uc.GetFileStream(ctx, userID, fileID)
    if err != nil {
        return err
    }
    defer reader.Close()

    // 设置正确的 Content-Type
    if mimeType != "" {
        w.Header().Set("Content-Type", mimeType)
    } else {
        w.Header().Set("Content-Type", "application/octet-stream")
    }

    // 设置 Content-Length（让浏览器显示下载进度）
    if file.Size > 0 {
        w.Header().Set("Content-Length", strconv.FormatInt(file.Size, 10))
    }

    // 流式传输文件内容：io.Copy 内部按 32KB 缓冲区循环读写，边读边发
    if _, err := io.Copy(w, reader); err != nil {
        return err
    }

    return nil
}

// detectMimeType 根据文件名推断 MIME 类型
// 优先使用系统 MIME 数据库，缺失时回退到内置常见类型映射
// （Docker 精简镜像可能没有 /etc/mime.types，导致视频等类型识别失败）
func detectMimeType(filename string) string {
    ext := filepath.Ext(filename)
    if ext == "" {
        return "application/octet-stream"
    }
    // 优先使用系统 MIME 数据库
    if mimeType := mime.TypeByExtension(ext); mimeType != "" {
        return mimeType
    }
    // 回退到内置映射（覆盖 Docker 精简镜像缺失 mime.types 的场景）
    if mimeType, ok := builtinMimeTypes[strings.ToLower(ext)]; ok {
        return mimeType
    }
    return "application/octet-stream"
}

func (uc *RecycleUsecase) Trash(ctx context.Context, userID uint64, fileIDs, folderIDs []uint64) ([]uint64, []uint64, error) {
    trashedFiles := make([]uint64, 0, len(fileIDs))
    trashedFolders := make([]uint64, 0, len(folderIDs))

    // 1. 文件：批量查所有权 → 写 RecycleItem → 软删除（status=1）
    if len(fileIDs) > 0 {
        files, err := uc.fileRepo.FindByIDs(ctx, fileIDs)
        if err != nil {
            return nil, nil, err
        }
        now := time.Now()
        expire := now.Add(7 * 24 * time.Hour)
        for _, f := range files {
            if f.UserID != userID { // IDOR 防护：越权拒绝
                return nil, nil, ErrForbidden
            }
            item := &RecycleItem{
                UserID:    userID,
                ItemType:  "file",
                ItemID:    f.ID,
                Name:      f.Name,
                FileSize:  f.Size,
                FileType:  f.Type,
                DeletedAt: now,
                ExpireAt:  expire,
            }
            if _, err := uc.recycleRepo.Create(ctx, item); err != nil {
                return nil, nil, err
            }
            // 删除该文件的所有分享记录（源文件删除，分享也应删除）
            if uc.shareRepo != nil {
                _ = uc.shareRepo.DeleteByItemID(ctx, "file", f.ID)
            }
            trashedFiles = append(trashedFiles, f.ID)
        }
        if len(trashedFiles) > 0 {
            if err := uc.fileRepo.BatchUpdateStatus(ctx, trashedFiles, 1); err != nil {
                return nil, nil, err
            }
        }
    }
    // 2. 文件夹：循环查所有权 → 写 RecycleItem → 软删除内部文件 → 物理删除文件夹记录
    for _, fid := range folderIDs {
        folder, err := uc.folderRepo.FindByID(ctx, fid)
        if err != nil {
            return nil, nil, err
        }
        if folder.UserID != userID { // IDOR 防护
            return nil, nil, ErrForbidden
        }
        // ... 写 RecycleItem、软删除子文件、删文件夹记录、删分享记录
    }

    // 清理文件列表缓存与存储缓存，发布 EventFileTrashed
    if uc.cache != nil {
        _ = uc.cache.DeleteByPattern(ctx, fmt.Sprintf("files:list:%d:*", userID))
        _ = uc.cache.Delete(ctx, fmt.Sprintf(cacheKeyUserStorage, userID))
    }
    return trashedFiles, trashedFolders, nil
}

func (uc *RecycleUsecase) DeleteForever(ctx context.Context, userID uint64, recycleID uint64) error {
    item, err := uc.recycleRepo.FindByID(ctx, recycleID)
    if err != nil {
        return err
    }
    if item.UserID != userID { // IDOR 防护
        return ErrForbidden
    }

    deletedFileIDs := uc.permanentlyDeleteItem(ctx, userID, item)

    // 发布文件永久删除事件（失败不影响主流程）
    if uc.eventPublisher != nil && len(deletedFileIDs) > 0 {
        _ = uc.eventPublisher.Publish(ctx, EventFileDeleted, &FileChangedPayload{
            UserID:  userID,
            FileID:  deletedFileIDs[0],
            Action:  "deleted",
        })
    }

    return uc.recycleRepo.Delete(ctx, recycleID)
}

// permanentlyDeleteItem 永久删除：删对象存储 + status=2 + 扣减配额
func (uc *RecycleUsecase) permanentlyDeleteItem(ctx context.Context, userID uint64, item *RecycleItem) []uint64 {
    deletedFileIDs := make([]uint64, 0)
    if item.ItemType == "file" {
        file, err := uc.fileRepo.FindByID(ctx, item.ItemID)
        if err != nil {
            return deletedFileIDs
        }
        if err := uc.storage.Delete(ctx, file.Path); err != nil { // 删物理文件
            log.Error("recycle: failed to delete physical file", "path", file.Path, "err", err)
        }
        _ = uc.fileRepo.BatchUpdateStatus(ctx, []uint64{item.ItemID}, 2)
        if uc.userUC != nil {
            _ = uc.userUC.SubUsedStorage(ctx, userID, file.Size) // 扣减配额
        }
        deletedFileIDs = append(deletedFileIDs, item.ItemID)
    }
    // ... 文件夹递归删内部文件
    return deletedFileIDs
}