package org.xyzh.api.file.service;

import org.springframework.web.multipart.MultipartFile;
import org.xyzh.api.file.dto.TbSysFileDTO;
import org.xyzh.common.core.domain.ResultDomain;

/**
 * @description    文件服务接口
 * @filename    FileService.java
 * @author    yslg
 * @copyright yslg
 * @since 2025-11-03
 */
public interface FileService {

    /**
     * @description 上传文件
     * @param file 文件对象
     * @param module 所属模块
     * @param businessId 业务ID
     * @return ResultDomain<TbSysFile> 上传结果，包含文件信息
     * @author yslg
     * @since 2025-10-16
     */
    ResultDomain<TbSysFileDTO> uploadFile(MultipartFile file, String module, String businessId);

    /**
     * @description 批量上传文件
     * @param files 文件对象列表
     * @param module 所属模块
     * @param businessId 业务ID
     * @param uploader 上传者用户ID（可选）
     * @return ResultDomain<TbSysFile> 上传结果，包含文件信息列表
     * @author yslg
     * @since 2025-11-03
     */
    ResultDomain<TbSysFileDTO> batchUploadFiles(MultipartFile[] files, String module, String businessId, String uploader);

    /**
     * @description 删除文件
     * @param fileId 文件ID
     * @return ResultDomain<String> 删除结果
     * @author yslg
     * @since 2025-11-03
     */
    ResultDomain<Boolean> deleteFile(String fileId);

    /**
     * @description 批量删除文件（逻辑删除）
     * @param fileIds 文件ID列表
     * @return ResultDomain<TbSysFileDTO> 删除结果
     * @author yslg
     * @since 2025-10-16
     */
    ResultDomain<TbSysFileDTO> batchDeleteFiles(String[] fileIds);

    /**
     * @description 下载文件
     * @param fileId 文件ID
     * @return ResultDomain<byte[]> 文件字节数组
     * @author yslg
     * @since 2025-11-03
     */
    ResultDomain<byte[]> downloadFile(String fileId);

    /**
     * @description 根据文件ID查询文件信息
     * @param fileId 文件ID
     * @return ResultDomain<TbSysFile> 文件信息
     * @author yslg
     * @since 2025-11-03
     */
    ResultDomain<TbSysFileDTO> getFileById(String fileId);

    /**
     * @description 保存临时文件
     * @param file 文件对象
     * @param module 所属模块
     * @param businessId 业务ID
     * @return ResultDomain<TbSysFileDTO> 保存结果
     * @author yslg
     * @since 2025-11-03
     */
    ResultDomain<TbSysFileDTO> saveTempFile(MultipartFile file, String module, String businessId);

    /**
     * @description    上传新版本文件（用于文件更新，fileRootId保持一致，version递增）
     * @param    file 文件对象
     * @param    module 所属模块
     * @param    businessId 业务ID
     * @param    fileRootId 文件根ID（多版本一致）
     * @return    ResultDomain<TbSysFileDTO> 上传结果，包含新版本文件信息
     * @author    yslg
     * @since 2025-12-18
     */
    ResultDomain<TbSysFileDTO> uploadFileVersion(MultipartFile file, String module, String businessId, String fileRootId);

    /**
     * @description    通过字节数组上传文件（用于跨模块 Dubbo 调用）
     * @param    fileBytes 文件字节数组
     * @param    fileName 文件名
     * @param    contentType 文件类型
     * @param    module 所属模块
     * @param    businessId 业务ID
     * @return    ResultDomain<TbSysFileDTO> 上传结果
     * @author    yslg
     * @since 2025-12-20
     */
    ResultDomain<TbSysFileDTO> uploadFileBytes(byte[] fileBytes, String fileName, String contentType, String module, String businessId);

    /**
     * @description    通过字节数组上传文件（支持直接指定上传者，用于未登录用户场景如AIChat）
     * @param    fileBytes 文件字节数组
     * @param    fileName 文件名
     * @param    contentType 文件类型
     * @param    module 所属模块
     * @param    businessId 业务ID
     * @param    uploaderUserId 上传者用户ID（可为null）
     * @return    ResultDomain<TbSysFileDTO> 上传结果
     * @author    yslg
     * @since 2025-12-20
     */
    ResultDomain<TbSysFileDTO> uploadFileBytesWithUser(byte[] fileBytes, String fileName, String contentType, String module, String businessId, String uploaderUserId);

    /**
     * @description    通过字节数组上传新版本文件（用于跨模块 Dubbo 调用的文件版本更新）
     * @param    fileBytes 文件字节数组
     * @param    fileName 文件名
     * @param    contentType 文件类型
     * @param    module 所属模块
     * @param    businessId 业务ID
     * @param    fileRootId 文件根ID（多版本一致）
     * @return    ResultDomain<TbSysFileDTO> 上传结果，包含新版本文件信息
     * @author    yslg
     * @since 2025-12-20
     */
    ResultDomain<TbSysFileDTO> uploadFileBytesVersion(byte[] fileBytes, String fileName, String contentType, String module, String businessId, String fileRootId);

    /**
     * @description    通过字节数组上传新版本文件（支持直接指定上传者）
     * @param    fileBytes 文件字节数组
     * @param    fileName 文件名
     * @param    contentType 文件类型
     * @param    module 所属模块
     * @param    businessId 业务ID
     * @param    fileRootId 文件根ID（多版本一致）
     * @param    uploaderUserId 上传者用户ID（可为null）
     * @return    ResultDomain<TbSysFileDTO> 上传结果，包含新版本文件信息
     * @author    yslg
     * @since 2025-12-20
     */
    ResultDomain<TbSysFileDTO> uploadFileBytesVersionWithUser(byte[] fileBytes, String fileName, String contentType, String module, String businessId, String fileRootId, String uploaderUserId);

}
