senmesh-zc/src/main/java/com/senmesh/sfile/service/UserFileService.java

package com.senmesh.sfile.service;

import com.senmesh.sfile.dto.ExpandUserFileCreateDTO;
import com.senmesh.sfile.dto.ExpandUserFileDTO;
import com.senmesh.sfile.dto.UserFileCreateDTO;
import com.senmesh.sfile.dto.UserFileDTO;
import com.senmesh.sfile.dto.UserFileModifyDTO;
import com.senmesh.sfile.dto.UserFileModifyStatusDTO;
import com.senmesh.sfile.dto.UserFileQueryDTO;
import com.senmesh.sfile.dto.UserFileStatisticsDTO;

import java.util.List;

/**
 * 用户文件Service
 */
public interface UserFileService {

  /**
   * 创建用户文件
   *
   * @param createDTO 创建DTO
   * @return UserFileDTO
   */
  UserFileDTO create(UserFileCreateDTO createDTO);

  /**
   * 根据普通文件创建新的文件（复制）
   * 创建一个文件夹，文件名为原文件名+时间戳，然后复制原文件下所有文件类型的子文件
   *
   * @param expandCreateDTO 扩展创建DTO
   * @return 扩展用户文件DTO（包含文件夹信息和文件列表）
   */
  ExpandUserFileDTO create(ExpandUserFileCreateDTO expandCreateDTO);

  /**
   * 根据文件夹和文件列表创建文件夹和文件（用于传输文件解包）
   * 1. 从 folder 中获取 userId 和 rootType
   * 2. 创建文件夹
   * 3. 遍历文件列表，通过 fileCode 获取文件流，上传文件获取新的 fileCode，然后创建用户文件记录
   *
   * @param folder 文件夹信息（包含 userId、rootType、fileName 等）
   * @param files 文件列表（每个文件包含 fileCode、fileName 等）
   * @return 扩展用户文件DTO（包含创建后的文件夹信息和文件列表）
   */
  ExpandUserFileDTO create(UserFileDTO folder, List<UserFileDTO> files);

  /**
   * 修改用户文件
   *
   * @param modifyDTO 修改DTO
   */
  void modify(UserFileModifyDTO modifyDTO);

  /**
   * 修改用户文件状态
   *
   * @param modifyStatusDTO 修改状态DTO
   */
  void modifyStatus(UserFileModifyStatusDTO modifyStatusDTO);

  /**
   * 修改用户文件状态（校验用户权限）
   *
   * @param modifyStatusDTO 修改状态DTO
   * @param userId 用户ID
   */
  void modifyStatus(UserFileModifyStatusDTO modifyStatusDTO, Long userId);

  /**
   * 删除用户文件
   *
   * @param id 主键ID
   */
  void remove(Long id);

  /**
   * 删除用户文件（校验用户权限）
   *
   * @param id 主键ID
   * @param userId 用户ID
   */
  void remove(Long id, Long userId);

  /**
   * 列表查询
   *
   * @param queryDTO 查询DTO
   * @return List<UserFileDTO>
   */
  List<UserFileDTO> list(UserFileQueryDTO queryDTO);

  /**
   * 分页查询
   *
   * @param queryDTO 查询DTO
   */
  void page(UserFileQueryDTO queryDTO);

  /**
   * 单个查询
   *
   * @param queryDTO 查询DTO
   * @return UserFileDTO
   */
  UserFileDTO find(UserFileQueryDTO queryDTO);

  /**
   * 单个查询（不存在抛异常）
   *
   * @param queryDTO 查询DTO
   * @return UserFileDTO
   */
  UserFileDTO findOne(UserFileQueryDTO queryDTO);

  /**
   * 按文件种类统计文件个数和总大小
   *
   * @param queryDTO 查询DTO
   * @return List<UserFileStatisticsDTO>
   */
  List<UserFileStatisticsDTO> statisticsByCategory(UserFileQueryDTO queryDTO);
}