package incheon.com.file.service;

import incheon.com.file.vo.ComFileDtlVO;
import incheon.com.file.vo.ComFileSearchVO;
import incheon.com.file.vo.ComFileVO;
import org.springframework.web.multipart.MultipartFile;

import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.util.List;

/**
 * 공통 파일 서비스
 * *
 * @since 2025.10.17
 */
public interface ComFileService {

    /**
     * 파일 그룹 목록 조회
     */
    List<ComFileVO> selectComFileList(ComFileSearchVO searchVO);

    /**
     * 파일 그룹 목록 총 개수
     */
    int selectComFileListTotCnt(ComFileSearchVO searchVO);

    /**
     * 파일 그룹 상세 조회
     */
    ComFileVO selectComFileDetail(String atchFileId);

    /**
     * 파일 상세 목록 조회
     */
    List<ComFileDtlVO> selectComFileDtlList(String atchFileId);

    /**
     * 파일 상세 단건 조회
     */
    ComFileDtlVO selectComFileDtlDetail(String fileId);

    /**
     * 파일 업로드 (임시)
     * @param files 업로드할 파일들
     * @param atchFileId 기존 파일그룹ID (없으면 신규 생성)
     * @return 파일그룹ID
     */
    String uploadFiles(MultipartFile[] files, String atchFileId) throws IOException;

    /**
     * 단일 파일 업로드 (임시)
     * @param file 업로드할 파일
     * @param atchFileId 기존 파일그룹ID (없으면 신규 생성)
     * @return 파일 정보
     */
    ComFileDtlVO uploadFile(MultipartFile file, String atchFileId) throws IOException;

    /**
     * 임시 파일을 정식 파일로 전환
     * @param atchFileId 파일그룹ID
     * @param trgtNm 대상키명 (예: NOTICE_123)
     */
    void confirmFiles(String atchFileId, String trgtNm);

    /**
     * 파일 삭제 (논리 삭제)
     * @param fileId 파일ID
     */
    void deleteFile(String fileId);

    /**
     * 파일 그룹 삭제 (물리 삭제)
     * @param atchFileId 파일그룹ID
     */
    void deleteFileGroup(String atchFileId);

    /**
     * 파일 다운로드
     * @param fileId 파일ID
     * @param response HTTP 응답 객체
     */
    void downloadFile(String fileId, HttpServletResponse response) throws IOException;

    /**
     * 파일 그룹 일괄 다운로드 (ZIP)
     * @param atchFileId 파일그룹ID
     * @param response HTTP 응답 객체
     */
    void downloadFileGroup(String atchFileId, HttpServletResponse response) throws IOException;

    /**
     * 파일 정렬 순서 변경
     * @param fileId 파일ID
     * @param sortSeq 정렬 순서
     */
    void updateFileSortSeq(String fileId, Integer sortSeq);

    /**
     * 파일 크기 포맷팅
     * @param bytes 바이트 크기
     * @return 포맷팅된 크기 문자열 (예: "1.5 MB")
     */
    String formatFileSize(Long bytes);

    /**
     * 파일 확장자로 MIME 타입 추정
     * @param fileName 파일명
     * @return MIME 타입
     */
    String getMimeType(String fileName);

    /**
     * ULID 생성
     * @return 생성된 ULID
     */
    String generateUlid();
}