test(backend): généralise la vérification du 403 de rôle à toute route, pas seulement admin

test_every_administration_route_documents_the_role_refusal ne couvrait que le tag users : sites vient de passer inaperçu deux fois (tag et 403 absents) pendant le merge avec dev. Remplacé par ROUTES_A_ROLE, une liste maintenue à la main sur le modèle de ORIGINE_VERIFIEE, qui couvre toute route derrière require_role. Ajoute la checklist d'ajout d'une route métier à 20-backend.md.
2026-09-16 12:09:53 +02:00
18 changed files with 32 additions and 632 deletions
@@ -1,36 +1,18 @@
 BACKEND := apps/backend
 FRONTEND := apps/frontend
 .DEFAULT_GOAL := help
-.PHONY: help install install-backend install-frontend dev dev-backend dev-frontend \
+.PHONY: help install dev lint format typecheck test test-cov test-integration check \
        lint format typecheck test test-cov test-integration check \
        openapi docker-build db-up db-down db-reset db-logs db-psql migrate bootstrap-admin
 help: ## Liste les cibles disponibles
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-16s\033[0m %s\n", $$1, $$2}'
-install: install-backend install-frontend ## Installe les dépendances backend et frontend
+install: ## Installe les dépendances du backend
 install-backend: ## Installe les dépendances du backend
 	cd $(BACKEND) && uv sync --all-groups
-install-frontend: ## Installe les dépendances du frontend
+dev: ## Lance l'API en rechargement à chaud
 	cd $(FRONTEND) && npm ci
 dev: ## Lance toute la stack (backend + frontend) en rechargement à chaud
 	@trap 'kill 0' EXIT INT TERM; \
 	$(MAKE) --no-print-directory dev-backend & \
 	$(MAKE) --no-print-directory dev-frontend & \
 	wait
 dev-backend: ## Lance l'API seule en rechargement à chaud
 	@echo "backend  -> http://localhost:8000 (docs sur /docs)"
 	cd $(BACKEND) && uv run uvicorn app.main:create_app --factory --reload --host 0.0.0.0 --port 8000
 dev-frontend: ## Lance le frontend seul en rechargement à chaud
 	@echo "frontend -> http://localhost:4200"
 	cd $(FRONTEND) && npm start
 lint: ## Analyse statique du backend
 	cd $(BACKEND) && uv run ruff check .
@@ -63,17 +63,16 @@ L'etat detaille de chaque brique et les vues d'architecture sont dans
 ## Demarrage
-Prerequis : uv, Docker, Node 24 LTS (npm fourni). Le poste doit disposer de Python 3.14, que
+Prerequis : uv, Docker. Le poste doit disposer de Python 3.14, que `uv` installe seul.
 `uv` installe seul.
 ```bash
 cp .env.example .env                               # variables de docker-compose
 cp apps/backend/.env.example apps/backend/.env     # variables du backend hors conteneur
 make db-up     # PostgreSQL + TimescaleDB, publie sur le port 5433
-make install   # dependances du backend et du frontend
+make install   # dependances du backend
 make migrate   # applique les migrations Alembic
-make dev       # backend sur http://localhost:8000 (docs sur /docs), frontend sur http://localhost:4200
+make dev       # API sur http://localhost:8000, docs sur /docs
 make check     # lint + typage + tests
 ```
@@ -84,11 +83,9 @@ Deux fichiers d'environnement, deux usages : `.env` a la racine alimente `docker
 5432, souvent deja pris par une autre base.
 La boucle de developpement est `make db-up` puis `make dev` : seule la base tourne en
-conteneur, le backend et le frontend tournent tous les deux sur le poste, lances ensemble par
+conteneur. Le service `backend` du `docker-compose.yml` sert la stack complete et la recette,
-`make dev` (logs entrelaces dans le meme terminal, Ctrl+C arrete les deux). `make dev-backend`
+et n'embarque pas le source, donc toute modification y demande un
-et `make dev-frontend` restent disponibles pour lancer un seul des deux. Le service `backend`
+`docker compose up -d --build backend`.
 du `docker-compose.yml` sert la stack complete et la recette, et n'embarque pas le source, donc
 toute modification y demande un `docker compose up -d --build backend`.
 Verifier que la base repond et que l'extension est chargee :
@@ -23,13 +23,11 @@ from app.core.security import decode_access_token as decode_token
 from app.db.session import get_session
 from app.repositories.audit_log import AuditLogRepository
 from app.repositories.login_attempt import LoginAttemptRepository
 from app.repositories.reading import ReadingRepository
 from app.repositories.refresh_token import RefreshTokenRepository
 from app.repositories.site import SiteRepository
 from app.repositories.user import UserRepository
 from app.services.auth import AuthService, LoginPolicy
 from app.services.site import SiteService
 from app.services.stats import StatsService
 from app.services.user import UserService
 SessionDep = Annotated[AsyncSession, Depends(get_session)]
@@ -142,13 +140,6 @@ def get_site_service(session: SessionDep) -> SiteService:
 SiteServiceDep = Annotated[SiteService, Depends(get_site_service)]
 def get_stats_service(session: SessionDep) -> StatsService:
    return StatsService(sites=SiteRepository(session), readings=ReadingRepository(session))
 StatsServiceDep = Annotated[StatsService, Depends(get_stats_service)]
 async def get_current_principal(
    credentials: CredentialsDep,
    session: SessionDep,
@@ -54,11 +54,6 @@ TAGS: Final[list[dict[str, Any]]] = [
        "name": "sites",
        "description": "Consultation du parc de sites. Accessible à partir du rôle `lecteur`.",
    },
    {
        "name": "stats",
        "description": "Statistiques agrégées de consommation. Accessible à partir du rôle "
        "`lecteur`.",
    },
 ]
 cookie_de_rafraichissement = APIKeyCookie(
@@ -1,16 +0,0 @@
 from fastapi import APIRouter
 from app.api.deps import LecteurDep, StatsServiceDep
 from app.schemas.stats import StatsSummaryResponse
 router = APIRouter()
@router.get(
    "/summary",
    response_model=StatsSummaryResponse,
    summary="Résume la consommation instantanée du parc",
 )
 async def get_summary(_: LecteurDep, service: StatsServiceDep) -> StatsSummaryResponse:
    resume = await service.summary()
    return StatsSummaryResponse.model_validate(resume)
@@ -1,11 +1,10 @@
 from fastapi import APIRouter
 from app.api.openapi import REPONSE_SERVEUR, REPONSES_ADMIN, REPONSES_LECTEUR
-from app.api.v1.endpoints import auth, health, sites, stats, users
+from app.api.v1.endpoints import auth, health, sites, users
 api_router = APIRouter(responses=REPONSE_SERVEUR)
 api_router.include_router(health.router, prefix="/health", tags=["health"])
 api_router.include_router(auth.router, prefix="/auth", tags=["auth"])
 api_router.include_router(users.router, prefix="/users", tags=["users"], responses=REPONSES_ADMIN)
 api_router.include_router(sites.router, prefix="/sites", tags=["sites"], responses=REPONSES_LECTEUR)
 api_router.include_router(stats.router, prefix="/stats", tags=["stats"], responses=REPONSES_LECTEUR)
@@ -1,21 +0,0 @@
 from collections.abc import Sequence
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 from app.models.energy import Reading
 class ReadingRepository:
    def __init__(self, session: AsyncSession) -> None:
        self._session = session
    async def latest_by_site(self) -> Sequence[Reading]:
        # `.distinct(site_id)` compile en `DISTINCT ON (site_id)` sous PostgreSQL : une seule
        # ligne par site, la plus récente grâce à l'ordre composite qui suit.
        requete = (
            select(Reading)
            .distinct(Reading.site_id)
            .order_by(Reading.site_id, Reading.timestamp.desc())
        )
        return (await self._session.execute(requete)).scalars().all()
@@ -1,26 +0,0 @@
 from datetime import datetime
 from typing import Literal
 from pydantic import BaseModel, ConfigDict
 class SiteSummaryResponse(BaseModel):
    model_config = ConfigDict(from_attributes=True)
    site_id: str
    site_name: str
    current_consumption_kw: float | None
    capacity_kw: float
    load_percent: float | None
    data_quality: Literal["good", "partial", "degraded", "critical"]
 class StatsSummaryResponse(BaseModel):
    model_config = ConfigDict(from_attributes=True)
    timestamp: datetime
    total_sites: int
    total_consumption_kw: float
    total_capacity_kw: float
    average_load_percent: float
    sites: list[SiteSummaryResponse]
@@ -1,81 +0,0 @@
 from dataclasses import dataclass
 from datetime import UTC, datetime
 from typing import Literal
 from app.models.energy import Reading, Site
 from app.repositories.reading import ReadingRepository
 from app.repositories.site import SiteRepository
 DataQuality = Literal["good", "partial", "degraded", "critical"]
 QUALITES_CONNUES: frozenset[str] = frozenset({"good", "partial", "degraded", "critical"})
@dataclass(frozen=True, slots=True)
 class SiteConsumption:
    site_id: str
    site_name: str
    current_consumption_kw: float | None
    capacity_kw: float
    load_percent: float | None
    data_quality: DataQuality
@dataclass(frozen=True, slots=True)
 class ConsumptionSummary:
    timestamp: datetime
    total_sites: int
    total_consumption_kw: float
    total_capacity_kw: float
    average_load_percent: float
    sites: list[SiteConsumption]
 class StatsService:
    def __init__(self, sites: SiteRepository, readings: ReadingRepository) -> None:
        self._sites = sites
        self._readings = readings
    async def summary(self) -> ConsumptionSummary:
        sites = await self._sites.list_all()
        dernieres = {lecture.site_id: lecture for lecture in await self._readings.latest_by_site()}
        resumes = [self._resume_site(site, dernieres.get(site.site_id)) for site in sites]
        consommation_totale = sum(r.current_consumption_kw or 0 for r in resumes)
        capacite_totale = sum(r.capacity_kw for r in resumes)
        return ConsumptionSummary(
            timestamp=datetime.now(UTC),
            total_sites=len(resumes),
            total_consumption_kw=consommation_totale,
            total_capacity_kw=capacite_totale,
            average_load_percent=(
                consommation_totale / capacite_totale * 100 if capacite_totale > 0 else 0
            ),
            sites=resumes,
        )
    @staticmethod
    def _resume_site(site: Site, derniere: Reading | None) -> SiteConsumption:
        capacite = site.capacity_kw or 0
        # Piège : `data_quality` est nul dès qu'un site n'a jamais reçu de lecture, ou que le
        # producteur n'a pas su la qualifier. Le contrat frontend n'a pas de valeur pour ce cas,
        # `critical` est la seule des quatre qui n'induit pas une confiance qu'on n'a pas.
        qualite: DataQuality = "critical"
        consommation = None
        if derniere is not None and derniere.data_quality in QUALITES_CONNUES:
            qualite = derniere.data_quality  # type: ignore[assignment]
            consommation = derniere.consumption_kw
        charge = (
            consommation / capacite * 100 if consommation is not None and capacite > 0 else None
        )
        return SiteConsumption(
            site_id=site.site_id,
            site_name=site.site_name,
            current_consumption_kw=consommation,
            capacity_kw=capacite,
            load_percent=charge,
            data_quality=qualite,
        )
@@ -920,62 +920,6 @@
          }
        }
      }
    },
    "/api/v1/stats/summary": {
      "get": {
        "tags": [
          "stats"
        ],
        "summary": "Résume la consommation instantanée du parc",
        "operationId": "get_summary_api_v1_stats_summary_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatsSummaryResponse"
                }
              }
            }
          },
          "500": {
            "description": "Erreur interne. `correlation` identifie la trace côté serveur, qui n'est pas renvoyée au client.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Jeton absent, illisible, périmé, ou rendu caduc par un changement de rôle ou une désactivation. L'en-tête `WWW-Authenticate` porte la cause dans `error=`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Mot de passe provisoire à changer (`detail` vaut `password_change_required`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "Jeton d'accès": []
          }
        ]
      }
    }
  },
  "components": {
@@ -1235,106 +1179,6 @@
        ],
        "title": "SiteResponse"
      },
      "SiteSummaryResponse": {
        "properties": {
          "site_id": {
            "type": "string",
            "title": "Site Id"
          },
          "site_name": {
            "type": "string",
            "title": "Site Name"
          },
          "current_consumption_kw": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Current Consumption Kw"
          },
          "capacity_kw": {
            "type": "number",
            "title": "Capacity Kw"
          },
          "load_percent": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Load Percent"
          },
          "data_quality": {
            "type": "string",
            "enum": [
              "good",
              "partial",
              "degraded",
              "critical"
            ],
            "title": "Data Quality"
          }
        },
        "type": "object",
        "required": [
          "site_id",
          "site_name",
          "current_consumption_kw",
          "capacity_kw",
          "load_percent",
          "data_quality"
        ],
        "title": "SiteSummaryResponse"
      },
      "StatsSummaryResponse": {
        "properties": {
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "title": "Timestamp"
          },
          "total_sites": {
            "type": "integer",
            "title": "Total Sites"
          },
          "total_consumption_kw": {
            "type": "number",
            "title": "Total Consumption Kw"
          },
          "total_capacity_kw": {
            "type": "number",
            "title": "Total Capacity Kw"
          },
          "average_load_percent": {
            "type": "number",
            "title": "Average Load Percent"
          },
          "sites": {
            "items": {
              "$ref": "#/components/schemas/SiteSummaryResponse"
            },
            "type": "array",
            "title": "Sites"
          }
        },
        "type": "object",
        "required": [
          "timestamp",
          "total_sites",
          "total_consumption_kw",
          "total_capacity_kw",
          "average_load_percent",
          "sites"
        ],
        "title": "StatsSummaryResponse"
      },
      "TemporaryPasswordResponse": {
        "properties": {
          "user": {
@@ -1551,10 +1395,6 @@
    {
      "name": "sites",
      "description": "Consultation du parc de sites. Accessible à partir du rôle `lecteur`."
    },
    {
      "name": "stats",
      "description": "Statistiques agrégées de consommation. Accessible à partir du rôle `lecteur`."
    }
  ]
 }
@@ -31,7 +31,6 @@ ROUTES_A_ROLE = {
    ("POST", "/api/v1/users/{id}/password-reset"),
    ("GET", "/api/v1/sites"),
    ("GET", "/api/v1/sites/{site_id}"),
    ("GET", "/api/v1/stats/summary"),
 }
@@ -1,73 +0,0 @@
 from collections.abc import Callable, Iterator
 from datetime import UTC, datetime
 from uuid import uuid4
 import pytest
 from fastapi import FastAPI
 from httpx import AsyncClient
 from app.api.deps import get_current_principal, get_stats_service
 from app.core.principal import Principal
 from app.core.roles import AccountKind, Role
 from app.services.stats import ConsumptionSummary, SiteConsumption
 def principal(role: Role = Role.LECTEUR) -> Principal:
    return Principal(
        id=uuid4(),
        email=f"{role.value}@enervision.fr",
        role=role,
        kind=AccountKind.HUMAIN,
        must_change_password=False,
    )
 class FauxService:
    def __init__(self) -> None:
        self.resume = ConsumptionSummary(
            timestamp=datetime.now(UTC),
            total_sites=1,
            total_consumption_kw=87.34,
            total_capacity_kw=200,
            average_load_percent=43.7,
            sites=[
                SiteConsumption(
                    site_id="SITE001",
                    site_name="Bureau Paris La Défense",
                    current_consumption_kw=87.34,
                    capacity_kw=200,
                    load_percent=43.7,
                    data_quality="good",
                )
            ],
        )
    async def summary(self) -> ConsumptionSummary:
        return self.resume
@pytest.fixture
 def servi(app: FastAPI) -> Iterator[Callable[[], FauxService]]:
    def installe() -> FauxService:
        service = FauxService()
        app.dependency_overrides[get_stats_service] = lambda: service
        app.dependency_overrides[get_current_principal] = lambda: principal()
        return service
    yield installe
    app.dependency_overrides.pop(get_stats_service, None)
    app.dependency_overrides.pop(get_current_principal, None)
 async def test_get_summary_returns_the_service_result(
    servi: Callable[[], FauxService], client: AsyncClient
 ) -> None:
    servi()
    response = await client.get("/api/v1/stats/summary")
    assert response.status_code == 200
    corps = response.json()
    assert corps["total_sites"] == 1
    assert corps["sites"][0]["site_id"] == "SITE001"
    assert corps["sites"][0]["data_quality"] == "good"
@@ -1,72 +0,0 @@
 import uuid
 from datetime import UTC, datetime, timedelta
 import pytest
 from sqlalchemy.ext.asyncio import AsyncSession
 from app.models.energy import Reading, Site
 from app.repositories.reading import ReadingRepository
 pytestmark = pytest.mark.integration
 def identifiant() -> str:
    return f"SITE-{uuid.uuid4().hex[:8]}"
 def lecture(site_id: str, *, timestamp: datetime, consumption_kw: float) -> Reading:
    return Reading(
        site_id=site_id,
        timestamp=timestamp,
        source="api_current",
        consumption_kw=consumption_kw,
        data_quality="good",
        raw_data={},
    )
 async def test_latest_by_site_keeps_only_the_most_recent_reading(session: AsyncSession) -> None:
    site_id = identifiant()
    maintenant = datetime.now(UTC)
    session.add(Site(site_id=site_id, site_name="Site", site_type="bureau", capacity_kw=100))
    await session.flush()
    session.add_all(
        [
            lecture(site_id, timestamp=maintenant - timedelta(hours=1), consumption_kw=10),
            lecture(site_id, timestamp=maintenant, consumption_kw=42),
        ]
    )
    await session.flush()
    depot = ReadingRepository(session)
    resultats = await depot.latest_by_site()
    consommations = [r.consumption_kw for r in resultats if r.site_id == site_id]
    await session.rollback()
    assert consommations == [42]
 async def test_latest_by_site_returns_one_row_per_site(session: AsyncSession) -> None:
    premier, second = identifiant(), identifiant()
    maintenant = datetime.now(UTC)
    session.add_all(
        [
            Site(site_id=premier, site_name="A", site_type="bureau", capacity_kw=100),
            Site(site_id=second, site_name="B", site_type="bureau", capacity_kw=200),
        ]
    )
    await session.flush()
    session.add_all(
        [
            lecture(premier, timestamp=maintenant, consumption_kw=10),
            lecture(second, timestamp=maintenant, consumption_kw=20),
        ]
    )
    await session.flush()
    depot = ReadingRepository(session)
    resultats = await depot.latest_by_site()
    identifiants = {r.site_id for r in resultats if r.site_id in (premier, second)}
    await session.rollback()
    assert identifiants == {premier, second}
@@ -1,107 +0,0 @@
 from dataclasses import dataclass
 from app.services.stats import StatsService
@dataclass
 class FauxSite:
    site_id: str
    site_name: str
    capacity_kw: float | None
@dataclass
 class FauxLecture:
    site_id: str
    consumption_kw: float | None
    data_quality: str | None
 class FauxDepotSites:
    def __init__(self, sites: list[FauxSite]) -> None:
        self._sites = sites
    async def list_all(self) -> list[FauxSite]:
        return self._sites
 class FauxDepotLectures:
    def __init__(self, lectures: list[FauxLecture]) -> None:
        self._lectures = lectures
    async def latest_by_site(self) -> list[FauxLecture]:
        return self._lectures
 async def test_summary_computes_totals_and_the_average_load() -> None:
    service = StatsService(
        sites=FauxDepotSites([FauxSite("A", "Site A", 200), FauxSite("B", "Site B", 800)]),  # type: ignore[arg-type]
        readings=FauxDepotLectures(  # type: ignore[arg-type]
            [
                FauxLecture("A", 100, "good"),
                FauxLecture("B", 400, "good"),
            ]
        ),
    )
    resume = await service.summary()
    assert resume.total_sites == 2
    assert resume.total_consumption_kw == 500
    assert resume.total_capacity_kw == 1000
    assert resume.average_load_percent == 50
    par_site = {site.site_id: site for site in resume.sites}
    assert par_site["A"].load_percent == 50
    assert par_site["B"].load_percent == 50
 async def test_summary_treats_a_site_without_any_reading_as_critical() -> None:
    service = StatsService(
        sites=FauxDepotSites([FauxSite("A", "Site A", 200)]),  # type: ignore[arg-type]
        readings=FauxDepotLectures([]),  # type: ignore[arg-type]
    )
    resume = await service.summary()
    site = resume.sites[0]
    assert site.data_quality == "critical"
    assert site.current_consumption_kw is None
    assert site.load_percent is None
 async def test_summary_treats_a_reading_with_an_unknown_quality_as_critical() -> None:
    service = StatsService(
        sites=FauxDepotSites([FauxSite("A", "Site A", 200)]),  # type: ignore[arg-type]
        readings=FauxDepotLectures([FauxLecture("A", 50, None)]),  # type: ignore[arg-type]
    )
    resume = await service.summary()
    site = resume.sites[0]
    assert site.data_quality == "critical"
    assert site.current_consumption_kw is None
 async def test_summary_exposes_a_missing_capacity_as_zero_without_dividing_by_it() -> None:
    service = StatsService(
        sites=FauxDepotSites([FauxSite("A", "Site A", None)]),  # type: ignore[arg-type]
        readings=FauxDepotLectures([FauxLecture("A", 50, "good")]),  # type: ignore[arg-type]
    )
    resume = await service.summary()
    site = resume.sites[0]
    assert site.capacity_kw == 0
    assert site.current_consumption_kw == 50
    assert site.load_percent is None
 async def test_summary_returns_zero_average_load_when_no_site_has_a_capacity() -> None:
    service = StatsService(
        sites=FauxDepotSites([FauxSite("A", "Site A", None)]),  # type: ignore[arg-type]
        readings=FauxDepotLectures([]),  # type: ignore[arg-type]
    )
    resume = await service.summary()
    assert resume.average_load_percent == 0
@@ -2,8 +2,7 @@
  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
  "version": 1,
  "cli": {
-    "packageManager": "npm",
+    "packageManager": "npm"
    "analytics": false
  },
  "newProjectRoot": "projects",
  "projects": {
@@ -35,10 +35,9 @@ 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 et `ng serve` tournent sur le poste avec le rechargement
+seule la base tourne en conteneur, l'API tourne sur le poste avec le rechargement à chaud. Le
-à chaud, lancés ensemble par `make dev` (`make dev-backend`/`make dev-frontend` pour lancer l'un
+service `backend` sert la stack complète et la recette. Les deux occupent le port 8000, ils ne se
-des deux seul). Le service `backend` sert la stack complète et la recette. Les deux occupent le
+lancent donc pas ensemble.
 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 :
@@ -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, stats"]
+  ep["endpoints<br/>health, auth, users, sites"]
  sc["schemas<br/>Pydantic"]
-  sv["services<br/>AuthService, UserService,<br/>SiteService, StatsService"]
+  sv["services<br/>AuthService, UserService,<br/>SiteService"]
-  rp["repositories<br/>user, refresh_token,<br/>login_attempt, audit_log,<br/>site, reading"]
+  rp["repositories<br/>user, refresh_token,<br/>login_attempt, audit_log,<br/>site"]
  md["models<br/>10 tables"]
  db[("PostgreSQL")]
@@ -142,7 +142,6 @@ Deux fichiers d'environnement, deux usages : `.env` à la racine alimente `docke
 | POST | `/api/v1/users/{id}/password-reset` | Réinitialise et ferme les sessions. `admin` | 401, 403, 404, 422, 500 |
 | GET | `/api/v1/sites` | Liste les sites. `lecteur` | 401, 403, 500 |
 | GET | `/api/v1/sites/{site_id}` | Décrit un site. `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` | |
@@ -161,9 +160,7 @@ déjà créées par la révision Alembic `e6d2026091501`. Elles n'exigent que le
 contrairement aux routes d'administration qui exigent `admin`. `SiteRepository` lit par
 `AsyncSession.scalar()` (une ligne) et `AsyncSession.scalars()` (plusieurs lignes) plutôt que par
 `execute()`, ce qui la rend testable par la fixture `fake_session` au niveau endpoint sans base
-réelle. `GET /stats/summary` agrège ces deux repositories (`SiteRepository`, `ReadingRepository`)
+réelle. Le contrat détaillé pour le frontend est dans
 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`
@@ -238,20 +235,19 @@ 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
+**Ajouter une route métier** (`sites` est le gabarit, `reading`/`dataset`/`prediction`/`alert`/
 `recommendation` suivront) :
-Checklist pour toute nouvelle route sur le gabarit `sites`/`stats` (`reading`, `dataset`,
+1. Composer ses `responses=` depuis `app/api/openapi.py` : `REPONSES_LECTEUR` ou `REPONSES_ADMIN`
-`prediction`, `alert`, `recommendation`) :
+   au niveau de l'`include_router` dans `app/api/v1/router.py` (401 et le 403 propre au rôle),
-
+   `REPONSE_VALIDATION` et les codes locaux (404, 409, ...) sur l'endpoint lui-même s'il a un
-1. Composer ses `responses=` depuis `app/api/openapi.py` : `REPONSES_LECTEUR`/`REPONSES_ADMIN`
+   corps, un paramètre ou peut échouer par identifiant.
-   au niveau de l'`include_router()` du routeur, `REPONSE_VALIDATION` et les codes locaux
+2. Décrire son tag dans `TAGS` (`app/api/openapi.py`).
-   (404, 409, ...) directement sur l'endpoint qui les rend.
+3. Si elle passe par `require_role`, l'ajouter à `ROUTES_A_ROLE`
-2. Décrire son tag dans `TAGS`.
+   (`tests/api/test_openapi.py`) ; si elle passe par `require_trusted_origin`, l'ajouter à
-3. Si elle passe par `require_role` (`LecteurDep`/`OperateurDep`/`AdminDep`), l'ajouter à
+   `ORIGINE_VERIFIEE`. Ces deux listes sont maintenues à la main, pas déduites automatiquement du
-   `ROUTES_A_ROLE` dans `tests/api/test_openapi.py`. Si elle passe par `require_trusted_origin`,
+   code : une route protégée qui n'y figure pas ne sera pas détectée par les tests.
-   l'ajouter à `ORIGINE_VERIFIEE`. **Ces deux listes sont maintenues à la main, pas dérivées** :
+4. `make openapi`, puis `pytest tests/api/test_openapi.py`.
   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é
@@ -108,9 +108,8 @@ 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 a ses cibles dans le `Makefile` racine (`install-frontend`, `dev-frontend`,
+Le frontend **n'a pas de cible dans le `Makefile` racine** et **aucun service dans
-englobées par `install` et `dev`), mais **aucun service dans `docker-compose.yml`** : en
+`docker-compose.yml`** : il se pilote uniquement par `npm`, depuis `apps/frontend`. Le port 4200
 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