Aller au contenu principal

Rôles et Permissions (Admin)

Le système de rôles de Caffette permet un contrôle d'accès granulaire basé sur des permissions atomiques. Les rôles peuvent être définis au niveau organisation (N1) ou système (N2).

Modèle de permissions​

Les permissions sont des chaînes au format dot-notation ({domaine}.{action}). Un rôle est un ensemble de permissions regroupées sous un nom.

Permissions atomiques​

DomainePermissions
cardread, create, update, delete, manage, manual_access, holder.*
productread, create, update, delete, manage
stockread, adjust, purchase, produce, transfer
categoryread, create, update, delete
siteread, create, update, delete
posread, create, update, delete
registerread, open, close
userread, create, update, delete
roleread, create, update, delete, permission_assign
transactionread, debit, manage
reservationread, create, update, delete, manage
notificationread, create, update, delete
ticketread, create, update
anomalymanage, threshold.configure
logread
analyticsread
organizationmanage
platformuser.manage
statsexhaustive.read

Permissions wildcard​

La permission {domaine}.manage donne tous les droits du domaine. Par exemple, card.manage donne card.read, card.create, card.update, card.delete.

De plus, certaines permissions manage couvrent des domaines parent :

PermissionCouvre
organization.manageuser.*, role.*, settings.*, log.read, anomaly.*
site.managepos.*, register.*
product.managestock.*, category.*
reservation.manageticket.*

Rôles organisation (N1)​

Rôles définis au niveau d'une organisation. Chaque organisation a ses propres rôles.

Permissions : role.read, role.create, role.update, role.delete, role.permission_assign

Base URL : /api/v1/admin/org/roles

Les rôles système sont des rôles intégrés marqués is_system_role = true. Ils ne peuvent pas être modifiés ni supprimés.

GET /admin/org/permissions​

Catalogue des permissions disponibles (utilisé par l'UI des rôles).

Permissions : role.read ou organization.manage

Réponse (200) : { "items": [{ "id", "code", "description", "module" }], "total": n } (non paginé).

GET /admin/org/roles​

Liste des rôles de l'organisation avec leurs permissions.

ParamTypeDescription
limitintegerÉléments par page (défaut: 20)
offsetintegerDécalage (défaut: 0)

Réponse :

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Caissier",
      "description": "Peut encaisser les ventes et consulter les cartes",
      "is_system_role": false,
      "permissions": [
        {
          "id": "uuid",
          "code": "card.read",
          "description": "Lecture des cartes et soldes",
          "module": "card"
        },
        {
          "id": "uuid",
          "code": "transaction.debit",
          "description": "Effectuer une vente / débit",
          "module": "transaction"
        },
        {
          "id": "uuid",
          "code": "register.open",
          "description": "Ouvrir une session de caisse",
          "module": "register"
        }
      ],
      "created_at": "2025-01-10T00:00:00Z"
    }
  ],
  "total": 5
}

Les permissions sont résolues en une requête batch pour tous les rôles.

POST /admin/org/roles​

Créer un rôle. Les permissions sont assignées via un endpoint séparé.

{
  "name": "Superviseur",
  "description": "Supervise les opérations de caisse"
}

Réponse (201) :

{
  "message": "Rôle créé",
  "role": {
    "id": "uuid",
    "name": "Superviseur",
    "description": "Supervise les opérations de caisse"
  }
}

GET /admin/org/roles/{id}​

Détails d'un rôle avec ses permissions.

Réponse :

{
  "role": {
    "id": "uuid",
    "name": "Caissier",
    "description": "Peut encaisser les ventes",
    "is_system_role": false,
    "created_at": "2025-01-10T00:00:00Z"
  },
  "permissions": [
    {
      "id": "uuid",
      "code": "card.read",
      "description": "Lecture des cartes et soldes",
      "module": "card"
    }
  ]
}

PUT /admin/org/roles/{id}​

Mettre à jour un rôle. Les rôles système (is_system_role = true) ne peuvent pas être modifiés.

{
  "name": "Superviseur Sénior",
  "description": "Supervise toutes les opérations"
}

Réponse :

{
  "message": "Rôle mis à jour",
  "role": {
    "id": "uuid",
    "name": "Superviseur Sénior",
    "description": "Supervise toutes les opérations"
  }
}

DELETE /admin/org/roles/{id}​

Supprimer un rôle. Les rôles système ne peuvent pas être supprimés.

Réponse :

{
  "message": "Rôle supprimé"
}

POST /admin/org/roles/{role_id}/permissions​

Assigner une permission à un rôle.

{
  "permission_id": "uuid"
}

Réponse :

{
  "message": "Permission assignée"
}

DELETE /admin/org/roles/{role_id}/permissions/{permission_id}​

Retirer une permission d'un rôle.

Réponse :

{
  "message": "Permission retirée"
}

Rôles système (N2)​

Rôles définis au niveau plateforme, accessibles dans toutes les organisations.

Permissions requises : organization.manage

Base URL : /api/v1/admin/system/roles

GET /admin/system/roles​

Liste des rôles système. La réponse est similaire aux rôles organisation mais les permissions sont retournées sous forme de codes (liste de chaînes).

Réponse :

{
  "items": [
    {
      "id": "uuid",
      "name": "Platform Admin",
      "description": null,
      "is_system_role": true,
      "permissions": [
        "organization.manage",
        "platform.user.manage",
        "stats.exhaustive.read"
      ],
      "created_at": "2025-01-01T00:00:00Z"
    }
  ],
  "total": 2
}

POST /admin/system/roles​

Créer un rôle système.

{
  "name": "Observateur Global",
  "description": "Accès lecture seule sur toutes les organisations"
}

GET /admin/system/roles/{id}​

Détails d'un rôle système.

PUT /admin/system/roles/{id}​

Mettre à jour un rôle système.

{
  "name": "Observateur Global Senior",
  "description": "Accès lecture seule avec export"
}

DELETE /admin/system/roles/{id}​

Supprimer un rôle système.

POST /admin/system/roles/{id}/permissions​

Assigner une permission à un rôle système.

{
  "permission_id": "uuid"
}

DELETE /admin/system/roles/{id}/permissions/{permission_name}​

Retirer une permission d'un rôle système.

Permissions disponibles​

GET /admin/system/permissions​

Lister toutes les permissions disponibles dans le système.

Permissions requises : organization.manage

Réponse :

[
  "card.read",
  "card.create",
  "card.update",
  "card.delete",
  "card.manage",
  "product.read",
  "user.create",
  "role.read",
  "role.delete",
  "organization.manage",
  "platform.user.manage",
  "stats.exhaustive.read",
  "..."
]

Exemple : Configuration d'un rôle​

sequenceDiagram
    actor Admin
    Admin->>API: POST /org/roles { name: "Caissier" }
    API-->>Admin: role créé (id: R1)
    Admin->>API: GET /system/permissions
    API-->>Admin: [...permissions...]
    Admin->>API: POST /org/roles/R1/permissions { permission_id: "card.read" }
    Admin->>API: POST /org/roles/R1/permissions { permission_id: "transaction.debit" }
    Admin->>API: POST /org/roles/R1/permissions { permission_id: "register.open" }
    Admin->>API: POST /org/users/{id}/roles { role_id: "R1", site_id: "S1" }
    API-->>Admin: Rôle assigné

Bonnes pratiques​

  • Principe du moindre privilège : Commencez avec les permissions minimales nécessaires et ajoutez progressivement. Un caissier n'a pas besoin de organization.manage.
  • Rôles système : Limitez les rôles système (N2) aux administrateurs plateforme. Privilégiez les rôles organisation (N1) pour les opérations quotidiennes.
  • Scope par site : Utilisez le paramètre site_id lors de l'assignation d'un rôle pour limiter les permissions d'un utilisateur à un site spécifique.
  • Permissions manage : Les wildcards (card.manage, site.manage) sont pratiques mais donnent des droits étendus. Réservez-les aux rôles de supervision.