unionflow-server-api/unionflow/specs/admin-org-membres-import-quota.md

# Admin organisation : gestion des membres et import massif Excel avec quota

## Contexte

- Un **administrateur d’organisation** (ADMIN_ORGANISATION) doit pouvoir **gérer les membres de son organisation** (liste, création unitaire, modification).
- Il doit pouvoir **créer des membres en masse** via un **fichier Excel strictement formaté**.
- Le nombre de créations doit être **plafonné** par le **quota de la souscription** (tranche/forme d’abonnement) de l’organisation.

## Règles métier

1. **Droits**
   - ADMIN_ORGANISATION : accès limité aux membres des organisations qu’il gère (liste, détail, création, mise à jour, import).
   - ADMIN / SUPER_ADMIN : accès à tous les membres (comportement actuel).

2. **Import massif**
   - Format : **Excel (.xlsx)** (et optionnellement CSV) avec colonnes obligatoires strictes (ex. nom, prénom, email, téléphone).
   - **organisationId** obligatoire pour un org admin ; les membres créés sont rattachés à cette organisation (création de `MembreOrganisation`).
   - **Quota** : avant d’accepter l’import, vérifier que  
     `quota_utilise + nombre de nouveaux membres à créer ≤ quota_max`  
     (ou pas de limite si `quota_max` est null, ex. formule Crystal).
   - À chaque membre **nouvellement créé** (pas les mises à jour) : créer le lien `MembreOrganisation` et incrémenter `quota_utilise` de la souscription.
   - Si le quota est dépassé en cours d’import : rejeter la requête (ou arrêter et retourner les erreurs selon le choix métier).

3. **Souscription**
   - Une organisation (racine) a au plus une souscription active (`souscriptions_organisation`).
   - `quota_max` = snapshot de la formule (ex. 50 pour Starter, null pour Crystal).
   - `quota_utilise` = nombre de membres comptabilisés pour cette souscription (incrémenté à chaque adhésion validée / membre créé dans l’org).

## Existant (WOU/DRY)

- **Backend**
  - `MembreResource` : GET list, GET /recherche, POST create, POST /import, GET /import/modele — existants ; à sécuriser et à scoper pour ADMIN_ORGANISATION.
  - `MembreImportExportService.importerMembres` : import Excel/CSV existant ; prend déjà `organisationId` ; **manque** : création de `MembreOrganisation`, vérification et incrément du quota.
  - Entités : `SouscriptionOrganisation` (quota_max, quota_utilise, incrementerQuota), `FormuleAbonnement` (max_membres), `MembreOrganisation` (lien membre–organisation).
- **Mobile**
  - Annuaire membres : critères de recherche avec `organisationIds` ; pour org admin, passer les IDs de “mes organisations” (déjà possible côté app si l’API les filtre).

## Implémentation préconisée

### Backend

1. **Sécurité et périmètre**
   - Sur `MembreResource` : ajouter `@RolesAllowed` adaptés (ex. MEMBRE, ADMIN, ADMIN_ORGANISATION pour liste/création/import).
   - Pour un utilisateur avec rôle ADMIN_ORGANISATION (et sans ADMIN/SUPER_ADMIN) :  
     - Lister les organisations du membre connecté (ex. `OrganisationService.listerOrganisationsPourUtilisateur(email)`).  
     - **Liste / recherche** : filtrer les membres par ces `organisationIds` (via `MembreOrganisation`).  
     - **Création** : exiger un `organisationId` dans le corps (ou le déduire) et vérifier qu’il appartient à ses organisations ; créer le `MembreOrganisation` après création du membre.  
     - **Import** : exiger `organisationId` et vérifier qu’il appartient à ses organisations ; appliquer la règle de quota et créer les `MembreOrganisation` + incrément de quota.

2. **Quota et import**
   - **Repository** : `SouscriptionOrganisationRepository` avec `findByOrganisationId(UUID)` (souscription active si besoin).
   - **Import** (dans `MembreImportExportService` ou service appelant) :  
     - Si `organisationId != null` : charger la souscription active de l’organisation.  
     - Pour chaque ligne du fichier : si c’est un **nouveau** membre (création, pas mise à jour) :  
       - Vérifier `souscription.getPlacesRestantes() > 0` (ou pas de limite si `quota_max == null`).  
       - Si dépassement : erreur explicite (ex. “Quota souscription atteint (max N membres)”) et arrêt ou rapport d’erreur.  
       - Après `creerMembre` : créer `MembreOrganisation` (membre, organisation, statut, dateAdhesion), persister, puis `souscription.incrementerQuota()` et persister la souscription.

3. **Modèle Excel**
   - Conserver le modèle actuel (GET `/api/membres/import/modele`) ; documenter les colonnes obligatoires et le fait que le fichier doit être strict (pas de colonnes en plus / types cohérents si besoin).
   - Optionnel : endpoint GET pour “quota actuel / places restantes” par organisation (pour affichage côté client).

### Mobile (optionnel dans un second temps)

- Pour un org admin : envoyer en requête liste/recherche les `organisationIds` (ses organisations) pour n’afficher que les membres de son périmètre.
- Écran “Import membres” : choix de l’organisation (pré-rempli si une seule), upload du fichier Excel, affichage du quota restant (si l’API le fournit) et du résultat d’import (succès / erreurs).

## Critères d’acceptation

- [ ] Un admin d’organisation ne voit que les membres de ses organisations (liste, recherche).
- [ ] Un admin d’organisation peut créer un membre dans une de ses organisations (et le lien MembreOrganisation est créé).
- [ ] Un admin d’organisation peut lancer un import Excel avec `organisationId` ; le fichier est validé (format strict), le quota souscription est vérifié avant/pendant l’import.
- [ ] Les nouveaux membres créés lors de l’import sont rattachés à l’organisation et le quota souscription est incrémenté.
- [ ] Si le quota est dépassé (fichier trop gros ou quota déjà saturé), l’import est refusé ou s’arrête avec un message clair (quota max N, X demandés, etc.).