# Matrice des Permissions - Espace Paie Odentas

## Vue d'ensemble

Le système de permissions de l'Espace Paie Odentas repose sur **5 rôles hiérarchiques** :

1. **STAFF** - Équipe Odentas (super-administrateurs globaux)
2. **SUPER_ADMIN** - Administrateur principal de l'organisation (1 seul par organisation)
3. **ADMIN** - Administrateurs secondaires (plusieurs possibles)
4. **AGENT** - Opérateurs RH (gestion contrats/paies/salariés uniquement)
5. **COMPTA** - Comptables (accès financier en lecture seule)

---

## Tableau Récapitulatif des Permissions

| Ressource/Action | STAFF | SUPER_ADMIN | ADMIN | AGENT | COMPTA |
|------------------|-------|-------------|-------|-------|--------|
| **CONTRATS** |
| Voir liste contrats | ✅ | ✅ | ✅ | ✅ | ❌ |
| Créer contrat | ✅ | ✅ | ✅ | ✅ | ❌ |
| Modifier contrat | ✅ | ✅ | ✅ | ✅ | ❌ |
| Supprimer contrat | ✅ | ✅ | ✅ | ✅ | ❌ |
| **PAIES** |
| Voir fiches de paie | ✅ | ✅ | ✅ | ✅ | ❌ |
| Générer fiches de paie | ✅ | ✅ | ✅ | ✅ | ❌ |
| Modifier fiches de paie | ✅ | ✅ | ✅ | ✅ | ❌ |
| **SALARIÉS** |
| Voir liste salariés | ✅ | ✅ | ✅ | ✅ | ❌ |
| Créer salarié | ✅ | ✅ | ✅ | ✅ | ❌ |
| Modifier salarié | ✅ | ✅ | ✅ | ✅ | ❌ |
| Supprimer salarié | ✅ | ✅ | ✅ | ✅ | ❌ |
| **COTISATIONS** |
| Voir cotisations mensuelles | ✅ | ✅ | ✅ | ❌ | ✅ (lecture seule) |
| Modifier cotisations | ✅ | ✅ | ✅ | ❌ | ❌ |
| **VIREMENTS SALAIRES** |
| Voir virements | ✅ | ✅ | ✅ | ❌ | ✅ (lecture seule) |
| Créer/modifier virements | ✅ | ✅ | ✅ | ❌ | ❌ |
| **FACTURATION** |
| Voir factures | ✅ | ✅ | ✅ | ❌ | ✅ (lecture seule) |
| Créer/modifier factures | ✅ | ✅ | ✅ | ❌ | ❌ |
| **DOCUMENTS** |
| Upload documents | ✅ | ✅ | ✅ | ✅ | ❌ |
| Voir tous documents | ✅ | ✅ | ✅ | ✅ | ❌ |
| Voir documents comptables* | ✅ | ✅ | ✅ | ❌ | ✅ |
| **GESTION UTILISATEURS** |
| Voir liste utilisateurs | ✅ | ✅ | ✅ | ❌ | ❌ |
| Créer SUPER_ADMIN | ✅ | ❌ | ❌ | ❌ | ❌ |
| Créer ADMIN/AGENT/COMPTA | ✅ | ✅ | ✅ | ❌ | ❌ |
| Modifier rôle SUPER_ADMIN | ✅ | ❌ | ❌ | ❌ | ❌ |
| Modifier rôle autres | ✅ | ✅ | ✅ | ❌ | ❌ |
| Révoquer SUPER_ADMIN | ✅ | ❌ | ❌ | ❌ | ❌ |
| Révoquer autres | ✅ | ✅ | ✅ | ❌ | ❌ |
| **INFORMATIONS STRUCTURE** |
| Voir informations | ✅ | ✅ | ✅ | ✅ | ✅ |
| Modifier SIRET/SEPA | ✅ | ✅ | ❌ | ❌ | ❌ |
| Modifier autres infos | ✅ | ✅ | ✅ | ❌ | ❌ |

**Documents comptables inclus** : factures, devis, relevés cotisations, virements salaires, justificatifs bancaires, bilans, documents comptables généraux

---

## Détails par Rôle

### 🔴 STAFF (Équipe Odentas)
**Accès complet** à toutes les organisations et toutes les fonctionnalités. Ce rôle est réservé à l'équipe technique Odentas.

**Permissions spécifiques :**
- Peut créer et supprimer des SUPER_ADMIN
- Accès multi-organisations
- Aucune restriction

---

### 🟣 SUPER_ADMIN (Administrateur Principal)

**Responsable principal de l'organisation**. Il existe **un seul SUPER_ADMIN par organisation**.

**Permissions :**
- ✅ Accès complet à toutes les données de l'organisation
- ✅ Peut gérer tous les utilisateurs (sauf autres SUPER_ADMIN)
- ✅ Peut créer ADMIN, AGENT, COMPTA
- ✅ Peut modifier les informations structurelles critiques (SIRET, SEPA)
- ✅ Accès en lecture/écriture à facturation, cotisations, virements
- ✅ Gestion complète des contrats, paies, salariés

**Restrictions :**
- ❌ Ne peut pas être modifié ou révoqué par un ADMIN
- ❌ Seul STAFF peut créer un nouveau SUPER_ADMIN

**Protection :**
- Les ADMIN ne peuvent pas modifier ou supprimer le SUPER_ADMIN
- C'est le "propriétaire" de l'organisation

---

### 🔵 ADMIN (Administrateur Secondaire)

**Administrateurs opérationnels**. Plusieurs ADMIN peuvent coexister.

**Permissions :**
- ✅ Accès complet aux données opérationnelles
- ✅ Peut gérer les utilisateurs (sauf SUPER_ADMIN)
- ✅ Peut créer AGENT et COMPTA
- ✅ Accès en lecture/écriture à facturation, cotisations, virements
- ✅ Gestion complète des contrats, paies, salariés
- ✅ Upload et accès à tous les documents

**Restrictions :**
- ❌ Ne peut pas modifier les informations structurelles critiques (SIRET/SEPA)
- ❌ Ne peut pas modifier/révoquer un SUPER_ADMIN
- ❌ Ne peut pas créer de SUPER_ADMIN

---

### 🟢 AGENT (Opérateur RH)

**Rôle opérationnel** pour la gestion quotidienne des contrats, paies et salariés.

**Permissions :**
- ✅ Gestion complète des contrats (CDDU, RG)
- ✅ Gestion des fiches de paie
- ✅ Gestion des salariés
- ✅ Upload de documents généraux
- ✅ Consultation des informations de structure

**Restrictions :**
- ❌ Pas d'accès aux données financières (facturation, cotisations, virements)
- ❌ Pas d'accès à la gestion des utilisateurs
- ❌ Pas d'accès aux documents comptables
- ❌ Pas de modification des informations de structure

**Cas d'usage :** Assistant RH, chargé de production, gestionnaire de paie junior

---

### 🟡 COMPTA (Comptable)

**Accès financier en lecture seule**. Le COMPTA ne peut ni créer, ni modifier, ni supprimer de données.

**Permissions :**
- ✅ Consultation des cotisations mensuelles
- ✅ Consultation des virements salaires
- ✅ Consultation des factures
- ✅ Consultation des documents comptables uniquement :
  - Factures
  - Devis
  - Relevés de cotisations
  - Virements salaires
  - Justificatifs bancaires
  - Bilans
  - Documents comptables généraux
- ✅ Consultation des informations de structure

**Restrictions :**
- ❌ Pas d'accès aux contrats
- ❌ Pas d'accès aux fiches de paie
- ❌ Pas d'accès aux salariés
- ❌ Pas d'upload de documents
- ❌ Pas d'accès à la gestion des utilisateurs
- ❌ Pas de modification possible (lecture seule uniquement)

**Cas d'usage :** Expert-comptable externe, comptable ne nécessitant que les données financières

---

## Hiérarchie et Protection

### Règle de Hiérarchie

```
STAFF
  └── SUPER_ADMIN (protégé)
        └── ADMIN
              ├── AGENT
              └── COMPTA
```

**Règles de modification :**
1. **STAFF** peut tout modifier
2. **SUPER_ADMIN** peut modifier ADMIN, AGENT, COMPTA (pas d'autres SUPER_ADMIN)
3. **ADMIN** peut modifier AGENT, COMPTA (pas SUPER_ADMIN ni autres ADMIN)
4. **AGENT** et **COMPTA** ne peuvent rien modifier

### Protection du SUPER_ADMIN

Le SUPER_ADMIN est **protégé** :
- Un ADMIN ne peut pas changer son rôle
- Un ADMIN ne peut pas le révoquer
- Un ADMIN ne peut pas créer un nouveau SUPER_ADMIN

Seul le **STAFF** d'Odentas peut modifier un SUPER_ADMIN.

---

## Implémentation Technique

### Fichier central : `lib/permissions.ts`

Toutes les vérifications de permissions sont centralisées dans `lib/permissions.ts`.

**Fonctions principales :**

```typescript
// Récupérer les permissions d'un utilisateur
getUserPermissions(supabaseClient): Promise<UserPermissions | null>

// Ressources opérationnelles
canAccessContrats(role: UserRole): boolean
canAccessPaies(role: UserRole): boolean
canAccessSalaries(role: UserRole): boolean

// Ressources financières
canAccessFacturation(role: UserRole): boolean
canAccessCotisations(role: UserRole): boolean
canAccessVirements(role: UserRole): boolean

// Gestion utilisateurs
canManageUsers(role: UserRole): boolean
canModifyUser(permissions: UserPermissions, targetRole: UserRole): boolean
canCreateUserWithRole(permissions: UserPermissions, newRole: UserRole): boolean

// Documents
canUploadDocuments(role: UserRole): boolean
canAccessDocumentType(role: UserRole, docType: string): boolean

// Informations structure
canModifyStructureInfo(role: UserRole): boolean
```

### Routes protégées

**Backend (API Routes) :**
- `/api/contrats/*` - Bloque COMPTA
- `/api/facturation/*` - Bloque AGENT
- `/api/cotisations/*` - Bloque AGENT
- `/api/virements-salaires/*` - Bloque AGENT
- `/api/access/*` - Bloque AGENT et COMPTA
- `/api/access/[memberId]/role/*` - Empêche ADMIN de modifier SUPER_ADMIN
- `/api/access/[memberId]/revoke/*` - Empêche ADMIN de révoquer SUPER_ADMIN
- `/api/access/nouveau/*` - Empêche ADMIN de créer SUPER_ADMIN

**Frontend (Composants React) :**
- Masquage/désactivation des boutons selon le rôle
- Navigation conditionnelle

---

## Exemples de Cas d'Usage

### Scénario 1 : Cabinet de Production
**Organisation :** Compagnie de théâtre de 20 salariés

**Utilisateurs :**
- **1 SUPER_ADMIN** : Directeur administratif (gestion complète + informations critiques)
- **2 ADMIN** : Responsable RH + Responsable production (gestion complète opérationnelle)
- **3 AGENT** : Assistants RH (gestion contrats/paies uniquement)
- **1 COMPTA** : Expert-comptable externe (consultation financière uniquement)

---

### Scénario 2 : Petite Structure Associative
**Organisation :** Association culturelle de 5 salariés

**Utilisateurs :**
- **1 SUPER_ADMIN** : Président de l'association (tout)
- **1 AGENT** : Secrétaire générale (contrats/paies)
- **1 COMPTA** : Trésorier (consultation financière)

---

### Scénario 3 : Grande Production
**Organisation :** Festival avec 100+ salariés

**Utilisateurs :**
- **1 SUPER_ADMIN** : Directeur général
- **5 ADMIN** : Équipe de direction
- **10 AGENT** : Équipe RH/production
- **2 COMPTA** : Cabinet comptable externe

---

## Migration et Changement de Rôle

### Promotion d'utilisateur

**AGENT → ADMIN**
- Action possible par SUPER_ADMIN ou ADMIN
- Débloque l'accès financier et la gestion utilisateurs

**ADMIN → SUPER_ADMIN**
- ⚠️ **Action STAFF uniquement**
- L'ancien SUPER_ADMIN doit être rétrogradé en ADMIN d'abord
- Il ne peut y avoir qu'un seul SUPER_ADMIN

### Rétrogradation d'utilisateur

**ADMIN → AGENT**
- Action possible par SUPER_ADMIN
- Bloque l'accès financier et gestion utilisateurs

**SUPER_ADMIN → ADMIN**
- ⚠️ **Action STAFF uniquement**
- Permet de désigner un nouveau SUPER_ADMIN

---

## FAQ

### Pourquoi un seul SUPER_ADMIN ?

Pour éviter les conflits de gestion et garantir une responsabilité claire. Le SUPER_ADMIN est le "propriétaire" de l'organisation.

### Un ADMIN peut-il modifier un autre ADMIN ?

Non. Les ADMIN peuvent uniquement gérer les AGENT et COMPTA. Seul le SUPER_ADMIN peut modifier un ADMIN.

### Pourquoi le COMPTA ne peut pas uploader de documents ?

Le rôle COMPTA est en **lecture seule** pour éviter toute modification des données opérationnelles ou financières. Il peut uniquement consulter.

### Comment ajouter un nouveau SUPER_ADMIN ?

Seul le **STAFF Odentas** peut créer un SUPER_ADMIN. Contactez support@odentas.com.

### Le COMPTA peut-il voir les fiches de paie ?

Non. Le COMPTA ne voit que les **données financières agrégées** :
- Cotisations mensuelles (montants globaux)
- Virements salaires (montants globaux)
- Factures
- Documents comptables

Les fiches de paie détaillées sont réservées aux rôles opérationnels (SUPER_ADMIN, ADMIN, AGENT).

### Un AGENT peut-il créer des factures ?

Non. Les factures sont considérées comme des **ressources financières**. Seuls SUPER_ADMIN et ADMIN ont accès.

---

## Support Technique

Pour toute question sur les permissions ou demande de modification de rôle, contactez :

**Support Odentas**
- Email : support@odentas.com
- Interface : [Espace Paie Odentas](https://espace-paie.odentas.com)

---

**Version :** 1.0  
**Dernière mise à jour :** Janvier 2025  
**Auteur :** Équipe Technique Odentas