package tech.easyflow.ai.service;

import com.mybatisflex.core.service.IService;
import tech.easyflow.ai.entity.KnowledgeShare;
import tech.easyflow.ai.vo.KnowledgeShareAuthContext;
import tech.easyflow.ai.vo.KnowledgeShareUrlCreateResult;

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

/**
 * 知识库分享服务。
 */
public interface KnowledgeShareService extends IService<KnowledgeShare> {

    /**
     * 创建 URL 分享。
     *
     * @param knowledgeId 目标知识库
     * @param tenantId 租户 ID
     * @param deptId 部门 ID
     * @param operatorId 操作人
     * @param baseUrl 分享页基础 URL
     * @param permissionScopes 授权范围
     * @return 创建结果
     */
    KnowledgeShareUrlCreateResult createUrlShare(
        BigInteger knowledgeId,
        BigInteger tenantId,
        BigInteger deptId,
        BigInteger operatorId,
        String baseUrl,
        Set<String> permissionScopes
    );

    /**
     * 校验 URL 分享并返回上下文。
     *
     * @param shareKey 分享访问密钥
     * @return 鉴权上下文
     */
    KnowledgeShareAuthContext validateUrlShare(String shareKey);

    /**
     * 断言 URL 分享允许当前动作。
     *
     * @param shareKey 分享访问密钥
     * @param knowledgeId 知识库 ID
     * @param actionScope 动作范围
     * @return 鉴权上下文
     */
    KnowledgeShareAuthContext assertUrlShareAccess(
        String shareKey,
        BigInteger knowledgeId,
        String actionScope
    );
}
