UC-11 — Gestion des rôles

Acteur : Gestionnaire (N1) ou Administrateur (N2) But : Créer des rôles et les assigner à des utilisateurs

Trigger

Un gestionnaire doit attribuer des permissions à un utilisateur.

Préconditions

• Permissions role.create / role.permission.assign / user.update

Postconditions

• Le rôle existe avec ses permissions
• L'utilisateur détient les permissions du rôle (reflétées dans son prochain JWT au refresh)

Endpoints

1. Créer un rôle

POST /api/v1/admin/org/roles
Content-Type: application/json

{
  "name": "Caissier senior",
  "description": "Encaisse et supervise la caisse"
}

Permissions séparées

La création de rôle ne prend que name et description. Les permissions s'assignent ensuite via l'endpoint dédié.

2. Assigner des permissions au rôle

POST /api/v1/admin/org/roles/{role_id}/permissions
Content-Type: application/json

{
  "permission_id": "uuid-permission"
}

Le catalogue des permissions disponibles est exposé par GET /admin/org/permissions.

3. Assigner le rôle à un utilisateur

POST /api/v1/admin/org/users/{id}/roles
Content-Type: application/json

{
  "role_id": "uuid-role",
  "site_id": "uuid-site"
}

site_id est optionnel (scope du rôle à un site).

4. Retirer un rôle

DELETE /api/v1/admin/org/users/{id}/roles/{role_id}

Flow

sequenceDiagram
    participant Admin
    participant Dashboard
    participant API
    participant DB

    Admin->>Dashboard: "Créer un rôle"
    Dashboard->>API: POST /admin/org/roles {name, description}
    API->>DB: INSERT roles
    API-->>Dashboard: {role}

    Admin->>Dashboard: Sélectionner des permissions
    Dashboard->>API: GET /admin/org/permissions
    API-->>Dashboard: [{id, code, module}]
    Dashboard->>API: POST /admin/org/roles/{id}/permissions {permission_id}
    API->>DB: INSERT role_permissions
    API-->>Dashboard: {message: "Permission assignée"}

    Admin->>Dashboard: Assigner le rôle à un utilisateur
    Dashboard->>API: POST /admin/org/users/{id}/roles {role_id}
    API->>DB: INSERT tenant_user_roles
    API-->>Dashboard: {message: "Rôle assigné"}

Exemple de réponse (création)

{
  "message": "Rôle créé",
  "role": {
    "id": "uuid",
    "name": "Caissier senior",
    "description": "Encaisse et supervise la caisse",
    "is_system_role": false,
    "created_at": "2025-06-01T08:00:00Z"
  }
}

Résolution des permissions

Les permissions sont résolues au login et embarquées dans le JWT. Pour les rafraîchir sans re-login, utiliser POST /auth/refresh (qui re-résout les permissions depuis la base).

Login → rôles → permissions → claims.permissions

Permissions

Permission	Description
role.create / role.update / role.delete	CRUD rôle
role.permission.assign	Assigner des permissions
user.update	Assigner un rôle à un utilisateur

Erreurs

error_code	Description
NotFound	Rôle ou utilisateur introuvable
Conflict	Rôle déjà assigné
Forbidden	Rôle système non modifiable

Voir Rôles (Admin) et Matrice des rôles.