package tech.easyflow.ai.service;

import java.math.BigInteger;
import java.util.Set;

/**
 * 知识库分享权限服务。
 */
public interface KnowledgeSharePermissionService {

    /**
     * 为系统访问令牌授予知识库 API 分享权限。
     *
     * @param apiKeyId 系统访问令牌 ID
     * @param knowledgeId 知识库 ID
     * @param actionScopes 动作范围
     */
    void grantApiShare(BigInteger apiKeyId, BigInteger knowledgeId, Set<String> actionScopes);

    /**
     * 按访问令牌维度开启或关闭知识库 API 分享授权。
     *
     * <p>产品固定为全量知识库的非删除范围，不向前端暴露动作粒度。</p>
     *
     * @param apiKeyId 系统访问令牌 ID
     * @param enabled 是否启用知识库分享授权
     */
    void replaceApiShareEnabled(BigInteger apiKeyId, boolean enabled);

    /**
     * 替换访问令牌的三类知识库 Public API 权限。
     *
     * @param apiKeyId 系统访问令牌 ID
     * @param readEnabled 是否开启读取
     * @param importEnabled 是否开启导入
     * @param maintenanceEnabled 是否开启维护
     */
    void replaceApiPermissions(BigInteger apiKeyId,
                               boolean readEnabled,
                               boolean importEnabled,
                               boolean maintenanceEnabled);

    /**
     * 查询访问令牌已开启的知识库 Public API 权限。
     *
     * @param apiKeyId 系统访问令牌 ID
     * @return 权限 Scope 集合
     */
    Set<String> getApiPermissionScopes(BigInteger apiKeyId);

    /**
     * 断言当前令牌具备知识库分享权限。
     *
     * @param apiKeyId 系统访问令牌 ID
     * @param requestUri 请求地址
     * @param knowledgeId 知识库 ID
     * @param actionScope 动作范围
     */
    void assertApiShare(BigInteger apiKeyId, String requestUri, BigInteger knowledgeId, String actionScope);
}
