package org.qinan.safetyeval.client.api;

import org.qinan.safetyeval.client.co.FileInfoCO;
import org.qinan.safetyeval.client.dto.SingleResponse;

import java.util.List;

/**
 * 文件存储管理接口定义（Client层）
 * <p>
 * 提供 filestorage 表的查询、删除、获取签名URL等管理功能。
 * 文件的新增由上传接口（{@link FileUploadApi}）间接完成，本接口不提供直接新增能力。
 * </p>
 *
 * @author safety-eval
 */
public interface FileStorageApi {

    /**
     * 获取文件签名URL（临时访问链接）
     *
     * @param fileId 文件ID
     * @return 文件信息（含签名URL）
     */
    SingleResponse<FileInfoCO> getPresignedUrl(Integer fileId);

    /**
     * 获取文件信息
     *
     * @param fileId 文件ID
     * @return 文件信息
     */
    SingleResponse<FileInfoCO> getInfo(Integer fileId);

    /**
     * 删除文件（OSS + DB）
     *
     * @param fileId 文件ID
     * @return 操作结果
     */
    SingleResponse<Void> delete(Integer fileId);

    /**
     * 批量删除文件（OSS + DB）
     *
     * @param fileIds 文件ID列表
     * @return 操作结果
     */
    SingleResponse<Void> deleteBatch(List<Integer> fileIds);

    /**
     * 获取所有文件列表
     *
     * @return 文件信息列表
     */
    SingleResponse<List<FileInfoCO>> listAll();

    /**
     * 根据上传者获取文件列表
     *
     * @param creatorUid 上传者UID
     * @return 文件信息列表
     */
    SingleResponse<List<FileInfoCO>> listByCreator(String creatorUid);
}
