docs: add V1 setup README

2026-07-09 10:52:12 +02:00
parent 24e2793cf8
commit 1d271e225c
1 changed files with 232 additions and 0 deletions
@@ -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.