merge: readme v1 docs

README.md

@@ -0,0 +1,232 @@
+# EME — Emprunt Matériel ENSUP
+
+EME est une application web de gestion des emprunts de matériel pédagogique pour ENSUP / Ensitech.
+
+La V1 couvre le parcours étudiant : consulter le catalogue, emprunter un matériel, restituer un emprunt et détecter automatiquement les retours non conformes.
+
+## Stack
+
+| Couche | Technologie |
+|---|---|
+| Frontend | Flutter Web |
+| Backend | Express.js + TypeScript |
+| Base de données | SQL Server 2022 |
+| ORM | Prisma |
+| Conteneurs | Docker Compose |
+| Interface BDD | Adminer |
+
+## Structure
+
+```text
+eme_app/
+├── compose.yaml
+├── CONTEXT.md
+├── TODO.md
+├── review.md
+├── docs/
+├── eme-backend/
+└── eme-frontend/
+```
+
+Documents utiles :
+
+- `CONTEXT.md` : contexte projet, stack, acteurs, modèle et charte.
+- `TODO.md` : plan d'action et reste à faire.
+- `review.md` : journal des décisions et état courant.
+- `docs/regles-metier/regles-gestion.md` : règles métier validées.
+
+## Prérequis
+
+- Docker Desktop
+- Node.js + npm
+- Flutter SDK avec support Web
+- Git
+
+Vérifications rapides :
+
+```bash
+docker --version
+node --version
+npm --version
+flutter --version
+```
+
+## Configuration
+
+### Docker
+
+Le fichier racine `.env` doit fournir le mot de passe SQL Server utilisé par `compose.yaml` :
+
+```env
+MSSQL_SA_PASSWORD=EmePass2026!
+```
+
+### Backend
+
+Créer `eme-backend/.env` à partir de `eme-backend/.env.example`, puis vérifier que le mot de passe correspond à celui du `.env` racine.
+
+Exemple de configuration locale :
+
+```env
+PORT=3000
+NODE_ENV=development
+FRONTEND_URL=http://localhost:5000
+
+DATABASE_URL="sqlserver://localhost:1433;database=eme_db;user=sa;password=EmePass2026!;encrypt=true;trustServerCertificate=true"
+DB_SERVER=localhost
+DB_PORT=1433
+DB_NAME=eme_db
+DB_USER=sa
+DB_PASSWORD=EmePass2026!
+
+AZURE_TENANT_ID=ton_tenant_id
+AZURE_CLIENT_ID=ton_client_id
+```
+
+Azure AD n'est pas encore branché en V1 locale : l'authentification est simulée via `x-user-email`.
+
+## Installation
+
+Depuis la racine :
+
+```bash
+cd eme-backend
+npm install
+cd ../eme-frontend
+flutter pub get
+```
+
+## Lancement local
+
+### 1. Démarrer SQL Server et Adminer
+
+Depuis la racine :
+
+```bash
+docker compose up -d
+```
+
+Services :
+
+- SQL Server : `localhost:1433`
+- Adminer : `http://localhost:8081`
+
+### 2. Préparer la base
+
+Depuis `eme-backend` :
+
+```bash
+npm run prisma:generate
+npx prisma migrate deploy
+npm run seed
+npm run fixtures
+```
+
+Les fixtures ajoutent des utilisateurs, du matériel, des emprunts et des anomalies de démonstration.
+
+### 3. Démarrer le backend
+
+Depuis `eme-backend` :
+
+```bash
+npm run dev
+```
+
+API :
+
+```text
+http://localhost:3000
+```
+
+Contrôle rapide :
+
+```bash
+curl http://localhost:3000/health
+```
+
+### 4. Démarrer le frontend
+
+Depuis `eme-frontend` :
+
+```bash
+flutter run -d web-server --web-port 5000
+```
+
+Application :
+
+```text
+http://localhost:5000
+```
+
+## Parcours de démo V1
+
+1. Ouvrir `http://localhost:5000`.
+2. S'identifier avec l'option mail ENSUP ou carte étudiante.
+3. Cliquer sur `Emprunter`.
+4. Sélectionner un matériel disponible.
+5. Valider la checklist de départ.
+6. Vérifier la confirmation de l'emprunt.
+7. Revenir à l'accueil.
+8. Cliquer sur `Restituer`.
+9. Sélectionner un emprunt en cours.
+10. Valider un retour conforme ou indiquer un élément absent/détérioré.
+11. Vérifier le résultat conforme ou non conforme.
+
+## Endpoints principaux
+
+| Méthode | Route | Description |
+|---|---|---|
+| `GET` | `/health` | Santé API |
+| `GET` | `/api/auth/me` | Profil utilisateur courant |
+| `GET` | `/api/auth/carte/:qr` | Identification par QR code |
+| `GET` | `/api/materiels` | Catalogue disponible |
+| `GET` | `/api/materiels/:id` | Détail matériel |
+| `POST` | `/api/emprunts` | Création d'un emprunt |
+| `GET` | `/api/mes-emprunts` | Emprunts en cours de l'utilisateur |
+| `POST` | `/api/emprunts/:id/restitution` | Restitution |
+
+En local, les routes protégées utilisent l'en-tête :
+
+```http
+x-user-email: lucas.martin@ensitech.eu
+```
+
+## Vérifications
+
+Backend :
+
+```bash
+cd eme-backend
+npm run build
+npm run lint
+```
+
+Frontend :
+
+```bash
+cd eme-frontend
+flutter analyze
+```
+
+Note : dans l'environnement Codex, `flutter analyze` et `dart format` ont déjà bloqué au timeout. Les relancer dans un terminal local Flutter si nécessaire.
+
+## État V1
+
+Terminé pour la V1 étudiant :
+
+- catalogue matériel ;
+- détail matériel ;
+- emprunt avec checklist de départ ;
+- restitution avec checklist de retour ;
+- détection automatique de retour non conforme ;
+- fixtures de démonstration ;
+- tests runtime manuels du parcours étudiant.
+
+Reste à faire :
+
+- authentification Azure AD réelle ;
+- parcours responsable matériel ;
+- OpenAPI / Swagger ;
+- tests automatisés ;
+- documentation utilisateur complète ;
+- déploiement production.

review.md

@@ -20,10 +20,61 @@ Ces décisions s'appliquent à tout le projet, sauf mention contraire.
 | Champs nullable selon les cardinalités `0..1` du diagramme de classes | Un champ non connu à la création (ex. date de retour) ou optionnel doit être `NULL`, sinon le workflow métier est bloqué. |
 | `onDelete: NoAction, onUpdate: NoAction` sur les données de traçabilité (Emprunt, Checklist, ChecklistElement, Anomalie, Historique) | Ces données ne doivent jamais être supprimées/altérées automatiquement en cascade. Toute suppression sera explicite côté service. Évite aussi l'erreur SQL Server "multiple cascade paths". |
 | ERD tenu à jour en miroir du schéma (`docs/conceptions/uml/ERD.md`) | La source de vérité doit refléter le code réel (nullable, `UK`, etc.). |
-| Workflow Git : commits sur `develop` uniquement | `master` est figé ; `develop` reste toujours à jour de `master` (aucune divergence puisque master ne bouge plus). |
+| Workflow Git : `develop` comme branche d'intégration + branches dédiées `feat/...`, `fix/...`, `docs/...` | `master` reste figé ; chaque changement logique est isolé sur une branche puis mergé dans `develop`, conformément à `CLAUDE.md`. |
 | Process avant chaque migration : `prisma format` -> `prisma validate` -> `npm run build` -> migration | Détecter toute erreur de schéma/typage avant de toucher la base. |
 | DTO nommés `XxxResponse` (sortie) et `XxxRequest` (entrée) | Le sens est explicite dans le nom. Sortie = mapping (`toXxxResponse`), entrée = validation. |
 
+---
+
+## État actuel synthétique
+
+Cette section résume l'état courant du projet. Le journal chronologique plus bas conserve
+l'historique complet, y compris des étapes devenues obsolètes après branchement API.
+
+| Bloc | État | Commentaire |
+|---|---|---|
+| Infrastructure | Terminé | Docker Compose SQL Server + Adminer, monorepo, backend Node/TS, frontend Flutter Web. |
+| Base de données | Terminé pour la V1 | Schéma Prisma 16 entités, migrations, seeds et fixtures de démonstration. |
+| API étudiant | Terminé pour la V1 | Catalogue, détail matériel, création d'emprunt, mes emprunts, restitution, anomalie automatique. |
+| Frontend étudiant | Terminé pour la V1 | Parcours emprunt et restitution branchés sur l'API et testés en réel. |
+| Authentification | Simulée | `x-user-email` côté backend et identité démo côté frontend ; Azure AD reste à faire. |
+| Responsable matériel | Non démarré | Dashboard, stock, anomalies, historique à développer. |
+| Tests automatisés | Non démarré | Tests backend/frontend/E2E à ajouter ; tests runtime manuels effectués. |
+| Documentation | Partielle | `CONTEXT.md`, `TODO.md`, `review.md` existent ; README principal et OpenAPI restent à créer. |
+
+## Commandes validées
+
+Commandes utilisées et validées dans l'environnement de développement local :
+
+```bash
+docker compose up -d
+cd eme-backend
+npm run dev
+npm run build
+npm run lint
+npm run seed
+npm run fixtures
+cd ../eme-frontend
+flutter run -d web-server --web-port 5000
+```
+
+Notes :
+- le backend écoute sur `http://localhost:3000` ;
+- le frontend web de démo écoute sur `http://localhost:5000` ;
+- Adminer est disponible sur `http://localhost:8081` ;
+- dans l'environnement Codex, `flutter analyze`, `flutter analyze --no-pub` et `dart format` ont déjà bloqué au timeout ; à relancer dans un terminal local Flutter.
+
+## Scénario de démo validé
+
+Scénario étudiant validé avec SQL Server Docker et backend compilé :
+
+1. Afficher le catalogue des matériels disponibles du campus.
+2. Ouvrir le détail d'un matériel et vérifier les accessoires.
+3. Créer un emprunt avec checklist de départ.
+4. Vérifier que l'emprunt apparaît dans `mes-emprunts`.
+5. Restituer conforme : l'emprunt passe `CLOTURE` et le matériel redevient disponible.
+6. Restituer non conforme : l'emprunt passe `RETOUR_NON_CONFORME` et le matériel sort du catalogue disponible.
+
 ### Note outillage — migrations en environnement non-interactif
 
 `prisma migrate dev` se bloque quand il doit demander une confirmation (ex. ajout de contrainte `@unique` sur table existante) car le terminal est non-interactif.
@@ -192,18 +243,24 @@ En terminal interactif (VS Code), `migrate dev` fonctionne normalement (taper `y
 - Modèle `MaterielItem` enrichi (marque, modèle, état, accessoires) ; données statiques mises à jour.
 - Navigation : Catalogue (Sélectionner) -> Détail ; « Démarrer l'emprunt » -> placeholder (checklist à venir).
 
+> Note historique : les étapes 21 à 25 décrivent l'état initial statique du frontend.
+> Elles ont été remplacées fonctionnellement par les branchements API des étapes 26 à 32.
+
 ---
 
 ## Dette technique en attente
 
 À traiter ensemble plus tard (avec mise à jour ERD en miroir) :
 
-1. `CarteEtudiante.qr_code` -> `@unique` (identification, RG02)
+| Dette | Statut | Impact V1 |
-2. `MaterielAccessoire` -> `@@unique([materielId, accessoireId])` (un accessoire une seule fois par matériel)
+|---|---|---|
-3. `Materiel.statut` -> `@default("DISPONIBLE")` (un matériel neuf est disponible, RG07)
+| `CarteEtudiante.qr_code` -> `@unique` | À faire avec migration + ERD | Moyen : sécurise l'identification QR. |
-4. Tailles de colonnes `@db.NVarChar(n)` (actuellement `NVARCHAR(1000)` partout)
+| `MaterielAccessoire` -> `@@unique([materielId, accessoireId])` | À faire avec migration + ERD | Moyen : évite les doublons d'accessoires. |
-5. Swagger/OpenAPI (Block 1, reporté après les endpoints)
+| `Materiel.statut` -> `@default("DISPONIBLE")` | À faire avec migration + ERD | Faible : le code fournit déjà le statut explicitement. |
-6. Auth réelle Azure AD (Block 3) — remplacera l'auth simulée par en-tête
+| Tailles de colonnes `@db.NVarChar(n)` | À cadrer | Faible V1, important pour qualité BDD. |
+| Swagger/OpenAPI | À faire | Moyen : utile pour tester/documenter l'API. |
+| Auth réelle Azure AD | À faire | Fort : requis pour sortir de la démo avec auth simulée. |
+| Limite d'emprunts actifs par étudiant | À valider métier | Non bloquant V1 ; décision métier non présente dans les règles actuelles. |
 
 ---
 
@@ -259,6 +316,14 @@ En terminal interactif (VS Code), `migrate dev` fonctionne normalement (taper `y
 - Commentaire obsolète du modèle `MaterielItem` corrigé : les données viennent maintenant de l'API.
 - `TODO.md` mis à jour : les parcours emprunt et restitution étudiant sont maintenant branchés API.
 
+### Étape 33 — Clarification du journal de décisions
+- Branche dédiée `docs/review-current-state` créée depuis `develop`.
+- Ajout d'une synthèse d'état courant pour éviter de devoir relire tout l'historique.
+- Correction de la convention Git : `develop` est la branche d'intégration, les travaux passent par branches dédiées.
+- Ajout des commandes validées et du scénario de démo étudiant testé.
+- Dette technique reformatée en tableau avec statut et impact V1.
+- Clarification des étapes frontend statiques historiques : elles sont conservées pour mémoire mais remplacées par les branchements API ultérieurs.
+
 ---
 
-*Dernière mise à jour : 2026-07-08 — Parcours étudiant complet testé et libellés V1 harmonisés.*
+*Dernière mise à jour : 2026-07-09 — État courant du projet et journal de décisions clarifiés.*