package de.effigenix.shared.security;

/**
 * Authorization Port - Domain-facing interface for authorization.
 *
 * This is the Anti-Corruption Layer (ACL) between domain logic and User Management.
 * It allows:
 * - Type-safe, action-oriented authorization (not role-based!)
 * - Domain language: BCs use their own Action enums
 * - Decoupling: BCs don't depend on User Management
 * - Future Keycloak migration without BC changes
 * - Framework-agnostic: no dependency on Spring Security or thread-locals
 *
 * Implementation 1 (MVP): SpringSecurityAuthorizationAdapter → User Management BC
 * Implementation 2 (future): KeycloakAuthorizationAdapter → Keycloak
 *
 * Usage in Use Cases:
 * <pre>
 * // Use Case bekommt ActorId als Parameter vom Controller
 * if (!authPort.can(actorId, ProductionAction.RECIPE_WRITE)) {
 *     return Result.failure(new Unauthorized());
 * }
 *
 * // Resource-level check (e.g., only own branch)
 * if (!authPort.can(actorId, QualityAction.TEMPERATURE_LOG_WRITE, branchId)) {
 *     return Result.failure(new Unauthorized());
 * }
 * </pre>
 */
public interface AuthorizationPort {

    /**
     * Checks if the given actor can execute a domain action.
     *
     * @param actor  The actor performing the action
     * @param action Type-safe action from a BC's Action enum
     * @return true if authorized, false otherwise
     */
    boolean can(ActorId actor, Action action);

    /**
     * Checks if the given actor can execute a domain action on a specific resource.
     * For resource-level authorization (e.g., user can only access their own branch).
     *
     * @param actor    The actor performing the action
     * @param action   Type-safe action from a BC's Action enum
     * @param resource Resource identifier (e.g., BranchId)
     * @return true if authorized, false otherwise
     */
    boolean can(ActorId actor, Action action, ResourceId resource);
}
