package tech.easyflow.skill.file;

import org.springframework.web.multipart.MultipartFile;

import java.io.InputStream;
import java.math.BigInteger;
import java.util.List;

/**
 * Skill 逻辑文件服务。
 */
public interface SkillFileService {

    /**
     * 获取 Skill 文件树。
     *
     * @param skillId Skill ID
     * @return 文件树
     */
    List<SkillFileNode> tree(BigInteger skillId);

    /**
     * 获取逻辑文件内容。
     *
     * @param skillId Skill ID
     * @param path 逻辑路径
     * @return 文件内容
     */
    SkillFileContent getContent(BigInteger skillId, String path);

    /**
     * 保存文本文件内容。
     *
     * @param request 保存请求
     * @return 保存后的文件内容
     */
    SkillFileContent saveContent(SkillFileSaveRequest request);

    /**
     * 创建 Skill 文本资源。
     *
     * @param request 创建请求
     * @return 创建后的文件内容
     */
    SkillFileContent createTextFile(SkillFileSaveRequest request);

    /**
     * 重命名 Skill 资源。
     *
     * @param request 重命名请求
     * @return 重命名后的文件内容
     */
    SkillFileContent renameFile(SkillFileRenameRequest request);

    /**
     * 删除逻辑文件。
     *
     * @param skillId Skill ID
     * @param path 逻辑路径
     */
    void deleteFile(BigInteger skillId, String path);

    /**
     * 按客户端读取到的内容 hash 删除逻辑文件。
     *
     * @param skillId Skill ID
     * @param path 逻辑路径
     * @param expectedContentHash 客户端读取到的内容 hash
     */
    void deleteFile(BigInteger skillId, String path, String expectedContentHash);

    /**
     * 上传 asset 文件。
     *
     * @param skillId Skill ID
     * @param path asset 逻辑路径
     * @param file 上传文件
     * @return asset 文件内容
     */
    SkillFileContent uploadAsset(BigInteger skillId, String path, MultipartFile file);

    /**
     * 上传任意安全的二进制资源。
     *
     * @param skillId Skill ID
     * @param path 目标逻辑路径
     * @param file 上传文件
     * @return 保存后的资源内容
     */
    SkillFileContent uploadResource(BigInteger skillId, String path, MultipartFile file);

    /**
     * 上传或按内容 hash 原子替换二进制资源。
     *
     * @param skillId Skill ID
     * @param path 目标逻辑路径
     * @param file 上传文件
     * @param expectedContentHash 已有路径的客户端内容 hash；新路径为空
     * @return 保存后的资源内容
     */
    SkillFileContent uploadResource(BigInteger skillId,
                                    String path,
                                    MultipartFile file,
                                    String expectedContentHash);

    /**
     * 打开 asset 输入流。
     *
     * @param skillId Skill ID
     * @param path asset 逻辑路径
     * @return asset 输入流
     */
    InputStream openAsset(BigInteger skillId, String path);

    /**
     * 打开二进制资源输入流。
     *
     * @param skillId Skill ID
     * @param path 逻辑路径
     * @return 输入流，调用方负责关闭
     */
    InputStream openResource(BigInteger skillId, String path);
}
