Merge remote-tracking branch 'origin/dev' into feat/endpoint-recommandations

docs/architecture/10-infra.md

@@ -35,9 +35,10 @@ flowchart TB
 | `backend` | Construite depuis `apps/backend` | `depends_on: db, condition: service_healthy`. **N'embarque pas le source** : toute modification impose `docker compose up -d --build backend` |
 
 **La boucle de développement n'utilise pas le service `backend`.** `make db-up` puis `make dev` :
-seule la base tourne en conteneur, l'API tourne sur le poste avec le rechargement à chaud. Le
-service `backend` sert la stack complète et la recette. Les deux occupent le port 8000, ils ne se
-lancent donc pas ensemble.
+seule la base tourne en conteneur, l'API et `ng serve` tournent sur le poste avec le rechargement
+à chaud, lancés ensemble par `make dev` (`make dev-backend`/`make dev-frontend` pour lancer l'un
+des deux seul). Le service `backend` sert la stack complète et la recette. Les deux occupent le
+port 8000, ils ne se lancent donc pas ensemble.
 
 Deux pièges sont documentés en tête du `docker-compose.yml`, ils ne se devinent pas :
 

docs/architecture/20-backend.md

@@ -12,10 +12,10 @@ Les quatre couches existent désormais, portées par l'authentification.
 
 ```mermaid
 flowchart TB
-  ep["endpoints<br/>health, auth, users, sites"]
+  ep["endpoints<br/>health, auth, users, sites,<br/>recommendations, stats"]
   sc["schemas<br/>Pydantic"]
-  sv["services<br/>AuthService, UserService,<br/>SiteService"]
-  rp["repositories<br/>user, refresh_token,<br/>login_attempt, audit_log,<br/>site"]
+  sv["services<br/>AuthService, UserService,<br/>SiteService, RecommendationService,<br/>StatsService"]
+  rp["repositories<br/>user, refresh_token,<br/>login_attempt, audit_log,<br/>site, recommendation, reading"]
   md["models<br/>10 tables"]
   db[("PostgreSQL")]
 
@@ -144,6 +144,7 @@ Deux fichiers d'environnement, deux usages : `.env` à la racine alimente `docke
 | GET | `/api/v1/sites/{site_id}` | Décrit un site. `lecteur` | 401, 403, 404, 422, 500 |
 | GET | `/api/v1/recommendations` | Liste les recommandations. `lecteur` | 401, 403, 500 |
 | GET | `/api/v1/recommendations/{recommendation_id}` | Décrit une recommandation. `lecteur` | 401, 403, 404, 422, 500 |
+| GET | `/api/v1/stats/summary` | Résume la consommation instantanée du parc. `lecteur` | 401, 403, 500 |
 | GET | `/metrics` | Format Prometheus, hors du schéma. Jeton requis si `APP_METRICS_TOKEN` est posé | |
 | GET | `/docs`, `/redoc`, `/openapi.json` | Hors du schéma. Fermés en `staging` et en `prod` | |
 
@@ -165,7 +166,9 @@ contrairement aux routes d'administration qui exigent `admin`. `SiteRepository`
 réelle. `GET /recommendations` et `GET /recommendations/{recommendation_id}` reprennent le même
 gabarit à la lettre, `recommendation_id` étant un entier plutôt qu'un texte. Une recommandation ne
 porte pas `site_id` : elle remonte à un site par sa seule `alert_id`, `alert` n'étant pas encore
-exposée. Le contrat détaillé pour le frontend est dans
+exposée. `GET /stats/summary` agrège deux repositories (`SiteRepository`, `ReadingRepository`)
+dans un service dédié plutôt que d'exposer une table : elle n'entre donc pas dans ce gabarit
+route-par-table. Le contrat détaillé pour le frontend est dans
 [31-contrat-authentification.md](31-contrat-authentification.md).
 
 ### `/health/ready`
@@ -240,6 +243,21 @@ Les modèles de `app/schemas/errors.py` décrivent ce que les gestionnaires renv
 `loc` n'apparaît dans aucune réponse de cette API : `validation_error_handler()` rend `champ` et
 `type`. Renommer un champ là-bas sans le faire ici rend la documentation fausse en silence.
 
+### Ajouter une route métier
+
+Checklist pour toute nouvelle route sur le gabarit `sites`/`recommendations`/`stats`
+(`reading`, `dataset`, `prediction`, `alert`) :
+
+1. Composer ses `responses=` depuis `app/api/openapi.py` : `REPONSES_LECTEUR`/`REPONSES_ADMIN`
+   au niveau de l'`include_router()` du routeur, `REPONSE_VALIDATION` et les codes locaux
+   (404, 409, ...) directement sur l'endpoint qui les rend.
+2. Décrire son tag dans `TAGS`.
+3. Si elle passe par `require_role` (`LecteurDep`/`OperateurDep`/`AdminDep`), l'ajouter à
+   `ROUTES_A_ROLE` dans `tests/api/test_openapi.py`. Si elle passe par `require_trusted_origin`,
+   l'ajouter à `ORIGINE_VERIFIEE`. **Ces deux listes sont maintenues à la main, pas dérivées** :
+   une route oubliée n'y est pas détectée automatiquement.
+4. `make openapi`, puis `uv run pytest tests/api/test_openapi.py`.
+
 ## Sécurité
 
 Voir la vue consolidée dans [00-vue-ensemble.md](00-vue-ensemble.md) et les décisions dans les

docs/architecture/30-frontend.md

@@ -108,8 +108,9 @@ déploiement, en même temps que sera tranchée la question de l'ingress dans
 le message d'erreur arrive avant toute compilation. Un poste en 22.21 ou en 24.12 ne peut donc ni
 tester ni construire le frontend.
 
-Le frontend **n'a pas de cible dans le `Makefile` racine** et **aucun service dans
-`docker-compose.yml`** : il se pilote uniquement par `npm`, depuis `apps/frontend`. Le port 4200
+Le frontend a ses cibles dans le `Makefile` racine (`install-frontend`, `dev-frontend`,
+englobées par `install` et `dev`), mais **aucun service dans `docker-compose.yml`** : en
+développement il tourne toujours directement via `npm`, depuis `apps/frontend`. Le port 4200
 n'apparaît dans le compose que comme valeur par défaut d'`APP_CORS_ORIGINS`, côté backend.
 
 Un `Dockerfile` frontend existe sur la branche `feat/pipeline-cd`, mais il est mono-étage et sans