# 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)