Update apps/backend/tests/services/test_sensor.py

Dérive l'état de santé de 5 capteurs par site et un statut overall depuis
la dernière lecture (data_quality, null_reasons, nullité des colonnes),
sur le gabarit d'agrégation de StatsService. Route réservée au rôle admin.

apps/backend/README.md

@@ -109,6 +109,8 @@ Le sens de dependance est unique : `endpoints` vers `services` vers `repositorie
 | `/api/v1/users/{id}/password-reset` | Réinitialise et ferme les sessions | `admin` |
 | `/api/v1/sites` | Liste les sites | `lecteur` |
 | `/api/v1/sites/{site_id}` | Décrit un site | `lecteur` |
+| `/api/v1/recommendations` | Liste les recommandations | `lecteur` |
+| `/api/v1/recommendations/{recommendation_id}` | Décrit une recommandation | `lecteur` |
 | `/metrics` | Métriques au format Prometheus | jeton si `APP_METRICS_TOKEN` |
 | `/docs`, `/openapi.json` | Documentation, fermée en `staging` et `prod` | public sinon |
 

apps/backend/app/api/deps.py

@@ -21,13 +21,20 @@ from app.core.roles import AccountKind, Role, has_at_least
 from app.core.security import TokenExpiredError, TokenInvalidError, TokenPolicy
 from app.core.security import decode_access_token as decode_token
 from app.db.session import get_session
+from app.repositories.alert import AlertRepository
 from app.repositories.audit_log import AuditLogRepository
 from app.repositories.login_attempt import LoginAttemptRepository
+from app.repositories.reading import ReadingRepository
+from app.repositories.recommendation import RecommendationRepository
 from app.repositories.refresh_token import RefreshTokenRepository
 from app.repositories.site import SiteRepository
 from app.repositories.user import UserRepository
+from app.services.alert import AlertService
 from app.services.auth import AuthService, LoginPolicy
+from app.services.recommendation import RecommendationService
+from app.services.sensor import SensorService
 from app.services.site import SiteService
+from app.services.stats import StatsService
 from app.services.user import UserService
 
 SessionDep = Annotated[AsyncSession, Depends(get_session)]
@@ -140,6 +147,34 @@ def get_site_service(session: SessionDep) -> SiteService:
 SiteServiceDep = Annotated[SiteService, Depends(get_site_service)]
 
 
+def get_alert_service(session: SessionDep) -> AlertService:
+    return AlertService(alerts=AlertRepository(session))
+
+
+AlertServiceDep = Annotated[AlertService, Depends(get_alert_service)]
+
+
+def get_recommendation_service(session: SessionDep) -> RecommendationService:
+    return RecommendationService(recommendations=RecommendationRepository(session))
+
+
+RecommendationServiceDep = Annotated[RecommendationService, Depends(get_recommendation_service)]
+
+
+def get_stats_service(session: SessionDep) -> StatsService:
+    return StatsService(sites=SiteRepository(session), readings=ReadingRepository(session))
+
+
+StatsServiceDep = Annotated[StatsService, Depends(get_stats_service)]
+
+
+def get_sensor_service(session: SessionDep) -> SensorService:
+    return SensorService(sites=SiteRepository(session), readings=ReadingRepository(session))
+
+
+SensorServiceDep = Annotated[SensorService, Depends(get_sensor_service)]
+
+
 async def get_current_principal(
     credentials: CredentialsDep,
     session: SessionDep,

apps/backend/app/api/openapi.py

@@ -54,6 +54,27 @@ TAGS: Final[list[dict[str, Any]]] = [
         "name": "sites",
         "description": "Consultation du parc de sites. Accessible à partir du rôle `lecteur`.",
     },
+    {
+        "name": "alerts",
+        "description": "Consultation des alertes de consommation. Accessible à partir du rôle "
+        "`lecteur`.",
+    },
+    {
+        "name": "recommendations",
+        "description": (
+            "Consultation des recommandations issues des alertes. Accessible à partir du rôle "
+            "`lecteur`."
+        ),
+    },
+    {
+        "name": "stats",
+        "description": "Statistiques agrégées de consommation. Accessible à partir du rôle "
+        "`lecteur`.",
+    },
+    {
+        "name": "sensors",
+        "description": "État de santé des capteurs par site. Réservé au rôle `admin`.",
+    },
 ]
 
 cookie_de_rafraichissement = APIKeyCookie(

apps/backend/app/api/v1/endpoints/alerts.py

@@ -0,0 +1,23 @@
+from fastapi import APIRouter
+
+from app.api.deps import AlertServiceDep, LecteurDep
+from app.api.openapi import REPONSE_VALIDATION
+from app.schemas.alert import AlertResponse, AlertSeverity
+
+router = APIRouter()
+
+
+@router.get(
+    "",
+    response_model=list[AlertResponse],
+    summary="Liste les alertes",
+    responses=REPONSE_VALIDATION,
+)
+async def list_alerts(
+    _: LecteurDep,
+    service: AlertServiceDep,
+    site_id: str | None = None,
+    severity: AlertSeverity | None = None,
+) -> list[AlertResponse]:
+    alertes = await service.list_all(site_id=site_id, severity=severity)
+    return [AlertResponse.model_validate(alerte) for alerte in alertes]

apps/backend/app/api/v1/endpoints/recommendations.py

@@ -0,0 +1,40 @@
+from fastapi import APIRouter, HTTPException, status
+
+from app.api.deps import LecteurDep, RecommendationServiceDep
+from app.api.openapi import REPONSE_VALIDATION, Reponses
+from app.schemas.errors import ErrorResponse
+from app.schemas.recommendation import RecommendationResponse
+from app.services.recommendation import RecommendationNotFoundError
+
+router = APIRouter()
+
+REPONSES_INTROUVABLE: Reponses = {
+    **REPONSE_VALIDATION,
+    404: {"model": ErrorResponse, "description": "Aucune recommandation ne porte cet identifiant."},
+}
+
+
+@router.get("", response_model=list[RecommendationResponse], summary="Liste les recommandations")
+async def list_recommendations(
+    _: LecteurDep, service: RecommendationServiceDep
+) -> list[RecommendationResponse]:
+    recommendations = await service.list_all()
+    return [RecommendationResponse.model_validate(r) for r in recommendations]
+
+
+@router.get(
+    "/{recommendation_id}",
+    response_model=RecommendationResponse,
+    summary="Décrit une recommandation",
+    responses=REPONSES_INTROUVABLE,
+)
+async def get_recommendation(
+    recommendation_id: int, _: LecteurDep, service: RecommendationServiceDep
+) -> RecommendationResponse:
+    try:
+        recommendation = await service.get_by_id(recommendation_id)
+    except RecommendationNotFoundError as erreur:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Recommandation introuvable"
+        ) from erreur
+    return RecommendationResponse.model_validate(recommendation)

apps/backend/app/api/v1/endpoints/sensors.py

@@ -0,0 +1,16 @@
+from fastapi import APIRouter
+
+from app.api.deps import AdminDep, SensorServiceDep
+from app.schemas.sensor import SensorStatusResponse
+
+router = APIRouter()
+
+
+@router.get(
+    "/status",
+    response_model=SensorStatusResponse,
+    summary="État de santé des capteurs par site",
+)
+async def get_status(_: AdminDep, service: SensorServiceDep) -> SensorStatusResponse:
+    etat = await service.status()
+    return SensorStatusResponse.model_validate(etat)

apps/backend/app/api/v1/endpoints/stats.py

@@ -0,0 +1,16 @@
+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)

apps/backend/app/api/v1/router.py

@@ -1,10 +1,23 @@
 from fastapi import APIRouter
 
 from app.api.openapi import REPONSE_SERVEUR, REPONSES_ADMIN, REPONSES_LECTEUR
-from app.api.v1.endpoints import auth, health, sites, users
+from app.api.v1.endpoints import alerts, auth, health, recommendations, sensors, sites, stats, 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(
+    alerts.router, prefix="/alerts", tags=["alerts"], responses=REPONSES_LECTEUR
+)
+api_router.include_router(
+    recommendations.router,
+    prefix="/recommendations",
+    tags=["recommendations"],
+    responses=REPONSES_LECTEUR,
+)
+api_router.include_router(stats.router, prefix="/stats", tags=["stats"], responses=REPONSES_LECTEUR)
+api_router.include_router(
+    sensors.router, prefix="/sensors", tags=["sensors"], responses=REPONSES_ADMIN
+)

apps/backend/app/repositories/alert.py

@@ -0,0 +1,21 @@
+from collections.abc import Sequence
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.energy import Alert
+
+
+class AlertRepository:
+    def __init__(self, session: AsyncSession) -> None:
+        self._session = session
+
+    async def list_all(
+        self, *, site_id: str | None = None, severity: str | None = None
+    ) -> Sequence[Alert]:
+        requete = select(Alert).order_by(Alert.timestamp.desc(), Alert.alert_id.desc())
+        if site_id is not None:
+            requete = requete.where(Alert.site_id == site_id)
+        if severity is not None:
+            requete = requete.where(Alert.severity == severity)
+        return (await self._session.scalars(requete)).all()

apps/backend/app/repositories/reading.py

@@ -0,0 +1,21 @@
+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()

apps/backend/app/repositories/recommendation.py

@@ -0,0 +1,22 @@
+from collections.abc import Sequence
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.energy import Recommendation
+
+
+class RecommendationRepository:
+    def __init__(self, session: AsyncSession) -> None:
+        self._session = session
+
+    async def list_all(self) -> Sequence[Recommendation]:
+        requete = select(Recommendation).order_by(Recommendation.recommendation_id)
+        return (await self._session.scalars(requete)).all()
+
+    async def get_by_id(self, recommendation_id: int) -> Recommendation | None:
+        requete = select(Recommendation).where(
+            Recommendation.recommendation_id == recommendation_id
+        )
+        recommendation: Recommendation | None = await self._session.scalar(requete)
+        return recommendation

apps/backend/app/schemas/alert.py

@@ -0,0 +1,34 @@
+from datetime import datetime
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict
+
+
+class AlertType(StrEnum):
+    SPIKE = "spike"
+    THRESHOLD = "threshold"
+    ANOMALY = "anomaly"
+    OUTAGE = "outage"
+    SENSOR = "sensor"
+
+
+class AlertSeverity(StrEnum):
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+
+class AlertResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    alert_id: int
+    site_id: str
+    timestamp: datetime
+    type: AlertType
+    severity: AlertSeverity
+    message: str
+    value: float | None
+    threshold: float | None
+    metric: str | None
+    prediction_id: int | None

apps/backend/app/schemas/recommendation.py

@@ -0,0 +1,14 @@
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
+
+
+class RecommendationResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    recommendation_id: int
+    alert_id: int
+    action: str
+    explanation: str
+    rule_reference: str
+    created_at: datetime

apps/backend/app/schemas/sensor.py

@@ -0,0 +1,42 @@
+from datetime import datetime
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class SensorDiagnosticResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    status: Literal["ok", "failing"]
+    since: datetime | None = Field(
+        description=(
+            "Horodatage de la dernière lecture reçue pour ce site. Ce n'est pas le début de la "
+            "panne : l'historique ne permet pas de le dater sans requête supplémentaire."
+        )
+    )
+
+
+class SiteSensorsResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    consumption: SensorDiagnosticResponse
+    electrical: SensorDiagnosticResponse
+    temperature: SensorDiagnosticResponse
+    humidity: SensorDiagnosticResponse
+    network: SensorDiagnosticResponse
+
+
+class SiteSensorStatusResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    site_id: str
+    site_name: str
+    sensors: SiteSensorsResponse
+    overall: Literal["ok", "degraded", "critical"]
+
+
+class SensorStatusResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    timestamp: datetime
+    sites: list[SiteSensorStatusResponse]

apps/backend/app/schemas/stats.py

@@ -0,0 +1,26 @@
+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]

apps/backend/app/services/alert.py

@@ -0,0 +1,14 @@
+from collections.abc import Sequence
+
+from app.models.energy import Alert
+from app.repositories.alert import AlertRepository
+
+
+class AlertService:
+    def __init__(self, *, alerts: AlertRepository) -> None:
+        self._alerts = alerts
+
+    async def list_all(
+        self, *, site_id: str | None = None, severity: str | None = None
+    ) -> Sequence[Alert]:
+        return await self._alerts.list_all(site_id=site_id, severity=severity)

apps/backend/app/services/recommendation.py

@@ -0,0 +1,26 @@
+from collections.abc import Sequence
+
+from app.models.energy import Recommendation
+from app.repositories.recommendation import RecommendationRepository
+
+
+class RecommendationError(Exception):
+    pass
+
+
+class RecommendationNotFoundError(RecommendationError):
+    pass
+
+
+class RecommendationService:
+    def __init__(self, *, recommendations: RecommendationRepository) -> None:
+        self._recommendations = recommendations
+
+    async def list_all(self) -> Sequence[Recommendation]:
+        return await self._recommendations.list_all()
+
+    async def get_by_id(self, recommendation_id: int) -> Recommendation:
+        recommendation = await self._recommendations.get_by_id(recommendation_id)
+        if recommendation is None:
+            raise RecommendationNotFoundError(recommendation_id)
+        return recommendation

apps/backend/app/services/sensor.py

@@ -0,0 +1,137 @@
+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
+
+CapteurStatus = Literal["ok", "failing"]
+OverallStatus = Literal["ok", "degraded", "critical"]
+
+QUALITES_CONNUES: frozenset[str] = frozenset({"good", "partial", "degraded", "critical"})
+
+RAISON_VERS_CAPTEUR: dict[str, str] = {
+    "consumption_sensor_failure": "consumption",
+    "electrical_sensor_failure": "electrical",
+    "temperature_sensor_failure": "temperature",
+    "humidity_sensor_failure": "humidity",
+    "network_loss": "network",
+}
+
+CHAMPS_PAR_CAPTEUR: dict[str, tuple[str, ...]] = {
+    "consumption": ("consumption_kw",),
+    "electrical": ("voltage_v", "current_a", "power_factor"),
+    "temperature": ("temperature_celsius",),
+    "humidity": ("humidity_percent",),
+}
+
+
+@dataclass(frozen=True, slots=True)
+class DiagnosticCapteur:
+    status: CapteurStatus
+    since: datetime | None
+
+
+@dataclass(frozen=True, slots=True)
+class SanteCapteurs:
+    consumption: DiagnosticCapteur
+    electrical: DiagnosticCapteur
+    temperature: DiagnosticCapteur
+    humidity: DiagnosticCapteur
+    network: DiagnosticCapteur
+
+
+@dataclass(frozen=True, slots=True)
+class SanteSite:
+    site_id: str
+    site_name: str
+    sensors: SanteCapteurs
+    overall: OverallStatus
+
+
+@dataclass(frozen=True, slots=True)
+class EtatCapteurs:
+    timestamp: datetime
+    sites: list[SanteSite]
+
+
+class SensorService:
+    def __init__(self, sites: SiteRepository, readings: ReadingRepository) -> None:
+        self._sites = sites
+        self._readings = readings
+
+    async def status(self) -> EtatCapteurs:
+        sites = await self._sites.list_all()
+        dernieres = {lecture.site_id: lecture for lecture in await self._readings.latest_by_site()}
+
+        return EtatCapteurs(
+            timestamp=datetime.now(UTC),
+            sites=[_sante_site(site, dernieres.get(site.site_id)) for site in sites],
+        )
+
+
+def _sante_site(site: Site, derniere: Reading | None) -> SanteSite:
+    if derniere is None:
+        return SanteSite(
+            site_id=site.site_id,
+            site_name=site.site_name,
+            sensors=_tout_en_echec(since=None),
+            overall="critical",
+        )
+
+    qualite = derniere.data_quality if derniere.data_quality in QUALITES_CONNUES else "critical"
+    overall = _overall_depuis_qualite(qualite)
+
+    if overall == "critical":
+        return SanteSite(
+            site_id=site.site_id,
+            site_name=site.site_name,
+            sensors=_tout_en_echec(since=derniere.timestamp),
+            overall="critical",
+        )
+
+    raisons_signalees = {
+        RAISON_VERS_CAPTEUR[raison]
+        for raison in (derniere.null_reasons or [])
+        if raison in RAISON_VERS_CAPTEUR
+    }
+
+    return SanteSite(
+        site_id=site.site_id,
+        site_name=site.site_name,
+        sensors=SanteCapteurs(
+            consumption=_diagnostic("consumption", derniere, raisons_signalees),
+            electrical=_diagnostic("electrical", derniere, raisons_signalees),
+            temperature=_diagnostic("temperature", derniere, raisons_signalees),
+            humidity=_diagnostic("humidity", derniere, raisons_signalees),
+            network=_diagnostic("network", derniere, raisons_signalees),
+        ),
+        overall=overall,
+    )
+
+
+def _overall_depuis_qualite(qualite: str) -> OverallStatus:
+    if qualite == "good":
+        return "ok"
+    if qualite in ("partial", "degraded"):
+        return "degraded"
+    return "critical"
+
+
+def _diagnostic(capteur: str, derniere: Reading, raisons_signalees: set[str]) -> DiagnosticCapteur:
+    champs = CHAMPS_PAR_CAPTEUR.get(capteur, ())
+    en_echec = capteur in raisons_signalees or any(
+        getattr(derniere, champ) is None for champ in champs
+    )
+    return DiagnosticCapteur(
+        status="failing" if en_echec else "ok",
+        since=derniere.timestamp if en_echec else None,
+    )
+
+
+def _tout_en_echec(since: datetime | None) -> SanteCapteurs:
+    echec = DiagnosticCapteur(status="failing", since=since)
+    return SanteCapteurs(
+        consumption=echec, electrical=echec, temperature=echec, humidity=echec, network=echec
+    )

apps/backend/app/services/stats.py

@@ -0,0 +1,81 @@
+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,
+        )

apps/backend/openapi.json

@@ -920,6 +920,369 @@
           }
         }
       }
+    },
+    "/api/v1/alerts": {
+      "get": {
+        "tags": [
+          "alerts"
+        ],
+        "summary": "Liste les alertes",
+        "operationId": "list_alerts_api_v1_alerts_get",
+        "security": [
+          {
+            "Jeton d'accès": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "site_id",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "title": "Site Id"
+            }
+          },
+          {
+            "name": "severity",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "anyOf": [
+                {
+                  "$ref": "#/components/schemas/AlertSeverity"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "title": "Severity"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/AlertResponse"
+                  },
+                  "title": "Response List Alerts Api V1 Alerts Get"
+                }
+              }
+            }
+          },
+          "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"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Corps invalide. Le détail nomme le champ fautif et le type d'erreur, jamais la valeur envoyée.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ValidationErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/recommendations": {
+      "get": {
+        "tags": [
+          "recommendations"
+        ],
+        "summary": "Liste les recommandations",
+        "operationId": "list_recommendations_api_v1_recommendations_get",
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "items": {
+                    "$ref": "#/components/schemas/RecommendationResponse"
+                  },
+                  "type": "array",
+                  "title": "Response List Recommendations Api V1 Recommendations Get"
+                }
+              }
+            }
+          },
+          "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": []
+          }
+        ]
+      }
+    },
+    "/api/v1/recommendations/{recommendation_id}": {
+      "get": {
+        "tags": [
+          "recommendations"
+        ],
+        "summary": "Décrit une recommandation",
+        "operationId": "get_recommendation_api_v1_recommendations__recommendation_id__get",
+        "security": [
+          {
+            "Jeton d'accès": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "recommendation_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "title": "Recommendation Id"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RecommendationResponse"
+                }
+              }
+            }
+          },
+          "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"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Corps invalide. Le détail nomme le champ fautif et le type d'erreur, jamais la valeur envoyée.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ValidationErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Aucune recommandation ne porte cet identifiant.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/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": []
+          }
+        ]
+      }
+    },
+    "/api/v1/sensors/status": {
+      "get": {
+        "tags": [
+          "sensors"
+        ],
+        "summary": "État de santé des capteurs par site",
+        "operationId": "get_status_api_v1_sensors_status_get",
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SensorStatusResponse"
+                }
+              }
+            }
+          },
+          "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": "Droits insuffisants, ou mot de passe provisoire à changer quand `detail` vaut `password_change_required`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "Jeton d'accès": []
+          }
+        ]
+      }
     }
   },
   "components": {
@@ -932,6 +1295,112 @@
         ],
         "title": "AccountKind"
       },
+      "AlertResponse": {
+        "properties": {
+          "alert_id": {
+            "type": "integer",
+            "title": "Alert Id"
+          },
+          "site_id": {
+            "type": "string",
+            "title": "Site Id"
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time",
+            "title": "Timestamp"
+          },
+          "type": {
+            "$ref": "#/components/schemas/AlertType"
+          },
+          "severity": {
+            "$ref": "#/components/schemas/AlertSeverity"
+          },
+          "message": {
+            "type": "string",
+            "title": "Message"
+          },
+          "value": {
+            "anyOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Value"
+          },
+          "threshold": {
+            "anyOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Threshold"
+          },
+          "metric": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Metric"
+          },
+          "prediction_id": {
+            "anyOf": [
+              {
+                "type": "integer"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Prediction Id"
+          }
+        },
+        "type": "object",
+        "required": [
+          "alert_id",
+          "site_id",
+          "timestamp",
+          "type",
+          "severity",
+          "message",
+          "value",
+          "threshold",
+          "metric",
+          "prediction_id"
+        ],
+        "title": "AlertResponse"
+      },
+      "AlertSeverity": {
+        "type": "string",
+        "enum": [
+          "low",
+          "medium",
+          "high",
+          "critical"
+        ],
+        "title": "AlertSeverity"
+      },
+      "AlertType": {
+        "type": "string",
+        "enum": [
+          "spike",
+          "threshold",
+          "anomaly",
+          "outage",
+          "sensor"
+        ],
+        "title": "AlertType"
+      },
       "ErrorResponse": {
         "properties": {
           "detail": {
@@ -1111,6 +1580,45 @@
         ],
         "title": "ReadinessStatus"
       },
+      "RecommendationResponse": {
+        "properties": {
+          "recommendation_id": {
+            "type": "integer",
+            "title": "Recommendation Id"
+          },
+          "alert_id": {
+            "type": "integer",
+            "title": "Alert Id"
+          },
+          "action": {
+            "type": "string",
+            "title": "Action"
+          },
+          "explanation": {
+            "type": "string",
+            "title": "Explanation"
+          },
+          "rule_reference": {
+            "type": "string",
+            "title": "Rule Reference"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time",
+            "title": "Created At"
+          }
+        },
+        "type": "object",
+        "required": [
+          "recommendation_id",
+          "alert_id",
+          "action",
+          "explanation",
+          "rule_reference",
+          "created_at"
+        ],
+        "title": "RecommendationResponse"
+      },
       "Role": {
         "type": "string",
         "enum": [
@@ -1120,6 +1628,59 @@
         ],
         "title": "Role"
       },
+      "SensorDiagnosticResponse": {
+        "properties": {
+          "status": {
+            "type": "string",
+            "enum": [
+              "ok",
+              "failing"
+            ],
+            "title": "Status"
+          },
+          "since": {
+            "anyOf": [
+              {
+                "type": "string",
+                "format": "date-time"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Since",
+            "description": "Horodatage de la dernière lecture reçue pour ce site. Ce n'est pas le début de la panne : l'historique ne permet pas de le dater sans requête supplémentaire."
+          }
+        },
+        "type": "object",
+        "required": [
+          "status",
+          "since"
+        ],
+        "title": "SensorDiagnosticResponse"
+      },
+      "SensorStatusResponse": {
+        "properties": {
+          "timestamp": {
+            "type": "string",
+            "format": "date-time",
+            "title": "Timestamp"
+          },
+          "sites": {
+            "items": {
+              "$ref": "#/components/schemas/SiteSensorStatusResponse"
+            },
+            "type": "array",
+            "title": "Sites"
+          }
+        },
+        "type": "object",
+        "required": [
+          "timestamp",
+          "sites"
+        ],
+        "title": "SensorStatusResponse"
+      },
       "SiteResponse": {
         "properties": {
           "site_id": {
@@ -1179,6 +1740,166 @@
         ],
         "title": "SiteResponse"
       },
+      "SiteSensorStatusResponse": {
+        "properties": {
+          "site_id": {
+            "type": "string",
+            "title": "Site Id"
+          },
+          "site_name": {
+            "type": "string",
+            "title": "Site Name"
+          },
+          "sensors": {
+            "$ref": "#/components/schemas/SiteSensorsResponse"
+          },
+          "overall": {
+            "type": "string",
+            "enum": [
+              "ok",
+              "degraded",
+              "critical"
+            ],
+            "title": "Overall"
+          }
+        },
+        "type": "object",
+        "required": [
+          "site_id",
+          "site_name",
+          "sensors",
+          "overall"
+        ],
+        "title": "SiteSensorStatusResponse"
+      },
+      "SiteSensorsResponse": {
+        "properties": {
+          "consumption": {
+            "$ref": "#/components/schemas/SensorDiagnosticResponse"
+          },
+          "electrical": {
+            "$ref": "#/components/schemas/SensorDiagnosticResponse"
+          },
+          "temperature": {
+            "$ref": "#/components/schemas/SensorDiagnosticResponse"
+          },
+          "humidity": {
+            "$ref": "#/components/schemas/SensorDiagnosticResponse"
+          },
+          "network": {
+            "$ref": "#/components/schemas/SensorDiagnosticResponse"
+          }
+        },
+        "type": "object",
+        "required": [
+          "consumption",
+          "electrical",
+          "temperature",
+          "humidity",
+          "network"
+        ],
+        "title": "SiteSensorsResponse"
+      },
+      "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": {
@@ -1395,6 +2116,22 @@
     {
       "name": "sites",
       "description": "Consultation du parc de sites. Accessible à partir du rôle `lecteur`."
+    },
+    {
+      "name": "alerts",
+      "description": "Consultation des alertes de consommation. Accessible à partir du rôle `lecteur`."
+    },
+    {
+      "name": "recommendations",
+      "description": "Consultation des recommandations issues des alertes. Accessible à partir du rôle `lecteur`."
+    },
+    {
+      "name": "stats",
+      "description": "Statistiques agrégées de consommation. Accessible à partir du rôle `lecteur`."
+    },
+    {
+      "name": "sensors",
+      "description": "État de santé des capteurs par site. Réservé au rôle `admin`."
     }
   ]
 }

apps/backend/tests/api/test_alerts.py

@@ -0,0 +1,137 @@
+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_alert_service, get_current_principal
+from app.core.principal import Principal
+from app.core.roles import AccountKind, Role
+from app.models.energy import Alert
+from app.schemas.alert import AlertSeverity
+
+
+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,
+    )
+
+
+def alert(alert_id: int = 1, site_id: str = "site-1", severity: str = "high") -> Alert:
+    return Alert(
+        alert_id=alert_id,
+        source_alert_id=f"ALR-{alert_id}",
+        site_id=site_id,
+        source="enervision",
+        timestamp=datetime(2026, 9, 16, tzinfo=UTC),
+        type="threshold",
+        severity=severity,
+        message="Dépassement du seuil configuré",
+        value=812.5,
+        threshold=720.0,
+        metric="consumption_kw",
+        prediction_id=None,
+        raw_data={},
+    )
+
+
+class FauxService:
+    def __init__(self) -> None:
+        self.alert = alert()
+        self.appels: list[tuple[str | None, str | None]] = []
+
+    async def list_all(
+        self, *, site_id: str | None = None, severity: str | None = None
+    ) -> list[Alert]:
+        self.appels.append((site_id, severity))
+        return [self.alert]
+
+
+@pytest.fixture
+def lecteur_connecte(app: FastAPI) -> Iterator[None]:
+    app.dependency_overrides[get_current_principal] = lambda: principal()
+    yield
+    app.dependency_overrides.pop(get_current_principal, None)
+
+
+@pytest.fixture
+def servi(app: FastAPI, lecteur_connecte: None) -> Iterator[Callable[[], FauxService]]:
+    def installe() -> FauxService:
+        service = FauxService()
+        app.dependency_overrides[get_alert_service] = lambda: service
+        return service
+
+    yield installe
+    app.dependency_overrides.pop(get_alert_service, None)
+
+
+async def test_list_alerts_returns_the_alerts(
+    servi: Callable[[], FauxService], client: AsyncClient
+) -> None:
+    servi()
+
+    response = await client.get("/api/v1/alerts")
+
+    assert response.status_code == 200
+    corps = response.json()
+    assert corps == [
+        {
+            "alert_id": 1,
+            "site_id": "site-1",
+            "timestamp": "2026-09-16T00:00:00Z",
+            "type": "threshold",
+            "severity": "high",
+            "message": "Dépassement du seuil configuré",
+            "value": 812.5,
+            "threshold": 720.0,
+            "metric": "consumption_kw",
+            "prediction_id": None,
+        }
+    ]
+
+
+async def test_list_alerts_transmits_the_site_id_filter(
+    servi: Callable[[], FauxService], client: AsyncClient
+) -> None:
+    service = servi()
+
+    await client.get("/api/v1/alerts?site_id=site-1")
+
+    assert service.appels == [("site-1", None)]
+
+
+async def test_list_alerts_transmits_the_severity_filter(
+    servi: Callable[[], FauxService], client: AsyncClient
+) -> None:
+    service = servi()
+
+    await client.get("/api/v1/alerts?severity=critical")
+
+    assert service.appels == [(None, AlertSeverity.CRITICAL)]
+
+
+async def test_list_alerts_returns_422_for_an_unknown_severity(
+    servi: Callable[[], FauxService], client: AsyncClient
+) -> None:
+    servi()
+
+    response = await client.get("/api/v1/alerts?severity=invalide")
+
+    assert response.status_code == 422
+
+
+async def test_list_alerts_returns_an_empty_list_when_there_is_nothing(
+    lecteur_connecte: None, fake_session: Callable[..., None], client: AsyncClient
+) -> None:
+    fake_session(result=[])
+
+    response = await client.get("/api/v1/alerts")
+
+    assert response.status_code == 200
+    assert response.json() == []

apps/backend/tests/api/test_openapi.py

@@ -22,6 +22,22 @@ ORIGINE_VERIFIEE = {
     ("POST", "/api/v1/auth/password"),
 }
 
+# Toute route derrière `require_role` (LecteurDep, OperateurDep, AdminDep) peut rendre 403 pour
+# `password_change_required`, pas seulement les routes `admin`.
+ROUTES_A_ROLE = {
+    ("GET", "/api/v1/users"),
+    ("POST", "/api/v1/users"),
+    ("PATCH", "/api/v1/users/{id}"),
+    ("POST", "/api/v1/users/{id}/password-reset"),
+    ("GET", "/api/v1/sites"),
+    ("GET", "/api/v1/sites/{site_id}"),
+    ("GET", "/api/v1/alerts"),
+    ("GET", "/api/v1/recommendations"),
+    ("GET", "/api/v1/recommendations/{recommendation_id}"),
+    ("GET", "/api/v1/stats/summary"),
+    ("GET", "/api/v1/sensors/status"),
+}
+
 
 @pytest.fixture(scope="module")
 def schema() -> dict[str, Any]:
@@ -55,11 +71,11 @@ def test_every_route_demanding_an_identity_says_how_it_refuses(schema: dict[str,
     assert muettes == []
 
 
-def test_every_administration_route_documents_the_role_refusal(schema: dict[str, Any]) -> None:
+def test_every_role_guarded_route_documents_the_role_refusal(schema: dict[str, Any]) -> None:
     sans_403 = [
         (methode, chemin)
         for methode, chemin, operation in operations(schema)
-        if "users" in operation.get("tags", []) and "403" not in operation["responses"]
+        if (methode, chemin) in ROUTES_A_ROLE and "403" not in operation["responses"]
     ]
 
     assert sans_403 == []

apps/backend/tests/api/test_recommendations.py

@@ -0,0 +1,144 @@
+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_recommendation_service
+from app.core.principal import Principal
+from app.core.roles import AccountKind, Role
+from app.models.energy import Recommendation
+from app.services.recommendation import RecommendationNotFoundError
+
+MOMENT = datetime(2024, 1, 1, tzinfo=UTC)
+
+
+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,
+    )
+
+
+def recommendation(recommendation_id: int = 1) -> Recommendation:
+    return Recommendation(
+        recommendation_id=recommendation_id,
+        alert_id=1,
+        action="Vérifier la consommation",
+        explanation="Pic détecté",
+        rule_reference="spike-v1",
+        created_at=MOMENT,
+    )
+
+
+class FauxService:
+    def __init__(self, erreur: Exception | None = None) -> None:
+        self._erreur = erreur
+        self.recommendation = recommendation()
+
+    async def list_all(self) -> list[Recommendation]:
+        return [self.recommendation]
+
+    async def get_by_id(self, recommendation_id: int) -> Recommendation:
+        if self._erreur is not None:
+            raise self._erreur
+        return self.recommendation
+
+
+@pytest.fixture
+def lecteur_connecte(app: FastAPI) -> Iterator[None]:
+    app.dependency_overrides[get_current_principal] = lambda: principal()
+    yield
+    app.dependency_overrides.pop(get_current_principal, None)
+
+
+@pytest.fixture
+def servi(
+    app: FastAPI, lecteur_connecte: None
+) -> Iterator[Callable[[Exception | None], FauxService]]:
+    def installe(erreur: Exception | None = None) -> FauxService:
+        service = FauxService(erreur)
+        app.dependency_overrides[get_recommendation_service] = lambda: service
+        return service
+
+    yield installe
+    app.dependency_overrides.pop(get_recommendation_service, None)
+
+
+async def test_list_recommendations_returns_the_recommendations(
+    servi: Callable[..., FauxService], client: AsyncClient
+) -> None:
+    servi()
+
+    response = await client.get("/api/v1/recommendations")
+
+    assert response.status_code == 200
+    corps = response.json()
+    assert corps == [
+        {
+            "recommendation_id": 1,
+            "alert_id": 1,
+            "action": "Vérifier la consommation",
+            "explanation": "Pic détecté",
+            "rule_reference": "spike-v1",
+            "created_at": "2024-01-01T00:00:00Z",
+        }
+    ]
+
+
+async def test_get_recommendation_returns_the_matching_recommendation(
+    servi: Callable[..., FauxService], client: AsyncClient
+) -> None:
+    servi()
+
+    response = await client.get("/api/v1/recommendations/1")
+
+    assert response.status_code == 200
+    assert response.json()["recommendation_id"] == 1
+
+
+async def test_get_recommendation_returns_404_for_an_unknown_recommendation(
+    servi: Callable[..., FauxService], client: AsyncClient
+) -> None:
+    servi(RecommendationNotFoundError(404))
+
+    response = await client.get("/api/v1/recommendations/404")
+
+    assert response.status_code == 404
+
+
+async def test_list_recommendations_reaches_the_repository_through_the_session(
+    lecteur_connecte: None, fake_session: Callable[..., None], client: AsyncClient
+) -> None:
+    fake_session(result=[recommendation(1), recommendation(2)])
+
+    response = await client.get("/api/v1/recommendations")
+
+    assert response.status_code == 200
+    assert [r["recommendation_id"] for r in response.json()] == [1, 2]
+
+
+async def test_get_recommendation_reaches_the_repository_through_the_session(
+    lecteur_connecte: None, fake_session: Callable[..., None], client: AsyncClient
+) -> None:
+    fake_session(result=recommendation(1))
+
+    response = await client.get("/api/v1/recommendations/1")
+
+    assert response.status_code == 200
+    assert response.json()["recommendation_id"] == 1
+
+
+async def test_get_recommendation_returns_404_when_the_session_finds_nothing(
+    lecteur_connecte: None, fake_session: Callable[..., None], client: AsyncClient
+) -> None:
+    fake_session(result=None)
+
+    response = await client.get("/api/v1/recommendations/404")
+
+    assert response.status_code == 404

apps/backend/tests/api/test_sensors.py

@@ -0,0 +1,91 @@
+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_sensor_service
+from app.core.principal import Principal
+from app.core.roles import AccountKind, Role
+from app.services.sensor import DiagnosticCapteur, EtatCapteurs, SanteCapteurs, SanteSite
+
+TIMESTAMP = datetime(2026, 9, 16, 12, 0, tzinfo=UTC)
+
+
+def principal(role: Role = Role.ADMIN) -> 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:
+        ok = DiagnosticCapteur(status="ok", since=None)
+        en_echec = DiagnosticCapteur(status="failing", since=TIMESTAMP)
+        self.etat = EtatCapteurs(
+            timestamp=TIMESTAMP,
+            sites=[
+                SanteSite(
+                    site_id="SITE001",
+                    site_name="Bureau Paris La Défense",
+                    sensors=SanteCapteurs(
+                        consumption=ok,
+                        electrical=ok,
+                        temperature=en_echec,
+                        humidity=ok,
+                        network=ok,
+                    ),
+                    overall="degraded",
+                )
+            ],
+        )
+
+    async def status(self) -> EtatCapteurs:
+        return self.etat
+
+
+@pytest.fixture
+def admin_connecte(app: FastAPI) -> Iterator[None]:
+    app.dependency_overrides[get_current_principal] = lambda: principal()
+    yield
+    app.dependency_overrides.pop(get_current_principal, None)
+
+
+@pytest.fixture
+def servi(app: FastAPI, admin_connecte: None) -> Iterator[Callable[[], FauxService]]:
+    def installe() -> FauxService:
+        service = FauxService()
+        app.dependency_overrides[get_sensor_service] = lambda: service
+        return service
+
+    yield installe
+    app.dependency_overrides.pop(get_sensor_service, None)
+
+
+async def test_get_status_returns_the_service_result(
+    servi: Callable[[], FauxService], client: AsyncClient
+) -> None:
+    servi()
+
+    response = await client.get("/api/v1/sensors/status")
+
+    assert response.status_code == 200
+    corps = response.json()
+    assert corps["sites"][0]["site_id"] == "SITE001"
+    assert corps["sites"][0]["overall"] == "degraded"
+    assert corps["sites"][0]["sensors"]["temperature"]["status"] == "failing"
+    assert corps["sites"][0]["sensors"]["consumption"]["status"] == "ok"
+
+
+async def test_get_status_refuses_a_reader(app: FastAPI, client: AsyncClient) -> None:
+    app.dependency_overrides[get_current_principal] = lambda: principal(Role.LECTEUR)
+
+    response = await client.get("/api/v1/sensors/status")
+
+    assert response.status_code == 403

apps/backend/tests/api/test_stats.py

@@ -0,0 +1,73 @@
+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"

apps/backend/tests/repositories/test_alert.py

@@ -0,0 +1,91 @@
+import uuid
+from datetime import UTC, datetime
+
+import pytest
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.energy import Alert
+from app.repositories.alert import AlertRepository
+from app.schemas.alert import AlertSeverity
+from tests.repositories.test_site import creer as creer_site
+from tests.repositories.test_site import identifiant as identifiant_site
+
+pytestmark = pytest.mark.integration
+
+
+async def creer_alerte(session: AsyncSession, *, site_id: str, **overrides: object) -> Alert:
+    alerte = Alert(
+        source_alert_id=overrides.get("source_alert_id", f"ALR-{uuid.uuid4().hex[:12]}"),
+        site_id=site_id,
+        source=overrides.get("source", "enervision"),
+        timestamp=overrides.get("timestamp", datetime(2026, 9, 16, tzinfo=UTC)),
+        type=overrides.get("type", "threshold"),
+        severity=overrides.get("severity", "high"),
+        message=overrides.get("message", "Dépassement du seuil configuré"),
+        value=overrides.get("value", 812.5),
+        threshold=overrides.get("threshold", 720.0),
+        metric=overrides.get("metric", "consumption_kw"),
+        prediction_id=overrides.get("prediction_id"),
+        raw_data=overrides.get("raw_data", {}),
+    )
+    session.add(alerte)
+    await session.flush()
+    return alerte
+
+
+async def test_list_all_returns_the_alerts_sorted_by_timestamp_descending(
+    session: AsyncSession,
+) -> None:
+    site = await creer_site(session)
+    depot = AlertRepository(session)
+    ancienne = await creer_alerte(
+        session, site_id=site.site_id, timestamp=datetime(2026, 9, 1, tzinfo=UTC)
+    )
+    recente = await creer_alerte(
+        session, site_id=site.site_id, timestamp=datetime(2026, 9, 15, tzinfo=UTC)
+    )
+
+    alertes = await depot.list_all()
+    identifiants = [
+        a.alert_id for a in alertes if a.alert_id in (ancienne.alert_id, recente.alert_id)
+    ]
+    await session.rollback()
+
+    assert identifiants == [recente.alert_id, ancienne.alert_id]
+
+
+async def test_list_all_filters_by_site_id(session: AsyncSession) -> None:
+    premier = await creer_site(session)
+    second = await creer_site(session)
+    depot = AlertRepository(session)
+    voulue = await creer_alerte(session, site_id=premier.site_id)
+    await creer_alerte(session, site_id=second.site_id)
+
+    alertes = await depot.list_all(site_id=premier.site_id)
+    identifiants = [a.alert_id for a in alertes]
+    await session.rollback()
+
+    assert identifiants == [voulue.alert_id]
+
+
+async def test_list_all_filters_by_severity(session: AsyncSession) -> None:
+    site = await creer_site(session)
+    depot = AlertRepository(session)
+    voulue = await creer_alerte(session, site_id=site.site_id, severity="critical")
+    await creer_alerte(session, site_id=site.site_id, severity="low")
+
+    alertes = await depot.list_all(severity=AlertSeverity.CRITICAL)
+    identifiants = [a.alert_id for a in alertes]
+    await session.rollback()
+
+    assert identifiants == [voulue.alert_id]
+
+
+async def test_list_all_returns_an_empty_list_when_there_is_nothing(
+    session: AsyncSession,
+) -> None:
+    depot = AlertRepository(session)
+
+    alertes = await depot.list_all(site_id=identifiant_site())
+
+    assert list(alertes) == []

apps/backend/tests/repositories/test_reading.py

@@ -0,0 +1,72 @@
+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}

apps/backend/tests/repositories/test_recommendation.py

@@ -0,0 +1,85 @@
+import uuid
+from datetime import UTC, datetime
+
+import pytest
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.energy import Alert, Recommendation, Site
+from app.repositories.recommendation import RecommendationRepository
+
+pytestmark = pytest.mark.integration
+
+MOMENT = datetime(2024, 1, 1, tzinfo=UTC)
+
+
+async def creer_site(session: AsyncSession) -> str:
+    site_id = f"TEST-{uuid.uuid4()}"
+    session.add(Site(site_id=site_id, site_name="Site de test", site_type="office"))
+    await session.flush()
+    return site_id
+
+
+async def creer_alerte(session: AsyncSession) -> int:
+    site_id = await creer_site(session)
+    alerte = Alert(
+        source_alert_id=str(uuid.uuid4()),
+        site_id=site_id,
+        source="api_mock",
+        timestamp=MOMENT,
+        type="spike",
+        severity="high",
+        message="Test",
+        raw_data={},
+    )
+    session.add(alerte)
+    await session.flush()
+    return alerte.alert_id
+
+
+async def creer(session: AsyncSession, **overrides: object) -> Recommendation:
+    recommendation = Recommendation(
+        alert_id=overrides.get("alert_id") or await creer_alerte(session),
+        action=overrides.get("action", "Vérifier la consommation"),
+        explanation=overrides.get("explanation", "Pic détecté"),
+        rule_reference=overrides.get("rule_reference", f"spike-{uuid.uuid4().hex[:8]}"),
+    )
+    session.add(recommendation)
+    await session.flush()
+    return recommendation
+
+
+async def test_get_by_id_returns_the_matching_recommendation(session: AsyncSession) -> None:
+    depot = RecommendationRepository(session)
+    cree = await creer(session)
+
+    trouve = await depot.get_by_id(cree.recommendation_id)
+    action = trouve.action if trouve else None
+    await session.rollback()
+
+    assert action == "Vérifier la consommation"
+
+
+async def test_get_by_id_returns_nothing_for_an_unknown_identifier(
+    session: AsyncSession,
+) -> None:
+    trouve = await RecommendationRepository(session).get_by_id(0)
+
+    assert trouve is None
+
+
+async def test_list_all_returns_the_recommendations_sorted_by_identifier(
+    session: AsyncSession,
+) -> None:
+    depot = RecommendationRepository(session)
+    premiere = await creer(session)
+    seconde = await creer(session)
+
+    recommendations = await depot.list_all()
+    identifiants = [
+        r.recommendation_id
+        for r in recommendations
+        if r.recommendation_id in (premiere.recommendation_id, seconde.recommendation_id)
+    ]
+    await session.rollback()
+
+    assert identifiants == sorted(identifiants)

apps/backend/tests/services/test_alert.py

@@ -0,0 +1,55 @@
+from datetime import UTC, datetime
+
+from app.models.energy import Alert
+from app.services.alert import AlertService
+
+
+def alert(
+    alert_id: int = 1,
+    site_id: str = "site-1",
+    severity: str = "high",
+) -> Alert:
+    return Alert(
+        alert_id=alert_id,
+        source_alert_id=f"ALR-{alert_id}",
+        site_id=site_id,
+        source="enervision",
+        timestamp=datetime(2026, 9, 16, tzinfo=UTC),
+        type="threshold",
+        severity=severity,
+        message="Dépassement du seuil configuré",
+        value=812.5,
+        threshold=720.0,
+        metric="consumption_kw",
+        prediction_id=None,
+        raw_data={},
+    )
+
+
+class FakeRepository:
+    def __init__(self, alerts: list[Alert]) -> None:
+        self._alerts = alerts
+        self.appels: list[tuple[str | None, str | None]] = []
+
+    async def list_all(
+        self, *, site_id: str | None = None, severity: str | None = None
+    ) -> list[Alert]:
+        self.appels.append((site_id, severity))
+        return self._alerts
+
+
+async def test_list_all_returns_the_repository_alerts() -> None:
+    service = AlertService(alerts=FakeRepository([alert(1), alert(2)]))
+
+    alertes = await service.list_all()
+
+    assert [a.alert_id for a in alertes] == [1, 2]
+
+
+async def test_list_all_relays_the_filters_to_the_repository() -> None:
+    depot = FakeRepository([])
+    service = AlertService(alerts=depot)
+
+    await service.list_all(site_id="site-1", severity="critical")
+
+    assert depot.appels == [("site-1", "critical")]

apps/backend/tests/services/test_recommendation.py

@@ -0,0 +1,55 @@
+from datetime import UTC, datetime
+
+import pytest
+
+from app.models.energy import Recommendation
+from app.services.recommendation import RecommendationNotFoundError, RecommendationService
+
+
+def recommendation(recommendation_id: int = 1) -> Recommendation:
+    return Recommendation(
+        recommendation_id=recommendation_id,
+        alert_id=1,
+        action="Vérifier la consommation",
+        explanation="Pic détecté",
+        rule_reference="spike-v1",
+        created_at=datetime(2024, 1, 1, tzinfo=UTC),
+    )
+
+
+class FakeRepository:
+    def __init__(self, recommendations: list[Recommendation]) -> None:
+        self._recommendations = recommendations
+
+    async def list_all(self) -> list[Recommendation]:
+        return self._recommendations
+
+    async def get_by_id(self, recommendation_id: int) -> Recommendation | None:
+        return next(
+            (r for r in self._recommendations if r.recommendation_id == recommendation_id), None
+        )
+
+
+async def test_list_all_returns_the_repository_recommendations() -> None:
+    service = RecommendationService(
+        recommendations=FakeRepository([recommendation(1), recommendation(2)])
+    )
+
+    recommendations = await service.list_all()
+
+    assert [r.recommendation_id for r in recommendations] == [1, 2]
+
+
+async def test_get_by_id_returns_the_matching_recommendation() -> None:
+    service = RecommendationService(recommendations=FakeRepository([recommendation(1)]))
+
+    trouve = await service.get_by_id(1)
+
+    assert trouve.recommendation_id == 1
+
+
+async def test_get_by_id_raises_when_the_recommendation_is_unknown() -> None:
+    service = RecommendationService(recommendations=FakeRepository([]))
+
+    with pytest.raises(RecommendationNotFoundError):
+        await service.get_by_id(404)

apps/backend/tests/services/test_sensor.py

@@ -0,0 +1,224 @@
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+
+from app.services.sensor import SensorService
+
+TIMESTAMP = datetime(2026, 9, 16, 12, 0, tzinfo=UTC)
+
+
+@dataclass
+class FauxSite:
+    site_id: str
+    site_name: str
+
+
+@dataclass
+class FauxLecture:
+    site_id: str
+    timestamp: datetime
+    data_quality: str | None
+    null_reasons: list[str] | None = field(default_factory=list)
+    consumption_kw: float | None = 10.0
+    voltage_v: float | None = 230.0
+    current_a: float | None = 5.0
+    power_factor: float | None = 0.95
+    temperature_celsius: float | None = 21.0
+    humidity_percent: float | None = 40.0
+
+
+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_status_marks_a_site_without_any_reading_as_critical_with_every_sensor_failing() -> (
+    None
+):
+    service = SensorService(
+        sites=FauxDepotSites([FauxSite("A", "Site A")]),  # type: ignore[arg-type]
+        readings=FauxDepotLectures([]),  # type: ignore[arg-type]
+    )
+
+    etat = await service.status()
+
+    site = etat.sites[0]
+    assert site.overall == "critical"
+    for capteur in (
+        site.sensors.consumption,
+        site.sensors.electrical,
+        site.sensors.temperature,
+        site.sensors.humidity,
+        site.sensors.network,
+    ):
+        assert capteur.status == "failing"
+        assert capteur.since is None
+
+
+async def test_status_marks_every_sensor_ok_on_a_good_quality_reading_with_no_null_field() -> None:
+    service = SensorService(
+        sites=FauxDepotSites([FauxSite("A", "Site A")]),  # type: ignore[arg-type]
+        readings=FauxDepotLectures([FauxLecture("A", TIMESTAMP, "good")]),  # type: ignore[arg-type]
+    )
+
+    etat = await service.status()
+
+    site = etat.sites[0]
+    assert site.overall == "ok"
+    for capteur in (
+        site.sensors.consumption,
+        site.sensors.electrical,
+        site.sensors.temperature,
+        site.sensors.humidity,
+        site.sensors.network,
+    ):
+        assert capteur.status == "ok"
+        assert capteur.since is None
+
+
+async def test_status_flags_the_sensor_named_in_null_reasons() -> None:
+    service = SensorService(
+        sites=FauxDepotSites([FauxSite("A", "Site A")]),  # type: ignore[arg-type]
+        readings=FauxDepotLectures(  # type: ignore[arg-type]
+            [
+                FauxLecture(
+                    "A",
+                    TIMESTAMP,
+                    "partial",
+                    null_reasons=["temperature_sensor_failure"],
+                    temperature_celsius=None,
+                )
+            ]
+        ),
+    )
+
+    etat = await service.status()
+
+    site = etat.sites[0]
+    assert site.overall == "degraded"
+    assert site.sensors.temperature.status == "failing"
+    assert site.sensors.temperature.since == TIMESTAMP
+    assert site.sensors.consumption.status == "ok"
+    assert site.sensors.electrical.status == "ok"
+    assert site.sensors.humidity.status == "ok"
+    assert site.sensors.network.status == "ok"
+
+
+async def test_status_flags_a_sensor_from_a_null_field_even_without_a_null_reason() -> None:
+    service = SensorService(
+        sites=FauxDepotSites([FauxSite("A", "Site A")]),  # type: ignore[arg-type]
+        readings=FauxDepotLectures(  # type: ignore[arg-type]
+            [FauxLecture("A", TIMESTAMP, "partial", null_reasons=[], humidity_percent=None)]
+        ),
+    )
+
+    etat = await service.status()
+
+    site = etat.sites[0]
+    assert site.sensors.humidity.status == "failing"
+    assert site.sensors.humidity.since == TIMESTAMP
+
+
+async def test_status_flags_electrical_as_failing_when_any_of_its_three_fields_is_null() -> None:
+    service = SensorService(
+        sites=FauxDepotSites([FauxSite("A", "Site A")]),  # type: ignore[arg-type]
+        readings=FauxDepotLectures(  # type: ignore[arg-type]
+            [FauxLecture("A", TIMESTAMP, "partial", null_reasons=[], power_factor=None)]
+        ),
+    )
+
+    etat = await service.status()
+
+    site = etat.sites[0]
+    assert site.sensors.electrical.status == "failing"
+
+
+async def test_status_forces_every_sensor_to_failing_when_overall_is_critical() -> None:
+    service = SensorService(
+        sites=FauxDepotSites([FauxSite("A", "Site A")]),  # type: ignore[arg-type]
+        readings=FauxDepotLectures([FauxLecture("A", TIMESTAMP, "critical", null_reasons=[])]),  # type: ignore[arg-type]
+    )
+
+    etat = await service.status()
+
+    site = etat.sites[0]
+    assert site.overall == "critical"
+    for capteur in (
+        site.sensors.consumption,
+        site.sensors.electrical,
+        site.sensors.temperature,
+        site.sensors.humidity,
+        site.sensors.network,
+    ):
+        assert capteur.status == "failing"
+        assert capteur.since == TIMESTAMP
+
+
+async def test_status_treats_an_unknown_data_quality_as_critical() -> None:
+    service = SensorService(
+        sites=FauxDepotSites([FauxSite("A", "Site A")]),  # type: ignore[arg-type]
+        readings=FauxDepotLectures([FauxLecture("A", TIMESTAMP, None, null_reasons=[])]),  # type: ignore[arg-type]
+    )
+
+    etat = await service.status()
+
+    assert etat.sites[0].overall == "critical"
+
+
+async def test_status_ignores_an_unknown_null_reason() -> None:
+    service = SensorService(
+        sites=FauxDepotSites([FauxSite("A", "Site A")]),  # type: ignore[arg-type]
+        readings=FauxDepotLectures(  # type: ignore[arg-type]
+            [FauxLecture("A", TIMESTAMP, "good", null_reasons=["something_else"])]
+        ),
+    )
+
+    etat = await service.status()
+
+    site = etat.sites[0]
+    assert site.overall == "ok"
+    for capteur in (
+        site.sensors.consumption,
+        site.sensors.electrical,
+        site.sensors.temperature,
+        site.sensors.humidity,
+        site.sensors.network,
+    ):
+        assert capteur.status == "ok"
+
+
+async def test_status_flags_network_from_null_reasons_only() -> None:
+    service = SensorService(
+        sites=FauxDepotSites([FauxSite("A", "Site A")]),  # type: ignore[arg-type]
+        readings=FauxDepotLectures(  # type: ignore[arg-type]
+            [
+                FauxLecture(
+                    "A",
+                    TIMESTAMP,
+                    "partial",
+                    null_reasons=["network_loss"],
+                )
+            ]
+        ),
+    )
+
+    etat = await service.status()
+
+    site = etat.sites[0]
+    assert site.overall == "degraded"
+    assert site.sensors.network.status == "failing"
+    assert site.sensors.network.since == TIMESTAMP
+    assert site.sensors.consumption.status == "ok"
+    assert site.sensors.electrical.status == "ok"
+    assert site.sensors.temperature.status == "ok"
+    assert site.sensors.humidity.status == "ok"

apps/backend/tests/services/test_stats.py

@@ -0,0 +1,107 @@
+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

docs/architecture/00-vue-ensemble.md

@@ -74,7 +74,7 @@ collecteur ne vient le lire.
 
 | Domaine | Technologie | Emplacement | Statut | Ce qui existe réellement |
 |---|---|---|---|---|
-| Backend | FastAPI, Python 3.14 | `apps/backend` | `En cours` | Factory, configuration, journalisation, 2 sondes de santé, `/metrics`, `GET /sites` et `GET /sites/{site_id}` (première couche métier, endpoints → services → repositories → models) |
+| Backend | FastAPI, Python 3.14 | `apps/backend` | `En cours` | Factory, configuration, journalisation, 2 sondes de santé, `/metrics`, contrat OpenAPI versionné, routes `sites` et `recommendations` en lecture (endpoints → services → repositories → models) |
 | Frontend | Angular 22, Node 24 | `apps/frontend` | `En cours` | Tableau de bord sur route `/dashboard`, deux services HTTP, graphiques Chart.js, données servies par des fixtures |
 | Base | PostgreSQL 17 + TimescaleDB | `db` | `Fait` | Bootstrap de l'extension, base de test, chaîne Alembic. Schéma applicatif créé (`site`, `dataset`, `reading` en hypertable, `prediction`, `alert`, `recommendation`) |
 | Infra | Terraform, k3s single-node | `infra/terraform` | `En cours` | Module d'installation du cluster. Jamais appliqué, aucune ressource Kubernetes déclarée |

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, alerts,<br/>recommendations, stats, sensors"]
   sc["schemas<br/>Pydantic"]
-  sv["services<br/>AuthService, UserService,<br/>SiteService"]
+  sv["services<br/>AuthService, UserService,<br/>SiteService, AlertService, RecommendationService,<br/>StatsService, SensorService"]
-  rp["repositories<br/>user, refresh_token,<br/>login_attempt, audit_log,<br/>site"]
+  rp["repositories<br/>user, refresh_token,<br/>login_attempt, audit_log,<br/>site, alert, recommendation, reading"]
   md["models<br/>10 tables"]
   db[("PostgreSQL")]
 
@@ -142,6 +142,11 @@ 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/alerts` | Liste les alertes, filtrable par `site_id` et `severity`. `lecteur` | 401, 403, 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 | `/api/v1/sensors/status` | État de santé des capteurs par site, dérivé de la dernière lecture. `admin` | 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` | |
 
@@ -153,14 +158,20 @@ Les codes de la dernière colonne sont ceux que le schéma **déclare**, et le f
 échoue si l'une d'elles répond autre chose qu'un 401 ou un 403. Rendre une route publique impose
 donc de modifier la liste dans ce fichier de test.
 
-`GET /sites` et `GET /sites/{site_id}` sont la première route métier, et le gabarit à réutiliser
+`GET /sites` et `GET /sites/{site_id}` sont la première route métier, et le gabarit repris pour
-pour les suivantes (`reading`, `dataset`, `prediction`, `alert`, `recommendation`) : les quatre
+`GET /alerts` puis pour les suivantes (`reading`, `dataset`, `prediction`, `recommendation`) : les
-couches `endpoints → services → repositories → models` y sont toutes présentes, sur des tables
+quatre couches `endpoints → services → repositories → models` y sont toutes présentes, sur des
-déjà créées par la révision Alembic `e6d2026091501`. Elles n'exigent que le rôle `lecteur`,
+tables déjà créées par la révision Alembic `e6d2026091501`. Elles n'exigent que le rôle `lecteur`,
 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. Le contrat détaillé pour le frontend est dans
+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. `GET /stats/summary` et `GET /sensors/status` agrègent chacune deux repositories
+(`SiteRepository`, `ReadingRepository`) dans un service dédié plutôt que d'exposer une table :
+elles n'entrent 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`
@@ -235,6 +246,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`/`alerts`/`recommendations`/`stats`/
+`sensors` (`reading`, `dataset`, `prediction`) :
+
+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/owasp-traceabilite.md

@@ -9,8 +9,8 @@ Ce qui est défendable, c'est une ligne par contrôle réellement implémenté,
 et une section qui dit ce qui n'est pas couvert et pourquoi.
 
 Statut : `Fait` pour le périmètre authentification et autorisation. `GET /sites` et
-`GET /sites/{site_id}` sont les premiers endpoints métier, en lecture seule ; plusieurs lignes
+`GET /recommendations`, chacune avec sa route de détail, sont les premiers endpoints métier, en
-resteront à compléter une fois les endpoints d'écriture posés.
+lecture seule ; plusieurs lignes resteront à compléter une fois les endpoints d'écriture posés.
 
 ## Contrôles en place
 
@@ -49,7 +49,7 @@ règles Bandit. Ajouter Bandit à la CI serait redondant, contrairement à ce qu
 
 | Item | État | Raison |
 |---|---|---|
-| **API1 Broken Object Level Authorization** | **ouvert** | Les rôles sont globaux, il n'y a pas de portée par site : `GET /sites/{site_id}` répond à tout compte `lecteur` pour n'importe quel site, sans vérifier une affectation compte-site qui n'existe pas encore. Un opérateur du site A pourra agir sur le site B dès que les endpoints d'écriture métier existeront. Correctif prévu : table d'affectation compte-site, contrôle d'appartenance dans la même dépendance que le contrôle de rôle. |
+| **API1 Broken Object Level Authorization** | **ouvert** | Les rôles sont globaux, il n'y a pas de portée par site : `GET /sites/{site_id}` et `GET /recommendations/{recommendation_id}` répondent à tout compte `lecteur` pour n'importe quel site ou recommandation, sans vérifier une affectation compte-site qui n'existe pas encore. Un opérateur du site A pourra agir sur le site B dès que les endpoints d'écriture métier existeront. Correctif prévu : table d'affectation compte-site, contrôle d'appartenance dans la même dépendance que le contrôle de rôle. |
 | **API4, lectures de séries temporelles** | **ouvert** | Pas encore d'endpoint métier, donc ni pagination plafonnée, ni fenêtre temporelle maximale, ni `statement_timeout`. C'est la façon la plus probable dont la démonstration tombera : une requête sur dix ans d'historique suffit. |
 | **API8 Security Misconfiguration, transport** | **ouvert** | Pas de TLS, donc ni HSTS, ni cookie `Secure` réellement posé en production. Ils appartiennent au terminateur TLS, qui n'existe pas. |
 | **API10 Unsafe Consumption of APIs** | **ouvert, et spécifique à ce projet** | L'API Mock de l'école n'a aucune authentification, tourne en HTTP clair sur le réseau de l'école, et expose un endpoint mutatif à quiconque. Sa réponse doit être traitée comme une entrée hostile : bornes physiques, taille de tableau plafonnée, timeout, et frontière d'anti-corruption. La conséquence la plus sérieuse n'est pas la fausse alerte, c'est l'empoisonnement du jeu d'entraînement du modèle de prédiction. |