package com.crm.auth.security;

import com.crm.auth.domain.entity.SysMenu;

import java.util.List;

/**
 * 权限解析引擎：每请求把一个用户的全部授权事实一次算清（ADR-0011）。
 *
 * <p>深模块：调用方只见两个方法，「用户 → 角色 → 授权 → 资源」的查询链、
 * 档位取舍、子树展开、权限码并集的断路规则全部藏在实现里。</p>
 *
 * <p>fail-closed（ADR-0006）：解析失败即抛异常，由请求入口拒绝该请求；
 * 不存在「部分成功」的第三状态。</p>
 */
public interface PermissionResolver {

    /**
     * 解析用户的数据可见性与全部授权码。纯取值——不装载任何线程上下文，
     * 装载 {@link com.crm.base.security.DataVisibilityContext} 由调用方按请求生命周期负责。
     *
     * @param userId 本地用户 ID
     * @return 可见性 + 权限码并集 + 角色编码；无角色用户返回最窄档可见性与空授权集合
     */
    PermissionGrant resolve(Long userId);

    /**
     * 用户可见菜单树（catalog/menu 节点，按角色授权过滤、排除 button、按 sort 排序）。
     * 登录后渲染侧边栏用，不参与每请求解析。
     *
     * @param userId 本地用户 ID
     * @return 组好父子关系的菜单树；无任何授权时返回空列表
     */
    List<SysMenu> visibleMenuTree(Long userId);
}