docs(#117): CDC V1.4 (users à jour, reste conservé) + SRS utilisateurs.

- CDC complet conservé ; sections gestion utilisateurs / dossiers alignées v0.1.0 - Archive V1.3 + EVOLUTIONS_CDC ; nouvelle 12_SRS-GESTION-UTILISATEURS - INDEX / versions / bilan mis à jour Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-15 10:22:32 +02:00
parent 71b1897678
commit 89f65356d1
11 changed files with 1657 additions and 92 deletions
@@ -0,0 +1,250 @@
+# SRS — Gestion des utilisateurs (domaine livré v0.1.0)
+
+**Version** : 1.0  
+**Date** : 15/09/2026  
+**Ticket** : [#117](https://git.ptits-pas.fr/jmartin/petitspas/issues/117)  
+**Niveau** : **technique** (dev / QA)  
+**CDC associé** : [01_CAHIER-DES-CHARGES.md](./01_CAHIER-DES-CHARGES.md) (V1.4 — **CDC complet** ; cette SRS ne couvre que le domaine utilisateurs)
+
+> Périmètre SRS : comptes, auth liée, dossiers famille/AM, enfants, affiliations, dashboard staff, suppressions.  
+> Le CDC V1.4 conserve **l’ensemble** des chapitres cibles (contrats, messagerie, etc.) ; ils ne sont **pas** redécrits ici.  
+> Hors SRS technique : OpenAPI exhaustif, PRA/CI → voir [11_API](./11_API.md), [10_DATABASE](./10_DATABASE.md).
+
+---
+
+## 1. Glossaire
+
+| Terme | Définition |
+|-------|------------|
+| **User / utilisateur** | Compte authentifiable (`utilisateurs`) avec `role` et `statut` |
+| **Parent pivot** | Responsable principal du foyer à l’inscription / création staff |
+| **Co-parent** | Second responsable optionnel (au plus un), lié au pivot |
+| **Foyer** | Pivot + co-parent éventuel + enfants affiliés |
+| **Dossier** | Unité métier identifiée par `numero_dossier` (format `AAAA-NNNNNN`) — famille ou AM |
+| **Pending / en_attente** | Compte ou dossier en attente de validation staff |
+| **Refus** | Rejet sans suppression ; ouvre la **reprise** |
+| **Relais** | Structure RPE ; rattachement optionnel d’un gestionnaire |
+| **Staff** | `gestionnaire`, `administrateur`, `super_admin` |
+
+---
+
+## 2. Acteurs et rôles applicatifs
+
+| `role` | Inscription publique | Dashboard staff | Créer staff | Suppressions métier usagers | Supprimer gestionnaire | Supprimer admin |
+|--------|---------------------|-----------------|-------------|----------------------------|------------------------|-----------------|
+| `parent` | oui | non | non | non | non | non |
+| `assistante_maternelle` | oui | non | non | non | non | non |
+| `gestionnaire` | non (créé staff) | oui | non | oui* | non | non |
+| `administrateur` | non | oui | oui | oui* | oui | oui** |
+| `super_admin` | non (install) | oui | oui | oui* | oui | oui** |
+
+\* Sous réserve des garde-fous (pas soi-même pour sa fiche staff, etc.).  
+\*\* Pas soi-même ; pas de cible `super_admin` ; dernier admin : règles `canDeleteAdministrateur` (front `staff_deletion_rights.dart`).
+
+Réf. front : `frontend/lib/utils/staff_deletion_rights.dart`  
+- `canCreateStaffAccounts` → admin / super_admin  
+- `canDeleteMetier` → gestionnaire / admin / super_admin  
+- `canDeleteGestionnaire` → admin / super_admin  
+
+---
+
+## 3. Statuts
+
+### 3.1 Utilisateur (`statut_utilisateur_type`)
+
+| Statut | Signification |
+|--------|----------------|
+| `en_attente` | Inscrit, non validé ; **login refusé** |
+| `actif` | Validé / utilisable |
+| `suspendu` | Bloqué ; **login refusé** |
+
+### 3.2 Enfant (`statut_enfant_type`)
+
+Valeurs actuelles : `a_naitre`, `actif`, `scolarise` (évolution métier « gardé / sans garde » **hors** cette SRS — ticket dédié).
+
+### 3.3 Validation dossier
+
+Circuit staff : revue → **valider** ou **refuser**. Refus ≠ delete. Reprise → nouveau passage en attente.
+
+---
+
+## 4. Modèle de données (vue synthétique)
+
+```mermaid
+flowchart TB
+  user[utilisateurs]
+  parent[parents]
+  am[assistantes_maternelles]
+  enfant[enfants]
+  ep[enfants_parents]
+  df[dossier_famille]
+  user --> parent
+  user --> am
+  parent --> ep
+  enfant --> ep
+  parent --> df
+```
+
+| Concept | Tables / liens clés |
+|---------|---------------------|
+| Compte | `utilisateurs` (role, statut, email, numero_dossier, relais…) |
+| Parent | `parents` (+ `id_co_parent` optionnel) |
+| AM | `assistantes_maternelles` (agrément, capacité, NIR…) |
+| Enfant | `enfants` |
+| Affiliation parent | `enfants_parents` (N–N) |
+| Dossier famille | `dossier_famille` (+ enfants dossier) |
+| Tokens MDP | tables / flux tokens création & reset (TTL, usage unique) |
+
+Détail colonnes : [10_DATABASE.md](./10_DATABASE.md).
+
+### Invariants
+
+1. **Pas** de champ `est_multiple` / naissance multiple (#152).  
+2. Au plus **un** co-parent par fiche parent.  
+3. Affiliation création enfant : rattache **pivot + co-parent** s’il existe (#158).  
+4. Détachement du **dernier** parent → enfant **sans responsable** possible (#157).  
+5. Rattachement AM plafonné par **capacité** (#148 / #149).  
+6. `super_admin` **non supprimable**.
+
+---
+
+## 5. Flux
+
+### 5.1 Inscription → validation → mot de passe
+
+```mermaid
+sequenceDiagram
+  participant U as Usager
+  participant API as API
+  participant S as Staff
+  participant M as Mail
+  U->>API: register parent/AM
+  API-->>U: numero_dossier, statut en_attente
+  S->>API: review / valider
+  API->>M: mail lien create-password
+  U->>API: verify token + set password
+  API-->>U: compte actif, login OK
+```
+
+Variante **refus** : staff refuse → mail refus → usager **reprise** (token lien ou n° dossier) → resoumission → à valider.
+
+### 5.2 Mot de passe oublié
+
+Flux distinct de la création post-validation : demande → e-mail → reset (#127). Tokens durcis (#123).
+
+### 5.3 Création dossier staff
+
+- Famille : wizard + `POST` staff parent/dossier (#129).  
+- AM : wizard + API staff AM (#156).  
+- Édition : mode `edit` wizards + PATCH fiches ; ajout co-parent `POST …/co-parent` (#135).
+
+### 5.4 Rattachements
+
+| Lien | Opérations |
+|------|------------|
+| Parent ↔ enfant | attach / detach (fiche parent, fiche enfant) |
+| AM ↔ enfant | attach / detach (fiche AM, fiche enfant) ; UI capacité |
+
+API : tickets #115 / #116 ; liste enfants enrichie #136.
+
+---
+
+## 6. Matrice droits × actions (synthèse)
+
+| Action | gestionnaire | administrateur | super_admin |
+|--------|:------------:|:--------------:|:-----------:|
+| Voir dashboard usagers / dossiers | ✓ | ✓ | ✓ |
+| Valider / refuser dossier | ✓ | ✓ | ✓ |
+| Créer dossier parent / AM | ✓ | ✓ | ✓ |
+| Éditer fiches parent / AM / enfant | ✓ | ✓ | ✓ |
+| Rattacher / détacher enfant | ✓ | ✓ | ✓ |
+| GET liste relais (combo) | ✓ | ✓ | ✓ |
+| Créer gestionnaire / admin | ✗ | ✓ | ✓ |
+| Supprimer parent / AM / enfant / dossier | ✓ | ✓ | ✓ |
+| Supprimer gestionnaire | ✗ | ✓ | ✓ |
+| Supprimer admin (garde-fous) | ✗ | ✓* | ✓* |
+| Supprimer super_admin | ✗ | ✗ | ✗ |
+| Supprimer son propre compte staff | ✗ | ✗ | ✗ |
+
+\* Voir `canDeleteAdministrateur` / messages `adminDeleteBlockedReason`.
+
+---
+
+## 7. UI staff (points d’entrée code)
+
+| Zone | Emplacement typique |
+|------|---------------------|
+| Panneau gestion users | `widgets/dashboard/user_management_panel.dart` |
+| Onglets parents / AM / enfants / dossiers | `widgets/dashboard/*_management_widget.dart` |
+| Fiche parent | `parent_edit_modal.dart` |
+| Fiche AM | `am_edit_modal.dart` |
+| Fiche enfant | `child_detail_modal.dart` |
+| Wizards dossier | `parent_dossier_wizard.dart`, `am_dossier_wizard.dart` |
+| Modale staff | `staff_user_form_modal.dart` (`StaffUserFormModal`) |
+| Confirm suppressions | `widgets/dashboard/common/suppression_confirm_dialog.dart` |
+| Champs contrôlés | `validation_detail_section.dart` (`ValidationEmailField`, `ValidationPhoneField`…) |
+| Thème primaire modales | `validation_modal_theme.dart` |
+
+Shell fiches / wizards : largeur **930**, labels au-dessus, primaire violet `ValidationModalTheme`.
+
+---
+
+## 8. API — groupes (renvoi)
+
+Ne pas dupliquer OpenAPI ici. Groupes utiles au domaine :
+
+| Groupe | Exemples d’usage |
+|--------|------------------|
+| Auth / register | Inscription parent & AM, login, tokens MDP, oubli MDP |
+| Dossiers | `GET /dossiers/:numero`, listes à valider / unifiées, validate/refuse |
+| Parents | Fiche PATCH, co-parent POST, dossier staff POST |
+| AM | Fiche PATCH, dossier staff POST |
+| Enfants | CRUD staff, attach/detach parent & AM |
+| Users / staff | CRUD gestionnaires / admins, DELETE métier |
+| Relais | `GET /relais` (autorisé gestionnaire — #151) |
+| Config | setup / configuration instance |
+
+Référence : [11_API.md](./11_API.md) (à maintenir en parallèle si écart).
+
+---
+
+## 9. Exigences non fonctionnelles (domaine users)
+
+| ID | Exigence |
+|----|----------|
+| NFR-U1 | Tokens création / reset MDP : TTL strict, usage unique |
+| NFR-U2 | Mots de passe : politique min. longueur (création staff / usager selon flux) |
+| NFR-U3 | E-mails métier (validation, refus, MDP) via config SMTP instance |
+| NFR-U4 | Pas de login si `en_attente` ou `suspendu` |
+| NFR-U5 | Confirmations explicites avant toute suppression |
+| NFR-U6 | Champs e-mail / téléphone : validation & normalisation côté UI staff (SRS UX #164) |
+
+Hors scope immédiat : normalisation erreurs auth globale (#121), observabilité (#122), audit trail complet (#128).
+
+---
+
+## 10. Limites modèle famille (assumées)
+
+Documentées pour les développeurs — détail produit : [28_EVOLUTION-FAMILLE-ET-RESPONSABLES.md](./28_EVOLUTION-FAMILLE-ET-RESPONSABLES.md).
+
+- Un `numero_dossier` / user ; un seul co-parent.  
+- Familles recomposées multi-contextes : contournement (2ᵉ compte / composition staff) jusqu’à epic #139.  
+- La SRS **n’exige pas** N responsables en v0.1.0.
+
+---
+
+## 11. Traçabilité livré 0.1.0
+
+Source : [29_BILAN-VERSION-0.1.0.md](./29_BILAN-VERSION-0.1.0.md) — 48 tickets milestone 0.1.0 (auth, inscription, fiches, dossiers, suppressions, cleanups #152/#155/#162/#164).
+
+---
+
+## 12. Hors périmètre de cette SRS
+
+- Contrats, avenants, fin de contrat (restent dans le **CDC** cible)  
+- Messagerie, agenda, événements RPE (idem CDC)  
+- Paie / Pajemploi  
+- Recherche AM côté parent  
+- PRA, CI/CD, monitoring infra  
+- Spécification OpenAPI ligne à ligne  
+- Texte fonctionnel complet → [01_CAHIER-DES-CHARGES.md](./01_CAHIER-DES-CHARGES.md)