using OmsorgCore.Application.Models;
using OmsorgCore.Domain.Enums;

namespace OmsorgCore.Application.Abstractions;

/// <summary>
/// Zentrale Rechteprüfung: Rollen-Default kombiniert mit individuellen Overrides des Benutzers.
/// Wird sowohl vom API-Authorization-Attribut als auch von Business-Services genutzt, damit
/// Rechte auf Daten- UND Funktionsebene geprüft werden (REQUIREMENTS.md NFR-9).
/// </summary>
public interface IPermissionService
{
    Task<bool> HasPermissionAsync(Guid userId, ModuleType module, PermissionAction action, CancellationToken cancellationToken = default);

    /// <summary>
    /// Liefert den effektiven <see cref="PermissionScope"/> für Modul/Aktion dieses Users, oder
    /// <c>null</c> wenn gar nicht gewährt. Scope-unabhängig vom reinen Endpunkt-Gate
    /// (<see cref="HasPermissionAsync"/>) — wird von datenzugreifenden Application-Services
    /// konsultiert, um Own-Scope-Filterung anzuwenden (siehe REQUIREMENTS.md FR-MA-6).
    /// </summary>
    Task<PermissionScope?> GetScopeAsync(Guid userId, ModuleType module, PermissionAction action, CancellationToken cancellationToken = default);

    /// <summary>Alle tatsächlich gewährten Modul/Aktion-Kombinationen dieses Users (Rollen-Default + Overrides aufgelöst).</summary>
    Task<IReadOnlyList<PermissionGrant>> GetGrantedPermissionsAsync(Guid userId, CancellationToken cancellationToken = default);

    /// <summary>Entfernt den gecachten Rechte-Stand dieses einzelnen Users - nach einem individuellen Override oder Rollenwechsel.</summary>
    void InvalidateUserPermissions(Guid userId);

    /// <summary>Entfernt den gecachten Rechte-Stand aller User mit dieser Rolle - nach einer Änderung der Rollen-Rechte-Matrix.</summary>
    Task InvalidateRolePermissionsAsync(Guid roleId, CancellationToken cancellationToken = default);
}
