===================================== Matrice des Permissions par Rôle ===================================== Ce document décrit en détail les permissions accordées à chaque rôle dans l'application KoproGo. Vue d'ensemble des rôles ========================= KoproGo implémente un système de contrôle d'accès basé sur les rôles (RBAC) avec 4 rôles principaux: 1. **SuperAdmin** - Administrateur de la plateforme SaaS 2. **Syndic** - Gestionnaire de copropriété 3. **Accountant** (Comptable) - Gestionnaire comptable 4. **Owner** (Copropriétaire) - Propriétaire d'un lot Règles métier fondamentales ============================ Données structurelles (Immuables après création) ------------------------------------------------- Les **buildings** et **units** (avec leurs quotités) constituent la structure de base d'une copropriété. Ces données ne changent pratiquement jamais après l'encodage initial. Pour éviter les erreurs: - ✅ Seul le **SuperAdmin** peut créer/modifier/supprimer buildings et units - ❌ Le **Syndic** ne peut PAS modifier ces données structurelles - 💡 **Raison**: Prévenir les erreurs sur des données critiques qui impactent tous les calculs de charges Principe de transparence ------------------------- Tous les rôles peuvent **lire** toutes les données de leur organisation pour garantir la transparence de la gestion. Séparation des responsabilités ------------------------------- - **SuperAdmin**: Configuration initiale et gestion multi-tenant - **Syndic**: Gestion quotidienne de la copropriété - **Accountant**: Saisie comptable et gestion des paiements - **Owner**: Consultation uniquement Matrice détaillée des permissions ================================== Buildings (Immeubles) --------------------- +-------------------+------------+--------+------------+-------+ | Action | SuperAdmin | Syndic | Accountant | Owner | +===================+============+========+============+=======+ | Créer | ✅ | ❌ | ❌ | ❌ | +-------------------+------------+--------+------------+-------+ | Lire | ✅ | ✅ | ✅ | ✅ | +-------------------+------------+--------+------------+-------+ | Modifier | ✅ | ❌ | ❌ | ❌ | +-------------------+------------+--------+------------+-------+ | Supprimer | ✅ | ❌ | ❌ | ❌ | +-------------------+------------+--------+------------+-------+ Units (Lots) ------------ +-------------------+------------+--------+------------+-------+ | Action | SuperAdmin | Syndic | Accountant | Owner | +===================+============+========+============+=======+ | Créer | ✅ | ❌ | ❌ | ❌ | +-------------------+------------+--------+------------+-------+ | Lire | ✅ | ✅ | ✅ | ✅ | +-------------------+------------+--------+------------+-------+ | Modifier | ✅ | ❌ | ❌ | ❌ | +-------------------+------------+--------+------------+-------+ | Modifier quotités | ✅ | ❌ | ❌ | ❌ | +-------------------+------------+--------+------------+-------+ | Supprimer | ✅ | ❌ | ❌ | ❌ | +-------------------+------------+--------+------------+-------+ Owners (Copropriétaires) ------------------------ +-------------------+------------+--------+------------+-------+ | Action | SuperAdmin | Syndic | Accountant | Owner | +===================+============+========+============+=======+ | Créer | ✅ | ✅ | ❌ | ❌ | +-------------------+------------+--------+------------+-------+ | Lire | ✅ | ✅ | ✅ | ✅ | +-------------------+------------+--------+------------+-------+ | Modifier | ✅ | ✅ | ❌ | ❌ | +-------------------+------------+--------+------------+-------+ | Supprimer | ✅ | ✅ | ❌ | ❌ | +-------------------+------------+--------+------------+-------+ | Lier à un User | ✅ | ❌ | ❌ | ❌ | +-------------------+------------+--------+------------+-------+ Unit-Owner Relations (Qui possède quoi) ---------------------------------------- +------------------------+------------+--------+------------+-------+ | Action | SuperAdmin | Syndic | Accountant | Owner | +========================+============+========+============+=======+ | Ajouter propriétaire | ✅ | ✅ | ❌ | ❌ | +------------------------+------------+--------+------------+-------+ | Retirer propriétaire | ✅ | ✅ | ❌ | ❌ | +------------------------+------------+--------+------------+-------+ | Modifier quote-part | ✅ | ✅ | ❌ | ❌ | +------------------------+------------+--------+------------+-------+ | Transférer propriété | ✅ | ✅ | ❌ | ❌ | +------------------------+------------+--------+------------+-------+ | Voir relations | ✅ | ✅ | ✅ | ✅ | +------------------------+------------+--------+------------+-------+ | Voir historique | ✅ | ✅ | ✅ | ✅ | +------------------------+------------+--------+------------+-------+ Expenses (Charges) ------------------ +-------------------+------------+--------+------------+-------+ | Action | SuperAdmin | Syndic | Accountant | Owner | +===================+============+========+============+=======+ | Créer | ✅ | ✅ | ✅ | ❌ | +-------------------+------------+--------+------------+-------+ | Lire | ✅ | ✅ | ✅ | ✅ | +-------------------+------------+--------+------------+-------+ | Modifier | ✅ | ✅ | ❌ | ❌ | +-------------------+------------+--------+------------+-------+ | Marquer payé | ✅ | ✅ | ✅ | ❌ | +-------------------+------------+--------+------------+-------+ | Annuler | ✅ | ✅ | ❌ | ❌ | +-------------------+------------+--------+------------+-------+ | Réactiver | ✅ | ✅ | ❌ | ❌ | +-------------------+------------+--------+------------+-------+ | Supprimer | ✅ | ✅ | ❌ | ❌ | +-------------------+------------+--------+------------+-------+ Meetings (Assemblées) --------------------- +-------------------+------------+--------+------------+-------+ | Action | SuperAdmin | Syndic | Accountant | Owner | +===================+============+========+============+=======+ | Créer | ✅ | ✅ | ❌ | ❌ | +-------------------+------------+--------+------------+-------+ | Lire | ✅ | ✅ | ✅ | ✅ | +-------------------+------------+--------+------------+-------+ | Modifier | ✅ | ✅ | ❌ | ❌ | +-------------------+------------+--------+------------+-------+ | Compléter | ✅ | ✅ | ❌ | ❌ | +-------------------+------------+--------+------------+-------+ | Annuler | ✅ | ✅ | ❌ | ❌ | +-------------------+------------+--------+------------+-------+ Documents --------- +--------------------+------------+--------+------------+-------+ | Action | SuperAdmin | Syndic | Accountant | Owner | +====================+============+========+============+=======+ | Upload | ✅ | ✅ | ✅ | ❌ | +--------------------+------------+--------+------------+-------+ | Lire/Télécharger | ✅ | ✅ | ✅ | ✅ | +--------------------+------------+--------+------------+-------+ | Supprimer | ✅ | ✅ | ❌ | ❌ | +--------------------+------------+--------+------------+-------+ Organizations ------------- +-------------------+------------+--------+------------+-------+ | Action | SuperAdmin | Syndic | Accountant | Owner | +===================+============+========+============+=======+ | Créer | ✅ | ❌ | ❌ | ❌ | +-------------------+------------+--------+------------+-------+ | Lire | ✅ | ✅\* | ❌ | ❌ | +-------------------+------------+--------+------------+-------+ | Modifier | ✅ | ❌ | ❌ | ❌ | +-------------------+------------+--------+------------+-------+ | Supprimer | ✅ | ❌ | ❌ | ❌ | +-------------------+------------+--------+------------+-------+ \* Syndic peut voir uniquement les données de sa propre organisation Users ----- +-------------------+------------+--------+------------+-------+ | Action | SuperAdmin | Syndic | Accountant | Owner | +===================+============+========+============+=======+ | Créer | ✅ | ✅\*\* | ❌ | ❌ | +-------------------+------------+--------+------------+-------+ | Lire | ✅ | ✅\* | ❌ | ❌ | +-------------------+------------+--------+------------+-------+ | Modifier | ✅ | ✅\*\* | ❌ | ❌ | +-------------------+------------+--------+------------+-------+ | Supprimer | ✅ | ❌ | ❌ | ❌ | +-------------------+------------+--------+------------+-------+ \*\* Syndic peut créer/modifier des users uniquement dans sa propre organisation Détails par rôle ================ SuperAdmin ---------- **Responsabilité**: Administration de la plateforme multi-tenant **Permissions**: - ✅ Accès complet à toutes les organisations - ✅ Création et configuration initiale des buildings et units - ✅ Spécification libre de l'organization_id et building_id lors de la création - ✅ Gestion des organizations - ✅ Liaison des comptes User aux entités Owner - ✅ Peut opérer au niveau de n'importe quelle organisation **Cas d'usage typiques**: 1. Créer une nouvelle organisation (syndic) 2. Configurer la structure initiale d'un immeuble (lots, quotités) 3. Lier un compte utilisateur owner à l'entité propriétaire correspondante 4. Support et dépannage multi-tenant **Endpoints spécifiques**: - ``PUT /owners/{id}/link-user`` - Lier un user à un owner Syndic ------ **Responsabilité**: Gestion quotidienne d'une copropriété **Permissions**: - ✅ Gestion des owners (créer, modifier, supprimer) - ✅ Gestion des attributions (qui possède quel lot) - ✅ Gestion des expenses (créer, marquer payé, annuler) - ✅ Gestion des meetings - ✅ Upload et gestion des documents - ✅ Lecture de toutes les données de son organisation - ❌ Ne peut PAS modifier buildings ni units (données structurelles) **Cas d'usage typiques**: 1. Ajouter un nouveau copropriétaire 2. Attribuer un lot à un propriétaire lors d'une vente 3. Créer et gérer les charges 4. Organiser les assemblées générales 5. Uploader les procès-verbaux et documents officiels **Restrictions importantes**: - Scope limité à sa propre organization_id - Ne peut pas modifier la structure (buildings/units) pour éviter les erreurs - Ne peut pas lier des users aux owners (réservé au SuperAdmin) Accountant (Comptable) ---------------------- **Responsabilité**: Saisie comptable et gestion des paiements **Permissions**: - ✅ Créer des expenses - ✅ Marquer les expenses comme payés - ✅ Upload de documents (factures, justificatifs) - ✅ Lecture complète de toutes les données (transparence) - ❌ Ne peut PAS modifier buildings, units, owners - ❌ Ne peut PAS gérer les attributions de propriété - ❌ Ne peut PAS annuler ou modifier des expenses **Cas d'usage typiques**: 1. Encoder les factures reçues 2. Pointer les paiements effectués 3. Uploader les justificatifs comptables 4. Consulter les données pour préparer les comptes **Restrictions importantes**: - Rôle strictement limité à la comptabilité - Pas d'accès aux données structurelles (lecture seule) - Pas de gestion des propriétaires Owner (Copropriétaire) ---------------------- **Responsabilité**: Consultation de ses données **Permissions**: - ✅ Lecture complète de toutes les données de son organisation (transparence) - ❌ Aucune modification (lecture seule complète) **Cas d'usage typiques**: 1. Consulter ses lots 2. Voir les charges et leur état de paiement 3. Télécharger les procès-verbaux 4. Consulter les autres copropriétaires (transparence) **Restrictions importantes**: - Aucune action de modification possible - Rôle strictement consultatif Implémentation technique ======================== Vérification des permissions ----------------------------- Les permissions sont vérifiées au niveau des **handlers HTTP** via le middleware ``AuthenticatedUser`` qui extrait le rôle du JWT. **Exemple de vérification** (building_handlers.rs):: #[post("/buildings")] pub async fn create_building( state: web::Data, user: AuthenticatedUser, dto: web::Json, ) -> impl Responder { // Only SuperAdmin can create buildings (structural data) if user.role != "superadmin" { return HttpResponse::Forbidden().json(serde_json::json!({ "error": "Only SuperAdmin can create buildings" })); } // ... rest of the handler } Fonctions helper ---------------- Pour éviter la duplication, des fonctions helper sont utilisées:: // expense_handlers.rs fn check_owner_readonly(user: &AuthenticatedUser) -> Option { if user.role == "owner" { Some(HttpResponse::Forbidden().json(serde_json::json!({ "error": "Owner role has read-only access" }))) } else { None } } // unit_owner_handlers.rs fn check_unit_ownership_permission(user: &AuthenticatedUser) -> Option { if user.role == "owner" || user.role == "accountant" { Some(HttpResponse::Forbidden().json(serde_json::json!({ "error": "Only SuperAdmin and Syndic can modify unit ownership" }))) } else { None } } Organisation Scoping -------------------- Pour les rôles non-SuperAdmin, les requêtes sont automatiquement scopées à leur ``organization_id`` via le JWT:: let organization_id = user.require_organization()?; // Filters all queries by this organization_id Messages d'erreur ================= Lorsqu'un utilisateur tente une action non autorisée, il reçoit: - **Code HTTP**: ``403 Forbidden`` - **Message**: Description claire de la restriction **Exemples de messages**: +------------+------------------+--------------------------------------------------------------------+ | Rôle | Action | Message | +============+==================+====================================================================+ | Syndic | Créer building | "Only SuperAdmin can create buildings (structural data)" | +------------+------------------+--------------------------------------------------------------------+ | Accountant | Modifier unit | "Only SuperAdmin can update units (structural data)" | +------------+------------------+--------------------------------------------------------------------+ | Owner | Créer expense | "Owner role has read-only access" | +------------+------------------+--------------------------------------------------------------------+ | Syndic | Lier user-owner | "Only SuperAdmin can link users to owners" | +------------+------------------+--------------------------------------------------------------------+ Évolution et maintenance ======================== Ajouter un nouveau endpoint ---------------------------- 1. Déterminer quel(s) rôle(s) peut/peuvent y accéder 2. Ajouter la vérification de permission en début de handler 3. Mettre à jour cette documentation 4. Ajouter des tests pour vérifier les restrictions Modifier les permissions existantes ------------------------------------ 1. Discuter et valider le changement métier 2. Modifier les handlers concernés 3. Mettre à jour cette documentation 4. Vérifier les tests existants 5. Communiquer le changement aux utilisateurs Références ========== **Code source**: - Building handlers: ``backend/src/infrastructure/web/handlers/building_handlers.rs`` - Unit handlers: ``backend/src/infrastructure/web/handlers/unit_handlers.rs`` - Owner handlers: ``backend/src/infrastructure/web/handlers/owner_handlers.rs`` - Unit-Owner handlers: ``backend/src/infrastructure/web/handlers/unit_owner_handlers.rs`` - Expense handlers: ``backend/src/infrastructure/web/handlers/expense_handlers.rs`` **Middleware**: ``backend/src/infrastructure/web/mod.rs`` (AuthenticatedUser) **Tests**: - ``backend/tests/e2e_auth.rs`` - Tests E2E d'authentification et permissions - ``backend/tests/features/auth.feature`` - Tests BDD multi-rôles Notes de sécurité ================= 1. **Jamais de confiance côté client**: Toutes les permissions sont vérifiées côté serveur 2. **JWT sécurisé**: Le rôle est extrait du JWT signé et ne peut être falsifié 3. **Organization scoping**: Les utilisateurs ne peuvent accéder qu'aux données de leur organisation 4. **Audit logging**: Toutes les actions de modification sont loggées pour audit 5. **Principe du moindre privilège**: Chaque rôle a le minimum de permissions nécessaires ---- **Dernière mise à jour**: 31 octobre 2025 **Version**: 1.0