docs(r0): kickoff SIOP V2 — vision, cadrage, charte graphique, maquettes HD

Refondation design-first du projet SIOP (v1 gelée) :
- Playbook 00-vision (charte projet, personas, benchmark Atlas)
- Playbook 01-cadrage (releases R0→R5 + DoD, user-story map, exigences, risques)
- Playbook 02-design : charte graphique, tokens.css bi-thème (palettes
  analytics validées CVD/contraste par script), maquettes HD navigables
  (7 écrans dont démo-login DEMO_MODE, bilan codé, portail QR, mobile)

Prochaine étape : validation des maquettes par le référent avant tout code.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/01-cadrage/exigences.md

@@ -0,0 +1,55 @@
+# Exigences non fonctionnelles — SIOP V2
+
+> **Rôle de ce document (playbook)** : les exigences fonctionnelles vivent dans la
+> user-story map et les issues ; ici on fige ce qui est **transversal** — qualité, sécurité,
+> conformité, exploitation — avec des critères **mesurables** (sinon invérifiables).
+
+## Qualité & design
+
+| Exigence | Critère mesurable |
+| --- | --- |
+| Fidélité au design | Revue pixel par release : écrans conformes aux maquettes validées (`../02-design/`) |
+| Réactivité | Interfaces utilisables de 360 px (mobile) à 1920 px ; tables scrollables sans casser la page |
+| Thème | Clair **et** sombre, pilotés par les tokens ; aucun style codé en dur hors tokens |
+| Accessibilité | Navigation clavier sur les parcours critiques ; libellés/aria sur tous les contrôles ; contraste AA |
+| Langue | 100 % français (produit), zéro franglais dans l'UI |
+
+## Performance
+
+| Exigence | Critère |
+| --- | --- |
+| Chargement des listes | < 1 s pour 10 000 OT (pagination serveur, index SQL) |
+| Tableau de bord | < 2 s (agrégations SQL, jamais de calcul en mémoire sur tout l'historique) |
+| Mobile offline | Ouverture d'un OT déjà synchronisé : instantanée (< 200 ms, lecture locale) |
+
+## Sécurité
+
+| Exigence | Critère |
+| --- | --- |
+| API fermée par défaut | Guard JWT global ; routes publiques explicitement `@Public()` ; test de couverture des routes |
+| Permissions | Matrice rôles × objets × droits **en base** (jamais dans le JWT), testée rôle par rôle |
+| Démo-login | `POST /auth/demo-login` **inexistant** (404) si `DEMO_MODE` n'est pas `true` ; jamais activé en production réelle ; test e2e dédié |
+| Fichiers | Accès aux objets MinIO uniquement par URL signée à durée courte ; clés opaques |
+| Secrets | Jamais en git ; `.env.example` exhaustifs ; secrets Dokploy |
+
+## Conformité (loi 09-08)
+
+Consentement explicite pour toute géolocalisation ; géolocalisation limitée aux heures de
+service ; purge des enregistrements audio après transcription (R5) ; droit d'accès/rectification
+des données personnelles (procédure au runbook).
+
+## Fiabilité & exploitation
+
+| Exigence | Critère |
+| --- | --- |
+| Sauvegardes | PostgreSQL + MinIO sauvegardés quotidiennement ; restauration testée 1×/release (runbook) |
+| Migrations | `prisma migrate deploy` rejouable ; seed idempotent (rejouer ne casse rien) |
+| Offline mobile | Aucune saisie terrain perdue : file locale + verrou optimiste + rejeu (testé) |
+| Supervision | Endpoint `/health` (base, Redis, MinIO) ; vérifié au déploiement |
+
+## Testabilité
+
+Pyramide : unitaires (logique pure), intégration contre infra réelle (Docker), parcours
+navigateur Playwright (1+ par release), mobile testé en Node (`node:sqlite`), contrat
+OpenAPI bloquant en CI. Couverture API ≥ 70 % **bloquante**. Chaque bug corrigé = un test
+qui l'aurait attrapé.

docs/01-cadrage/releases.md

@@ -0,0 +1,71 @@
+# Plan de releases — SIOP V2
+
+> **Rôle de ce document (playbook)** : découper le produit en releases **fermées** — chaque
+> release a un périmètre figé, une définition de fini (DoD) et se termine par une recette
+> formelle + un déploiement. On n'ouvre pas Rn+1 avant la clôture de Rn. C'est l'antidote
+> à la dérive de périmètre constatée en v1.
+
+## Définition de fini (DoD) commune à toutes les releases
+
+1. Toutes les stories de la release recettées (critères d'acceptation × preuves).
+2. CI verte : lint, typecheck, tests (couverture API ≥ 70 % bloquante), contrat OpenAPI à jour.
+3. **Revue pixel** : les écrans livrés sont conformes aux maquettes validées.
+4. Déployé en production (Dokploy) et vérifié en ligne.
+5. Chapitre(s) de playbook de la release relus par le référent.
+6. Journal + tag git `release/rX`.
+
+## R0 — Fondations *(aucun écran métier)*
+
+**But** : tout ce qui rend les releases suivantes rapides et propres.
+
+- Playbook 00-vision, 01-cadrage, 02-design (charte + tokens + **maquettes HD validées**), 03-architecture (ADRs, C4, modèle de données).
+- Monorepo pnpm/Turborepo, infra Docker locale (PostgreSQL + Redis + MinIO), CI (4 pipelines : node, contrat, python, e2e).
+- `apps/api` : auth JWT, matrice de permissions (7 rôles × objets × droits, en base), seed réaliste (parc d'ascenseurs de démonstration).
+- **Sélecteur de compte démo** (`DEMO_MODE=true`) : bascule de rôle en < 3 s, local et démo, jamais en prod réelle.
+- `apps/web` : coquille applicative (login, layout, navigation, design system appliqué, page vitrine du design system).
+- Déploiement Dokploy « hello SIOP » (l'app en ligne dès R0).
+
+**Hors R0** : tout écran métier.
+
+## R1 — Référentiel
+
+Sites/emplacements (hiérarchie + carte), ascenseurs + organes (hiérarchie, statuts, QR
+imprimable), catégories, personnes & équipes (invitation, activation, profils).
+**Recette type** : créer un site → un ascenseur → ses organes → imprimer l'étiquette QR →
+inviter un technicien.
+
+## R2 — Exploitation
+
+Ordres de travail (machine à états, priorités dont **« personne bloquée »**, assignation,
+commentaires, pièces jointes), **bilan codé** (6 champs + référentiels administrables +
+garde de clôture), portail de demandes (public via QR + interne) convergeant vers l'OT,
+préventif (gabarits à périodicité, génération mensuelle idempotente, checklist, premier
+contrôle), compteurs.
+**Recette type** : demande gardien → approbation → OT → intervention → bilan codé →
+clôture → suivi demandeur ; génération du préventif de juillet.
+
+## R3 — Gestion
+
+Stock (mouvements, seuils, alertes), consommation sur OT à prix figé, bons de commande,
+tiers, main-d'œuvre valorisée (taux figé) et coût total OT, analytics (KPI + graphiques),
+bibliothèque de fichiers (documents rattachables).
+**Recette type** : consommer sous seuil → BC → réception → réappro ; coût complet d'un OT ;
+tableau de bord direction.
+
+## R4 — Mobile technicien
+
+App Expo offline-first : OT assignés, fiche, scan QR → fiche ascenseur, checklist du mois
+cochable hors-ligne, clôture terrain, synchro à verrou optimiste (patron validé en v1).
+**Recette type** : mode avion en sous-sol → cocher la grille → retour réseau → synchro.
+
+## R5 — IA
+
+Assistant RAG (notices + historiques ingérés, réponses **citant leurs sources**), aide à
+la saisie du bilan (suggestion de codes à partir d'une description libre). Si budget temps :
+transcription vocale du bilan. Principe : l'IA propose, l'humain valide.
+**Recette type** : « quel couple de serrage pour les guides du Gen2 ? » → réponse sourcée.
+
+## Après v1 (backlog v2)
+
+PV PDF signé hors-ligne, check-in/out géolocalisés, agent vocal, affectation géospatiale
+automatique, multi-langue, exports comptables.

docs/01-cadrage/risques.md

@@ -0,0 +1,20 @@
+# Registre des risques — SIOP V2
+
+> **Rôle de ce document (playbook)** : nommer les risques AVANT qu'ils ne frappent, avec
+> une mitigation concrète et un signal d'alerte. Relu à chaque clôture de release ;
+> les risques réalisés sont documentés (post-mortem court) — c'est de la matière de cours.
+
+| # | Risque | Prob. | Impact | Mitigation | Signal d'alerte |
+| --- | --- | --- | --- | --- | --- |
+| 1 | **Dérive de périmètre** (la cause n°1 de l'abandon de la v1) | Haute | Haut | Releases fermées (DoD stricte) ; toute idée hors release va au backlog v2, jamais dans la release courante | Une story « en plus » apparaît dans un jalon en cours |
+| 2 | **Dette design** — l'esthétique se dégrade sous la pression du fonctionnel | Haute | Haut | Maquettes validées avant code ; revue pixel par release ; tokens obligatoires (pas de styles ad hoc) | Un écran livré « à peu près comme la maquette » |
+| 3 | **Playbook en retard** sur le produit (docs bâclées en fin de release) | Moyenne | Haut (objectif B) | Le chapitre s'écrit PENDANT la release ; sa relecture fait partie de la DoD | Chapitre vide à mi-release |
+| 4 | **Serveur partenaire indisponible** ou repris | Moyenne | Moyen | Tout est Docker/Dokploy → portable en heures ; sauvegardes exportées hors du serveur | Latence/pannes récurrentes |
+| 5 | **Rupture d'outillage** (versions Expo/React/Prisma, pnpm) | Moyenne | Moyen | Versions épinglées ; leçons v1 documentées (jest-expo↔jest, peers Expo/pnpm, worklets) ; monter de version = tâche dédiée, jamais en passant | CI rouge après un simple `install` |
+| 6 | **Équipe qui s'élargit** (étudiants) sans conventions intégrées | Moyenne | Moyen | CLAUDE.md + 04-developpement comme contrat d'équipe ; PR + CI obligatoires dès leur arrivée ; exercices d'onboarding (07-formation) | Styles/patterns divergents dans les PR |
+| 7 | **IA (R5) survendue** — attentes RAG > réalité | Moyenne | Moyen | Jeu d'évaluation constitué AVANT le développement ; « l'IA propose, l'humain valide » ; périmètre R5 réduit et honnête | Réponses non sourcées jugées « suffisantes » |
+| 8 | **Données de démo peu crédibles** → démos commerciales ternes | Basse | Moyen | Seed réaliste dès R0 (parc marocain nommé, historiques plausibles) maintenu à chaque release | Démo qui montre des « Test 123 » |
+
+## Post-mortems
+
+*(vide — se remplit quand un risque se réalise)*

docs/01-cadrage/user-story-map.md

@@ -0,0 +1,53 @@
+# User-story map — SIOP V2
+
+> **Rôle de ce document (playbook)** : la carte relie les activités des personas (colonnes)
+> aux releases (lignes). Chaque cellule = stories. Les critères d'acceptation détaillés
+> sont écrits au cadrage de chaque release (format *Étant donné / Quand / Alors*) dans les
+> issues GitHub du jalon correspondant.
+
+## Activités (le « squelette » horizontal)
+
+| | A. Gérer le parc | B. Exploiter (pannes) | C. Prévenir (réglementaire) | D. Gérer les ressources | E. Piloter | F. Terrain (mobile) | G. Être assisté (IA) |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| Personas | Salma, Nadia | Salma, Ahmed, Karim | Salma, Ahmed | Nadia | M. Bennis | Ahmed | Ahmed, Salma |
+
+## Carte (stories clés par release)
+
+### R0 — Fondations
+- En tant qu'**équipe**, je me connecte avec mon rôle et ne vois que ce que ma matrice autorise.
+- En tant que **développeur/démonstrateur**, je bascule de compte en 1 clic (`DEMO_MODE`).
+- En tant que **visiteur**, je vois une app en ligne au design abouti (coquille + design system).
+
+### R1 — Référentiel
+- **A** Salma crée un site (adresse, position carte) puis un ascenseur (marque, n° série, mise en service) et ses organes.
+- **A** Salma imprime l'étiquette **QR** à coller en cabine.
+- **A** L'admin invite un technicien (lien d'activation) et compose des équipes.
+
+### R2 — Exploitation
+- **B** Karim scanne le QR en cabine → formulaire de signalement prérempli avec photo ; il suit ensuite l'avancement sans jargon.
+- **B** Salma approuve la demande → un OT est créé (lien 1-1) et assigné en 1 clic.
+- **B** Un OT « **personne bloquée** » saute en tête partout, visuellement impossible à manquer.
+- **B** Ahmed clôt son OT par le **bilan codé** (6 champs) ; la clôture est bloquée si incomplet.
+- **C** Le 1er du mois, les OT préventifs se génèrent avec la **checklist des tâches dues** (parachute en juillet, premier contrôle = tout) ; regénérer ne double rien.
+- **C** La clôture d'un OT préventif exige la checklist complète (Fait / N-A).
+
+### R3 — Gestion
+- **D** Nadia consomme une pièce sur un OT (prix figé) ; sous le seuil, une alerte part et un BC se prépare ; la réception réapprovisionne.
+- **D** Nadia range notices et certificats dans la **bibliothèque**, rattachés à l'ascenseur.
+- **D** La main-d'œuvre saisie (taux figé par personne) donne le **coût total** de l'OT.
+- **E** M. Bennis lit en 30 s : OT par statut, pannes par organe, taux de préventif, coûts, top équipements.
+
+### R4 — Mobile
+- **F** Ahmed voit ses OT triés priorité/échéance, **même sans réseau**.
+- **F** Il scanne le QR → fiche de l'ascenseur et ses interventions.
+- **F** Il coche la grille du mois hors-ligne et clôt du terrain ; tout se synchronise au retour du réseau **sans perdre une saisie** (verrou optimiste).
+
+### R5 — IA
+- **G** Ahmed demande « procédure de réglage des portes Gen2 » → réponse **avec source** (notice ingérée).
+- **G** Ahmed décrit la panne en langage libre → l'assistant **suggère les codes** du bilan ; il valide ou corrige.
+
+## Priorisation
+
+Le chemin critique produit est **B + C** (c'est le carnet papier remplacé) — d'où R2 au
+centre du programme. A (R1) est le prérequis de tout ; D/E (R3) rendent l'outil gestionnaire ;
+F (R4) supprime la ressaisie ; G (R5) différencie.