package org.xyzh.api.file;

import org.springframework.web.multipart.MultipartFile;
import org.xyzh.common.core.domain.ResultDomain;
import org.xyzh.common.dto.system.TbSysFile;

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

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

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

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

    /**
     * @description 删除文件（逻辑删除）
     * @param fileId 文件ID
     * @return ResultDomain<TbSysFile> 删除结果
     * @author yslg
     * @since 2025-10-16
     */
    ResultDomain<TbSysFile> deleteFile(String fileId);

    /**
     * @description 物理删除文件（同时删除存储和数据库记录）
     * @param fileId 文件ID
     * @return ResultDomain<TbSysFile> 删除结果
     * @author yslg
     * @since 2025-10-16
     */
    ResultDomain<TbSysFile> deleteFilePhysically(String fileId);

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

    /**
     * @description 根据业务ID查询文件列表
     * @param module 所属模块
     * @param businessId 业务ID
     * @return ResultDomain<TbSysFile> 文件列表
     * @author yslg
     * @since 2025-10-16
     */
    ResultDomain<TbSysFile> getFilesByBusinessId(String module, String businessId);

    /**
     * @description 根据上传者查询文件列表
     * @param uploader 上传者用户ID
     * @return ResultDomain<TbSysFile> 文件列表
     * @author yslg
     * @since 2025-10-16
     */
    ResultDomain<TbSysFile> getFilesByUploader(String uploader);

    /**
     * @description 获取文件访问URL
     * @param fileId 文件ID
     * @return ResultDomain<String> 文件访问URL
     * @author yslg
     * @since 2025-10-16
     */
    ResultDomain<String> getFileUrl(String fileId);

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

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

