package com.dne.ems.service;

import org.springframework.core.io.Resource;
import org.springframework.web.multipart.MultipartFile;

import com.dne.ems.model.Attachment;
import com.dne.ems.model.Feedback;

/**
 * 文件存储服务接口，处理文件上传和下载
 *
 * <p>主要功能：
 * <ul>
 *   <li>安全存储上传文件</li>
 *   <li>管理文件与业务实体的关联</li>
 *   <li>提供文件下载功能</li>
 * </ul>
 *
 * @author DNE开发团队
 * @version 1.0
 * @since 2024
 */
public interface FileStorageService {

    /**
     * 存储文件并将其与反馈实体关联
     *
     * <p>功能说明：
     * <ul>
     *   <li>保存上传的文件到文件系统</li>
     *   <li>创建文件与反馈的关联关系</li>
     *   <li>返回创建的附件实体</li>
     * </ul>
     *
     * @param file 要存储的文件
     * @param feedback 关联的反馈实体
     * @return 创建的附件实体
     * @throws com.dne.ems.exception.FileStorageException 如果文件存储失败
     * @deprecated 请使用更通用的 storeFile(file) 方法，并手动创建关联关系
     */
    @Deprecated
    Attachment storeFileAndCreateAttachment(MultipartFile file, Feedback feedback);

    /**
     * 存储文件并返回其唯一存储名称
     *
     * <p>安全措施：
     * <ul>
     *   <li>验证文件类型和扩展名</li>
     *   <li>生成唯一文件名防止冲突</li>
     *   <li>检查路径遍历漏洞</li>
     *   <li>限制允许的文件类型</li>
     * </ul>
     *
     * @param file 要存储的文件
     * @return 存储文件的唯一名称
     * @throws com.dne.ems.exception.FileStorageException 如果文件存储失败
     */
    String storeFile(MultipartFile file);

    /**
     * 从存储位置加载文件资源
     *
     * @param fileName 要加载的文件名
     * @return 文件资源
     * @throws com.dne.ems.exception.FileStorageException 如果文件不存在或不可读
     */
    Resource loadFileAsResource(String fileName);

}