package com.agent.management.service;

import com.agent.management.model.dto.FileCreateDTO;
import com.agent.management.model.dto.FileNodeDTO;
import com.agent.management.model.dto.IOField;
import com.agent.management.model.dto.SkillDTO;
import com.agent.management.model.dto.SkillUpdateDTO;
import com.agent.management.model.vo.SkillDetailVO;
import org.springframework.web.multipart.MultipartFile;

import java.util.List;
import java.util.Map;

/**
 * Skill 业务服务接口
 */
public interface SkillService {

    /**
     * 获取所有 Skill 列表
     */
    List<SkillDTO> listSkills();

    /**
     * 获取单个 Skill 详情
     */
    SkillDTO getSkill(String folderName);

    /**
     * 上传并新增 Skill（zip 压缩包）
     */
    void createSkill(MultipartFile zipFile);

    /**
     * 更新 Skill 的 name 和 description。
     * 若 name 规范化后与 folderName 不同，将触发目录重命名并迁移全部副作用引用。
     *
     * @return 实际生效的 folderName（重命名后可能变化）
     */
    String updateSkill(String folderName, SkillUpdateDTO dto);

    /**
     * 删除 Skill（删除整个子目录）
     */
    void deleteSkill(String folderName);

    /**
     * 读取 Skill 的 SKILL.md 完整内容（用作 Agent 系统提示词）
     */
    String getSkillFullContent(String folderName);

    /**
     * 获取 Skill 详情（含正文）
     */
    SkillDetailVO getSkillDetail(String folderName);

    /**
     * 保存 SKILL.md（智能合并：保留原有非标准元数据字段）。
     * 若 name 与原值不同（kebab-case 规范化后），会触发目录重命名，
     * 同时迁移 _versions 历史、标签关联、工作流节点引用。
     *
     * @return 实际生效的 folderName（重命名后可能变化）
     */
    String saveSkillMd(String folderName, String name, String displayName,
                       String description,
                       boolean canGenerateSkill,
                       List<IOField> inputs, List<IOField> outputs, String body);

    /**
     * 列出 Skill 目录下的所有文件（树形结构）
     */
    List<FileNodeDTO> listSkillFiles(String folderName);

    /**
     * 读取 Skill 目录下的文件内容
     */
    String readFile(String folderName, String relativePath);

    /**
     * 保存文件内容
     */
    void saveFile(String folderName, String relativePath, String content);

    /**
     * 创建文件或目录
     */
    void createFileOrDir(String folderName, FileCreateDTO dto);

    /**
     * 删除文件或目录
     */
    void deleteFile(String folderName, String relativePath);

    /**
     * 扫描全部 skill 目录，将 folderName 与 SKILL.md name（kebab-case 规范化后）不一致的统一重命名，
     * 同时迁移 _versions 历史、标签关联、分类关联、工作流节点引用。用于历史数据迁移。
     *
     * <p>跳过策略：name 字段为空、规范化后非法（含中文等无法转换的字符）的条目记入 failed，
     * 不阻塞其他 skill 的迁移。
     *
     * @return 迁移摘要：{ total, migrated:[{from,to}], failed:[{folder,reason}], skipped:[folder] }
     */
    Map<String, Object> migrateAllFoldersNormalize();
}
