package tech.easyflow.skill.service;

import com.mybatisflex.core.service.IService;
import tech.easyflow.skill.entity.Skill;
import tech.easyflow.skill.entity.SkillToolBinding;

import java.math.BigInteger;
import java.util.List;
import java.util.Map;

/**
 * Skill 平台 Tool 绑定服务。
 */
public interface SkillToolBindingService extends IService<SkillToolBinding> {

    /**
     * 原子替换 Skill 的全部 Tool 草稿绑定。
     *
     * @param skillId Skill ID
     * @param bindings 客户端绑定引用
     * @return 规范化后的脱敏绑定摘要
     */
    List<SkillToolBinding> replaceBindings(BigInteger skillId, List<SkillToolBinding> bindings);

    /**
     * 查询 Skill 的草稿绑定并补齐脱敏摘要。
     *
     * @param skillId Skill ID
     * @return 稳定排序的绑定摘要
     */
    List<SkillToolBinding> listSummaries(BigInteger skillId);

    /**
     * 查询 Skill 的草稿绑定。
     *
     * @param skillId Skill ID
     * @return 稳定排序的草稿绑定
     */
    List<SkillToolBinding> listBindings(BigInteger skillId);

    /**
     * 构建并完整复核 Skill 的平台 Tool 发布快照。
     *
     * @param skill 已锁定的 Skill
     * @return Tool 发布快照
     */
    Map<String, Object> buildPublishSnapshot(Skill skill);

    /**
     * 复核已发布 Tool 快照中的目标资源、权限和 MCP manifest。
     *
     * @param skill 已发布 Skill
     */
    void assertPublishedSnapshotUsable(Skill skill);

    /**
     * 校验 Tool 发布快照的内容 hash。
     *
     * @param snapshot Tool 发布快照
     */
    void assertPublishedSnapshotHash(Map<String, Object> snapshot);

    /**
     * 删除指定 Skill 的全部草稿 Tool 绑定。
     *
     * @param skillId Skill ID
     */
    void removeBySkillId(BigInteger skillId);
}
