petitspas/docs/12_SRS-GESTION-UTILISATEURS.md

SRS — Gestion des utilisateurs (domaine livré v0.1.0)

Version : 1.0
Date : 15/09/2026
Ticket : #117
Niveau : technique (dev / QA)
CDC associé : 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, 10_DATABASE.

---

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)

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.

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

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 (à 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.

• 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 — 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