=====================================
Authorization — Politiques (PAP/PDP)
=====================================

Le PAP (Policy Administration Point) gère les politiques via l'API REST.
Le PDP (Policy Decision Point) évalue les politiques contre les attributs.


Modèle Policy (PAP)
====================

Module : ``src.module.authorization.infrastructure.models``

.. module:: src.module.authorization.infrastructure.models
   :synopsis: Modèles pour les politiques ABAC et les approbations

.. class:: Policy(TranslatableModel)

   Politique ABAC définissant les règles d'accès.
   Traduisible via django-parler.

   .. attribute:: name
      :type: CharField

      Identifiant programmatique de la politique (non traduit, utilisé dans
      les logs et l'évaluation ABAC).

   .. attribute:: display_name
      :type: CharField (traduit)

      Nom d'affichage traduisible (ex: ``"Les financiers peuvent lire les factures"``).

   .. attribute:: description
      :type: TextField (traduit)

      Description détaillée traduisible de la politique.

   :Table: ``mt_policy`` / ``mt_policy_translation``

   .. attribute:: effect
      :type: CharField

      ``"allow"`` ou ``"deny"``. Utilise ``PolicyEffect``.

   .. attribute:: priority
      :type: IntegerField

      Priorité d'évaluation. Plus élevée = évaluée en premier.

   .. attribute:: is_active
      :type: BooleanField

   .. attribute:: actions
      :type: JSONField

      Liste d'actions (ex: ``["read", "update", "delete"]``).

   .. attribute:: resource_type
      :type: CharField

      Type de ressource ciblé (ex: ``"Invoice"``, ``"Document"``, ``"*"``).

   .. attribute:: resource_id
      :type: UUIDField (nullable)

      Si défini, politique au niveau objet (une ressource spécifique).

   .. attribute:: subject_conditions
      :type: JSONField

      Conditions sur le sujet (utilisateur, rôles, attributs).

   .. attribute:: resource_conditions
      :type: JSONField

      Conditions sur la ressource (propriétaire, statut).

   .. attribute:: environment_conditions
      :type: JSONField

      Conditions sur l'environnement (heure, IP, géo).

   .. attribute:: scope
      :type: CharField

      ``"global"`` (tous les tenants) ou ``"tenant"`` (tenant spécifique).

   .. attribute:: requires_approval
      :type: BooleanField

      Si ``True``, l'action nécessite une approbation avant exécution.

   .. attribute:: approval_config
      :type: JSONField

      Configuration d'approbation :

      .. code-block:: json

         {
             "required_approvals": 2,
             "approver_roles": ["admin", "manager"],
             "expiration_hours": 48,
             "auto_execute": true
         }

   .. attribute:: version
      :type: IntegerField

      Verrouillage optimiste — incrémenté à chaque modification.

.. class:: AttributeDefinition(TranslatableModel)

   Catalogue des attributs disponibles pour les conditions ABAC.
   Traduisible via django-parler.

   .. attribute:: name
      :type: CharField(unique=True)

      Identifiant programmatique de l'attribut (non traduit).

   .. attribute:: display_name
      :type: CharField (traduit)

      Nom d'affichage traduisible.

   .. attribute:: description
      :type: TextField (traduit)

      Description traduisible de l'attribut.

   .. attribute:: attribute_type
      :type: CharField

      ``"subject"``, ``"resource"``, ``"environment"``

   .. attribute:: data_type
      :type: CharField

      ``"string"``, ``"integer"``, ``"boolean"``, ``"list"``, ``"json"``

   .. attribute:: allowed_values
      :type: JSONField (nullable)

   :Table: ``mt_attribute_definition`` / ``mt_attribute_definition_translation``


PDP — Policy Decision Point
============================

Module : ``src.module.authorization.domain.services``

.. module:: src.module.authorization.domain.services
   :synopsis: Service d'évaluation des politiques ABAC

.. class:: PolicyEvaluationService

   Évalue les politiques ABAC avec un algorithme basé sur la priorité.

   **Algorithme d'évaluation :**

   1. Charge les politiques statiques (système)
   2. Charge les politiques actives depuis la DB
   3. Trie par priorité (décroissant)
   4. Pour chaque politique :

      a. Vérifie que ``resource_type`` matche (ou ``"*"``)
      b. Vérifie que l'action est dans ``actions``
      c. Évalue ``subject_conditions`` via le moteur de conditions
      d. Évalue ``resource_conditions`` via le moteur de conditions
      e. Évalue ``environment_conditions`` via le moteur de conditions

   5. Première politique matchée → décision retournée
   6. Si aucune politique ne matche → ``ABAC_DEFAULT_EFFECT``

   .. method:: evaluate(request: EvaluationRequest) -> EvaluationResult

      Évalue une requête d'accès.

      :param request: Requête d'évaluation ABAC
      :returns: Résultat avec décision, politique matchée, raison


Politiques statiques
====================

Module : ``src.module.authorization.domain.static_policies``

.. module:: src.module.authorization.domain.static_policies
   :synopsis: Politiques système toujours actives

.. data:: STATIC_POLICIES

   Liste des politiques système évaluées en premier :

   - **superuser_full_access** (priorité 10000) : Les superusers ont accès à tout
   - **suspended_deny_all** (priorité 9999) : Les utilisateurs suspendus n'ont accès à rien

   Ces politiques ne peuvent pas être désactivées ou modifiées.


API REST (PAP)
==============

.. class:: PolicyViewSet(ModelViewSet)

   CRUD des politiques ABAC.

   ``GET/POST /api/v1/policies/``
   ``GET/PUT/PATCH/DELETE /api/v1/policies/<id>/``

   Actions supplémentaires :

   - ``POST /api/v1/policies/<id>/test/`` : teste une politique avec des attributs simulés