Initial plan

Definition des jalons
2026-09-15 14:50:42 +00:00 · 2026-09-14 11:30:01 +02:00
337 changed files with 8 additions and 35739 deletions
@@ -1,27 +0,0 @@
 # Dépendances (réinstallées dans l'image)
 node_modules/
 vendor/
 __pycache__/
 *.pyc
 # Git et IDE
 .git/
 .gitignore
 .vscode/
 .idea/
 *.swp
 # Fichiers de build locaux
 dist/
 build/
 *.log
 # Secrets et config locale (CRITIQUE : risque d'exfiltration)
 .env
 .env.local
 *.pem
 *.key
 secrets/
 .npmrc
 .pypirc
 kubeconfig
@@ -1,22 +0,0 @@
 root = true
 [*]
 charset = utf-8
 end_of_line = lf
 insert_final_newline = true
 trim_trailing_whitespace = true
 indent_style = space
 indent_size = 2
 [*.py]
 indent_size = 4
 max_line_length = 100
 [*.{tf,tfvars}]
 indent_size = 2
 [Makefile]
 indent_style = tab
 [*.md]
 trim_trailing_whitespace = false
@@ -1,19 +0,0 @@
 # Variables lues par docker-compose.yml à la racine.
 # Le backend lancé hors conteneur (`make dev`) lit apps/backend/.env, pas ce fichier.
 POSTGRES_USER=enervision
 POSTGRES_PASSWORD=change_me
 POSTGRES_DB=enervision
 # 5432 est souvent déjà pris par une autre base du poste.
 POSTGRES_PORT=5433
 # `basic` renvoie des statistiques d'usage à Timescale.
 TIMESCALEDB_TELEMETRY=off
 APP_ENV=local
 APP_DEBUG=false
 APP_LOG_LEVEL=INFO
 # L'API refuse de démarrer tant que cette valeur reste un exemple ou fait moins de
 # 32 caractères. Générer la vôtre : python -c "import secrets; print(secrets.token_urlsafe(48))"
 APP_SECRET_KEY=change_me
 APP_CORS_ORIGINS=http://localhost:4200
 BACKEND_PORT=8000
@@ -1,40 +0,0 @@
 version: 2
 updates:
  # Frontend — npm
  - package-ecosystem: "npm"
    directory: "/apps/frontend"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 5
    groups:
      frontend-dependencies:
        patterns:
          - "*"
  # Backend — uv (lit pyproject.toml / uv.lock)
  - package-ecosystem: "uv"
    directory: "/apps/backend"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 5
    groups:
      backend-dependencies:
        patterns:
          - "*"
  # Les workflows GitHub Actions eux-mêmes ont aussi des dépendances à jour
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
  # Si un Dockerfile existe pour le backend
  - package-ecosystem: "docker"
    directory: "/apps/backend"
    schedule:
      interval: "weekly"
  - package-ecosystem: "docker"
    directory: "/apps/frontend"
    schedule:
      interval: "weekly"
@@ -1,58 +0,0 @@
 name: Backend
 # Piège : la version de Python vient de apps/backend/.python-version, et elle doit rester
 # en 3.14. Le code utilise le PEP 758, qu'un interpréteur 3.13 refuse de compiler.
 on:
  push:
    paths:
      - "apps/backend/**"
      - ".github/workflows/backend.yml"
  pull_request:
    paths:
      - "apps/backend/**"
      - ".github/workflows/backend.yml"
 permissions:
  contents: read
 concurrency:
  group: backend-${{ github.ref }}
  cancel-in-progress: true
 jobs:
  verification:
    name: Lint, typage et tests
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: apps/backend
    steps:
      - name: Récupère le dépôt
        uses: actions/checkout@v4
      - name: Installe uv
        uses: astral-sh/setup-uv@v5
        with:
          enable-cache: true
          cache-dependency-glob: apps/backend/uv.lock
      - name: Installe l'interpréteur déclaré par .python-version
        run: uv python install
      - name: Synchronise les dépendances sans dévier du verrou
        run: uv sync --all-groups --frozen
      - name: Vérifie le formatage
        run: uv run ruff format --check .
      - name: Analyse statique
        run: uv run ruff check --output-format=github .
      - name: Typage
        run: uv run mypy app
      # Le marqueur `integration` est exclu par défaut, donc aucune base n'est nécessaire ici.
      - name: Tests et couverture
        run: uv run pytest --cov-fail-under=85
@@ -1,77 +0,0 @@
 name: Frontend
 # Pipeline à choix multiple
 on:
  # workflow_dispatch -> lancement manuel des jobs
  workflow_dispatch:
    inputs:
      job_choice:
        required: true
        description: "Choix du job"
        type: choice
        default: all
        options:
            - build
            - sonarqube
            - test
            - all # lancer tous les jobs
  push:
    paths:
      - "apps/frontend/**"
      - ".github/workflows/frontend.yml"
  pull_request:
    paths:
      - "apps/frontend/**"
      - ".github/workflows/frontend.yml"
 # Ordre de lancement des jobs
 # build -> test -> sonarqube -> deploy
 jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm
          cache-dependency-path: apps/frontend/package-lock.json
      - run: npm ci 
        working-directory: apps/frontend
      - run: npm run build
        working-directory: apps/frontend
  test:  
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm
          cache-dependency-path: apps/frontend/package-lock.json
      - run: npm ci 
        working-directory: apps/frontend
      - run: npm test -- --watch=false
        working-directory: apps/frontend
  sonarqube:
    needs: [build, test]
    name: SonarQube
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          fetch-depth: 0  # Shallow clones should be disabled for a better relevancy of analysis
      - name: SonarQube Scan
        uses: SonarSource/sonarqube-scan-action@7006c4492b2e0ee0f816d36501671557c97f5995 # v8.1.0
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
  # deploy:
  #   runs-on: ubuntu-latest
  #   steps:
  #   - run: echo "DEPLOY job is running"
@@ -1,59 +0,0 @@
 name: ML
 # Piège : la version de Python vient de ml/.python-version, et doit rester en 3.14 (cf.
 # .github/workflows/backend.yml, même contrainte).
 on:
  push:
    paths:
      - "ml/**"
      - ".github/workflows/ml.yml"
  pull_request:
    paths:
      - "ml/**"
      - ".github/workflows/ml.yml"
 permissions:
  contents: read
 concurrency:
  group: ml-${{ github.ref }}
  cancel-in-progress: true
 jobs:
  verification:
    name: Lint, typage et tests
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: ml
    steps:
      - name: Récupère le dépôt
        uses: actions/checkout@v4
      - name: Installe uv
        uses: astral-sh/setup-uv@v5
        with:
          enable-cache: true
          cache-dependency-glob: ml/uv.lock
      - name: Installe l'interpréteur déclaré par .python-version
        run: uv python install
      - name: Synchronise les dépendances sans dévier du verrou
        run: uv sync --all-groups --frozen
      - name: Vérifie le formatage
        run: uv run ruff format --check .
      - name: Analyse statique
        run: uv run ruff check --output-format=github .
      - name: Typage
        run: uv run mypy enervision_ml tests
      # Aucun test ne touche PostgreSQL ni MLflow distant : tout tourne sur donnees
      # synthetiques ou un magasin SQLite local jetable (cf. ml/tests/test_train.py).
      - name: Tests
        run: uv run pytest
@@ -1,74 +0,0 @@
 # Python
 __pycache__/
 *.py[cod]
 .venv/
 venv/
 .pytest_cache/
 .mypy_cache/
 .ruff_cache/
 .coverage
 coverage.xml
 htmlcov/
 test-results/
 dist/
 build/
 *.egg-info/
 # Node / Angular
 node_modules/
 .angular/
 apps/frontend/dist/
 apps/frontend/.angular/
 npm-debug.log*
 yarn-error.log*
 # Terraform
 .terraform/
 # .terraform.lock.hcl est versionne (pas ignore) pour figer les versions de provider entre contributeurs/CI
 *.tfstate
 *.tfstate.*
 *.tfplan
 crash.log
 override.tf
 override.tf.json
 *_override.tf
 *_override.tf.json
 *.tfvars
 !*.tfvars.example
 kubeconfig
 # Airflow
 etl/airflow/logs/
 airflow.db
 airflow-webserver.pid
 standalone_admin_password.txt
 # Environnement et secrets
 .env
 .env.*
 !.env.example
 *.pem
 *.key
 secrets/
 # Donnees locales
 data/raw/*
 !data/raw/.gitkeep
 *.sqlite3
 monitoring/grafana/data/
 monitoring/prometheus/data/
 # ML : jeu de donnees, modeles entraines et suivi MLflow local, tous generes/volumineux
 ml/data/
 ml/models/*
 !ml/models/.gitkeep
 ml/mlruns/
 ml/mlartifacts/
 ml/mlflow.db
 # IDE et OS
 .idea/
 .vscode/
 *.swp
 .DS_Store
 Thumbs.db
@@ -1,99 +0,0 @@
 BACKEND := apps/backend
 FRONTEND := apps/frontend
 ML := ml
 .DEFAULT_GOAL := help
 .PHONY: help install install-backend install-frontend install-ml dev dev-backend dev-frontend \
        lint format typecheck test test-cov test-integration check \
        openapi docker-build db-up db-down db-reset db-logs db-psql migrate bootstrap-admin \
        ml-lint ml-typecheck ml-test ml-check ml-train
 help: ## Liste les cibles disponibles
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-16s\033[0m %s\n", $$1, $$2}'
 install: install-backend install-frontend install-ml ## Installe les dépendances backend, frontend et ML
 install-backend: ## Installe les dépendances du backend
 	cd $(BACKEND) && uv sync --all-groups
 install-frontend: ## Installe les dépendances du frontend
 	cd $(FRONTEND) && npm ci
 install-ml: ## Installe les dépendances du pipeline ML
 	cd $(ML) && uv sync --all-groups
 dev: ## Lance toute la stack (backend + frontend) en rechargement à chaud
 	@trap 'kill 0' EXIT INT TERM; \
 	$(MAKE) --no-print-directory dev-backend & \
 	$(MAKE) --no-print-directory dev-frontend & \
 	wait
 dev-backend: ## Lance l'API seule en rechargement à chaud
 	@echo "backend  -> http://localhost:8000 (docs sur /docs)"
 	cd $(BACKEND) && uv run uvicorn app.main:create_app --factory --reload --host 0.0.0.0 --port 8000
 dev-frontend: ## Lance le frontend seul en rechargement à chaud
 	@echo "frontend -> http://localhost:4200"
 	cd $(FRONTEND) && npm start
 lint: ## Analyse statique du backend
 	cd $(BACKEND) && uv run ruff check .
 format: ## Formate et corrige le backend
 	cd $(BACKEND) && uv run ruff format . && uv run ruff check --fix .
 typecheck: ## Vérifie le typage du backend
 	cd $(BACKEND) && uv run mypy app
 test: ## Exécute les tests backend ne demandant pas de base
 	cd $(BACKEND) && uv run pytest --cov-fail-under=85
 test-cov: ## Rapports de couverture HTML et XML, plus les résultats au format JUnit
 	cd $(BACKEND) && uv run pytest --cov-fail-under=85 --cov-report=html \
 		--cov-report=xml --junitxml=test-results/junit.xml
 test-integration: ## Exécute les tests exigeant une base joignable
 	cd $(BACKEND) && uv run pytest -m integration
 check: lint typecheck test ## Chaîne de vérification complète
 openapi: ## Régénère apps/backend/openapi.json depuis les routes déclarées
 	cd $(BACKEND) && uv run python -m app.cli export-openapi
 ml-lint: ## Analyse statique du pipeline ML
 	cd $(ML) && uv run ruff check .
 ml-typecheck: ## Vérifie le typage du pipeline ML
 	cd $(ML) && uv run mypy enervision_ml tests
 ml-test: ## Exécute les tests du pipeline ML (donnees synthetiques, sans base ni serveur MLflow)
 	cd $(ML) && uv run pytest
 ml-check: ml-lint ml-typecheck ml-test ## Chaîne de vérification complète du pipeline ML
 ml-train: ## Entraine le modele LightGBM. CSV=chemin optionnel, sinon lit ML_DATABASE_URL
 	cd $(ML) && uv run python -m enervision_ml.train $(if $(CSV),--csv $(CSV),)
 docker-build: ## Construit l'image du backend
 	docker build -t enervision-backend:local $(BACKEND)
 db-up: ## Démarre la base PostgreSQL TimescaleDB
 	docker compose up -d db
 db-down: ## Arrête la base en conservant ses données
 	docker compose stop db
 db-reset: ## Détruit la base et rejoue db/init
 	docker compose down -v && docker compose up -d db
 db-logs: ## Suit les journaux de la base
 	docker compose logs -f db
 db-psql: ## Ouvre une session psql sur la base applicative
 	docker compose exec db psql -U $${POSTGRES_USER:-enervision} -d $${POSTGRES_DB:-enervision}
 migrate: ## Applique les migrations Alembic
 	cd $(BACKEND) && uv run alembic upgrade head
 bootstrap-admin: ## Crée le premier administrateur, mot de passe saisi au clavier
 	cd $(BACKEND) && uv run python -m app.cli create-admin --email $${EMAIL:?EMAIL=... requis}
@@ -1,106 +1,10 @@
 # EnerVision
-Monorepo de la plateforme EnerVision : collecte, stockage, analyse et restitution de
+## Jalons définis
-series temporelles energetiques, deployee sur une machine on-premise.
+J1 - Valider la préparation de l'environnement et du repo
 J2 - Valider le périmètre retenu et les choix technologiques
 J3 - Valider l'architecture et la gestion de la sécurité
 J4 - Valider la robustesse et assurer les livrables
-## Jalons
+## Outil de collaboration utilisé
-
+GitHub
 | Jalon | Intitulé |
 |-------|----------------------------------------------------------|
 | J1    | Valider la préparation de l'environnement et du repo     |
 | J2    | Valider le périmètre retenu et les choix technologiques  |
 | J3    | Valider l'architecture et la gestion de la sécurité      |
 | J4    | Valider la robustesse et assurer les livrables           |
 Ce que la documentation apporte à chacun : [docs/architecture/00-vue-ensemble.md](docs/architecture/00-vue-ensemble.md).
 ## Stack cible
 | Domaine    | Technologie                         | Emplacement         | Etat          |
 |------------|-------------------------------------|---------------------|---------------|
 | Backend    | FastAPI, Python 3.14                | `apps/backend`      | Initialise    |
 | Frontend   | Angular 22, Node 24 LTS             | `apps/frontend`     | Tableau de bord |
 | Base       | PostgreSQL 17 + TimescaleDB         | `db`                | Initialise    |
 | ETL        | Apache Airflow                      | `etl/airflow`       | A initialiser |
 | Infra      | Terraform (k3s single-node)         | `infra/terraform`   | Initialise    |
 | CI/CD      | GitHub Actions                      | `.github/workflows` | Backend en place |
 | Monitoring | Prometheus, Grafana, Alertmanager   | `monitoring`        | A initialiser |
 | ML         | LightGBM, MLflow                    | `ml`                | Entrainement initialise |
 Le backend, la base et l'infrastructure (Terraform/k3s) sont initialises a ce stade. Le frontend
 sert un tableau de bord sur `/dashboard`, dont les données proviennent de fixtures : les endpoints
 correspondants restent à écrire côté API. Les autres dossiers portent l'arborescence et un README
 de cadrage, leur contenu fait l'objet d'un ticket dedie.
 L'etat detaille de chaque brique et les vues d'architecture sont dans
 [docs/architecture](docs/architecture/README.md).
 ## Arborescence
 ```
 .
 ├── apps/
 │   ├── backend/        API FastAPI
 │   └── frontend/       Application Angular
 ├── db/
 │   ├── init/           Bootstrap PostgreSQL + TimescaleDB
 │   ├── migrations/     Migrations SQL versionnees
 │   └── seeds/          Jeux de donnees de reference
 ├── etl/airflow/
 │   ├── dags/           DAGs d'ingestion et d'agregation
 │   ├── plugins/        Operateurs et hooks maison
 │   ├── include/        Requetes SQL et ressources des DAGs
 │   └── tests/          Tests d'integrite des DAGs
 ├── infra/terraform/
 │   ├── modules/        Modules reutilisables
 │   └── environments/   Racines Terraform, une par environnement
 ├── ml/                 Pipeline d'entrainement LightGBM, suivi MLflow
 ├── monitoring/
 │   ├── prometheus/     Collecte et regles d'alerte
 │   ├── grafana/        Provisioning et dashboards
 │   └── alertmanager/   Routage des alertes
 ├── docs/               ADR et vues d'architecture
 └── scripts/            Outillage local
 ```
 ## Demarrage
 Prerequis : uv, Docker, Node 24 LTS (npm fourni). Le poste doit disposer de Python 3.14, que
 `uv` installe seul.
 ```bash
 cp .env.example .env                               # variables de docker-compose
 cp apps/backend/.env.example apps/backend/.env     # variables du backend hors conteneur
 make db-up     # PostgreSQL + TimescaleDB, publie sur le port 5433
 make install   # dependances du backend et du frontend
 make migrate   # applique les migrations Alembic
 make dev       # backend sur http://localhost:8000 (docs sur /docs), frontend sur http://localhost:4200
 make check     # lint + typage + tests
 ```
 `make help` liste les cibles disponibles.
 Deux fichiers d'environnement, deux usages : `.env` a la racine alimente `docker-compose.yml`,
 `apps/backend/.env` alimente le backend lance sur le poste. Le port 5433 est publie plutot que
 5432, souvent deja pris par une autre base.
 La boucle de developpement est `make db-up` puis `make dev` : seule la base tourne en
 conteneur, le backend et le frontend tournent tous les deux sur le poste, lances ensemble par
 `make dev` (logs entrelaces dans le meme terminal, Ctrl+C arrete les deux). `make dev-backend`
 et `make dev-frontend` restent disponibles pour lancer un seul des deux. Le service `backend`
 du `docker-compose.yml` sert la stack complete et la recette, et n'embarque pas le source, donc
 toute modification y demande un `docker compose up -d --build backend`.
 Verifier que la base repond et que l'extension est chargee :
 ```bash
 curl -s localhost:8000/api/v1/health/ready
 ```
 ## Conventions
 - Branches : `feat/`, `fix/`, `chore/`, `docs/`, `test/` suivi d'un libelle court.
 - Commits : Conventional Commits, portee = dossier de premier niveau concerne.
 - Toute decision structurante donne lieu a un ADR dans `docs/adr`.
 - Toute PR qui change un composant met a jour sa vue dans `docs/architecture`, dans la meme PR.
@@ -1,16 +0,0 @@
 .venv/
 __pycache__/
 *.py[cod]
 .pytest_cache/
 .mypy_cache/
 .ruff_cache/
 .coverage
 coverage.xml
 htmlcov/
 .env
 .env.*
 !.env.example
 tests/
 Dockerfile
 .dockerignore
 README.md
@@ -1,20 +0,0 @@
 APP_ENV=local
 APP_DEBUG=false
 APP_LOG_LEVEL=INFO
 # L'API refuse de démarrer tant que cette valeur reste un exemple ou fait moins de
 # 32 caractères. Générer la vôtre : python -c "import secrets; print(secrets.token_urlsafe(48))"
 APP_SECRET_KEY=change_me
 APP_CORS_ORIGINS=http://localhost:4200
 DATABASE_URL=postgresql+asyncpg://enervision:change_me@localhost:5433/enervision
 # Mot de passe oublié : lien à usage unique valable 15 minutes par défaut.
 APP_FRONTEND_RESET_PASSWORD_URL=http://localhost:4200/reset-password
 # SMTP local de dev (Mailpit, cf. docker-compose.yml) : aucune authentification, aucun TLS.
 # À remplacer par un vrai relais en staging/prod.
 APP_SMTP_HOST=localhost
 APP_SMTP_PORT=1025
 APP_SMTP_USE_TLS=false
 APP_SMTP_FROM_ADDRESS=no-reply@enervision.fr
@@ -1 +0,0 @@
 3.14
@@ -1,42 +0,0 @@
 FROM python:3.14-slim AS builder
 COPY --from=ghcr.io/astral-sh/uv:0.11.26 /uv /uvx /bin/
 ENV UV_COMPILE_BYTECODE=1 \
    UV_LINK_MODE=copy \
    UV_PYTHON_DOWNLOADS=never
 WORKDIR /app
 RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=bind,source=uv.lock,target=uv.lock \
    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
    uv sync --locked --no-install-project --no-dev
 COPY . /app
 RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --locked --no-dev
 FROM python:3.14-slim AS runtime
 RUN groupadd --system --gid 1001 app \
    && useradd --system --uid 1001 --gid app --create-home app
 ENV PATH="/app/.venv/bin:${PATH}" \
    PYTHONUNBUFFERED=1 \
    PYTHONDONTWRITEBYTECODE=1
 WORKDIR /app
 COPY --from=builder --chown=app:app /app /app
 USER app
 EXPOSE 8000
 HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
    CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/api/v1/health/live')"
 CMD ["uvicorn", "app.main:create_app", "--factory", "--host", "0.0.0.0", "--port", "8000"]
@@ -1,158 +0,0 @@
 # Backend EnerVision
 API FastAPI exposant les series temporelles energetiques.
 | Element     | Choix                                      |
 |-------------|--------------------------------------------|
 | Python      | 3.14                                       |
 | Gestionnaire| uv (`uv.lock` fait foi)                    |
 | Framework   | FastAPI + Uvicorn                          |
 | Persistance | SQLAlchemy 2 async + asyncpg + Alembic     |
 | Lint/format | ruff                                       |
 | Typage      | mypy en mode strict                        |
 | Tests       | pytest + pytest-asyncio + httpx            |
 ## Installation
 ```bash
 cp .env.example .env
 uv sync --all-groups
 ```
 `APP_SECRET_KEY` et `DATABASE_URL` n'ont pas de valeur par defaut : l'application refuse
 de demarrer sans elles.
 `DATABASE_URL` pointe sur `localhost:5433`, le port publie par le service `db` du
 `docker-compose.yml` racine. Demarrer la base depuis la racine avec `make db-up`.
 ## Commandes
 Depuis la racine du monorepo, via le `Makefile` : `make install`, `make dev`, `make lint`,
 `make format`, `make typecheck`, `make test`, `make check`, `make openapi`, `make docker-build`.
 Directement depuis ce dossier :
 ```bash
 uv run uvicorn app.main:create_app --factory --reload --port 8000
 uv run ruff check .          # lint
 uv run ruff format .         # format
 uv run mypy app              # typage strict
 uv run pytest                # tests + couverture
 uv run pytest -m integration # tests exigeant une base joignable
 uv run python -m app.cli export-openapi   # régénère openapi.json
 ```
 `openapi.json` est versionné : `tests/api/test_openapi.py` échoue si le fichier ne correspond
 plus aux routes déclarées. Toute PR qui change une route le régénère dans le même commit.
 Les conventions de tests, les gabarits et le detail des marqueurs sont dans
 [`TESTING.md`](TESTING.md).
 `pytest` ecarte par defaut les tests marques `integration`, pour que `make check` reste
 jouable sans Docker. Ces tests visent la base `enervision_test`, creee par
 `db/init/110-test-database.sql` au premier demarrage du conteneur.
 L'application est exposee par une factory (`create_app`) et non par un objet module :
 aucune configuration n'est lue a l'import, ce qui rend les tests et les migrations
 independants de l'environnement.
 ## Structure
 ```
 app/
 ├── api/
 │   ├── deps.py          Dépendances partagées : session, settings, principal, gardes de rôle
 │   ├── errors.py        Gestionnaires 422 et 500
 │   ├── middleware.py    En-têtes de sécurité
 │   ├── security.py      Garde du point /metrics
 │   └── v1/
 │       ├── router.py    Agrégation des routes de la version 1
 │       └── endpoints/   Un module par ressource exposée
 ├── core/
 │   ├── config.py        Settings Pydantic, source unique de configuration
 │   ├── cookies.py       Attributs du cookie de rafraîchissement
 │   ├── hashing.py       Argon2id, poussé dans un fil sous limiteur
 │   ├── logging.py       Journalisation console en local, JSON en production
 │   ├── principal.py     L'identité que voit le code métier
 │   ├── roles.py         Rôles ordonnés
 │   └── security.py      Encodage et décodage des jetons d'accès
 ├── db/
 │   ├── base.py          Base declarative SQLAlchemy
 │   └── session.py       Engine et sessions asynchrones
 ├── models/              Modeles SQLAlchemy
 ├── schemas/             Modeles Pydantic d'entree et de sortie
 ├── repositories/        Acces aux donnees, une classe par agregat
 ├── services/            Regles metier, orchestrent les repositories
 ├── cli.py               Commandes hors HTTP, dont l'amorcage du premier admin
 └── main.py              Factory applicative
 tests/                   Miroir de app/
 alembic/                 Migrations du schema applicatif
 ```
 Le sens de dependance est unique : `endpoints` vers `services` vers `repositories` vers
 `models`. Un endpoint ne touche jamais une session directement.
 ## Routes
 | Route | Rôle | Accès |
 |---|---|---|
 | `/api/v1/health/live` | Sonde de vivacité, aucune dépendance externe | public |
 | `/api/v1/health/ready` | Sonde de disponibilité, vérifie la base et TimescaleDB | public |
 | `/api/v1/auth/login` | Ouvre une session | public |
 | `/api/v1/auth/refresh` | Fait tourner la session | cookie |
 | `/api/v1/auth/logout` | Ferme la session courante | cookie, idempotente |
 | `/api/v1/auth/logout-all` | Ferme toutes les sessions du compte | jeton |
 | `/api/v1/auth/password` | Change son propre mot de passe | jeton |
 | `/api/v1/auth/forgot-password` | Demande un lien de réinitialisation par email | public |
 | `/api/v1/auth/reset-password` | Choisit un nouveau mot de passe depuis ce lien | public |
 | `/api/v1/auth/me` | Décrit le compte connecté | jeton |
 | `/api/v1/users` | Liste et crée des comptes | `admin` |
 | `/api/v1/users/{id}` | Change le rôle ou l'activation | `admin` |
 | `/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 |
 Le contrat détaillé pour le frontend est dans
 [`docs/architecture/31-contrat-authentification.md`](../../docs/architecture/31-contrat-authentification.md).
 ## Premier administrateur
 Aucun compte n'existe après les migrations. Il s'en crée un en ligne de commande :
 ```bash
 make bootstrap-admin EMAIL=prenom.nom@enervision.fr   # mot de passe saisi au clavier
 # ou, depuis apps/backend :
 uv run python -m app.cli create-admin --email prenom.nom@enervision.fr --generate
 ```
 Le compte est créé avec `must_change_password`, donc la première connexion ne donne accès qu'à
 `/auth/me` et `/auth/password` jusqu'au changement. Le mot de passe ne transite jamais par
 `argv`, visible de tout `ps`, et aucune révision Alembic n'insère de compte : son empreinte
 resterait dans Git pour toujours.
 ## Migrations
 ```bash
 uv run alembic revision --autogenerate -m "libelle"
 uv run alembic upgrade head
 ```
 L'URL de connexion vient de `DATABASE_URL`, pas de `alembic.ini`.
 La premiere revision ne cree aucune table : elle refuse de s'appliquer si l'extension
 TimescaleDB manque, ce qui arrive quand `db/init` n'a pas ete joue. Le DDL propre a
 TimescaleDB qui ne depend pas du schema applicatif vit dans `db/`, pas ici.
 ## Image Docker
 Build multi-stage, dependances resolues par uv depuis `uv.lock`, execution sous un
 utilisateur non root, sonde de sante integree.
 ```bash
 docker build -t enervision-backend:local .
 docker run --rm -p 8000:8000 --env-file .env enervision-backend:local
 ```
@@ -1,175 +0,0 @@
 # Conventions de tests unitaires : Backend
 ## Outil
 pytest, avec pytest-asyncio en mode `auto` : un `async def test_*` est collecte sans
 decorateur. Les appels HTTP passent par httpx sur `ASGITransport`, qui parle a
 l'application en memoire, sans serveur ni port ouvert.
 ## Ou ecrire les tests
 `tests/` est le miroir de `app/` : un test de `app/services/consumption.py` va dans
 `tests/services/test_consumption.py`. Les paquets `core`, `db`, `services` et
 `repositories` existent deja, vides, pour cette raison.
 ## Nommage
 - Fonctions en anglais : `test_<sujet>_<comportement>_when_<condition>`.
 - `ids=` de `parametrize` en francais : `ids=["erreur_sqlalchemy", "erreur_reseau"]`.
 - Pas de docstring : le nom porte l'intention.
 ## Structure attendue (Arrange / Act / Assert)
 Une ligne vide separe les trois temps, sans commentaire pour les annoncer.
 ```python
 async def test_readiness_returns_503_when_the_extension_is_missing(
    fake_session: Callable[..., None], client: AsyncClient
 ) -> None:
    fake_session(result=None)
    response = await client.get("/api/v1/health/ready")
    assert response.status_code == 503
    assert response.json()["detail"] == "Extension TimescaleDB absente"
 ```
 ## Ce qui doit etre teste en priorite
 Le sens de dependance du backend est `endpoints -> services -> repositories -> models`.
 | Couche | Ce qu'on teste |
 |---|---|
 | `services/` | La logique metier, cas nominal et cas d'erreur. C'est la priorite. |
 | `repositories/` | Chaque branche de decision, sous le marqueur `integration`. |
 | `endpoints/` | Le code de statut et la forme de la reponse, pas la logique metier. |
 | `schemas/` | Rien, sauf si le schema porte une validation ecrite a la main. |
 ## Doubles
 On remplace une dependance FastAPI par `app.dependency_overrides`, jamais par
 `unittest.mock`. `tests/factories.py` fournit le necessaire.
 - `fake_session(result=...)` : la session repond `result`.
 - `fake_session(failure=...)` : la session leve l'exception.
 - `make_settings(**overrides)` : fabrique une `Settings`, dont les valeurs priment sur
  l'environnement et sur `.env`. C'est le moyen de tester `create_app` en `prod`.
 ## Gabarit : un endpoint
 ```python
 from collections.abc import Callable
 from httpx import AsyncClient
 async def test_endpoint_returns_the_expected_payload(
    fake_session: Callable[..., None], client: AsyncClient
 ) -> None:
    fake_session(result=42)
    response = await client.get("/api/v1/...")
    assert response.status_code == 200
    assert response.json() == {"valeur": 42}
 ```
 ## Gabarit : un service avec repository factice
 Un service ne connait que son repository : on lui en passe un faux, sans base ni session.
 ```python
 from app.services.consumption import ConsumptionService
 class FakeRepository:
    async def total_for(self, site_id: int) -> float:
        return 12.5
 async def test_service_converts_the_total_to_kilowatt_hours() -> None:
    service = ConsumptionService(FakeRepository())
    total = await service.total_kwh(site_id=1)
    assert total == 12.5
 ```
 ## Gabarit : un repository sur la vraie base
 Un repository parle du SQL : le tester sur un double ne prouve rien. Il porte donc le
 marqueur `integration`, ecarte par defaut.
 ```python
 import pytest
 from sqlalchemy.ext.asyncio import AsyncSession
 from app.models.site import Site
 from app.repositories.site import SiteRepository
@pytest.mark.integration
 async def test_repository_reads_back_what_it_wrote(session: AsyncSession) -> None:
    repository = SiteRepository(session)
    await repository.add(Site(name="Toulouse"))
    assert await repository.by_name("Toulouse") is not None
 ```
 ## Marqueurs
 `integration` designe tout test exigeant une base joignable. `pytest` les ecarte par
 defaut, ce qui garde `make check` jouable sans Docker. Tout autre marqueur doit etre
 declare dans `pyproject.toml` : `--strict-markers` refuse les marqueurs inconnus.
 ## Couverture
 Les branches sont mesurees, pas seulement les lignes. Le seuil de 85 % ne s'applique
 qu'aux cibles qui jouent toute la suite, `make test` et `make test-cov` : un fichier
 joue seul affiche sa couverture sans jamais echouer dessus. Le detail se lit dans
 `htmlcov/index.html` apres `make test-cov`.
 ## Lancer les tests
 ```bash
 make test                          # suite unitaire, sans base
 make test-cov                      # idem, plus les rapports HTML, XML et JUnit
 make db-up && make test-integration # tests exigeant une base, demande Docker
 make check                         # lint + typage + suite unitaire
 uv run pytest tests/api/test_health.py           # un seul fichier
 uv run pytest -k readiness                       # par motif de nom
 ```
 ## Trois fichiers à connaître avant de toucher à l'authentification
 `tests/api/test_route_protection.py` interroge réellement chaque route sans identifiant et
 échoue si l'une d'elles répond autre chose qu'un 401 ou un 403. Il n'inspecte pas l'arbre de
 dépendances : celui-ci n'est accessible que par l'API privée de FastAPI, et surtout une route
 peut porter la bonne dépendance tout en répondant quand même. **Rendre une route publique impose
 donc de modifier la liste `ROUTES_PUBLIQUES` de ce fichier**, ce qui apparaît en clair dans la
 diff d'une pull request.
 `tests/services/test_auth.py` donne au faux hacheur un **compteur d'appels**. C'est ce qui rend
 possibles les deux assertions qui prouvent la conception, et qu'aucune autre forme de test
 n'atteint :
 - adresse inconnue → le compteur vaut 1, donc le haché leurre a bien été vérifié et il n'y a pas
  d'oracle temporel ;
 - limite de débit atteinte → le compteur vaut 0, donc la limite est évaluée avant Argon2.
 `tests/api/test_parcours_authentification.py` joue six parcours complets contre la vraie base,
 sous le marqueur `integration`, sans serveur ni port ouvert. C'est là que se démontrent
 l'atomicité de la rotation, la mort de la famille au rejeu d'un cookie déjà tourné, et la
 révocation immédiate d'un compte désactivé.
 ## Deux pièges d'écriture de test
 **Lire les attributs avant le `rollback`.** Un `session.rollback()` périme les attributs chargés,
 et les relire déclenche une entrée-sortie hors du contexte greenlet, donc un `MissingGreenlet`.
 On capture la valeur dans une variable locale avant d'annuler.
 **`audit_log` ne se nettoie pas.** La table est en ajout seul, garanti par déclencheur : un test
 ne peut pas effacer ce qu'il y écrit, et les lignes d'une exécution précédente sont encore là.
 Chaque test filtre donc sur son propre `target_id` plutôt que de supposer une table vide.
@@ -1,150 +0,0 @@
 # A generic, single database configuration.
 [alembic]
 # path to migration scripts.
 # this is typically a path given in POSIX (e.g. forward slashes)
 # format, relative to the token %(here)s which refers to the location of this
 # ini file
 script_location = %(here)s/alembic
 # template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
 # Uncomment the line below if you want the files to be prepended with date and time
 # see https://alembic.sqlalchemy.org/en/latest/tutorial.html#editing-the-ini-file
 # for all available tokens
 # file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
 # Or organize into date-based subdirectories (requires recursive_version_locations = true)
 # file_template = %%(year)d/%%(month).2d/%%(day).2d_%%(hour).2d%%(minute).2d_%%(second).2d_%%(rev)s_%%(slug)s
 # sys.path path, will be prepended to sys.path if present.
 # defaults to the current working directory.  for multiple paths, the path separator
 # is defined by "path_separator" below.
 prepend_sys_path = .
 # timezone to use when rendering the date within the migration file
 # as well as the filename.
 # If specified, requires the tzdata library which can be installed by adding
 # `alembic[tz]` to the pip requirements.
 # string value is passed to ZoneInfo()
 # leave blank for localtime
 # timezone =
 # max length of characters to apply to the "slug" field
 # truncate_slug_length = 40
 # set to 'true' to run the environment during
 # the 'revision' command, regardless of autogenerate
 # revision_environment = false
 # set to 'true' to allow .pyc and .pyo files without
 # a source .py file to be detected as revisions in the
 # versions/ directory
 # sourceless = false
 # version location specification; This defaults
 # to <script_location>/versions.  When using multiple version
 # directories, initial revisions must be specified with --version-path.
 # The path separator used here should be the separator specified by "path_separator"
 # below.
 # version_locations = %(here)s/bar:%(here)s/bat:%(here)s/alembic/versions
 # path_separator; This indicates what character is used to split lists of file
 # paths, including version_locations and prepend_sys_path within configparser
 # files such as alembic.ini.
 # The default rendered in new alembic.ini files is "os", which uses os.pathsep
 # to provide os-dependent path splitting.
 #
 # Note that in order to support legacy alembic.ini files, this default does NOT
 # take place if path_separator is not present in alembic.ini.  If this
 # option is omitted entirely, fallback logic is as follows:
 #
 # 1. Parsing of the version_locations option falls back to using the legacy
 #    "version_path_separator" key, which if absent then falls back to the legacy
 #    behavior of splitting on spaces and/or commas.
 # 2. Parsing of the prepend_sys_path option falls back to the legacy
 #    behavior of splitting on spaces, commas, or colons.
 #
 # Valid values for path_separator are:
 #
 # path_separator = :
 # path_separator = ;
 # path_separator = space
 # path_separator = newline
 #
 # Use os.pathsep. Default configuration used for new projects.
 path_separator = os
 # set to 'true' to search source files recursively
 # in each "version_locations" directory
 # new in Alembic version 1.10
 # recursive_version_locations = false
 # the output encoding used when revision files
 # are written from script.py.mako
 # output_encoding = utf-8
 # database URL.  This is consumed by the user-maintained env.py script only.
 # other means of configuring database URLs may be customized within the env.py
 # file.
 # L'URL est injectee par alembic/env.py depuis app.core.config.
 sqlalchemy.url =
 [post_write_hooks]
 # post_write_hooks defines scripts or Python functions that are run
 # on newly generated revision scripts.  See the documentation for further
 # detail and examples
 # format using "black" - use the console_scripts runner, against the "black" entrypoint
 # hooks = black
 # black.type = console_scripts
 # black.entrypoint = black
 # black.options = -l 79 REVISION_SCRIPT_FILENAME
 # lint with attempts to fix using "ruff" - use the module runner, against the "ruff" module
 # hooks = ruff
 # ruff.type = module
 # ruff.module = ruff
 # ruff.options = check --fix REVISION_SCRIPT_FILENAME
 # Alternatively, use the exec runner to execute a binary found on your PATH
 # hooks = ruff
 # ruff.type = exec
 # ruff.executable = ruff
 # ruff.options = check --fix REVISION_SCRIPT_FILENAME
 # Logging configuration.  This is also consumed by the user-maintained
 # env.py script only.
 [loggers]
 keys = root,sqlalchemy,alembic
 [handlers]
 keys = console
 [formatters]
 keys = generic
 [logger_root]
 level = WARNING
 handlers = console
 qualname =
 [logger_sqlalchemy]
 level = WARNING
 handlers =
 qualname = sqlalchemy.engine
 [logger_alembic]
 level = INFO
 handlers =
 qualname = alembic
 [handler_console]
 class = StreamHandler
 args = (sys.stderr,)
 level = NOTSET
 formatter = generic
 [formatter_generic]
 format = %(levelname)-5.5s [%(name)s] %(message)s
 datefmt = %H:%M:%S
@@ -1 +0,0 @@
 Generic single-database configuration with an async dbapi.
@@ -1,90 +0,0 @@
 import asyncio
 from logging.config import fileConfig
 from alembic import context
 from sqlalchemy import pool
 from sqlalchemy.engine import Connection
 from sqlalchemy.ext.asyncio import async_engine_from_config
 import app.models  # noqa: F401
 from app.core.config import get_settings
 from app.db.base import Base
 # this is the Alembic Config object, which provides
 # access to the values within the .ini file in use.
 config = context.config
 # Interpret the config file for Python logging.
 # This line sets up loggers basically.
 if config.config_file_name is not None:
    fileConfig(config.config_file_name)
 config.set_main_option("sqlalchemy.url", get_settings().database_url.replace("%", "%%"))
 target_metadata = Base.metadata
 # other values from the config, defined by the needs of env.py,
 # can be acquired:
 # my_important_option = config.get_main_option("my_important_option")
 # ... etc.
 def run_migrations_offline() -> None:
    """Run migrations in 'offline' mode.
    This configures the context with just a URL
    and not an Engine, though an Engine is acceptable
    here as well.  By skipping the Engine creation
    we don't even need a DBAPI to be available.
    Calls to context.execute() here emit the given string to the
    script output.
    """
    url = config.get_main_option("sqlalchemy.url")
    context.configure(
        url=url,
        target_metadata=target_metadata,
        literal_binds=True,
        dialect_opts={"paramstyle": "named"},
    )
    with context.begin_transaction():
        context.run_migrations()
 def do_run_migrations(connection: Connection) -> None:
    context.configure(connection=connection, target_metadata=target_metadata)
    with context.begin_transaction():
        context.run_migrations()
 async def run_async_migrations() -> None:
    """In this scenario we need to create an Engine
    and associate a connection with the context.
    """
    connectable = async_engine_from_config(
        config.get_section(config.config_ini_section, {}),
        prefix="sqlalchemy.",
        poolclass=pool.NullPool,
    )
    async with connectable.connect() as connection:
        await connection.run_sync(do_run_migrations)
    await connectable.dispose()
 def run_migrations_online() -> None:
    """Run migrations in 'online' mode."""
    asyncio.run(run_async_migrations())
 if context.is_offline_mode():
    run_migrations_offline()
 else:
    run_migrations_online()
@@ -1,28 +0,0 @@
 """${message}
 Revision ID: ${up_revision}
 Revises: ${down_revision | comma,n}
 Create Date: ${create_date}
 """
 from typing import Sequence, Union
 from alembic import op
 import sqlalchemy as sa
 ${imports if imports else ""}
 # revision identifiers, used by Alembic.
 revision: str = ${repr(up_revision)}
 down_revision: Union[str, Sequence[str], None] = ${repr(down_revision)}
 branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
 depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
 def upgrade() -> None:
    """Upgrade schema."""
    ${upgrades if upgrades else "pass"}
 def downgrade() -> None:
    """Downgrade schema."""
    ${downgrades if downgrades else "pass"}
@@ -1,119 +0,0 @@
 """tentatives de connexion et journal d audit
 Revision ID: 517053a3c044
 Revises: b1a7c3d9e240
 Create Date: 2026-09-15 14:31:07.966180
 Deux tables aux vocations opposees. `login_attempt` est le compteur de la limitation
 de debit : son volume est pilote par l'attaquant, donc elle se purge. `audit_log` est
 en ajout seul, garanti par deux declencheurs.
 Le declencheur TRUNCATE n'est pas redondant : TRUNCATE ne passe pas par les
 declencheurs de ligne. Et RAISE EXCEPTION plutot qu'un RETURN NULL, qui annulerait
 l'operation silencieusement.
 """
 from collections.abc import Sequence
 import sqlalchemy as sa
 from alembic import op
 from sqlalchemy.dialects import postgresql
 revision: str = "517053a3c044"
 down_revision: str | Sequence[str] | None = "b1a7c3d9e240"
 branch_labels: str | Sequence[str] | None = None
 depends_on: str | Sequence[str] | None = None
 FONCTION_AJOUT_SEUL = """
 CREATE FUNCTION audit_log_append_only() RETURNS trigger AS $$
 BEGIN
    RAISE EXCEPTION 'audit_log est en ajout seul : % interdit', TG_OP;
 END
 $$ LANGUAGE plpgsql;
 """
 DECLENCHEUR_LIGNE = """
 CREATE TRIGGER audit_log_no_update_delete
    BEFORE UPDATE OR DELETE ON audit_log
    FOR EACH ROW EXECUTE FUNCTION audit_log_append_only();
 """
 DECLENCHEUR_TRUNCATE = """
 CREATE TRIGGER audit_log_no_truncate
    BEFORE TRUNCATE ON audit_log
    FOR EACH STATEMENT EXECUTE FUNCTION audit_log_append_only();
 """
 def upgrade() -> None:
    op.create_table(
        "login_attempt",
        sa.Column("id", sa.BigInteger(), sa.Identity(always=True), nullable=False),
        sa.Column(
            "occurred_at",
            sa.DateTime(timezone=True),
            server_default=sa.text("now()"),
            nullable=False,
        ),
        sa.Column("email_tried", sa.String(length=320), nullable=False),
        sa.Column("client_ip", postgresql.INET(), nullable=True),
        sa.Column("outcome", sa.Text(), nullable=False),
        sa.Column("user_id", sa.UUID(), nullable=True),
        sa.CheckConstraint(
            "outcome in ('success', 'bad_credentials', 'throttled', 'inactive')",
            name="ck_login_attempt_outcome",
        ),
        sa.PrimaryKeyConstraint("id", name="pk_login_attempt"),
    )
    op.create_index(
        "ix_login_attempt_email_date", "login_attempt", ["email_tried", "occurred_at"]
    )
    op.create_index("ix_login_attempt_ip_date", "login_attempt", ["client_ip", "occurred_at"])
    op.create_table(
        "audit_log",
        sa.Column("id", sa.BigInteger(), sa.Identity(always=True), nullable=False),
        sa.Column(
            "occurred_at",
            sa.DateTime(timezone=True),
            server_default=sa.text("now()"),
            nullable=False,
        ),
        sa.Column("actor_id", sa.UUID(), nullable=True),
        sa.Column("actor_email", sa.Text(), nullable=True),
        sa.Column("actor_role", sa.Text(), nullable=True),
        sa.Column("action", sa.Text(), nullable=False),
        sa.Column("target_type", sa.Text(), nullable=True),
        sa.Column("target_id", sa.Text(), nullable=True),
        sa.Column("outcome", sa.Text(), nullable=False),
        sa.Column("client_ip", postgresql.INET(), nullable=True),
        sa.Column("user_agent", sa.Text(), nullable=True),
        sa.Column(
            "detail",
            postgresql.JSONB(astext_type=sa.Text()),
            server_default=sa.text("jsonb_build_object()"),
            nullable=False,
        ),
        sa.CheckConstraint("outcome in ('success', 'failure')", name="ck_audit_log_outcome"),
        sa.PrimaryKeyConstraint("id", name="pk_audit_log"),
    )
    op.create_index("ix_audit_log_date", "audit_log", ["occurred_at"])
    op.create_index("ix_audit_log_action_date", "audit_log", ["action", "occurred_at"])
    op.execute(FONCTION_AJOUT_SEUL)
    op.execute(DECLENCHEUR_LIGNE)
    op.execute(DECLENCHEUR_TRUNCATE)
 def downgrade() -> None:
    op.execute("DROP TRIGGER IF EXISTS audit_log_no_truncate ON audit_log;")
    op.execute("DROP TRIGGER IF EXISTS audit_log_no_update_delete ON audit_log;")
    op.execute("DROP FUNCTION IF EXISTS audit_log_append_only();")
    op.drop_index("ix_audit_log_action_date", table_name="audit_log")
    op.drop_index("ix_audit_log_date", table_name="audit_log")
    op.drop_table("audit_log")
    op.drop_index("ix_login_attempt_ip_date", table_name="login_attempt")
    op.drop_index("ix_login_attempt_email_date", table_name="login_attempt")
    op.drop_table("login_attempt")
@@ -1,37 +0,0 @@
 """socle garde extension timescaledb
 Revision ID: 5353c0e4f094
 Revises:
 Create Date: 2026-09-14 14:17:17.556764
 Premiere revision du schema applicatif. Elle ne cree aucune table : elle etablit
 alembic_version et refuse de s'appliquer sur une base ou l'extension TimescaleDB
 manque, cas qui se produit quand db/init n'a pas ete joue.
 """
 from collections.abc import Sequence
 from alembic import op
 revision: str = "5353c0e4f094"
 down_revision: str | Sequence[str] | None = None
 branch_labels: str | Sequence[str] | None = None
 depends_on: str | Sequence[str] | None = None
 GARDE_EXTENSION = """
 DO $$
 BEGIN
    IF NOT EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'timescaledb') THEN
        RAISE EXCEPTION 'extension timescaledb absente, voir db/init et db/README.md';
    END IF;
 END
 $$;
 """
 def upgrade() -> None:
    op.execute(GARDE_EXTENSION)
 def downgrade() -> None:
    pass
@@ -1,77 +0,0 @@
 """jetons de rafraichissement
 Revision ID: 821f71be74c0
 Revises: 517053a3c044
 Create Date: 2026-09-15 14:42:09.757949
 Le jeton lui-meme n'est jamais stocke : seule son empreinte SHA-256 l'est, dans
 `token_hash`. Un pg_dump qui fuiterait ne livrerait donc aucune session utilisable.
 L'index partiel `ix_refresh_token_vivants` sert la revocation en cascade et la
 recherche des sessions actives, qui ne regardent jamais les lignes deja tournees.
 """
 from collections.abc import Sequence
 import sqlalchemy as sa
 from alembic import op
 from sqlalchemy.dialects import postgresql
 revision: str = "821f71be74c0"
 down_revision: str | Sequence[str] | None = "517053a3c044"
 branch_labels: str | Sequence[str] | None = None
 depends_on: str | Sequence[str] | None = None
 MOTIFS = "'logout', 'rotation', 'reuse_detected', 'password_change', 'admin'"
 JETONS_VIVANTS = "revoked_at is null and rotated_at is null"
 def upgrade() -> None:
    op.create_table(
        "refresh_token",
        sa.Column(
            "id", sa.UUID(), server_default=sa.text("gen_random_uuid()"), nullable=False
        ),
        sa.Column("family_id", sa.UUID(), nullable=False),
        sa.Column("user_id", sa.UUID(), nullable=False),
        sa.Column("token_hash", sa.LargeBinary(), nullable=False),
        sa.Column(
            "issued_at",
            sa.DateTime(timezone=True),
            server_default=sa.text("now()"),
            nullable=False,
        ),
        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
        sa.Column("rotated_at", sa.DateTime(timezone=True), nullable=True),
        sa.Column("revoked_at", sa.DateTime(timezone=True), nullable=True),
        sa.Column("revoked_reason", sa.Text(), nullable=True),
        sa.Column("replaced_by", sa.UUID(), nullable=True),
        sa.Column("client_ip", postgresql.INET(), nullable=True),
        sa.Column("user_agent", sa.Text(), nullable=True),
        sa.CheckConstraint(
            f"revoked_reason is null or revoked_reason in ({MOTIFS})",
            name="ck_refresh_token_revoked_reason",
        ),
        sa.ForeignKeyConstraint(
            ["user_id"], ["app_user.id"], name="fk_refresh_token_user", ondelete="CASCADE"
        ),
        sa.PrimaryKeyConstraint("id", name="pk_refresh_token"),
        sa.UniqueConstraint("token_hash", name="uq_refresh_token_hash"),
    )
    op.create_index("ix_refresh_token_family", "refresh_token", ["family_id"])
    op.create_index("ix_refresh_token_user", "refresh_token", ["user_id"])
    op.create_index(
        "ix_refresh_token_vivants",
        "refresh_token",
        ["user_id"],
        postgresql_where=JETONS_VIVANTS,
    )
 def downgrade() -> None:
    op.drop_index(
        "ix_refresh_token_vivants", table_name="refresh_token", postgresql_where=JETONS_VIVANTS
    )
    op.drop_index("ix_refresh_token_user", table_name="refresh_token")
    op.drop_index("ix_refresh_token_family", table_name="refresh_token")
    op.drop_table("refresh_token")
@@ -1,72 +0,0 @@
 """comptes applicatifs
 Revision ID: b1a7c3d9e240
 Revises: 5353c0e4f094
 Create Date: 2026-09-15 14:40:00.000000
 Cree `app_user`, la table des comptes humains et de service. Le nom evite `user`,
 mot reserve de PostgreSQL. `gen_random_uuid()` est au coeur de PG17, aucune
 extension n'est necessaire.
 """
 from collections.abc import Sequence
 import sqlalchemy as sa
 from alembic import op
 from sqlalchemy.dialects import postgresql
 revision: str = "b1a7c3d9e240"
 down_revision: str | Sequence[str] | None = "5353c0e4f094"
 branch_labels: str | Sequence[str] | None = None
 depends_on: str | Sequence[str] | None = None
 def upgrade() -> None:
    op.create_table(
        "app_user",
        sa.Column(
            "id",
            postgresql.UUID(as_uuid=True),
            server_default=sa.text("gen_random_uuid()"),
            nullable=False,
        ),
        sa.Column("email", sa.String(length=320), nullable=False),
        sa.Column("password_hash", sa.Text(), nullable=False),
        sa.Column("role", sa.Text(), nullable=False),
        sa.Column("kind", sa.Text(), server_default=sa.text("'human'"), nullable=False),
        sa.Column("is_active", sa.Boolean(), server_default=sa.text("true"), nullable=False),
        sa.Column(
            "must_change_password", sa.Boolean(), server_default=sa.text("false"), nullable=False
        ),
        sa.Column(
            "credentials_changed_at",
            sa.DateTime(timezone=True),
            server_default=sa.text("now()"),
            nullable=False,
        ),
        sa.Column("last_login_at", sa.DateTime(timezone=True), nullable=True),
        sa.Column("full_name", sa.Text(), nullable=True),
        sa.Column(
            "created_at",
            sa.DateTime(timezone=True),
            server_default=sa.text("now()"),
            nullable=False,
        ),
        sa.Column(
            "updated_at",
            sa.DateTime(timezone=True),
            server_default=sa.text("now()"),
            nullable=False,
        ),
        sa.CheckConstraint("email = lower(email)", name="ck_app_user_email_minuscule"),
        sa.CheckConstraint(
            "role in ('lecteur', 'operateur', 'admin')", name="ck_app_user_role"
        ),
        sa.CheckConstraint("kind in ('human', 'service')", name="ck_app_user_kind"),
        sa.PrimaryKeyConstraint("id", name="pk_app_user"),
        sa.UniqueConstraint("email", name="uq_app_user_email"),
    )
 def downgrade() -> None:
    op.drop_table("app_user")
@@ -1,96 +0,0 @@
 """jetons et tentatives de reinitialisation de mot de passe
 Revision ID: c0adab96238c
 Revises: e6d2026091501
 Create Date: 2026-09-17 10:37:12.571314
 Meme schema que `refresh_token` pour `password_reset_token` : seule l'empreinte SHA-256 du
 jeton est stockee, jamais le jeton lui-meme, pour la meme raison (revocation en cascade,
 aucune session utilisable dans un pg_dump qui fuiterait).
 `password_reset_attempt` vit hors de `audit_log`, comme `login_attempt`, car son volume est
 pilote par l'attaquant : une campagne de demandes y ecrirait des lignes que l'audit, en ajout
 seul, ne devrait jamais purger.
 """
 from collections.abc import Sequence
 import sqlalchemy as sa
 from alembic import op
 from sqlalchemy.dialects import postgresql
 revision: str = "c0adab96238c"
 down_revision: str | Sequence[str] | None = "e6d2026091501"
 branch_labels: str | Sequence[str] | None = None
 depends_on: str | Sequence[str] | None = None
 JETONS_VIVANTS = "consumed_at is null"
 def upgrade() -> None:
    op.create_table(
        "password_reset_attempt",
        sa.Column("id", sa.BigInteger(), sa.Identity(always=True), nullable=False),
        sa.Column(
            "occurred_at",
            sa.DateTime(timezone=True),
            server_default=sa.text("now()"),
            nullable=False,
        ),
        sa.Column("email_tried", sa.String(length=320), nullable=False),
        sa.Column("client_ip", postgresql.INET(), nullable=True),
        sa.PrimaryKeyConstraint("id", name="pk_password_reset_attempt"),
    )
    op.create_index(
        "ix_password_reset_attempt_email_date",
        "password_reset_attempt",
        ["email_tried", "occurred_at"],
    )
    op.create_index(
        "ix_password_reset_attempt_ip_date", "password_reset_attempt", ["client_ip", "occurred_at"]
    )
    op.create_table(
        "password_reset_token",
        sa.Column("id", sa.UUID(), server_default=sa.text("gen_random_uuid()"), nullable=False),
        sa.Column("user_id", sa.UUID(), nullable=False),
        sa.Column("token_hash", sa.LargeBinary(), nullable=False),
        sa.Column(
            "issued_at",
            sa.DateTime(timezone=True),
            server_default=sa.text("now()"),
            nullable=False,
        ),
        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
        sa.Column("consumed_at", sa.DateTime(timezone=True), nullable=True),
        sa.Column("client_ip", postgresql.INET(), nullable=True),
        sa.Column("user_agent", sa.Text(), nullable=True),
        sa.ForeignKeyConstraint(
            ["user_id"],
            ["app_user.id"],
            name="fk_password_reset_token_user",
            ondelete="CASCADE",
        ),
        sa.PrimaryKeyConstraint("id", name="pk_password_reset_token"),
        sa.UniqueConstraint("token_hash", name="uq_password_reset_token_hash"),
    )
    op.create_index("ix_password_reset_token_user", "password_reset_token", ["user_id"])
    op.create_index(
        "ix_password_reset_token_vivants",
        "password_reset_token",
        ["user_id"],
        postgresql_where=JETONS_VIVANTS,
    )
 def downgrade() -> None:
    op.drop_index(
        "ix_password_reset_token_vivants",
        table_name="password_reset_token",
        postgresql_where=JETONS_VIVANTS,
    )
    op.drop_index("ix_password_reset_token_user", table_name="password_reset_token")
    op.drop_table("password_reset_token")
    op.drop_index("ix_password_reset_attempt_ip_date", table_name="password_reset_attempt")
    op.drop_index("ix_password_reset_attempt_email_date", table_name="password_reset_attempt")
    op.drop_table("password_reset_attempt")
@@ -1,218 +0,0 @@
 """Création des six tables Data et de l'hypertable reading.
 Revision ID: e6d2026091501
 Revises: 821f71be74c0
 """
 from alembic import op
 import sqlalchemy as sa
 from sqlalchemy.dialects import postgresql
 revision = "e6d2026091501"
 down_revision = "821f71be74c0"
 branch_labels = None
 depends_on = None
 def upgrade() -> None:
    # ### commands auto generated by Alembic - please adjust! ###
    op.create_table(
        "dataset",
        sa.Column("dataset_id", sa.BigInteger(), autoincrement=True, nullable=False),
        sa.Column("dataset_name", sa.Text(), nullable=False),
        sa.Column("archive_sha256", sa.String(length=64), nullable=False),
        sa.Column("storage_uri", sa.Text(), nullable=False),
        sa.Column("source_timezone", sa.Text(), nullable=True),
        sa.Column(
            "metadata", postgresql.JSONB(none_as_null=True, astext_type=sa.Text()), nullable=False
        ),
        sa.CheckConstraint("dataset_id > 0", name="ck_dataset_positive_id"),
        sa.PrimaryKeyConstraint("dataset_id"),
        sa.UniqueConstraint("archive_sha256", name="uq_dataset_archive_sha256"),
    )
    op.create_table(
        "site",
        sa.Column("site_id", sa.Text(), nullable=False),
        sa.Column("site_name", sa.Text(), nullable=False),
        sa.Column("site_type", sa.Text(), nullable=False),
        sa.Column("location", sa.Text(), nullable=True),
        sa.Column("capacity_kw", sa.Double(), nullable=True),
        sa.Column("status", sa.Text(), nullable=True),
        sa.PrimaryKeyConstraint("site_id"),
    )
    op.create_table(
        "prediction",
        sa.Column("prediction_id", sa.BigInteger(), autoincrement=True, nullable=False),
        sa.Column("site_id", sa.Text(), nullable=False),
        sa.Column(
            "created_at",
            sa.DateTime(timezone=True),
            server_default=sa.text("now()"),
            nullable=False,
        ),
        sa.Column("target_at", sa.DateTime(timezone=True), nullable=False),
        sa.Column("target_metric", sa.Text(), nullable=False),
        sa.Column("period_minutes", sa.Integer(), nullable=True),
        sa.Column("predicted_value", sa.Double(), nullable=True),
        sa.Column("model_reference", sa.Text(), nullable=False),
        sa.Column("status", sa.Text(), nullable=False),
        sa.Column("failure_reason", sa.Text(), nullable=True),
        sa.CheckConstraint(
            "(status = 'available' AND predicted_value IS NOT NULL AND failure_reason IS NULL) OR (status IN ('insufficient_data', 'error') AND predicted_value IS NULL AND failure_reason IS NOT NULL)",
            name="ck_prediction_status",
        ),
        sa.CheckConstraint(
            "target_metric <> 'consumption_kwh' OR period_minutes IS NOT NULL",
            name="ck_prediction_energy_period",
        ),
        sa.CheckConstraint(
            "target_metric IN ('consumption_kwh', 'consumption_kw')", name="ck_prediction_metric"
        ),
        sa.CheckConstraint(
            "period_minutes IS NULL OR period_minutes > 0", name="ck_prediction_period"
        ),
        sa.ForeignKeyConstraint(
            ["site_id"], ["site.site_id"], name="fk_prediction_site", ondelete="RESTRICT"
        ),
        sa.PrimaryKeyConstraint("prediction_id"),
        sa.UniqueConstraint("prediction_id", "site_id", name="uq_prediction_id_site"),
    )
    op.create_index(
        "ix_prediction_site_target", "prediction", ["site_id", "target_at"], unique=False
    )
    op.create_table(
        "reading",
        sa.Column("reading_id", sa.BigInteger(), autoincrement=True, nullable=False),
        sa.Column("site_id", sa.Text(), nullable=False),
        sa.Column("timestamp", sa.DateTime(timezone=True), nullable=False),
        sa.Column("source", sa.Text(), nullable=False),
        sa.Column("dataset_id", sa.BigInteger(), nullable=True),
        sa.Column("consumption_kw", sa.Double(), nullable=True),
        sa.Column("consumption_kwh", sa.Double(), nullable=True),
        sa.Column("consumption_euros", sa.Numeric(precision=14, scale=2), nullable=True),
        sa.Column("voltage_v", sa.Double(), nullable=True),
        sa.Column("current_a", sa.Double(), nullable=True),
        sa.Column("power_factor", sa.Double(), nullable=True),
        sa.Column("temperature_celsius", sa.Double(), nullable=True),
        sa.Column("humidity_percent", sa.Double(), nullable=True),
        sa.Column("solar_irradiance_wm2", sa.Double(), nullable=True),
        sa.Column("is_working_hours", sa.Boolean(), nullable=True),
        sa.Column("data_quality", sa.Text(), nullable=True),
        sa.Column("null_reasons", postgresql.ARRAY(sa.Text()), nullable=True),
        sa.Column(
            "imputed_values", postgresql.JSONB(none_as_null=True, astext_type=sa.Text()), nullable=True
        ),
        sa.Column("imputation_method", sa.Text(), nullable=True),
        sa.Column(
            "ingested_at",
            sa.DateTime(timezone=True),
            server_default=sa.text("now()"),
            nullable=False,
        ),
        sa.Column(
            "raw_data", postgresql.JSONB(none_as_null=True, astext_type=sa.Text()), nullable=False
        ),
        sa.CheckConstraint(
            "(source = 'csv' AND dataset_id IS NOT NULL) OR (source IN ('api_current', 'api_history') AND dataset_id IS NULL)",
            name="ck_reading_dataset_source",
        ),
        sa.CheckConstraint(
            "data_quality IS NULL OR data_quality IN ('good', 'partial', 'degraded', 'critical')",
            name="ck_reading_quality",
        ),
        sa.CheckConstraint(
            "source IN ('csv', 'api_current', 'api_history')", name="ck_reading_source"
        ),
        sa.CheckConstraint(
            "(imputed_values IS NULL AND imputation_method IS NULL) OR (imputed_values IS NOT NULL AND imputation_method IS NOT NULL)",
            name="ck_reading_imputation",
        ),
        sa.ForeignKeyConstraint(
            ["dataset_id"], ["dataset.dataset_id"], name="fk_reading_dataset", ondelete="RESTRICT"
        ),
        sa.ForeignKeyConstraint(
            ["site_id"], ["site.site_id"], name="fk_reading_site", ondelete="RESTRICT"
        ),
        sa.PrimaryKeyConstraint("reading_id", "timestamp"),
    )
    op.create_index("ix_reading_dataset_id", "reading", ["dataset_id"], unique=False)
    op.create_index(
        "ix_reading_site_timestamp", "reading", ["site_id", "timestamp"], unique=False
    )
    op.create_index(
        "uq_reading_source",
        "reading",
        ["site_id", "timestamp", "source", sa.literal_column("coalesce(dataset_id, 0)")],
        unique=True,
    )
    op.execute(
        "SELECT create_hypertable('reading', by_range('timestamp'), create_default_indexes => FALSE)"
    )
    op.create_table(
        "alert",
        sa.Column("alert_id", sa.BigInteger(), autoincrement=True, nullable=False),
        sa.Column("source_alert_id", sa.Text(), nullable=False),
        sa.Column("site_id", sa.Text(), nullable=False),
        sa.Column("source", sa.Text(), nullable=False),
        sa.Column("timestamp", sa.DateTime(timezone=True), nullable=False),
        sa.Column("type", sa.Text(), nullable=False),
        sa.Column("severity", sa.Text(), nullable=False),
        sa.Column("message", sa.Text(), nullable=False),
        sa.Column("value", sa.Double(), nullable=True),
        sa.Column("threshold", sa.Double(), nullable=True),
        sa.Column("metric", sa.Text(), nullable=True),
        sa.Column("prediction_id", sa.BigInteger(), nullable=True),
        sa.Column(
            "raw_data", postgresql.JSONB(none_as_null=True, astext_type=sa.Text()), nullable=False
        ),
        sa.CheckConstraint(
            "severity IN ('low', 'medium', 'high', 'critical')", name="ck_alert_severity"
        ),
        sa.CheckConstraint("source IN ('api_mock', 'enervision')", name="ck_alert_source"),
        sa.CheckConstraint(
            "type IN ('spike', 'threshold', 'anomaly', 'outage', 'sensor')", name="ck_alert_type"
        ),
        sa.ForeignKeyConstraint(
            ["prediction_id", "site_id"],
            ["prediction.prediction_id", "prediction.site_id"],
            name="fk_alert_prediction_site",
            ondelete="RESTRICT",
        ),
        sa.ForeignKeyConstraint(
            ["site_id"], ["site.site_id"], name="fk_alert_site", ondelete="RESTRICT"
        ),
        sa.PrimaryKeyConstraint("alert_id"),
        sa.UniqueConstraint(
            "source", "site_id", "source_alert_id", name="uq_alert_source_reference"
        ),
    )
    op.create_index("ix_alert_site_timestamp", "alert", ["site_id", "timestamp"], unique=False)
    op.create_table(
        "recommendation",
        sa.Column("recommendation_id", sa.BigInteger(), autoincrement=True, nullable=False),
        sa.Column("alert_id", sa.BigInteger(), nullable=False),
        sa.Column("action", sa.Text(), nullable=False),
        sa.Column("explanation", sa.Text(), nullable=False),
        sa.Column("rule_reference", sa.Text(), nullable=False),
        sa.Column(
            "created_at",
            sa.DateTime(timezone=True),
            server_default=sa.text("now()"),
            nullable=False,
        ),
        sa.ForeignKeyConstraint(
            ["alert_id"], ["alert.alert_id"], name="fk_recommendation_alert", ondelete="RESTRICT"
        ),
        sa.PrimaryKeyConstraint("recommendation_id"),
        sa.UniqueConstraint("alert_id", "rule_reference", name="uq_recommendation_alert_rule"),
    )
    # ### end Alembic commands ###
 def downgrade() -> None:
    op.drop_table("recommendation")
    op.drop_table("alert")
    op.drop_table("reading")
    op.drop_table("prediction")
    op.drop_table("site")
    op.drop_table("dataset")
@@ -1,278 +0,0 @@
 # Piège : `get_current_principal()` relit le compte en base à chaque requête au lieu de faire
 # confiance aux claims. C'est le renoncement assumé à la propriété « sans état » : sur un seul
 # service et une seule base, elle n'achetait rien, et la lecture par clé primaire coûte moins
 # d'un pour cent du budget d'une requête. Ce qu'elle achète, c'est la révocation immédiate.
 # Piège : le `Principal` est construit depuis la ligne, jamais depuis le claim `role`. Un claim
 # périmé ne peut donc pas provoquer d'élévation de privilège.
 from collections.abc import Callable
 from datetime import timedelta
 from functools import lru_cache
 from typing import Annotated
 from fastapi import Depends, HTTPException, Request, status
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
 from sqlalchemy.ext.asyncio import AsyncSession
 from app.core.config import Settings, get_settings
 from app.core.hashing import Argon2Hasher, build_hasher
 from app.core.mailer import Mailer, SmtpConfig
 from app.core.principal import Principal
 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.password_reset_attempt import PasswordResetAttemptRepository
 from app.repositories.password_reset_token import PasswordResetTokenRepository
 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, PasswordResetPolicy
 from app.services.reading import ReadingService
 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)]
 SettingsDep = Annotated[Settings, Depends(get_settings)]
 CODE_CHANGEMENT_REQUIS = "password_change_required"
 _porteur = HTTPBearer(auto_error=False, scheme_name="Jeton d'accès")
 CredentialsDep = Annotated[HTTPAuthorizationCredentials | None, Depends(_porteur)]
 def _non_authentifie(description: str) -> HTTPException:
    return HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="Authentification requise",
        headers={"WWW-Authenticate": f'Bearer error="{description}"'},
    )
 def get_token_policy(settings: SettingsDep) -> TokenPolicy:
    return TokenPolicy(
        secret=settings.secret_key.get_secret_value(),
        issuer=settings.jwt_issuer,
        audience=settings.jwt_audience,
        access_ttl=timedelta(seconds=settings.access_token_ttl_seconds),
    )
 # Construire un `Argon2Hasher` calcule un haché leurre, donc 17 ms : il est mis en cache sur
 # les paramètres plutôt que reconstruit à chaque requête.
@lru_cache
 def _hasher_cache(
    time_cost: int, memory_cost_kib: int, parallelism: int, max_concurrency: int
 ) -> Argon2Hasher:
    return build_hasher(
        time_cost=time_cost,
        memory_cost_kib=memory_cost_kib,
        parallelism=parallelism,
        max_concurrency=max_concurrency,
    )
 def get_hasher(settings: SettingsDep) -> Argon2Hasher:
    return _hasher_cache(
        settings.argon2_time_cost,
        settings.argon2_memory_cost_kib,
        settings.argon2_parallelism,
        settings.argon2_max_concurrency,
    )
 def get_client_ip(request: Request, settings: SettingsDep) -> str | None:
    # Derrière un proxy, `request.client.host` vaut l'IP du proxy : le compteur par IP
    # deviendrait global, donc un déni de service auto-infligé. Le dernier élément est le seul
    # qu'un proxy de confiance ait écrit, les précédents sont fournis par le client.
    if settings.trust_proxy_headers:
        transmis = request.headers.get("x-forwarded-for")
        if transmis:
            return transmis.split(",")[-1].strip()
    return request.client.host if request.client else None
 def get_mailer(settings: SettingsDep) -> Mailer:
    return Mailer(
        SmtpConfig(
            host=settings.smtp_host,
            port=settings.smtp_port,
            username=settings.smtp_username,
            password=(
                settings.smtp_password.get_secret_value() if settings.smtp_password else None
            ),
            use_tls=settings.smtp_use_tls,
            from_address=settings.smtp_from_address,
        )
    )
 def get_auth_service(
    session: SessionDep,
    settings: SettingsDep,
    hasher: Annotated[Argon2Hasher, Depends(get_hasher)],
    token_policy: Annotated[TokenPolicy, Depends(get_token_policy)],
    mailer: Annotated[Mailer, Depends(get_mailer)],
 ) -> AuthService:
    return AuthService(
        users=UserRepository(session),
        attempts=LoginAttemptRepository(session),
        refresh_tokens=RefreshTokenRepository(session),
        audit=AuditLogRepository(session),
        hasher=hasher,
        transaction=session,
        token_policy=token_policy,
        login_policy=LoginPolicy(
            window_seconds=settings.login_window_seconds,
            max_failures_per_identifier_and_ip=(settings.login_max_failures_per_identifier_and_ip),
            max_failures_per_ip=settings.login_max_failures_per_ip,
            max_failures_per_identifier=settings.login_max_failures_per_identifier,
        ),
        refresh_ttl=timedelta(seconds=settings.refresh_token_ttl_seconds),
        reset_tokens=PasswordResetTokenRepository(session),
        reset_attempts=PasswordResetAttemptRepository(session),
        reset_policy=PasswordResetPolicy(
            window_seconds=settings.password_reset_window_seconds,
            max_requests_per_identifier=settings.password_reset_max_requests_per_identifier,
            max_requests_per_ip=settings.password_reset_max_requests_per_ip,
            token_ttl=timedelta(seconds=settings.password_reset_ttl_seconds),
            frontend_reset_url=settings.frontend_reset_password_url,
        ),
        mailer=mailer,
    )
 AuthServiceDep = Annotated[AuthService, Depends(get_auth_service)]
 def get_user_service(
    session: SessionDep,
    hasher: Annotated[Argon2Hasher, Depends(get_hasher)],
 ) -> UserService:
    return UserService(
        users=UserRepository(session),
        refresh_tokens=RefreshTokenRepository(session),
        audit=AuditLogRepository(session),
        hasher=hasher,
        transaction=session,
    )
 UserServiceDep = Annotated[UserService, Depends(get_user_service)]
 def get_site_service(session: SessionDep) -> SiteService:
    return SiteService(sites=SiteRepository(session))
 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_reading_service(session: SessionDep) -> ReadingService:
    return ReadingService(readings=ReadingRepository(session))
 ReadingServiceDep = Annotated[ReadingService, Depends(get_reading_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,
    token_policy: Annotated[TokenPolicy, Depends(get_token_policy)],
 ) -> Principal:
    if credentials is None:
        raise _non_authentifie("invalid_request")
    try:
        claims = decode_token(token_policy, credentials.credentials)
    except TokenExpiredError as erreur:
        raise _non_authentifie("expired") from erreur
    except TokenInvalidError as erreur:
        raise _non_authentifie("invalid_token") from erreur
    compte = await UserRepository(session).get_by_id(claims.subject)
    if compte is None or not compte.is_active:
        raise _non_authentifie("invalid_token")
    # Piège : `iat` est une date JWT, donc en secondes entières. Comparer sans tronquer le
    # marqueur rejetterait tout jeton émis dans la même seconde que le changement, c'est-à-dire
    # celui que `/auth/password` vient de rendre pour garder l'appareil courant connecté.
    if int(claims.issued_at.timestamp()) < int(compte.credentials_changed_at.timestamp()):
        raise _non_authentifie("token_stale")
    if claims.role != compte.role:
        raise _non_authentifie("token_stale")
    return Principal(
        id=compte.id,
        email=compte.email,
        role=Role(compte.role),
        kind=AccountKind(compte.kind),
        must_change_password=compte.must_change_password,
    )
 CurrentPrincipalDep = Annotated[Principal, Depends(get_current_principal)]
 def require_role(minimum: Role) -> Callable[[Principal], Principal]:
    def garde(principal: CurrentPrincipalDep) -> Principal:
        if principal.must_change_password:
            raise HTTPException(
                status_code=status.HTTP_403_FORBIDDEN, detail=CODE_CHANGEMENT_REQUIS
            )
        if not has_at_least(principal.role, minimum):
            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Droits insuffisants")
        return principal
    return garde
 LecteurDep = Annotated[Principal, Depends(require_role(Role.LECTEUR))]
 OperateurDep = Annotated[Principal, Depends(require_role(Role.OPERATEUR))]
 AdminDep = Annotated[Principal, Depends(require_role(Role.ADMIN))]
 def require_trusted_origin(request: Request, settings: SettingsDep) -> None:
    # Un navigateur envoie toujours `Origin` sur une requête non sûre. Son absence signale un
    # client hors navigateur, qui ne détient aucun cookie de victime : rien à protéger.
    origine = request.headers.get("origin")
    if origine is None:
        return
    if origine not in settings.allowed_origins:
        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Origine refusée")
@@ -1,47 +0,0 @@
 # Piège : la réponse 422 par défaut de FastAPI contient la clé `input`, c'est-à-dire la valeur
 # rejetée. Sur `/auth/login`, un corps malformé renverrait donc le mot de passe au client et le
 # déposerait dans les journaux d'erreur. `validation_error_handler()` ne laisse passer que le
 # champ fautif et le type d'erreur.
 import uuid
 from typing import Any
 from fastapi import FastAPI, Request, status
 from fastapi.exceptions import RequestValidationError
 from fastapi.responses import JSONResponse
 from app.core.logging import get_logger
 logger = get_logger(__name__)
 async def validation_error_handler(_: Request, exception: RequestValidationError) -> JSONResponse:
    champs: list[dict[str, Any]] = [
        {
            "champ": ".".join(str(element) for element in erreur["loc"]),
            "type": erreur["type"],
        }
        for erreur in exception.errors()
    ]
    return JSONResponse(
        status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, content={"detail": champs}
    )
 async def unhandled_error_handler(request: Request, exception: Exception) -> JSONResponse:
    correlation = uuid.uuid4().hex
    logger.exception(
        "erreur non gérée correlation=%s methode=%s chemin=%s",
        correlation,
        request.method,
        request.url.path,
    )
    return JSONResponse(
        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
        content={"detail": "Erreur interne", "correlation": correlation},
    )
 def register_error_handlers(application: FastAPI) -> None:
    application.add_exception_handler(RequestValidationError, validation_error_handler)  # type: ignore[arg-type]
    application.add_exception_handler(Exception, unhandled_error_handler)
@@ -1,35 +0,0 @@
 # Pourquoi : `SecurityHeadersMiddleware` ne pose ni HSTS ni CSP, et c'est délibéré.
 # L'application ignore si TLS termine devant elle, donc elle ne peut pas décider d'un HSTS ;
 # et une CSP sur une API JSON ne protège presque rien, celle qui compte protège la page
 # Angular. Les deux appartiennent au terminateur TLS.
 # Contrainte : `/docs` charge Swagger depuis un CDN, une CSP stricte ici casserait la
 # documentation sans rien sécuriser.
 from collections.abc import Awaitable, Callable
 from typing import Final
 from starlette.middleware.base import BaseHTTPMiddleware
 from starlette.requests import Request
 from starlette.responses import Response
 EN_TETES: Final[dict[str, str]] = {
    "X-Content-Type-Options": "nosniff",
    "X-Frame-Options": "DENY",
    "Referrer-Policy": "no-referrer",
 }
 PREFIXE_AUTHENTIFICATION: Final = "/auth"
 class SecurityHeadersMiddleware(BaseHTTPMiddleware):
    async def dispatch(
        self, request: Request, call_next: Callable[[Request], Awaitable[Response]]
    ) -> Response:
        response = await call_next(request)
        for nom, valeur in EN_TETES.items():
            response.headers.setdefault(nom, valeur)
        # Une réponse d'authentification ne doit jamais être conservée par un intermédiaire.
        if PREFIXE_AUTHENTIFICATION in request.url.path:
            response.headers["Cache-Control"] = "no-store"
        return response
@@ -1,179 +0,0 @@
 # Piège : `cookie_de_rafraichissement` est purement documentaire, d'où son `auto_error=False`.
 # Avec la valeur par défaut, FastAPI répondrait 403 avant d'atteindre `lit_le_cookie()`, et
 # `/auth/refresh` cesserait de rendre le 401 que le frontend attend.
 from typing import Any, Final
 from fastapi.security import APIKeyCookie
 from app.core.config import REFRESH_COOKIE_DEFAUT
 from app.schemas.errors import ErrorResponse, InternalErrorResponse, ValidationErrorResponse
 Reponses = dict[int | str, dict[str, Any]]
 SUMMARY: Final = "Collecte, analyse et restitution de séries temporelles énergétiques."
 DESCRIPTION: Final = """
 Toutes les routes sont préfixées par `/api/v1`.
 **Authentification.** Le jeton d'accès se présente dans l'en-tête `Authorization: Bearer ...`.
 Le jeton de rafraîchissement est un cookie `HttpOnly` que le code client ne voit jamais : il
 suffit d'émettre les requêtes avec les identifiants de session. `POST /auth/refresh` rend un
 nouveau jeton d'accès et fait tourner le cookie.
 **Rôles.** `lecteur`, puis `operateur`, puis `admin`. Chaque rôle couvre les droits du
 précédent.
 **Erreurs.** Le corps porte toujours une clé `detail`. Un `403` dont le `detail` vaut
 `password_change_required` n'est pas un refus de droits : il exige le changement du mot de passe
 provisoire avant toute autre action.
 Le parcours de session complet est décrit dans
 `docs/architecture/31-contrat-authentification.md`.
 """
 TAGS: Final[list[dict[str, Any]]] = [
    {
        "name": "health",
        "description": (
            "Sondes d'infrastructure, publiques. `live` prouve que le processus répond, `ready` "
            "que la base répond et que l'extension TimescaleDB est chargée."
        ),
    },
    {
        "name": "auth",
        "description": (
            "Ouverture, rotation et fermeture de session, et changement de son propre mot de passe."
        ),
    },
    {
        "name": "users",
        "description": "Administration des comptes. Réservé au rôle `admin`.",
    },
    {
        "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": "readings",
        "description": (
            "Historique des lectures de consommation. Fenêtre temporelle plafonnée à 90 jours, "
            "24 dernières heures par défaut si `start`/`end` sont omis. 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(
    name=REFRESH_COOKIE_DEFAUT,
    scheme_name="Cookie de rafraîchissement",
    description=(
        "Cookie `HttpOnly` posé par `/auth/login` et tourné par `/auth/refresh`. Il prend le "
        "préfixe `__Secure-` dès que l'API tourne derrière TLS, et n'est émis que vers "
        "`/api/v1/auth`."
    ),
    auto_error=False,
 )
 # Le 422 n'est déclaré que sur les routes qui acceptent un corps ou un paramètre : ailleurs,
 # aucune validation ne peut échouer et l'annoncer serait faux.
 REPONSE_VALIDATION: Final[Reponses] = {
    422: {
        "model": ValidationErrorResponse,
        "description": (
            "Corps invalide. Le détail nomme le champ fautif et le type d'erreur, jamais la "
            "valeur envoyée."
        ),
    },
 }
 REPONSE_SERVEUR: Final[Reponses] = {
    500: {
        "model": InternalErrorResponse,
        "description": (
            "Erreur interne. `correlation` identifie la trace côté serveur, qui n'est pas "
            "renvoyée au client."
        ),
    },
 }
 REPONSE_INDISPONIBLE: Final[Reponses] = {
    503: {
        "model": ErrorResponse,
        "description": "Base injoignable, ou extension TimescaleDB absente de la base.",
    },
 }
 REPONSES_AUTHENTIFIEES: Final[Reponses] = {
    401: {
        "model": ErrorResponse,
        "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=`."
        ),
    },
 }
 REPONSES_ADMIN: Final[Reponses] = {
    **REPONSES_AUTHENTIFIEES,
    403: {
        "model": ErrorResponse,
        "description": (
            "Droits insuffisants, ou mot de passe provisoire à changer quand `detail` vaut "
            "`password_change_required`."
        ),
    },
 }
 # `lecteur` est le rôle minimum : `require_role` n'y refuse jamais un 403 pour droits
 # insuffisants, seulement pour le mot de passe provisoire.
 REPONSES_LECTEUR: Final[Reponses] = {
    **REPONSES_AUTHENTIFIEES,
    403: {
        "model": ErrorResponse,
        "description": (
            "Mot de passe provisoire à changer (`detail` vaut `password_change_required`)."
        ),
    },
 }
 REPONSE_ORIGINE_REFUSEE: Final[Reponses] = {
    403: {
        "model": ErrorResponse,
        "description": "Origine non autorisée (protection CSRF de `require_trusted_origin`).",
    },
 }
 REPONSE_LIMITE: Final[Reponses] = {
    429: {
        "model": ErrorResponse,
        "description": "Trop de demandes sur cette fenêtre glissante.",
        "headers": {
            "Retry-After": {
                "description": "Secondes à attendre avant une nouvelle tentative.",
                "schema": {"type": "integer"},
            }
        },
    },
 }
@@ -1,23 +0,0 @@
 # Pourquoi : `/metrics` est protégé par un jeton statique et non par un rôle applicatif. Coupler
 # la supervision au modèle d'utilisateurs casserait la collecte à chaque panne
 # d'authentification, c'est-à-dire précisément quand on a besoin des métriques. Le vrai contrôle
 # reste le réseau : Prometheus scrute sur le réseau interne et `/metrics` ne sort pas.
 import secrets
 from fastapi import HTTPException, Request, status
 from app.api.deps import SettingsDep
 def require_metrics_token(request: Request, settings: SettingsDep) -> None:
    attendu = settings.metrics_token
    if attendu is None:
        return
    presente = request.headers.get("authorization", "")
    prefixe = "Bearer "
    if not presente.startswith(prefixe) or not secrets.compare_digest(
        presente[len(prefixe) :], attendu.get_secret_value()
    ):
        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Jeton requis")
@@ -1,23 +0,0 @@
 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]
@@ -1,365 +0,0 @@
 # Piège : le jeton de rafraîchissement ne quitte jamais le cookie httpOnly, et le jeton
 # d'accès ne va jamais dans un cookie. C'est ce qui réduit la surface CSRF aux trois routes de
 # ce module : partout ailleurs, le navigateur n'attache rien de lui-même.
 from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, Request, Response, status
 from app.api.deps import (
    AuthServiceDep,
    CurrentPrincipalDep,
    SettingsDep,
    get_client_ip,
    require_trusted_origin,
 )
 from app.api.openapi import (
    REPONSE_LIMITE,
    REPONSE_ORIGINE_REFUSEE,
    REPONSE_VALIDATION,
    REPONSES_AUTHENTIFIEES,
    Reponses,
    cookie_de_rafraichissement,
 )
 from app.core.cookies import RefreshCookie, cookie_name
 from app.core.logging import get_logger
 from app.schemas.auth import (
    ForgotPasswordRequest,
    LoginRequest,
    PasswordChangeRequest,
    PrincipalResponse,
    ResetPasswordRequest,
    ResetTokenValidationResponse,
    TokenResponse,
 )
 from app.schemas.errors import ErrorResponse
 from app.services.auth import (
    AuthenticatedSession,
    InvalidCredentialsError,
    InvalidOrExpiredResetTokenError,
    RateLimitedError,
    SessionRejectedError,
 )
 router = APIRouter()
 logger = get_logger(__name__)
 DETAIL_IDENTIFIANTS = "Identifiants invalides"
 DETAIL_SESSION = "Session invalide"
 DETAIL_LIEN_RESET = "Lien invalide ou expiré"
 REPONSES_LOGIN: Reponses = {
    **REPONSE_VALIDATION,
    401: {
        "model": ErrorResponse,
        "description": (
            "Identifiants faux, compte inconnu ou compte désactivé. Le message est le même dans "
            "les trois cas, et n'apprend donc rien sur l'existence du compte."
        ),
    },
    429: {
        "model": ErrorResponse,
        "description": "Trop de tentatives sur cette fenêtre glissante.",
        "headers": {
            "Retry-After": {
                "description": "Secondes à attendre avant une nouvelle tentative.",
                "schema": {"type": "integer"},
            }
        },
    },
 }
 REPONSES_REFRESH: Reponses = {
    **REPONSE_ORIGINE_REFUSEE,
    401: {
        "model": ErrorResponse,
        "description": (
            "Cookie absent, session expirée, révoquée, ou jeton déjà tourné. Dans ce dernier cas "
            "toute la famille de sessions est révoquée et le cookie est effacé avec la réponse."
        ),
    },
 }
 REPONSES_LOGOUT: Reponses = {**REPONSE_ORIGINE_REFUSEE}
 REPONSES_LOGOUT_ALL: Reponses = {**REPONSES_AUTHENTIFIEES, **REPONSE_ORIGINE_REFUSEE}
 REPONSES_MOT_DE_PASSE: Reponses = {
    **REPONSE_VALIDATION,
    **REPONSE_ORIGINE_REFUSEE,
    401: {
        "model": ErrorResponse,
        "description": "Jeton d'accès invalide, ou mot de passe courant faux.",
    },
 }
 REPONSES_FORGOT_PASSWORD: Reponses = {
    **REPONSE_VALIDATION,
    **REPONSE_LIMITE,
 }
 REPONSES_RESET_PASSWORD: Reponses = {
    **REPONSE_VALIDATION,
    **REPONSE_ORIGINE_REFUSEE,
    400: {
        "model": ErrorResponse,
        "description": "Lien invalide, déjà utilisé, ou expiré (durée de vie : 15 minutes).",
    },
 }
 def repond(
    response: Response, settings: SettingsDep, session: AuthenticatedSession
 ) -> TokenResponse:
    response.headers["Cache-Control"] = "no-store"
    response.set_cookie(**RefreshCookie.build(settings, session.refresh_secret).as_kwargs())
    return TokenResponse(
        access_token=session.access_token,
        expires_in=session.expires_in,
        principal=PrincipalResponse.from_principal(session.principal),
    )
 # Piège : une `HTTPException` construit sa propre réponse, donc tout en-tête posé sur la
 # `Response` injectée est perdu. L'effacement du cookie doit voyager avec l'exception,
 # sans quoi un navigateur garderait un cookie mort après une détection de réutilisation.
 def entete_de_suppression(settings: SettingsDep) -> str:
    temoin = Response()
    temoin.delete_cookie(**RefreshCookie.expired(settings).as_deletion_kwargs())
    return temoin.headers["set-cookie"]
 def lit_le_cookie(request: Request, settings: SettingsDep) -> str:
    secret = request.cookies.get(cookie_name(settings))
    if not secret:
        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail=DETAIL_SESSION)
    return secret
@router.post(
    "/login",
    response_model=TokenResponse,
    summary="Ouvre une session",
    responses=REPONSES_LOGIN,
 )
 async def login(
    payload: LoginRequest,
    request: Request,
    response: Response,
    settings: SettingsDep,
    service: AuthServiceDep,
    client_ip: str | None = Depends(get_client_ip),
 ) -> TokenResponse:
    response.headers["Cache-Control"] = "no-store"
    agent = request.headers.get("user-agent")
    try:
        session = await service.authenticate(
            email=payload.email, password=payload.password, client_ip=client_ip, user_agent=agent
        )
    except RateLimitedError as erreur:
        logger.warning("auth.rate_limited email=%s ip=%s", payload.email, client_ip)
        raise HTTPException(
            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
            detail="Trop de tentatives, réessayez plus tard",
            headers={"Retry-After": str(erreur.retry_after)},
        ) from erreur
    except InvalidCredentialsError as erreur:
        logger.warning("auth.login.failure email=%s ip=%s", payload.email, client_ip)
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED, detail=DETAIL_IDENTIFIANTS
        ) from erreur
    logger.info("auth.login.success user_id=%s ip=%s", session.principal.id, client_ip)
    return repond(response, settings, session)
@router.post(
    "/refresh",
    response_model=TokenResponse,
    summary="Fait tourner la session",
    dependencies=[Depends(require_trusted_origin), Depends(cookie_de_rafraichissement)],
    responses=REPONSES_REFRESH,
 )
 async def refresh(
    request: Request,
    response: Response,
    settings: SettingsDep,
    service: AuthServiceDep,
    client_ip: str | None = Depends(get_client_ip),
 ) -> TokenResponse:
    response.headers["Cache-Control"] = "no-store"
    try:
        session = await service.refresh(
            secret=lit_le_cookie(request, settings),
            client_ip=client_ip,
            user_agent=request.headers.get("user-agent"),
        )
    except SessionRejectedError as erreur:
        logger.warning("auth.refresh.rejected ip=%s", client_ip)
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail=DETAIL_SESSION,
            headers={
                "Set-Cookie": entete_de_suppression(settings),
                "Cache-Control": "no-store",
            },
        ) from erreur
    return repond(response, settings, session)
@router.post(
    "/logout",
    status_code=status.HTTP_204_NO_CONTENT,
    summary="Ferme la session courante",
    dependencies=[Depends(require_trusted_origin), Depends(cookie_de_rafraichissement)],
    responses=REPONSES_LOGOUT,
 )
 async def logout(
    request: Request, response: Response, settings: SettingsDep, service: AuthServiceDep
 ) -> None:
    response.headers["Cache-Control"] = "no-store"
    secret = request.cookies.get(cookie_name(settings))
    if secret:
        await service.logout(secret=secret)
    response.delete_cookie(**RefreshCookie.expired(settings).as_deletion_kwargs())
@router.post(
    "/logout-all",
    status_code=status.HTTP_204_NO_CONTENT,
    summary="Ferme toutes les sessions du compte",
    dependencies=[Depends(require_trusted_origin)],
    responses=REPONSES_LOGOUT_ALL,
 )
 async def logout_all(
    principal: CurrentPrincipalDep,
    response: Response,
    settings: SettingsDep,
    service: AuthServiceDep,
 ) -> None:
    response.headers["Cache-Control"] = "no-store"
    revoquees = await service.logout_all(principal)
    logger.info("auth.logout_all user_id=%s sessions=%s", principal.id, revoquees)
    response.delete_cookie(**RefreshCookie.expired(settings).as_deletion_kwargs())
@router.get(
    "/me",
    response_model=PrincipalResponse,
    summary="Décrit le compte connecté",
    responses=REPONSES_AUTHENTIFIEES,
 )
 async def me(principal: CurrentPrincipalDep) -> PrincipalResponse:
    return PrincipalResponse.from_principal(principal)
@router.post(
    "/password",
    response_model=TokenResponse,
    summary="Change son propre mot de passe",
    dependencies=[Depends(require_trusted_origin)],
    responses=REPONSES_MOT_DE_PASSE,
 )
 async def change_password(
    payload: PasswordChangeRequest,
    principal: CurrentPrincipalDep,
    request: Request,
    response: Response,
    settings: SettingsDep,
    service: AuthServiceDep,
    client_ip: str | None = Depends(get_client_ip),
 ) -> TokenResponse:
    response.headers["Cache-Control"] = "no-store"
    try:
        session = await service.change_password(
            principal=principal,
            current_password=payload.current_password,
            new_password=payload.new_password,
            client_ip=client_ip,
            user_agent=request.headers.get("user-agent"),
        )
    except InvalidCredentialsError as erreur:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED, detail=DETAIL_IDENTIFIANTS
        ) from erreur
    logger.info("auth.password_changed user_id=%s", principal.id)
    return repond(response, settings, session)
@router.post(
    "/forgot-password",
    status_code=status.HTTP_202_ACCEPTED,
    summary="Demande un lien de réinitialisation par email",
    responses=REPONSES_FORGOT_PASSWORD,
 )
 async def forgot_password(
    payload: ForgotPasswordRequest,
    request: Request,
    response: Response,
    service: AuthServiceDep,
    background_tasks: BackgroundTasks,
    client_ip: str | None = Depends(get_client_ip),
 ) -> None:
    response.headers["Cache-Control"] = "no-store"
    try:
        await service.request_password_reset(
            email=payload.email,
            client_ip=client_ip,
            user_agent=request.headers.get("user-agent"),
            background_tasks=background_tasks,
        )
    except RateLimitedError as erreur:
        logger.warning("auth.password_reset.rate_limited ip=%s", client_ip)
        raise HTTPException(
            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
            detail="Trop de demandes, réessayez plus tard",
            headers={"Retry-After": str(erreur.retry_after)},
        ) from erreur
@router.get(
    "/reset-password/validate",
    response_model=ResetTokenValidationResponse,
    summary="Vérifie sans le consommer si un lien de réinitialisation est encore valide",
    responses=REPONSE_VALIDATION,
 )
 async def validate_reset_token(token: str, service: AuthServiceDep) -> ResetTokenValidationResponse:
    return ResetTokenValidationResponse(valid=await service.is_reset_token_valid(token=token))
@router.post(
    "/reset-password",
    response_model=TokenResponse,
    summary="Choisit un nouveau mot de passe depuis un lien reçu par email",
    dependencies=[Depends(require_trusted_origin)],
    responses=REPONSES_RESET_PASSWORD,
 )
 async def reset_password(
    payload: ResetPasswordRequest,
    request: Request,
    response: Response,
    settings: SettingsDep,
    service: AuthServiceDep,
    client_ip: str | None = Depends(get_client_ip),
 ) -> TokenResponse:
    response.headers["Cache-Control"] = "no-store"
    try:
        session = await service.confirm_password_reset(
            token=payload.token,
            new_password=payload.new_password,
            client_ip=client_ip,
            user_agent=request.headers.get("user-agent"),
        )
    except InvalidOrExpiredResetTokenError as erreur:
        logger.warning("auth.password_reset.invalid_token ip=%s", client_ip)
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST, detail=DETAIL_LIEN_RESET
        ) from erreur
    logger.info("auth.password_reset.success user_id=%s", session.principal.id)
    return repond(response, settings, session)
@@ -1,47 +0,0 @@
 from fastapi import APIRouter, HTTPException, status
 from sqlalchemy import text
 from sqlalchemy.exc import SQLAlchemyError
 from app.api.deps import SessionDep, SettingsDep
 from app.api.openapi import REPONSE_INDISPONIBLE
 from app.core.logging import get_logger
 from app.schemas.health import LivenessStatus, ReadinessStatus
 logger = get_logger(__name__)
 router = APIRouter()
 TIMESCALEDB_VERSION = text("SELECT extversion FROM pg_extension WHERE extname = 'timescaledb'")
@router.get("/live", summary="Sonde de vivacité")
 async def liveness(settings: SettingsDep) -> LivenessStatus:
    return LivenessStatus(
        status="ok",
        service=settings.name,
        version=settings.version,
        environment=settings.env,
    )
@router.get("/ready", summary="Sonde de disponibilité", responses=REPONSE_INDISPONIBLE)
 async def readiness(session: SessionDep) -> ReadinessStatus:
    try:
        version: str | None = await session.scalar(TIMESCALEDB_VERSION)
    # `# fmt: skip` contourne un bug de ruff format 0.16.7 : il retire les parenthèses de ce
    # `except` à deux types, ce qui produit une syntaxe invalide (`except A, B:`).
    except (SQLAlchemyError, OSError):  # fmt: skip
        logger.exception("Base de données injoignable")
        raise HTTPException(
            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
            detail="Base de données injoignable",
        ) from None
    if version is None:
        logger.error("Extension TimescaleDB absente de la base")
        raise HTTPException(
            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
            detail="Extension TimescaleDB absente",
        )
    logger.debug("Extension TimescaleDB en version %s", version)
    return ReadinessStatus(status="ready", database="reachable", timescaledb="loaded")
@@ -1,54 +0,0 @@
 from datetime import datetime
 from fastapi import APIRouter, HTTPException, Query, status
 from app.api.deps import LecteurDep, ReadingServiceDep
 from app.api.openapi import REPONSE_VALIDATION, Reponses
 from app.schemas.errors import ErrorResponse
 from app.schemas.reading import ReadingResponse
 from app.services.reading import FenetreInverseeError, FenetreTropLargeError
 router = APIRouter()
 REPONSES_FENETRE: Reponses = {
    **REPONSE_VALIDATION,
    400: {
        "model": ErrorResponse,
        "description": (
            "Fenêtre temporelle invalide : `start` postérieur ou égal à `end`, ou écart entre "
            "les deux supérieur à 90 jours."
        ),
    },
 }
@router.get(
    "",
    response_model=list[ReadingResponse],
    summary="Liste l'historique des lectures",
    responses=REPONSES_FENETRE,
 )
 async def list_readings(
    _: LecteurDep,
    service: ReadingServiceDep,
    site_id: str | None = None,
    start: datetime | None = None,
    end: datetime | None = None,
    limit: int = Query(500, ge=1, le=2000),
    offset: int = Query(0, ge=0),
 ) -> list[ReadingResponse]:
    try:
        lectures = await service.list_history(
            site_id=site_id, start=start, end=end, limit=limit, offset=offset
        )
    except FenetreInverseeError as erreur:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail="`start` doit être strictement antérieur à `end`",
        ) from erreur
    except FenetreTropLargeError as erreur:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail="L'écart entre `start` et `end` ne peut pas dépasser 90 jours",
        ) from erreur
    return [ReadingResponse.model_validate(lecture) for lecture in lectures]
@@ -1,40 +0,0 @@
 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)
@@ -1,16 +0,0 @@
 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)
@@ -1,36 +0,0 @@
 from fastapi import APIRouter, HTTPException, status
 from app.api.deps import LecteurDep, SiteServiceDep
 from app.api.openapi import REPONSE_VALIDATION, Reponses
 from app.schemas.errors import ErrorResponse
 from app.schemas.site import SiteResponse
 from app.services.site import SiteNotFoundError
 router = APIRouter()
 REPONSES_INTROUVABLE: Reponses = {
    **REPONSE_VALIDATION,
    404: {"model": ErrorResponse, "description": "Aucun site ne porte cet identifiant."},
 }
@router.get("", response_model=list[SiteResponse], summary="Liste les sites")
 async def list_sites(_: LecteurDep, service: SiteServiceDep) -> list[SiteResponse]:
    sites = await service.list_all()
    return [SiteResponse.model_validate(site) for site in sites]
@router.get(
    "/{site_id}",
    response_model=SiteResponse,
    summary="Décrit un site",
    responses=REPONSES_INTROUVABLE,
 )
 async def get_site(site_id: str, _: LecteurDep, service: SiteServiceDep) -> SiteResponse:
    try:
        site = await service.get_by_id(site_id)
    except SiteNotFoundError as erreur:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND, detail="Site introuvable"
        ) from erreur
    return SiteResponse.model_validate(site)
@@ -1,16 +0,0 @@
 from fastapi import APIRouter
 from app.api.deps import LecteurDep, StatsServiceDep
 from app.schemas.stats import StatsSummaryResponse
 router = APIRouter()
@router.get(
    "/summary",
    response_model=StatsSummaryResponse,
    summary="Résume la consommation instantanée du parc",
 )
 async def get_summary(_: LecteurDep, service: StatsServiceDep) -> StatsSummaryResponse:
    resume = await service.summary()
    return StatsSummaryResponse.model_validate(resume)
@@ -1,142 +0,0 @@
 from uuid import UUID
 from fastapi import APIRouter, HTTPException, Response, status
 from app.api.deps import AdminDep, UserServiceDep
 from app.api.openapi import REPONSE_VALIDATION, Reponses
 from app.core.logging import get_logger
 from app.schemas.errors import ErrorResponse
 from app.schemas.user import (
    TemporaryPasswordResponse,
    UserCreateRequest,
    UserResponse,
    UserUpdateRequest,
 )
 from app.services.user import EmailAlreadyUsedError, LastAdminError, UserNotFoundError
 router = APIRouter()
 logger = get_logger(__name__)
 REPONSES_CREATION: Reponses = {
    **REPONSE_VALIDATION,
    409: {"model": ErrorResponse, "description": "Adresse déjà portée par un autre compte."},
 }
 REPONSES_INTROUVABLE: Reponses = {
    **REPONSE_VALIDATION,
    404: {"model": ErrorResponse, "description": "Aucun compte ne porte cet identifiant."},
 }
 REPONSES_MODIFICATION: Reponses = {
    **REPONSES_INTROUVABLE,
    400: {"model": ErrorResponse, "description": "Corps vide, aucune modification demandée."},
    409: {
        "model": ErrorResponse,
        "description": (
            "L'opération laisserait la plateforme sans administrateur actif, qu'il s'agisse de "
            "rétrograder le dernier ou de le désactiver."
        ),
    },
 }
@router.get("", response_model=list[UserResponse], summary="Liste les comptes")
 async def list_users(_: AdminDep, service: UserServiceDep) -> list[UserResponse]:
    comptes = await service.list_all()
    return [UserResponse.model_validate(compte) for compte in comptes]
@router.post(
    "",
    response_model=TemporaryPasswordResponse,
    status_code=status.HTTP_201_CREATED,
    summary="Crée un compte avec un mot de passe provisoire",
    responses=REPONSES_CREATION,
 )
 async def create_user(
    payload: UserCreateRequest,
    acteur: AdminDep,
    service: UserServiceDep,
    response: Response,
 ) -> TemporaryPasswordResponse:
    # Le mot de passe provisoire ne doit être conservé par aucun intermédiaire.
    response.headers["Cache-Control"] = "no-store"
    try:
        cree = await service.create(
            actor=acteur,
            email=payload.email,
            role=payload.role,
            full_name=payload.full_name,
        )
    except EmailAlreadyUsedError as erreur:
        raise HTTPException(
            status_code=status.HTTP_409_CONFLICT, detail="Adresse déjà utilisée"
        ) from erreur
    logger.info("user.created actor=%s target=%s", acteur.id, cree.user.id)
    return TemporaryPasswordResponse(
        user=UserResponse.model_validate(cree.user),
        temporary_password=cree.temporary_password,
    )
@router.patch(
    "/{user_id}",
    response_model=UserResponse,
    summary="Change le rôle ou l'activation",
    responses=REPONSES_MODIFICATION,
 )
 async def update_user(
    user_id: UUID,
    payload: UserUpdateRequest,
    acteur: AdminDep,
    service: UserServiceDep,
 ) -> UserResponse:
    compte = None
    try:
        if payload.role is not None:
            compte = await service.change_role(actor=acteur, user_id=user_id, role=payload.role)
        if payload.is_active is not None:
            compte = await service.set_active(
                actor=acteur, user_id=user_id, is_active=payload.is_active
            )
    except UserNotFoundError as erreur:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND, detail="Compte introuvable"
        ) from erreur
    except LastAdminError as erreur:
        raise HTTPException(
            status_code=status.HTTP_409_CONFLICT,
            detail="Dernier administrateur actif, l'opération le laisserait sans successeur",
        ) from erreur
    if compte is None:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST, detail="Aucune modification demandée"
        )
    logger.info("user.updated actor=%s target=%s", acteur.id, user_id)
    return UserResponse.model_validate(compte)
@router.post(
    "/{user_id}/password-reset",
    response_model=TemporaryPasswordResponse,
    summary="Réinitialise le mot de passe et ferme les sessions",
    responses=REPONSES_INTROUVABLE,
 )
 async def reset_password(
    user_id: UUID, acteur: AdminDep, service: UserServiceDep, response: Response
 ) -> TemporaryPasswordResponse:
    response.headers["Cache-Control"] = "no-store"
    try:
        reinitialise = await service.reset_password(actor=acteur, user_id=user_id)
    except UserNotFoundError as erreur:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND, detail="Compte introuvable"
        ) from erreur
    logger.info("user.password_reset actor=%s target=%s", acteur.id, user_id)
    return TemporaryPasswordResponse(
        user=UserResponse.model_validate(reinitialise.user),
        temporary_password=reinitialise.temporary_password,
    )
@@ -1,36 +0,0 @@
 from fastapi import APIRouter
 from app.api.openapi import REPONSE_SERVEUR, REPONSES_ADMIN, REPONSES_LECTEUR
 from app.api.v1.endpoints import (
    alerts,
    auth,
    health,
    readings,
    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(
    readings.router, prefix="/readings", tags=["readings"], responses=REPONSES_LECTEUR
 )
 api_router.include_router(
    sensors.router, prefix="/sensors", tags=["sensors"], responses=REPONSES_ADMIN
 )
@@ -1,170 +0,0 @@
 # Pourquoi : `create_admin()` est une commande et non une révision Alembic. Une révision qui
 # insérerait un compte graverait son empreinte dans Git pour toujours, et son mot de passe
 # serait connu de quiconque lit le dépôt. L'ADR 0001 pose par ailleurs qu'Alembic porte le
 # schéma, pas les données.
 # Piège : le mot de passe ne transite jamais par `argv`, visible de tout `ps`, ni par
 # l'historique du shell. Il est saisi par `getpass` ou tiré au sort par la commande.
 import argparse
 import asyncio
 import json
 import secrets
 import string
 import sys
 from getpass import getpass
 from pathlib import Path
 from typing import Any
 from pydantic import SecretStr
 from app.core.config import Settings, get_settings
 from app.core.hashing import build_hasher
 from app.core.roles import Role
 from app.db.session import get_session_factory
 from app.main import create_app
 from app.repositories.user import UserRepository
 from app.schemas.auth import PASSWORD_MIN_LENGTH, SPECIAL_CHARACTERS, valide_complexite
 LONGUEUR_MOT_DE_PASSE_GENERE = 24
 CHEMIN_CONTRAT = Path(__file__).resolve().parent.parent / "openapi.json"
 async def create_admin(
    settings: Settings, *, email: str, password: str, force: bool
 ) -> tuple[bool, str]:
    hacheur = build_hasher(
        time_cost=settings.argon2_time_cost,
        memory_cost_kib=settings.argon2_memory_cost_kib,
        parallelism=settings.argon2_parallelism,
        max_concurrency=settings.argon2_max_concurrency,
    )
    empreinte = await hacheur.hash(password)
    async with get_session_factory()() as session:
        depot = UserRepository(session)
        if not force and await depot.count_active_admins() > 0:
            return False, "Un administrateur actif existe déjà, relancer avec --force pour forcer"
        if await depot.get_by_email(email) is not None:
            return False, f"Le compte {email} existe déjà"
        await depot.create(
            email=email,
            password_hash=empreinte,
            role=Role.ADMIN,
            must_change_password=True,
        )
        await session.commit()
    return (
        True,
        f"Administrateur {email.strip().lower()} créé, mot de passe à changer à la connexion",
    )
 # Piège : le schéma ne doit dépendre ni du `.env` du poste ni des variables `APP_*`, sinon le
 # fichier versionné changerait de machine en machine et le test de dérive deviendrait un oracle
 # de configuration locale. Tout ce qui atteint le schéma est donc posé ici, `_env_file` compris.
 def settings_du_contrat() -> Settings:
    return Settings(
        _env_file=None,
        name="EnerVision API",
        version="0.1.0",
        env="local",
        api_prefix="/api/v1",
        secret_key=SecretStr("contrat-openapi-sans-effet-sur-le-schema"),
        database_url="postgresql+asyncpg://openapi:contrat@localhost:5432/enervision",
    )
 def schema_du_contrat() -> dict[str, Any]:
    schema: dict[str, Any] = create_app(settings_du_contrat()).openapi()
    return schema
 def rend_le_contrat() -> str:
    return json.dumps(schema_du_contrat(), indent=2, ensure_ascii=False) + "\n"
 def export_openapi(destination: Path) -> str:
    destination.write_text(rend_le_contrat(), encoding="utf-8")
    return f"Contrat OpenAPI écrit dans {destination}"
 def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(prog="python -m app.cli", description="Outils EnerVision")
    sous_commandes = parser.add_subparsers(dest="commande", required=True)
    admin = sous_commandes.add_parser("create-admin", help="Crée le premier administrateur")
    admin.add_argument("--email", required=True)
    admin.add_argument(
        "--generate", action="store_true", help="Tire un mot de passe au sort et l'affiche une fois"
    )
    admin.add_argument(
        "--force", action="store_true", help="Crée le compte même si un administrateur existe"
    )
    contrat = sous_commandes.add_parser(
        "export-openapi", help="Écrit le contrat OpenAPI sur disque"
    )
    contrat.add_argument("--output", default=str(CHEMIN_CONTRAT))
    return parser
 def genere_mot_de_passe() -> str:
    tirage = secrets.SystemRandom()
    classes = [
        string.ascii_uppercase,
        string.ascii_lowercase,
        string.digits,
        SPECIAL_CHARACTERS,
    ]
    reste = LONGUEUR_MOT_DE_PASSE_GENERE - len(classes)
    caracteres = [tirage.choice(classe) for classe in classes]
    caracteres += [tirage.choice("".join(classes)) for _ in range(reste)]
    tirage.shuffle(caracteres)
    return "".join(caracteres)
 def read_password(*, generate: bool) -> str:
    if generate:
        mot_de_passe = genere_mot_de_passe()
        print(f"Mot de passe généré, il ne sera plus affiché : {mot_de_passe}")
        return mot_de_passe
    mot_de_passe = getpass("Mot de passe : ")
    if len(mot_de_passe) < PASSWORD_MIN_LENGTH:
        raise SystemExit(f"Le mot de passe doit faire au moins {PASSWORD_MIN_LENGTH} caractères")
    try:
        valide_complexite(mot_de_passe)
    except ValueError as erreur:
        raise SystemExit(str(erreur)) from erreur
    if mot_de_passe != getpass("Confirmation : "):
        raise SystemExit("Les deux saisies diffèrent")
    return mot_de_passe
 def main(argv: list[str] | None = None) -> int:
    arguments = build_parser().parse_args(argv)
    if arguments.commande == "export-openapi":
        print(export_openapi(Path(arguments.output)))
        return 0
    mot_de_passe = read_password(generate=arguments.generate)
    succes, message = asyncio.run(
        create_admin(
            get_settings(),
            email=arguments.email,
            password=mot_de_passe,
            force=arguments.force,
        )
    )
    print(message)
    return 0 if succes else 1
 if __name__ == "__main__":  # pragma: no cover
    sys.exit(main())
@@ -1,123 +0,0 @@
 from functools import lru_cache
 from typing import Literal, Self
 from pydantic import Field, SecretStr, model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 Environment = Literal["local", "dev", "staging", "prod"]
 SameSite = Literal["lax", "strict", "none"]
 SECRET_KEY_MIN_LENGTH = 32
 REFRESH_COOKIE_DEFAUT = "ev_refresh"
 SENTINELLES_INTERDITES = frozenset(
    {"change_me", "changeme", "secret", "secret-de-test", "changez-moi", "todo"}
 )
 class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_file=".env",
        env_prefix="APP_",
        env_file_encoding="utf-8",
        extra="ignore",
    )
    name: str = "EnerVision API"
    version: str = "0.1.0"
    env: Environment = "local"
    debug: bool = False
    log_level: str = "INFO"
    api_prefix: str = "/api/v1"
    secret_key: SecretStr
    cors_origins: str = ""
    database_url: str = Field(validation_alias="DATABASE_URL")
    database_pool_size: int = 5
    database_max_overflow: int = 10
    jwt_issuer: str = "enervision-api"
    jwt_audience: str = "enervision-web"
    access_token_ttl_seconds: int = Field(default=900, ge=60, le=3600)
    refresh_token_ttl_seconds: int = Field(default=604800, ge=3600, le=2592000)
    refresh_cookie_name: str = REFRESH_COOKIE_DEFAUT
    cookie_path: str = "/api/v1/auth"
    cookie_samesite: SameSite = "strict"
    cookie_secure: bool | None = None
    argon2_time_cost: int = Field(default=2, ge=1, le=10)
    argon2_memory_cost_kib: int = Field(default=19456, ge=8192)
    argon2_parallelism: int = Field(default=1, ge=1, le=4)
    argon2_max_concurrency: int = Field(default=4, ge=1, le=32)
    login_window_seconds: int = Field(default=900, ge=60)
    login_max_failures_per_identifier_and_ip: int = Field(default=5, ge=1)
    login_max_failures_per_ip: int = Field(default=20, ge=1)
    login_max_failures_per_identifier: int = Field(default=50, ge=1)
    password_reset_ttl_seconds: int = Field(default=900, ge=60, le=3600)
    password_reset_window_seconds: int = Field(default=900, ge=60)
    password_reset_max_requests_per_identifier: int = Field(default=3, ge=1)
    password_reset_max_requests_per_ip: int = Field(default=10, ge=1)
    smtp_host: str = "localhost"
    smtp_port: int = Field(default=587, ge=1, le=65535)
    smtp_username: str | None = None
    smtp_password: SecretStr | None = None
    smtp_use_tls: bool = False
    smtp_from_address: str = "no-reply@enervision.fr"
    frontend_reset_password_url: str = "http://localhost:4200/reset-password"  # noqa: S105
    trust_proxy_headers: bool = False
    expose_api_docs: bool | None = None
    metrics_token: SecretStr | None = None
    @property
    def allowed_origins(self) -> list[str]:
        return [origin.strip() for origin in self.cors_origins.split(",") if origin.strip()]
    @property
    def is_production(self) -> bool:
        return self.env == "prod"
    @property
    def cookies_are_secure(self) -> bool:
        return self.env != "local" if self.cookie_secure is None else self.cookie_secure
    @property
    def api_docs_are_exposed(self) -> bool:
        if self.expose_api_docs is not None:
            return self.expose_api_docs
        return self.env not in ("staging", "prod")
    @model_validator(mode="after")
    def _refuse_les_configurations_dangereuses(self) -> Self:
        secret = self.secret_key.get_secret_value()
        if len(secret) < SECRET_KEY_MIN_LENGTH:
            raise ValueError(
                f"APP_SECRET_KEY doit faire au moins {SECRET_KEY_MIN_LENGTH} caractères"
            )
        if secret.strip().lower() in SENTINELLES_INTERDITES:
            raise ValueError("APP_SECRET_KEY est une valeur d'exemple, il faut en générer une")
        # Piège : `create_app()` passe `debug` à FastAPI, qui renvoie alors la trace complète
        # au client, et à l'engine, qui journalise le SQL et ses paramètres.
        if self.debug and self.env in ("staging", "prod"):
            raise ValueError("APP_DEBUG doit rester faux hors des environnements locaux")
        if "*" in self.cors_origins:
            raise ValueError("APP_CORS_ORIGINS n'accepte pas de joker, les origines sont listées")
        # Sans origines, aucun middleware CORS n'est monté et la vérification d'`Origin` des
        # routes d'authentification n'a plus de référentiel auquel comparer.
        if self.env != "local" and not self.allowed_origins:
            raise ValueError("APP_CORS_ORIGINS doit lister au moins une origine hors local")
        if self.cookie_samesite == "none" and not self.cookies_are_secure:
            raise ValueError("Un cookie SameSite=None est rejeté par les navigateurs sans Secure")
        return self
@lru_cache
 def get_settings() -> Settings:
    return Settings()
@@ -1,61 +0,0 @@
 # Piège : le cookie de suppression doit reprendre exactement le nom et le `Path` du cookie
 # posé, sinon le navigateur en garde une copie et la déconnexion n'est que cosmétique.
 # `RefreshCookie.expired()` existe pour que les deux ne puissent pas diverger.
 from dataclasses import asdict, dataclass
 from typing import Any, Self
 from app.core.config import SameSite, Settings
 SECURE_PREFIX = "__Secure-"
@dataclass(frozen=True, slots=True)
 class RefreshCookie:
    key: str
    value: str
    max_age: int
    path: str
    secure: bool
    httponly: bool
    samesite: SameSite
    @classmethod
    def build(cls, settings: Settings, value: str) -> Self:
        return cls(
            key=cookie_name(settings),
            value=value,
            max_age=settings.refresh_token_ttl_seconds,
            path=settings.cookie_path,
            secure=settings.cookies_are_secure,
            httponly=True,
            samesite=settings.cookie_samesite,
        )
    @classmethod
    def expired(cls, settings: Settings) -> Self:
        return cls(
            key=cookie_name(settings),
            value="",
            max_age=0,
            path=settings.cookie_path,
            secure=settings.cookies_are_secure,
            httponly=True,
            samesite=settings.cookie_samesite,
        )
    def as_kwargs(self) -> dict[str, Any]:
        return asdict(self)
    def as_deletion_kwargs(self) -> dict[str, Any]:
        # `Response.delete_cookie()` n'accepte ni `value` ni `max_age`, mais il exige le même
        # nom, le même chemin et les mêmes attributs, sinon le navigateur garde le cookie.
        arguments = asdict(self)
        del arguments["value"], arguments["max_age"]
        return arguments
 def cookie_name(settings: Settings) -> str:
    if settings.cookies_are_secure:
        return f"{SECURE_PREFIX}{settings.refresh_cookie_name}"
    return settings.refresh_cookie_name
@@ -1,63 +0,0 @@
 # Piège : `PasswordHasher.verify()` bloque 17 ms. Appelé tel quel dans un `async def`, il fige
 # la boucle d'événements et gèle toutes les requêtes en cours, pas seulement la connexion.
 # `Argon2Hasher` le pousse donc dans un fil, sous un `CapacityLimiter` : le pool par défaut
 # d'anyio accepte 40 fils, soit 40 x 19 Mio dans le pire cas sur une machine qui héberge aussi
 # PostgreSQL, Prometheus et Grafana.
 # Piège : `verify_dummy()` doit être appelé quand l'utilisateur est introuvable. Sans lui,
 # l'écart entre 2 ms et 17 ms est un oracle d'existence de compte, mesurable à distance.
 import secrets
 import anyio
 import anyio.to_thread
 from argon2 import PasswordHasher
 from argon2.exceptions import Argon2Error, InvalidHashError, VerificationError
 _ERREURS_DE_VERIFICATION = (VerificationError, InvalidHashError, Argon2Error)
 class Argon2Hasher:
    def __init__(self, hasher: PasswordHasher, *, max_concurrency: int) -> None:
        self._hasher = hasher
        self._limiter = anyio.CapacityLimiter(max_concurrency)
        self._leurre = hasher.hash(secrets.token_urlsafe(32))
    async def hash(self, password: str) -> str:
        return await anyio.to_thread.run_sync(self._hasher.hash, password, limiter=self._limiter)
    async def verify(self, stored: str, password: str) -> bool:
        return await anyio.to_thread.run_sync(self._verify, stored, password, limiter=self._limiter)
    async def verify_dummy(self) -> None:
        await self.verify(self._leurre, "")
    def needs_rehash(self, stored: str) -> bool:
        try:
            return self._hasher.check_needs_rehash(stored)
        except _ERREURS_DE_VERIFICATION:
            return True
    def _verify(self, stored: str, password: str) -> bool:
        try:
            return self._hasher.verify(stored, password)
        except _ERREURS_DE_VERIFICATION:
            return False
 def build_hasher(
    *,
    time_cost: int,
    memory_cost_kib: int,
    parallelism: int,
    max_concurrency: int,
 ) -> Argon2Hasher:
    return Argon2Hasher(
        PasswordHasher(
            time_cost=time_cost,
            memory_cost=memory_cost_kib,
            parallelism=parallelism,
            hash_len=32,
            salt_len=16,
        ),
        max_concurrency=max_concurrency,
    )
@@ -1,92 +0,0 @@
 # Pourquoi : `RedactingFilter` est la troisième ligne de défense, pas la première. La première
 # est de ne jamais passer un secret au logger, la deuxième de ne jamais mettre un jeton dans
 # une URL, que le journal d'accès enregistrerait de toute façon. Le filtre rattrape l'erreur
 # que personne n'a relue, notamment l'écho SQL quand `debug` est actif.
 import logging
 import re
 from logging.config import dictConfig
 from typing import Final
 from app.core.config import Settings
 CAVIARDAGE: Final = "[expurgé]"
 REMPLACEMENTS: Final[tuple[tuple[re.Pattern[str], str], ...]] = (
    (re.compile(r"Bearer\s+[A-Za-z0-9._~+/-]{20,}=*"), f"Bearer {CAVIARDAGE}"),
    (re.compile(r"eyJ[A-Za-z0-9._-]{20,}"), CAVIARDAGE),
    (re.compile(r"\$argon2[a-z0-9]*\$\S+"), CAVIARDAGE),
    (
        re.compile(r'("?(?:password|mot_de_passe|secret|token)"?\s*[:=]\s*")[^"]*(")'),
        rf"\1{CAVIARDAGE}\2",
    ),
    (
        re.compile(r"((?:password|mot_de_passe|secret|token)[A-Za-z_]*=)[^&\s;\"]+"),
        rf"\1{CAVIARDAGE}",
    ),
    (re.compile(r"(ev_refresh=)[^;\s]+"), rf"\1{CAVIARDAGE}"),
 )
 def redact(message: str) -> str:
    for motif, remplacement in REMPLACEMENTS:
        message = motif.sub(remplacement, message)
    return message
 class RedactingFilter(logging.Filter):
    def filter(self, record: logging.LogRecord) -> bool:
        message = record.getMessage()
        expurge = redact(message)
        if expurge != message:
            record.msg = expurge
            record.args = ()
        return True
 def configure_logging(settings: Settings) -> None:
    formatter = "json" if settings.is_production else "console"
    dictConfig(
        {
            "version": 1,
            "disable_existing_loggers": False,
            "filters": {
                "redaction": {"()": "app.core.logging.RedactingFilter"},
            },
            "formatters": {
                "console": {
                    "format": "%(asctime)s %(levelname)-8s %(name)s %(message)s",
                },
                "json": {
                    "()": "pythonjsonlogger.json.JsonFormatter",
                    "format": "%(asctime)s %(levelname)s %(name)s %(message)s",
                },
            },
            "handlers": {
                "default": {
                    "class": "logging.StreamHandler",
                    "formatter": formatter,
                    "filters": ["redaction"],
                    "stream": "ext://sys.stdout",
                },
            },
            "root": {"handlers": ["default"], "level": settings.log_level},
            "loggers": {
                "uvicorn": {
                    "handlers": ["default"],
                    "level": settings.log_level,
                    "propagate": False,
                },
                "uvicorn.access": {
                    "handlers": ["default"],
                    "level": settings.log_level,
                    "propagate": False,
                },
                "sqlalchemy.engine": {"level": "WARNING"},
            },
        }
    )
 def get_logger(name: str) -> logging.Logger:
    return logging.getLogger(name)
@@ -1,48 +0,0 @@
 # Piège : l'URL de réinitialisation porte le jeton en clair. Ne jamais la journaliser :
 # `send_password_reset_email()` ne logue que le destinataire, jamais `reset_url`.
 from dataclasses import dataclass
 from email.message import EmailMessage
 import aiosmtplib
 from app.core.logging import get_logger
 logger = get_logger(__name__)
@dataclass(frozen=True, slots=True)
 class SmtpConfig:
    host: str
    port: int
    username: str | None
    password: str | None
    use_tls: bool
    from_address: str
 class Mailer:
    def __init__(self, config: SmtpConfig) -> None:
        self._config = config
    async def send_password_reset_email(self, *, to: str, reset_url: str) -> None:
        message = EmailMessage()
        message["From"] = self._config.from_address
        message["To"] = to
        message["Subject"] = "Réinitialisation de votre mot de passe EnerVision"
        message.set_content(
            "Une réinitialisation de mot de passe a été demandée pour ce compte.\n\n"
            f"Ouvrez ce lien dans les 15 minutes pour choisir un nouveau mot de passe : "
            f"{reset_url}\n\n"
            "Si vous n'êtes pas à l'origine de cette demande, ignorez cet email."
        )
        _, message_recu = await aiosmtplib.send(
            message,
            hostname=self._config.host,
            port=self._config.port,
            username=self._config.username,
            password=self._config.password,
            use_tls=self._config.use_tls,
        )
        logger.info("mailer.password_reset_sent to=%s smtp_response=%s", to, message_recu)
@@ -1,18 +0,0 @@
 # Pourquoi : tout le code métier dépend de `Principal` et jamais du modèle ORM ni des claims
 # du jeton. C'est ce qui garde la bascule vers un fournisseur OIDC locale à
 # `get_current_principal()` et à `AuthService.authenticate()`, au lieu de la répandre dans
 # chaque endpoint.
 from dataclasses import dataclass
 from uuid import UUID
 from app.core.roles import AccountKind, Role
@dataclass(frozen=True, slots=True)
 class Principal:
    id: UUID
    email: str
    role: Role
    kind: AccountKind
    must_change_password: bool
@@ -1,26 +0,0 @@
 from enum import StrEnum
 from typing import Final
 class Role(StrEnum):
    # Contrainte : ces valeurs voyagent en base, en JSON et dans les jetons. Elles restent
    # en ASCII, contrairement au libellé « opérateur » affiché à l'utilisateur.
    LECTEUR = "lecteur"
    OPERATEUR = "operateur"
    ADMIN = "admin"
 class AccountKind(StrEnum):
    HUMAIN = "human"
    SERVICE = "service"
 ROLE_RANK: Final[dict[Role, int]] = {
    Role.LECTEUR: 0,
    Role.OPERATEUR: 1,
    Role.ADMIN: 2,
 }
 def has_at_least(actual: Role, required: Role) -> bool:
    return ROLE_RANK[actual] >= ROLE_RANK[required]
@@ -1,117 +0,0 @@
 # Piège : `decode_access_token()` porte trois barrières indépendantes, et retirer l'une
 # d'elles ne casse aucun test évident. L'algorithme est épinglé, sinon un jeton forgé en
 # `alg: none` passerait. L'audience et l'émetteur sont vérifiés, sinon un jeton émis pour
 # un autre service serait accepté. Le claim `typ` est comparé, sinon un jeton de
 # rafraîchissement servirait de jeton d'accès, ce qui transformerait une fenêtre de
 # 15 minutes en fenêtre de 7 jours.
 # Contrainte : ce module ne lit jamais `get_settings()`, qui est mis en cache par
 # `lru_cache` et se contaminerait entre tests. Tout paramètre arrive par `TokenPolicy`.
 import hashlib
 import secrets
 from dataclasses import dataclass
 from datetime import UTC, datetime, timedelta
 from typing import Final
 from uuid import UUID, uuid4
 import jwt
 ACCESS_TOKEN_TYPE: Final = "access"  # noqa: S105
 REFRESH_SECRET_BYTES: Final = 32
 _ALGORITHME: Final = "HS256"
 _CLAIMS_REQUIS: Final = ["iss", "aud", "sub", "iat", "exp", "jti", "typ", "role", "kind"]
 class TokenInvalidError(Exception):
    pass
 class TokenExpiredError(TokenInvalidError):
    pass
@dataclass(frozen=True, slots=True)
 class TokenPolicy:
    secret: str
    issuer: str
    audience: str
    access_ttl: timedelta
@dataclass(frozen=True, slots=True)
 class AccessClaims:
    subject: UUID
    role: str
    kind: str
    token_id: UUID
    issued_at: datetime
 def encode_access_token(
    policy: TokenPolicy,
    *,
    subject: UUID,
    role: str,
    kind: str,
    now: datetime | None = None,
 ) -> str:
    emis_a = now or datetime.now(UTC)
    return jwt.encode(
        {
            "iss": policy.issuer,
            "aud": policy.audience,
            "sub": str(subject),
            "iat": emis_a,
            "exp": emis_a + policy.access_ttl,
            "jti": str(uuid4()),
            "typ": ACCESS_TOKEN_TYPE,
            "role": role,
            "kind": kind,
        },
        policy.secret,
        algorithm=_ALGORITHME,
    )
 def decode_access_token(policy: TokenPolicy, token: str) -> AccessClaims:
    try:
        charge = jwt.decode(
            token,
            policy.secret,
            algorithms=[_ALGORITHME],
            audience=policy.audience,
            issuer=policy.issuer,
            options={"require": _CLAIMS_REQUIS},
        )
    except jwt.ExpiredSignatureError as erreur:
        raise TokenExpiredError("Jeton expiré") from erreur
    except jwt.InvalidTokenError as erreur:
        raise TokenInvalidError("Jeton invalide") from erreur
    if charge["typ"] != ACCESS_TOKEN_TYPE:
        raise TokenInvalidError("Type de jeton inattendu")
    try:
        sujet = UUID(charge["sub"])
        identifiant = UUID(charge["jti"])
    except (AttributeError, TypeError, ValueError) as erreur:
        raise TokenInvalidError("Identifiants du jeton illisibles") from erreur
    return AccessClaims(
        subject=sujet,
        role=str(charge["role"]),
        kind=str(charge["kind"]),
        token_id=identifiant,
        issued_at=datetime.fromtimestamp(charge["iat"], tz=UTC),
    )
 def generate_refresh_secret() -> str:
    return secrets.token_urlsafe(REFRESH_SECRET_BYTES)
 # SHA-256 nu, pas Argon2id : 256 bits de CSPRNG n'ont ni dictionnaire ni préimage atteignable,
 # et une KDF lente coûterait 17 ms à chaque rafraîchissement pour aucun gain.
 def fingerprint_refresh(secret: str) -> bytes:
    return hashlib.sha256(secret.encode("utf-8")).digest()
@@ -1,5 +0,0 @@
 from sqlalchemy.orm import DeclarativeBase
 class Base(DeclarativeBase):
    """Base déclarative commune à tous les modèles."""
@@ -1,33 +0,0 @@
 from collections.abc import AsyncIterator
 from functools import lru_cache
 from sqlalchemy.ext.asyncio import (
    AsyncEngine,
    AsyncSession,
    async_sessionmaker,
    create_async_engine,
 )
 from app.core.config import get_settings
@lru_cache
 def get_engine() -> AsyncEngine:
    settings = get_settings()
    return create_async_engine(
        settings.database_url,
        echo=settings.debug,
        pool_pre_ping=True,
        pool_size=settings.database_pool_size,
        max_overflow=settings.database_max_overflow,
    )
@lru_cache
 def get_session_factory() -> async_sessionmaker[AsyncSession]:
    return async_sessionmaker(get_engine(), class_=AsyncSession, expire_on_commit=False)
 async def get_session() -> AsyncIterator[AsyncSession]:
    async with get_session_factory()() as session:
        yield session
@@ -1,621 +0,0 @@
 from __future__ import annotations
 import argparse
 import asyncio
 import hashlib
 import json
 from pathlib import Path
 from typing import Any, cast
 import pandas as pd
 from sqlalchemy import text
 from sqlalchemy.ext.asyncio import AsyncConnection, create_async_engine
 from app.core.config import get_settings
 REQUIRED_COLUMNS = {
    "timestamp",
    "site_id",
    "site_type",
    "site_name",
    "consumption_kwh",
    "consumption_euros",
    "temperature_celsius",
    "humidity_percent",
    "solar_irradiance_wm2",
    "hour",
    "day_of_week",
    "day_name",
    "month",
    "is_weekend",
    "is_working_hours",
 }
 MEASURE_COLUMNS = [
    "consumption_kwh",
    "consumption_euros",
    "temperature_celsius",
    "humidity_percent",
    "solar_irradiance_wm2",
 ]
 SOURCE_NAME = "csv"
 def compute_sha256(path: Path) -> str:
    """Calcule l'empreinte SHA-256 du fichier source."""
    sha256 = hashlib.sha256()
    with path.open("rb") as source:
        for block in iter(lambda: source.read(1024 * 1024), b""):
            sha256.update(block)
    return sha256.hexdigest()
 def load_metadata(path: Path) -> dict[str, Any]:
    """Charge les métadonnées fournies avec le dataset."""
    with path.open("r", encoding="utf-8") as source:
        metadata = json.load(source)
    if not isinstance(metadata, dict):
        raise ValueError("Le fichier de métadonnées doit contenir un objet JSON.")
    return cast(dict[str, Any], metadata)
 def classify_quality(
    row: dict[str, Any],
 ) -> tuple[str, list[str]]:
    """
    Déduit une qualité technique à partir des champs manquants.
    Les valeurs NULL sont conservées. On ne cherche pas ici à
    déterminer la cause physique exacte de leur absence.
    """
    missing = [column for column in MEASURE_COLUMNS if pd.isna(row.get(column))]
    if not missing:
        quality = "good"
    elif len(missing) == len(MEASURE_COLUMNS):
        quality = "critical"
    elif "consumption_kwh" in missing:
        quality = "degraded"
    else:
        quality = "partial"
    reasons = [f"missing:{column}" for column in missing]
    return quality, reasons
 def validate_source(
    frame: pd.DataFrame,
    metadata: dict[str, Any],
 ) -> None:
    """Valide le dataset avant tout chargement en base."""
    missing_columns = REQUIRED_COLUMNS.difference(frame.columns)
    if missing_columns:
        raise ValueError(f"Colonnes obligatoires absentes : {sorted(missing_columns)}")
    expected_records = int(metadata["total_records"])
    if len(frame) != expected_records:
        raise ValueError(f"Nombre de lignes inattendu : {len(frame)} au lieu de {expected_records}")
    expected_sites = set(metadata["sites"].keys())
    actual_sites = set(frame["site_id"].unique())
    if actual_sites != expected_sites:
        raise ValueError(
            f"Sites incohérents. Attendus={sorted(expected_sites)}, trouvés={sorted(actual_sites)}"
        )
    duplicated = frame.duplicated(subset=["site_id", "timestamp"]).sum()
    if duplicated:
        raise ValueError(f"{duplicated} doublons (site_id, timestamp) détectés")
    static_variants = frame.groupby("site_id")[["site_type", "site_name"]].nunique()
    if (static_variants > 1).any().any():
        raise ValueError("Un site possède plusieurs valeurs de site_type ou site_name.")
    # Vérifie également que tous les timestamps
    # peuvent être interprétés correctement.
    pd.to_datetime(
        frame["timestamp"],
        errors="raise",
    )
 def normalize_timestamps(
    frame: pd.DataFrame,
    source_timezone: str,
 ) -> pd.DataFrame:
    """
    Normalise les timestamps et leur associe une timezone.
    Les timestamps originaux sont conservés dans une colonne
    temporaire afin de pouvoir les stocker dans raw_data.
    """
    normalized = frame.copy()
    normalized["_source_timestamp"] = normalized["timestamp"]
    timestamps = pd.to_datetime(
        normalized["timestamp"],
        errors="raise",
    )
    if timestamps.dt.tz is None:
        timestamps = timestamps.dt.tz_localize(source_timezone)
    else:
        timestamps = timestamps.dt.tz_convert(source_timezone)
    normalized["timestamp"] = timestamps
    return normalized
 def to_json_value(value: Any) -> Any:
    """
    Convertit une valeur Pandas/Numpy en valeur
    compatible JSON.
    """
    if value is None:
        return None
    try:
        if pd.isna(value):
            return None
    except TypeError, ValueError:
        pass
    if isinstance(value, pd.Timestamp):
        return value.isoformat()
    if hasattr(value, "item"):
        return value.item()
    return value
 async def ensure_dataset(
    connection: AsyncConnection,
    metadata: dict[str, Any],
    sha256: str,
    source_timezone: str,
    storage_uri: str,
 ) -> int:
    """
    Crée l'entrée dataset si elle n'existe pas.
    Le SHA-256 permet de reconnaître un fichier déjà importé
    et participe à l'idempotence et à la traçabilité.
    """
    result = await connection.execute(
        text(
            """
            SELECT dataset_id
            FROM dataset
            WHERE archive_sha256 = :sha256
            LIMIT 1
            """
        ),
        {
            "sha256": sha256,
        },
    )
    existing = result.scalar_one_or_none()
    if existing is not None:
        return int(existing)
    metadata_summary = {
        "generator_version": metadata.get("generator_version"),
        "total_sites": metadata.get("total_sites"),
        "total_records": metadata.get("total_records"),
        "date_range": metadata.get("date_range"),
        "frequency": metadata.get("frequency"),
        "null_injection_enabled": metadata.get("null_injection_enabled"),
        "null_strategies": metadata.get("null_strategies"),
        "importer": "historical_import_v1",
    }
    result = await connection.execute(
        text(
            """
            INSERT INTO dataset (
                dataset_name,
                archive_sha256,
                storage_uri,
                source_timezone,
                "metadata"
            )
            VALUES (
                :dataset_name,
                :archive_sha256,
                :storage_uri,
                :source_timezone,
                CAST(:metadata AS jsonb)
            )
            RETURNING dataset_id
            """
        ),
        {
            "dataset_name": ("EnerVision historical dataset 2023-2024"),
            "archive_sha256": sha256,
            "storage_uri": storage_uri,
            "source_timezone": source_timezone,
            "metadata": json.dumps(
                metadata_summary,
                ensure_ascii=False,
            ),
        },
    )
    return int(result.scalar_one())
 async def upsert_sites(
    connection: AsyncConnection,
    frame: pd.DataFrame,
 ) -> None:
    """Insère ou met à jour les sites du dataset."""
    sites = cast(
        list[dict[str, Any]],
        frame[
            [
                "site_id",
                "site_type",
                "site_name",
            ]
        ]
        .drop_duplicates(subset=["site_id"])
        .to_dict(orient="records"),
    )
    await connection.execute(
        text(
            """
            INSERT INTO site (
                site_id,
                site_type,
                site_name
            )
            VALUES (
                :site_id,
                :site_type,
                :site_name
            )
            ON CONFLICT (site_id)
            DO UPDATE SET
                site_type = EXCLUDED.site_type,
                site_name = EXCLUDED.site_name
            """
        ),
        sites,
    )
 def build_reading_batch(
    chunk: pd.DataFrame,
    dataset_id: int,
 ) -> list[dict[str, Any]]:
    """
    Transforme un chunk Pandas en lignes prêtes
    à être chargées dans la table reading.
    """
    rows: list[dict[str, Any]] = []
    records = cast(
        list[dict[str, Any]],
        chunk.to_dict(orient="records"),
    )
    for record in records:
        quality, reasons = classify_quality(record)
        raw_data = {
            column: to_json_value(value)
            for column, value in record.items()
            if column != "_source_timestamp"
        }
        # Dans raw_data, on conserve le timestamp
        # exactement tel qu'il était dans le CSV.
        raw_data["timestamp"] = to_json_value(record["_source_timestamp"])
        rows.append(
            {
                "site_id": record["site_id"],
                "timestamp": record["timestamp"],
                "source": SOURCE_NAME,
                "dataset_id": dataset_id,
                # Non fourni par le dataset historique.
                "consumption_kw": None,
                "consumption_kwh": to_json_value(record["consumption_kwh"]),
                "consumption_euros": to_json_value(record["consumption_euros"]),
                # Non fournis par le CSV historique.
                "voltage_v": None,
                "current_a": None,
                "power_factor": None,
                "temperature_celsius": (to_json_value(record["temperature_celsius"])),
                "humidity_percent": (to_json_value(record["humidity_percent"])),
                "solar_irradiance_wm2": (to_json_value(record["solar_irradiance_wm2"])),
                "is_working_hours": bool(record["is_working_hours"]),
                "data_quality": quality,
                "null_reasons": reasons,
                # Aucune imputation pendant l'ingestion RAW.
                # Les valeurs manquantes sont conservées telles quelles
                # afin de préserver la donnée source.
                "imputed_values": None,
                "imputation_method": None,
                # Conservation de la donnée source
                # pour la traçabilité.
                "raw_data": json.dumps(
                    raw_data,
                    ensure_ascii=False,
                ),
            }
        )
    return rows
 READING_INSERT = text(
    """
    INSERT INTO reading (
        site_id,
        timestamp,
        source,
        dataset_id,
        consumption_kw,
        consumption_kwh,
        consumption_euros,
        voltage_v,
        current_a,
        power_factor,
        temperature_celsius,
        humidity_percent,
        solar_irradiance_wm2,
        is_working_hours,
        data_quality,
        null_reasons,
        imputed_values,
        imputation_method,
        raw_data
    )
    VALUES (
        :site_id,
        :timestamp,
        :source,
        :dataset_id,
        :consumption_kw,
        :consumption_kwh,
        :consumption_euros,
        :voltage_v,
        :current_a,
        :power_factor,
        :temperature_celsius,
        :humidity_percent,
        :solar_irradiance_wm2,
        :is_working_hours,
        :data_quality,
        :null_reasons,
        CAST(:imputed_values AS jsonb),
        :imputation_method,
        CAST(:raw_data AS jsonb)
    )
    ON CONFLICT DO NOTHING
    """
 )
 async def import_historical(
    csv_path: Path,
    metadata_path: Path,
    source_timezone: str,
    batch_size: int,
    dry_run: bool,
    storage_uri: str,
 ) -> None:
    """
    Exécute le pipeline ETL historique EnerVision.
    Étapes :
    1. Extract
    2. Validate
    3. Transform
    4. Load
    """
    metadata = load_metadata(metadata_path)
    frame = pd.read_csv(csv_path)
    validate_source(
        frame,
        metadata,
    )
    print(f"Lignes             : {len(frame)}")
    print(f"Sites              : {frame['site_id'].nunique()}")
    print(f"Période            : {frame['timestamp'].min()} -> {frame['timestamp'].max()}")
    print(f"Doublons           : {frame.duplicated(['site_id', 'timestamp']).sum()}")
    print("\nValeurs NULL :")
    print(frame[MEASURE_COLUMNS].isna().sum())
    sha256 = compute_sha256(csv_path)
    print(f"\nSHA-256            : {sha256}")
    if dry_run:
        print("\nDry-run terminé : aucune donnée écrite.")
        return
    normalized = normalize_timestamps(
        frame,
        source_timezone,
    )
    settings = get_settings()
    engine = create_async_engine(
        str(settings.database_url),
        pool_pre_ping=True,
    )
    try:
        async with engine.begin() as connection:
            dataset_id = await ensure_dataset(
                connection=connection,
                metadata=metadata,
                sha256=sha256,
                source_timezone=source_timezone,
                storage_uri=storage_uri,
            )
            await upsert_sites(
                connection,
                normalized,
            )
            result = await connection.execute(
                text(
                    """
                    SELECT COUNT(*)
                    FROM reading
                    WHERE dataset_id = :dataset_id
                      AND source = :source
                    """
                ),
                {
                    "dataset_id": dataset_id,
                    "source": SOURCE_NAME,
                },
            )
            before = int(result.scalar_one())
            for start in range(
                0,
                len(normalized),
                batch_size,
            ):
                chunk = normalized.iloc[start : start + batch_size]
                rows = build_reading_batch(
                    chunk,
                    dataset_id,
                )
                await connection.execute(
                    READING_INSERT,
                    rows,
                )
                loaded = min(
                    start + batch_size,
                    len(normalized),
                )
                print(f"Chargement : {loaded}/{len(normalized)}")
            result = await connection.execute(
                text(
                    """
                    SELECT COUNT(*)
                    FROM reading
                    WHERE dataset_id = :dataset_id
                      AND source = :source
                    """
                ),
                {
                    "dataset_id": dataset_id,
                    "source": SOURCE_NAME,
                },
            )
            after = int(result.scalar_one())
            print("\nImport terminé.")
            print(f"dataset_id         : {dataset_id}")
            print(f"lectures avant     : {before}")
            print(f"lectures après     : {after}")
            print(f"nouvelles lectures : {after - before}")
    finally:
        await engine.dispose()
 def parse_args() -> argparse.Namespace:
    """Définit les arguments CLI de l'import."""
    parser = argparse.ArgumentParser(description=("Import historique EnerVision"))
    parser.add_argument(
        "--csv",
        type=Path,
        required=True,
        help="Chemin vers le CSV historique.",
    )
    parser.add_argument(
        "--metadata",
        type=Path,
        required=True,
        help=("Chemin vers le fichier dataset_metadata.json."),
    )
    parser.add_argument(
        "--source-timezone",
        default="UTC",
        help=("Timezone associée aux timestamps du dataset. Défaut : UTC."),
    )
    parser.add_argument(
        "--batch-size",
        type=int,
        default=1000,
        help=("Nombre de lignes insérées par batch. Défaut : 1000."),
    )
    parser.add_argument(
        "--dry-run",
        action="store_true",
        help=("Valide les données sans écrire en base."),
    )
    return parser.parse_args()
 def main() -> None:
    """Point d'entrée CLI du pipeline."""
    args = parse_args()
    if args.batch_size <= 0:
        raise ValueError("--batch-size doit être strictement supérieur à 0.")
    # resolve() est volontairement exécuté ici,
    # dans la partie synchrone du programme.
    # Cela évite une opération filesystem bloquante
    # à l'intérieur d'une fonction async.
    storage_uri = args.csv.resolve().as_uri()
    asyncio.run(
        import_historical(
            csv_path=args.csv,
            metadata_path=args.metadata,
            source_timezone=(args.source_timezone),
            batch_size=args.batch_size,
            dry_run=args.dry_run,
            storage_uri=storage_uri,
        )
    )
 if __name__ == "__main__":
    main()
@@ -1,119 +0,0 @@
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
 from pathlib import Path
 from fastapi import Depends, FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.openapi.docs import get_redoc_html, get_swagger_ui_html
 from fastapi.staticfiles import StaticFiles
 from prometheus_fastapi_instrumentator import Instrumentator
 from starlette.requests import Request
 from starlette.responses import HTMLResponse
 from app.api.errors import register_error_handlers
 from app.api.middleware import SecurityHeadersMiddleware
 from app.api.openapi import DESCRIPTION, SUMMARY, TAGS
 from app.api.security import require_metrics_token
 from app.api.v1.router import api_router
 from app.core.config import Settings, get_settings
 from app.core.logging import configure_logging, get_logger
 from app.db.session import get_engine
 logger = get_logger(__name__)
 METHODES_AUTORISEES = ["GET", "POST", "PATCH", "PUT", "DELETE", "OPTIONS"]
 EN_TETES_AUTORISES = ["Authorization", "Content-Type"]
 STATIC_DIR = Path(__file__).parent / "static"
 LOGO_URL = "/static/logo-icon.png"
@asynccontextmanager
 async def lifespan(_: FastAPI) -> AsyncIterator[None]:
    settings = get_settings()
    logger.info(
        "Démarrage de %s %s en environnement %s", settings.name, settings.version, settings.env
    )
    yield
    await get_engine().dispose()
 def create_app(settings: Settings | None = None) -> FastAPI:
    resolved = settings or get_settings()
    configure_logging(resolved)
    documentee = resolved.api_docs_are_exposed
    application = FastAPI(
        title=resolved.name,
        version=resolved.version,
        summary=SUMMARY,
        description=DESCRIPTION,
        openapi_tags=TAGS,
        debug=resolved.debug,
        lifespan=lifespan,
        docs_url=None,
        redoc_url=None,
        openapi_url="/openapi.json" if documentee else None,
    )
    if documentee:
        application.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")
        # ReDoc supporte nativement `info.x-logo` (extension Redocly) pour afficher un logo
        # en en-tête ; Swagger UI n'a pas d'equivalent, il ne reprend que le favicon.
        openapi_original = application.openapi
        def openapi_avec_logo() -> dict[str, object]:
            schema = openapi_original()
            schema["info"]["x-logo"] = {"url": LOGO_URL, "altText": "EnerVision"}
            return schema
        application.openapi = openapi_avec_logo  # type: ignore[method-assign]
        @application.get("/docs", include_in_schema=False)
        async def docs_swagger(_: Request) -> HTMLResponse:
            return get_swagger_ui_html(
                openapi_url="/openapi.json",
                title=f"{application.title} · Swagger UI",
                swagger_favicon_url=LOGO_URL,
            )
        @application.get("/redoc", include_in_schema=False)
        async def docs_redoc(_: Request) -> HTMLResponse:
            return get_redoc_html(
                openapi_url="/openapi.json",
                title=f"{application.title} · ReDoc",
                redoc_favicon_url=LOGO_URL,
            )
    application.add_middleware(SecurityHeadersMiddleware)
    if resolved.allowed_origins:
        # Méthodes et en-têtes listés plutôt que joker : avec `allow_credentials`, la liste
        # d'origines devient l'unique contrôle, autant documenter le contrat exact.
        application.add_middleware(
            CORSMiddleware,
            allow_origins=resolved.allowed_origins,
            allow_credentials=True,
            allow_methods=METHODES_AUTORISEES,
            allow_headers=EN_TETES_AUTORISES,
            expose_headers=["Retry-After"],
            max_age=600,
        )
    register_error_handlers(application)
    Instrumentator().instrument(application).expose(
        application,
        endpoint="/metrics",
        include_in_schema=False,
        dependencies=[Depends(require_metrics_token)],
    )
    application.include_router(api_router, prefix=resolved.api_prefix)
    # Piège : sans cette surcharge, une configuration passée à `create_app()` ne piloterait
    # que la construction, et les dépendances continueraient de lire `get_settings()` depuis
    # l'environnement. Un test « en production » ne testerait alors pas la production.
    if settings is not None:
        application.dependency_overrides[get_settings] = lambda: resolved
    return application
@@ -1,25 +0,0 @@
 # Piège : tout modèle absent de ce module reste invisible de `alembic revision
 # --autogenerate`, qui générerait alors un drop de sa table.
 from app.models.audit_log import AuditLog
 from app.models.energy import Alert, Dataset, Prediction, Reading, Recommendation, Site
 from app.models.login_attempt import LoginAttempt
 from app.models.password_reset_attempt import PasswordResetAttempt
 from app.models.password_reset_token import PasswordResetToken
 from app.models.refresh_token import RefreshToken
 from app.models.user import AppUser
 __all__ = [
    "Alert",
    "AppUser",
    "AuditLog",
    "Dataset",
    "LoginAttempt",
    "PasswordResetAttempt",
    "PasswordResetToken",
    "Prediction",
    "Reading",
    "Recommendation",
    "RefreshToken",
    "Site",
 ]
@@ -1,66 +0,0 @@
 # Pourquoi : `actor_id` ne porte volontairement aucune clé étrangère. Une contrainte
 # `ON DELETE SET NULL` déclencherait un UPDATE que le déclencheur d'ajout seul refuserait, donc
 # la suppression d'un compte échouerait ; une contrainte `NO ACTION` interdirait toute
 # suppression. `actor_email` et `actor_role` sont dénormalisés pour la même raison : le journal
 # dit ce qui était vrai au moment de l'acte, pas ce qui est vrai aujourd'hui.
 import uuid
 from datetime import datetime
 from enum import StrEnum
 from typing import Any
 from sqlalchemy import BigInteger, CheckConstraint, DateTime, Identity, Index, Text, func
 from sqlalchemy.dialects.postgresql import INET, JSONB
 from sqlalchemy.dialects.postgresql import UUID as PG_UUID
 from sqlalchemy.orm import Mapped, mapped_column
 from app.db.base import Base
 class AuditOutcome(StrEnum):
    SUCCES = "success"
    ECHEC = "failure"
 class AuditAction(StrEnum):
    COMPTE_CREE = "user.created"
    COMPTE_ROLE_CHANGE = "user.role_changed"
    COMPTE_DESACTIVE = "user.disabled"
    COMPTE_ACTIVE = "user.enabled"
    COMPTE_MOT_DE_PASSE_REINITIALISE = "user.password_reset_by_admin"
    COMPTE_MOT_DE_PASSE_CHANGE = "user.password_changed"
    MOT_DE_PASSE_OUBLIE_DEMANDE = "auth.password_reset_requested"
    MOT_DE_PASSE_REINITIALISE_PAR_SOI = "auth.password_reset_self_service"
    REFRESH_REUTILISE = "auth.refresh_reuse_detected"
    SESSIONS_REVOQUEES = "auth.all_sessions_revoked"
    LIMITE_PAR_IDENTIFIANT = "auth.identifier_throttled"
    ADMIN_AMORCE = "bootstrap.admin_created"
 ISSUES_AUTORISEES = ", ".join(f"'{issue.value}'" for issue in AuditOutcome)
 class AuditLog(Base):
    __tablename__ = "audit_log"
    __table_args__ = (
        CheckConstraint(f"outcome in ({ISSUES_AUTORISEES})", name="ck_audit_log_outcome"),
        Index("ix_audit_log_date", "occurred_at"),
        Index("ix_audit_log_action_date", "action", "occurred_at"),
    )
    id: Mapped[int] = mapped_column(BigInteger, Identity(always=True), primary_key=True)
    occurred_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )
    actor_id: Mapped[uuid.UUID | None] = mapped_column(PG_UUID(as_uuid=True), nullable=True)
    actor_email: Mapped[str | None] = mapped_column(Text, nullable=True)
    actor_role: Mapped[str | None] = mapped_column(Text, nullable=True)
    action: Mapped[str] = mapped_column(Text, nullable=False)
    target_type: Mapped[str | None] = mapped_column(Text, nullable=True)
    target_id: Mapped[str | None] = mapped_column(Text, nullable=True)
    outcome: Mapped[str] = mapped_column(Text, nullable=False)
    client_ip: Mapped[str | None] = mapped_column(INET, nullable=True)
    user_agent: Mapped[str | None] = mapped_column(Text, nullable=True)
    detail: Mapped[dict[str, Any]] = mapped_column(
        JSONB, nullable=False, server_default=func.jsonb_build_object()
    )
@@ -1,210 +0,0 @@
 """Tables du modèle de données EnerVision (CSV, API Mock et résultats ML)."""
 from datetime import datetime
 from decimal import Decimal
 from typing import Any
 from sqlalchemy import (
    BigInteger,
    Boolean,
    CheckConstraint,
    DateTime,
    Double,
    ForeignKey,
    ForeignKeyConstraint,
    Index,
    Integer,
    Numeric,
    String,
    Text,
    UniqueConstraint,
    func,
    text,
 )
 from sqlalchemy.dialects.postgresql import ARRAY, JSONB
 from sqlalchemy.orm import Mapped, mapped_column
 from app.db.base import Base
 class Dataset(Base):
    __tablename__ = "dataset"
    __table_args__ = (
        CheckConstraint("dataset_id > 0", name="ck_dataset_positive_id"),
        UniqueConstraint("archive_sha256", name="uq_dataset_archive_sha256"),
    )
    dataset_id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=True)
    dataset_name: Mapped[str] = mapped_column(Text)
    archive_sha256: Mapped[str] = mapped_column(String(64))
    storage_uri: Mapped[str] = mapped_column(Text)
    source_timezone: Mapped[str | None] = mapped_column(Text)
    # "metadata" est réservé par SQLAlchemy ; le nom SQL reste inchangé.
    dataset_metadata: Mapped[dict[str, Any]] = mapped_column("metadata", JSONB(none_as_null=True))
 class Site(Base):
    __tablename__ = "site"
    site_id: Mapped[str] = mapped_column(Text, primary_key=True)
    site_name: Mapped[str] = mapped_column(Text)
    site_type: Mapped[str] = mapped_column(Text)
    location: Mapped[str | None] = mapped_column(Text)
    capacity_kw: Mapped[float | None] = mapped_column(Double)
    status: Mapped[str | None] = mapped_column(Text)
 class Reading(Base):
    __tablename__ = "reading"
    __table_args__ = (
        CheckConstraint(
            "source IN ('csv', 'api_current', 'api_history')", name="ck_reading_source"
        ),
        CheckConstraint(
            "(source = 'csv' AND dataset_id IS NOT NULL) OR "
            "(source IN ('api_current', 'api_history') AND dataset_id IS NULL)",
            name="ck_reading_dataset_source",
        ),
        CheckConstraint(
            "data_quality IS NULL OR data_quality IN ('good', 'partial', 'degraded', 'critical')",
            name="ck_reading_quality",
        ),
        CheckConstraint(
            "(imputed_values IS NULL AND imputation_method IS NULL) OR "
            "(imputed_values IS NOT NULL AND imputation_method IS NOT NULL)",
            name="ck_reading_imputation",
        ),
        Index("ix_reading_site_timestamp", "site_id", "timestamp"),
        Index("ix_reading_dataset_id", "dataset_id"),
    )
    reading_id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=True)
    site_id: Mapped[str] = mapped_column(
        Text, ForeignKey("site.site_id", name="fk_reading_site", ondelete="RESTRICT")
    )
    timestamp: Mapped[datetime] = mapped_column(DateTime(timezone=True), primary_key=True)
    source: Mapped[str] = mapped_column(Text)
    dataset_id: Mapped[int | None] = mapped_column(
        BigInteger,
        ForeignKey("dataset.dataset_id", name="fk_reading_dataset", ondelete="RESTRICT"),
    )
    consumption_kw: Mapped[float | None] = mapped_column(Double)
    consumption_kwh: Mapped[float | None] = mapped_column(Double)
    consumption_euros: Mapped[Decimal | None] = mapped_column(Numeric(14, 2))
    voltage_v: Mapped[float | None] = mapped_column(Double)
    current_a: Mapped[float | None] = mapped_column(Double)
    power_factor: Mapped[float | None] = mapped_column(Double)
    temperature_celsius: Mapped[float | None] = mapped_column(Double)
    humidity_percent: Mapped[float | None] = mapped_column(Double)
    solar_irradiance_wm2: Mapped[float | None] = mapped_column(Double)
    is_working_hours: Mapped[bool | None] = mapped_column(Boolean)
    data_quality: Mapped[str | None] = mapped_column(Text)
    null_reasons: Mapped[list[str] | None] = mapped_column(ARRAY(Text))
    imputed_values: Mapped[dict[str, Any] | None] = mapped_column(JSONB(none_as_null=True))
    imputation_method: Mapped[str | None] = mapped_column(Text)
    ingested_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), server_default=func.now()
    )
    raw_data: Mapped[dict[str, Any]] = mapped_column(JSONB(none_as_null=True))
 Index(
    "uq_reading_source",
    Reading.site_id,
    Reading.timestamp,
    Reading.source,
    func.coalesce(Reading.dataset_id, text("0")),
    unique=True,
 )
 class Prediction(Base):
    __tablename__ = "prediction"
    __table_args__ = (
        UniqueConstraint("prediction_id", "site_id", name="uq_prediction_id_site"),
        Index("ix_prediction_site_target", "site_id", "target_at"),
        CheckConstraint(
            "target_metric IN ('consumption_kwh', 'consumption_kw')",
            name="ck_prediction_metric",
        ),
        CheckConstraint(
            "period_minutes IS NULL OR period_minutes > 0", name="ck_prediction_period"
        ),
        CheckConstraint(
            "target_metric <> 'consumption_kwh' OR period_minutes IS NOT NULL",
            name="ck_prediction_energy_period",
        ),
        CheckConstraint(
            "(status = 'available' AND predicted_value IS NOT NULL AND failure_reason IS NULL) OR "
            "(status IN ('insufficient_data', 'error') AND predicted_value IS NULL "
            "AND failure_reason IS NOT NULL)",
            name="ck_prediction_status",
        ),
    )
    prediction_id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=True)
    site_id: Mapped[str] = mapped_column(
        Text, ForeignKey("site.site_id", name="fk_prediction_site", ondelete="RESTRICT")
    )
    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
    target_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
    target_metric: Mapped[str] = mapped_column(Text)
    period_minutes: Mapped[int | None] = mapped_column(Integer)
    predicted_value: Mapped[float | None] = mapped_column(Double)
    model_reference: Mapped[str] = mapped_column(Text)
    status: Mapped[str] = mapped_column(Text)
    failure_reason: Mapped[str | None] = mapped_column(Text)
 class Alert(Base):
    __tablename__ = "alert"
    __table_args__ = (
        UniqueConstraint("source", "site_id", "source_alert_id", name="uq_alert_source_reference"),
        Index("ix_alert_site_timestamp", "site_id", "timestamp"),
        ForeignKeyConstraint(
            ["prediction_id", "site_id"],
            ["prediction.prediction_id", "prediction.site_id"],
            name="fk_alert_prediction_site",
            ondelete="RESTRICT",
        ),
        CheckConstraint("source IN ('api_mock', 'enervision')", name="ck_alert_source"),
        CheckConstraint(
            "type IN ('spike', 'threshold', 'anomaly', 'outage', 'sensor')", name="ck_alert_type"
        ),
        CheckConstraint(
            "severity IN ('low', 'medium', 'high', 'critical')", name="ck_alert_severity"
        ),
    )
    alert_id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=True)
    source_alert_id: Mapped[str] = mapped_column(Text)
    site_id: Mapped[str] = mapped_column(
        Text, ForeignKey("site.site_id", name="fk_alert_site", ondelete="RESTRICT")
    )
    source: Mapped[str] = mapped_column(Text)
    timestamp: Mapped[datetime] = mapped_column(DateTime(timezone=True))
    type: Mapped[str] = mapped_column(Text)
    severity: Mapped[str] = mapped_column(Text)
    message: Mapped[str] = mapped_column(Text)
    value: Mapped[float | None] = mapped_column(Double)
    threshold: Mapped[float | None] = mapped_column(Double)
    metric: Mapped[str | None] = mapped_column(Text)
    prediction_id: Mapped[int | None] = mapped_column(BigInteger)
    raw_data: Mapped[dict[str, Any]] = mapped_column(JSONB(none_as_null=True))
 class Recommendation(Base):
    __tablename__ = "recommendation"
    __table_args__ = (
        UniqueConstraint("alert_id", "rule_reference", name="uq_recommendation_alert_rule"),
    )
    recommendation_id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=True)
    alert_id: Mapped[int] = mapped_column(
        BigInteger,
        ForeignKey("alert.alert_id", name="fk_recommendation_alert", ondelete="RESTRICT"),
    )
    action: Mapped[str] = mapped_column(Text)
    explanation: Mapped[str] = mapped_column(Text)
    rule_reference: Mapped[str] = mapped_column(Text)
    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
@@ -1,44 +0,0 @@
 # Pourquoi : les tentatives vivent ici et non dans `audit_log`, qui est en ajout seul. Leur
 # volume est piloté par l'attaquant : une force brute y écrirait des millions de lignes
 # indestructibles. Cette table-ci se purge, et c'est aussi le compteur de la limitation.
 # Piège : la tentative est enregistrée même quand l'email est inconnu, sinon le 429 dirait
 # qu'un compte existe.
 import uuid
 from datetime import datetime
 from enum import StrEnum
 from sqlalchemy import BigInteger, CheckConstraint, DateTime, Identity, Index, String, Text, func
 from sqlalchemy.dialects.postgresql import INET
 from sqlalchemy.dialects.postgresql import UUID as PG_UUID
 from sqlalchemy.orm import Mapped, mapped_column
 from app.db.base import Base
 class LoginOutcome(StrEnum):
    SUCCES = "success"
    IDENTIFIANTS_INVALIDES = "bad_credentials"
    LIMITE = "throttled"
    COMPTE_INDISPONIBLE = "inactive"
 ISSUES_AUTORISEES = ", ".join(f"'{issue.value}'" for issue in LoginOutcome)
 class LoginAttempt(Base):
    __tablename__ = "login_attempt"
    __table_args__ = (
        CheckConstraint(f"outcome in ({ISSUES_AUTORISEES})", name="ck_login_attempt_outcome"),
        Index("ix_login_attempt_email_date", "email_tried", "occurred_at"),
        Index("ix_login_attempt_ip_date", "client_ip", "occurred_at"),
    )
    id: Mapped[int] = mapped_column(BigInteger, Identity(always=True), primary_key=True)
    occurred_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )
    email_tried: Mapped[str] = mapped_column(String(320), nullable=False)
    client_ip: Mapped[str | None] = mapped_column(INET, nullable=True)
    outcome: Mapped[str] = mapped_column(Text, nullable=False)
    user_id: Mapped[uuid.UUID | None] = mapped_column(PG_UUID(as_uuid=True), nullable=True)
@@ -1,27 +0,0 @@
 # Pourquoi : même séparation que `login_attempt` par rapport à `audit_log` : ce compteur est
 # piloté par l'attaquant (une campagne de demandes) et se purge, l'audit log est en ajout seul.
 # Piège : la tentative est enregistrée même quand l'email est inconnu, sinon le 429 apprendrait
 # qu'un compte existe.
 from datetime import datetime
 from sqlalchemy import BigInteger, DateTime, Identity, Index, String, func
 from sqlalchemy.dialects.postgresql import INET
 from sqlalchemy.orm import Mapped, mapped_column
 from app.db.base import Base
 class PasswordResetAttempt(Base):
    __tablename__ = "password_reset_attempt"
    __table_args__ = (
        Index("ix_password_reset_attempt_email_date", "email_tried", "occurred_at"),
        Index("ix_password_reset_attempt_ip_date", "client_ip", "occurred_at"),
    )
    id: Mapped[int] = mapped_column(BigInteger, Identity(always=True), primary_key=True)
    occurred_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )
    email_tried: Mapped[str] = mapped_column(String(320), nullable=False)
    client_ip: Mapped[str | None] = mapped_column(INET, nullable=True)
@@ -1,40 +0,0 @@
 # Pourquoi : même schéma que `refresh_token` (chaîne opaque, jamais un JWT) pour la même
 # raison : un jeton de réinitialisation doit être révocable d'un coup, et un JWT ne figure
 # dans aucune ligne à invalider.
 import uuid
 from datetime import datetime
 from sqlalchemy import DateTime, ForeignKey, Index, LargeBinary, Text, func
 from sqlalchemy.dialects.postgresql import INET
 from sqlalchemy.dialects.postgresql import UUID as PG_UUID
 from sqlalchemy.orm import Mapped, mapped_column
 from app.db.base import Base
 class PasswordResetToken(Base):
    __tablename__ = "password_reset_token"
    __table_args__ = (
        Index("ix_password_reset_token_user", "user_id"),
        Index(
            "ix_password_reset_token_vivants",
            "user_id",
            postgresql_where="consumed_at is null",
        ),
    )
    id: Mapped[uuid.UUID] = mapped_column(
        PG_UUID(as_uuid=True), primary_key=True, server_default=func.gen_random_uuid()
    )
    user_id: Mapped[uuid.UUID] = mapped_column(
        PG_UUID(as_uuid=True), ForeignKey("app_user.id", ondelete="CASCADE"), nullable=False
    )
    token_hash: Mapped[bytes] = mapped_column(LargeBinary, nullable=False, unique=True)
    issued_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )
    expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
    consumed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
    client_ip: Mapped[str | None] = mapped_column(INET, nullable=True)
    user_agent: Mapped[str | None] = mapped_column(Text, nullable=True)
@@ -1,64 +0,0 @@
 # Pourquoi : un jeton de rafraîchissement est une chaîne opaque, jamais un JWT. Il doit être
 # révocable, donc cette ligne existe de toute façon ; le JWT n'ajouterait qu'un second chemin de
 # signature. Surtout, la séparation devient structurelle : un JWT ne figure dans aucune ligne,
 # une chaîne opaque échoue au décodage. Aucune confusion de type n'est possible.
 # Piège : `expires_at` est absolu et hérité du prédécesseur à chaque rotation. S'il glissait,
 # la promesse de sept jours serait fictive et une session active ne finirait jamais.
 import uuid
 from datetime import datetime
 from enum import StrEnum
 from sqlalchemy import CheckConstraint, DateTime, ForeignKey, Index, LargeBinary, Text, func
 from sqlalchemy.dialects.postgresql import INET
 from sqlalchemy.dialects.postgresql import UUID as PG_UUID
 from sqlalchemy.orm import Mapped, mapped_column
 from app.db.base import Base
 class RevocationReason(StrEnum):
    DECONNEXION = "logout"
    ROTATION = "rotation"
    REUTILISATION = "reuse_detected"
    CHANGEMENT_MOT_DE_PASSE = "password_change"
    ADMINISTRATION = "admin"
 MOTIFS_AUTORISES = ", ".join(f"'{motif.value}'" for motif in RevocationReason)
 class RefreshToken(Base):
    __tablename__ = "refresh_token"
    __table_args__ = (
        CheckConstraint(
            f"revoked_reason is null or revoked_reason in ({MOTIFS_AUTORISES})",
            name="ck_refresh_token_revoked_reason",
        ),
        Index("ix_refresh_token_family", "family_id"),
        Index("ix_refresh_token_user", "user_id"),
        Index(
            "ix_refresh_token_vivants",
            "user_id",
            postgresql_where="revoked_at is null and rotated_at is null",
        ),
    )
    id: Mapped[uuid.UUID] = mapped_column(
        PG_UUID(as_uuid=True), primary_key=True, server_default=func.gen_random_uuid()
    )
    family_id: Mapped[uuid.UUID] = mapped_column(PG_UUID(as_uuid=True), nullable=False)
    user_id: Mapped[uuid.UUID] = mapped_column(
        PG_UUID(as_uuid=True), ForeignKey("app_user.id", ondelete="CASCADE"), nullable=False
    )
    token_hash: Mapped[bytes] = mapped_column(LargeBinary, nullable=False, unique=True)
    issued_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )
    expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
    rotated_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
    revoked_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
    revoked_reason: Mapped[str | None] = mapped_column(Text, nullable=True)
    replaced_by: Mapped[uuid.UUID | None] = mapped_column(PG_UUID(as_uuid=True), nullable=True)
    client_ip: Mapped[str | None] = mapped_column(INET, nullable=True)
    user_agent: Mapped[str | None] = mapped_column(Text, nullable=True)
@@ -1,50 +0,0 @@
 # Contrainte : la table s'appelle `app_user` et non `user`, qui est un mot réservé PostgreSQL,
 # raccourci de `CURRENT_USER`. Le nom rappelle aussi qu'il s'agit d'un compte applicatif, par
 # opposition au rôle PostgreSQL qui porte, lui, le cantonnement des accès.
 import uuid
 from datetime import datetime
 from sqlalchemy import Boolean, CheckConstraint, DateTime, String, Text, func, text
 from sqlalchemy.dialects.postgresql import UUID as PG_UUID
 from sqlalchemy.orm import Mapped, mapped_column
 from app.core.roles import AccountKind, Role
 from app.db.base import Base
 ROLES_AUTORISES = ", ".join(f"'{role.value}'" for role in Role)
 NATURES_AUTORISEES = ", ".join(f"'{nature.value}'" for nature in AccountKind)
 class AppUser(Base):
    __tablename__ = "app_user"
    __table_args__ = (
        CheckConstraint("email = lower(email)", name="ck_app_user_email_minuscule"),
        CheckConstraint(f"role in ({ROLES_AUTORISES})", name="ck_app_user_role"),
        CheckConstraint(f"kind in ({NATURES_AUTORISEES})", name="ck_app_user_kind"),
    )
    id: Mapped[uuid.UUID] = mapped_column(
        PG_UUID(as_uuid=True), primary_key=True, server_default=func.gen_random_uuid()
    )
    email: Mapped[str] = mapped_column(String(320), unique=True, nullable=False)
    password_hash: Mapped[str] = mapped_column(Text, nullable=False)
    role: Mapped[str] = mapped_column(Text, nullable=False)
    kind: Mapped[str] = mapped_column(Text, nullable=False, server_default=text("'human'"))
    is_active: Mapped[bool] = mapped_column(Boolean, nullable=False, server_default=text("true"))
    must_change_password: Mapped[bool] = mapped_column(
        Boolean, nullable=False, server_default=text("false")
    )
    # Une seule colonne couvre le changement de mot de passe, le changement de rôle et la
    # désactivation : tout jeton émis avant cet instant est périmé.
    credentials_changed_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )
    last_login_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
    full_name: Mapped[str | None] = mapped_column(Text, nullable=True)
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )
    updated_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now(), onupdate=func.now()
    )
@@ -1,21 +0,0 @@
 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()
@@ -1,62 +0,0 @@
 # Piège : `detail` passe par une liste blanche de clés et jamais par un `dict(**kwargs)`. La
 # table est en ajout seul : une clé inattendue qui porterait un secret ou une donnée
 # personnelle ne pourrait plus en être retirée.
 from collections.abc import Mapping
 from typing import Any
 from sqlalchemy.ext.asyncio import AsyncSession
 from app.core.principal import Principal
 from app.models.audit_log import AuditAction, AuditLog, AuditOutcome
 CLES_DE_DETAIL_AUTORISEES = frozenset(
    {
        "email",
        "role_avant",
        "role_apres",
        "famille",
        "motif",
        "source",
        "sessions_revoquees",
    }
 )
 def assemble_detail(brut: Mapping[str, Any] | None) -> dict[str, Any]:
    if not brut:
        return {}
    return {cle: valeur for cle, valeur in brut.items() if cle in CLES_DE_DETAIL_AUTORISEES}
 class AuditLogRepository:
    def __init__(self, session: AsyncSession) -> None:
        self._session = session
    async def record(
        self,
        *,
        action: AuditAction,
        outcome: AuditOutcome = AuditOutcome.SUCCES,
        actor: Principal | None = None,
        actor_label: str | None = None,
        target_type: str | None = None,
        target_id: str | None = None,
        client_ip: str | None = None,
        user_agent: str | None = None,
        detail: Mapping[str, Any] | None = None,
    ) -> None:
        self._session.add(
            AuditLog(
                actor_id=actor.id if actor else None,
                actor_email=actor.email if actor else actor_label,
                actor_role=actor.role.value if actor else None,
                action=action.value,
                target_type=target_type,
                target_id=target_id,
                outcome=outcome.value,
                client_ip=client_ip,
                user_agent=user_agent,
                detail=assemble_detail(detail),
            )
        )
@@ -1,67 +0,0 @@
 # Pourquoi : les trois compteurs tiennent en une seule requête, grâce aux clauses FILTER de
 # PostgreSQL. Trois `count(*)` séparés feraient trois allers-retours sur le chemin critique de
 # la connexion, qui est justement celui qu'un attaquant martèle.
 from dataclasses import dataclass
 from datetime import UTC, datetime, timedelta
 from uuid import UUID
 from sqlalchemy import and_, func, select
 from sqlalchemy.ext.asyncio import AsyncSession
 from app.models.login_attempt import LoginAttempt, LoginOutcome
@dataclass(frozen=True, slots=True)
 class FailureCounts:
    per_identifier_and_ip: int
    per_ip: int
    per_identifier: int
 class LoginAttemptRepository:
    def __init__(self, session: AsyncSession) -> None:
        self._session = session
    async def record(
        self,
        *,
        email: str,
        client_ip: str | None,
        outcome: LoginOutcome,
        user_id: UUID | None = None,
    ) -> None:
        self._session.add(
            LoginAttempt(
                email_tried=email.strip().lower(),
                client_ip=client_ip,
                outcome=outcome.value,
                user_id=user_id,
            )
        )
    async def count_recent_failures(
        self, *, email: str, client_ip: str | None, window_seconds: int
    ) -> FailureCounts:
        identifiant = email.strip().lower()
        meme_email = LoginAttempt.email_tried == identifiant
        meme_ip = LoginAttempt.client_ip == client_ip
        requete = select(
            func.count().filter(and_(meme_email, meme_ip)),
            func.count().filter(meme_ip),
            func.count().filter(meme_email),
        ).where(
            LoginAttempt.outcome != LoginOutcome.SUCCES.value,
            LoginAttempt.occurred_at > datetime.now(UTC) - timedelta(seconds=window_seconds),
            meme_email | meme_ip,
        )
        par_identifiant_et_ip, par_ip, par_identifiant = (
            await self._session.execute(requete)
        ).one()
        return FailureCounts(
            per_identifier_and_ip=par_identifiant_et_ip,
            per_ip=par_ip,
            per_identifier=par_identifiant,
        )
@@ -1,42 +0,0 @@
 from dataclasses import dataclass
 from datetime import UTC, datetime, timedelta
 from sqlalchemy import func, select
 from sqlalchemy.ext.asyncio import AsyncSession
 from app.models.password_reset_attempt import PasswordResetAttempt
@dataclass(frozen=True, slots=True)
 class ResetRequestCounts:
    per_identifier: int
    per_ip: int
 class PasswordResetAttemptRepository:
    def __init__(self, session: AsyncSession) -> None:
        self._session = session
    async def record(self, *, email: str, client_ip: str | None) -> None:
        self._session.add(
            PasswordResetAttempt(email_tried=email.strip().lower(), client_ip=client_ip)
        )
    async def count_recent(
        self, *, email: str, client_ip: str | None, window_seconds: int
    ) -> ResetRequestCounts:
        identifiant = email.strip().lower()
        meme_email = PasswordResetAttempt.email_tried == identifiant
        meme_ip = PasswordResetAttempt.client_ip == client_ip
        requete = select(
            func.count().filter(meme_email),
            func.count().filter(meme_ip),
        ).where(
            PasswordResetAttempt.occurred_at
            > datetime.now(UTC) - timedelta(seconds=window_seconds),
            meme_email | meme_ip,
        )
        par_identifiant, par_ip = (await self._session.execute(requete)).one()
        return ResetRequestCounts(per_identifier=par_identifiant, per_ip=par_ip)
@@ -1,78 +0,0 @@
 # Piège : `consume()` est une seule instruction, sur le modèle de `claim_for_rotation()` du
 # jeton de rafraîchissement. Un SELECT puis un UPDATE laisseraient une fenêtre où deux
 # soumissions concurrentes du même lien réussiraient toutes les deux.
 from dataclasses import dataclass
 from datetime import datetime
 from uuid import UUID
 from sqlalchemy import func, select, update
 from sqlalchemy.ext.asyncio import AsyncSession
 from app.models.password_reset_token import PasswordResetToken
@dataclass(frozen=True, slots=True)
 class ConsumedResetToken:
    id: UUID
    user_id: UUID
 class PasswordResetTokenRepository:
    def __init__(self, session: AsyncSession) -> None:
        self._session = session
    async def create(
        self,
        *,
        user_id: UUID,
        token_hash: bytes,
        expires_at: datetime,
        client_ip: str | None,
        user_agent: str | None,
    ) -> PasswordResetToken:
        jeton = PasswordResetToken(
            user_id=user_id,
            token_hash=token_hash,
            expires_at=expires_at,
            client_ip=client_ip,
            user_agent=user_agent,
        )
        self._session.add(jeton)
        await self._session.flush()
        return jeton
    async def consume(self, token_hash: bytes) -> ConsumedResetToken | None:
        requete = (
            update(PasswordResetToken)
            .where(
                PasswordResetToken.token_hash == token_hash,
                PasswordResetToken.consumed_at.is_(None),
                PasswordResetToken.expires_at > func.clock_timestamp(),
            )
            .values(consumed_at=func.clock_timestamp())
            .returning(PasswordResetToken.id, PasswordResetToken.user_id)
        )
        ligne = (await self._session.execute(requete)).one_or_none()
        if ligne is None:
            return None
        return ConsumedResetToken(id=ligne.id, user_id=ligne.user_id)
    # Piège : simple SELECT, volontairement pas atomique avec la consommation. Sert seulement
    # au feedback UX (jeton encore valide ?) ; `consume()` reste la seule source de vérité.
    async def exists_valid(self, token_hash: bytes) -> bool:
        requete = select(PasswordResetToken.id).where(
            PasswordResetToken.token_hash == token_hash,
            PasswordResetToken.consumed_at.is_(None),
            PasswordResetToken.expires_at > func.clock_timestamp(),
        )
        return (await self._session.execute(requete)).first() is not None
    async def invalidate_all_for_user(self, user_id: UUID) -> int:
        resultat = await self._session.execute(
            update(PasswordResetToken)
            .where(PasswordResetToken.user_id == user_id, PasswordResetToken.consumed_at.is_(None))
            .values(consumed_at=func.clock_timestamp())
            .returning(PasswordResetToken.id)
        )
        return len(resultat.all())
@@ -1,42 +0,0 @@
 from collections.abc import Sequence
 from datetime import datetime
 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()
    async def list_history(
        self,
        *,
        start: datetime,
        end: datetime,
        site_id: str | None = None,
        limit: int,
        offset: int,
    ) -> Sequence[Reading]:
        requete = (
            select(Reading)
            .where(Reading.timestamp >= start, Reading.timestamp < end)
            .order_by(Reading.timestamp.desc(), Reading.reading_id.desc())
            .limit(limit)
            .offset(offset)
        )
        if site_id is not None:
            requete = requete.where(Reading.site_id == site_id)
        return (await self._session.scalars(requete)).all()
@@ -1,22 +0,0 @@
 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
@@ -1,106 +0,0 @@
 # Piège : `claim_for_rotation()` est une seule instruction. Un SELECT puis un UPDATE
 # laisseraient une fenêtre où deux onglets réussissent la même rotation. Zéro ligne retournée
 # signifie donc, sans ambiguïté, que le jeton était déjà tourné, révoqué, expiré ou inconnu, et
 # c'est `inspect()` qui départage ensuite ces cas.
 from dataclasses import dataclass
 from datetime import datetime
 from uuid import UUID
 from sqlalchemy import func, select, update
 from sqlalchemy.ext.asyncio import AsyncSession
 from app.models.refresh_token import RefreshToken, RevocationReason
@dataclass(frozen=True, slots=True)
 class ClaimedToken:
    id: UUID
    family_id: UUID
    user_id: UUID
    expires_at: datetime
 class RefreshTokenRepository:
    def __init__(self, session: AsyncSession) -> None:
        self._session = session
    async def create(
        self,
        *,
        user_id: UUID,
        family_id: UUID,
        token_hash: bytes,
        expires_at: datetime,
        client_ip: str | None,
        user_agent: str | None,
    ) -> RefreshToken:
        jeton = RefreshToken(
            user_id=user_id,
            family_id=family_id,
            token_hash=token_hash,
            expires_at=expires_at,
            client_ip=client_ip,
            user_agent=user_agent,
        )
        self._session.add(jeton)
        await self._session.flush()
        return jeton
    async def claim_for_rotation(self, token_hash: bytes) -> ClaimedToken | None:
        requete = (
            update(RefreshToken)
            .where(
                RefreshToken.token_hash == token_hash,
                RefreshToken.rotated_at.is_(None),
                RefreshToken.revoked_at.is_(None),
                RefreshToken.expires_at > func.clock_timestamp(),
            )
            .values(
                rotated_at=func.clock_timestamp(),
                revoked_at=func.clock_timestamp(),
                revoked_reason=RevocationReason.ROTATION.value,
            )
            .returning(
                RefreshToken.id,
                RefreshToken.family_id,
                RefreshToken.user_id,
                RefreshToken.expires_at,
            )
        )
        ligne = (await self._session.execute(requete)).one_or_none()
        if ligne is None:
            return None
        return ClaimedToken(
            id=ligne.id,
            family_id=ligne.family_id,
            user_id=ligne.user_id,
            expires_at=ligne.expires_at,
        )
    async def inspect(self, token_hash: bytes) -> RefreshToken | None:
        requete = select(RefreshToken).where(RefreshToken.token_hash == token_hash)
        return (await self._session.execute(requete)).scalar_one_or_none()
    async def link_replacement(self, ancien_id: UUID, nouveau_id: UUID) -> None:
        await self._session.execute(
            update(RefreshToken).where(RefreshToken.id == ancien_id).values(replaced_by=nouveau_id)
        )
    async def revoke_family(self, family_id: UUID, reason: RevocationReason) -> int:
        resultat = await self._session.execute(
            update(RefreshToken)
            .where(RefreshToken.family_id == family_id, RefreshToken.revoked_at.is_(None))
            .values(revoked_at=func.clock_timestamp(), revoked_reason=reason.value)
            .returning(RefreshToken.id)
        )
        return len(resultat.all())
    async def revoke_all_for_user(self, user_id: UUID, reason: RevocationReason) -> int:
        resultat = await self._session.execute(
            update(RefreshToken)
            .where(RefreshToken.user_id == user_id, RefreshToken.revoked_at.is_(None))
            .values(revoked_at=func.clock_timestamp(), revoked_reason=reason.value)
            .returning(RefreshToken.id)
        )
        return len(resultat.all())
@@ -1,20 +0,0 @@
 from collections.abc import Sequence
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 from app.models.energy import Site
 class SiteRepository:
    def __init__(self, session: AsyncSession) -> None:
        self._session = session
    async def list_all(self) -> Sequence[Site]:
        requete = select(Site).order_by(Site.site_id)
        return (await self._session.scalars(requete)).all()
    async def get_by_id(self, site_id: str) -> Site | None:
        requete = select(Site).where(Site.site_id == site_id)
        site: Site | None = await self._session.scalar(requete)
        return site
@@ -1,97 +0,0 @@
 # Piège : `set_role()` et `set_active()` avancent `credentials_changed_at`. C'est ce qui rend
 # un changement de rôle ou une désactivation effectifs à la requête suivante au lieu d'attendre
 # l'expiration du jeton d'accès. Une mise à jour qui l'oublierait laisserait 15 minutes de
 # privilèges périmés.
 from collections.abc import Sequence
 from uuid import UUID
 from sqlalchemy import func, select, update
 from sqlalchemy.ext.asyncio import AsyncSession
 from app.core.roles import AccountKind, Role
 from app.models.user import AppUser
 class UserRepository:
    def __init__(self, session: AsyncSession) -> None:
        self._session = session
    async def get_by_email(self, email: str) -> AppUser | None:
        requete = select(AppUser).where(AppUser.email == email.strip().lower())
        return (await self._session.execute(requete)).scalar_one_or_none()
    async def get_by_id(self, user_id: UUID) -> AppUser | None:
        return await self._session.get(AppUser, user_id)
    async def list_all(self) -> Sequence[AppUser]:
        requete = select(AppUser).order_by(AppUser.email)
        return (await self._session.execute(requete)).scalars().all()
    async def count_active_admins(self) -> int:
        requete = (
            select(func.count())
            .select_from(AppUser)
            .where(AppUser.role == Role.ADMIN.value, AppUser.is_active.is_(True))
        )
        return (await self._session.execute(requete)).scalar_one()
    async def create(
        self,
        *,
        email: str,
        password_hash: str,
        role: Role,
        kind: AccountKind = AccountKind.HUMAIN,
        full_name: str | None = None,
        must_change_password: bool = False,
    ) -> AppUser:
        compte = AppUser(
            email=email.strip().lower(),
            password_hash=password_hash,
            role=role.value,
            kind=kind.value,
            full_name=full_name,
            must_change_password=must_change_password,
        )
        self._session.add(compte)
        await self._session.flush()
        return compte
    async def update_password(
        self, user_id: UUID, password_hash: str, *, must_change_password: bool
    ) -> None:
        await self._session.execute(
            update(AppUser)
            .where(AppUser.id == user_id)
            .values(
                password_hash=password_hash,
                must_change_password=must_change_password,
                credentials_changed_at=func.clock_timestamp(),
            )
        )
    async def rehash_password(self, user_id: UUID, password_hash: str) -> None:
        # Un simple recalcul avec des paramètres Argon2 plus récents ne périme aucun jeton.
        await self._session.execute(
            update(AppUser).where(AppUser.id == user_id).values(password_hash=password_hash)
        )
    async def touch_last_login(self, user_id: UUID) -> None:
        await self._session.execute(
            update(AppUser).where(AppUser.id == user_id).values(last_login_at=func.now())
        )
    async def set_role(self, user_id: UUID, role: Role) -> None:
        await self._session.execute(
            update(AppUser)
            .where(AppUser.id == user_id)
            .values(role=role.value, credentials_changed_at=func.clock_timestamp())
        )
    async def set_active(self, user_id: UUID, *, is_active: bool) -> None:
        await self._session.execute(
            update(AppUser)
            .where(AppUser.id == user_id)
            .values(is_active=is_active, credentials_changed_at=func.clock_timestamp())
        )
@@ -1,3 +0,0 @@
 from app.schemas.health import LivenessStatus, ReadinessStatus
 __all__ = ["LivenessStatus", "ReadinessStatus"]
@@ -1,34 +0,0 @@
 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
@@ -1,95 +0,0 @@
 # Contrainte : le mot de passe est borné à 128 caractères. Sans plafond, une chaîne de dix
 # mégaoctets ferait travailler Argon2 gratuitement, à la charge du serveur.
 # Contrainte : `SPECIAL_CHARACTERS` doit rester identique à `password.validator.ts` côté
 # frontend. `\w`/`\d` divergent entre Python (Unicode) et JavaScript (ASCII) : une classe
 # explicite, plutôt qu'une négation, évite qu'un mot de passe soit accepté d'un côté et
 # rejeté de l'autre (ex. "Sécurité1", où "é" comptait comme "spécial" pour Python seul).
 import re
 from typing import Literal, Self
 from uuid import UUID
 from pydantic import BaseModel, ConfigDict, EmailStr, Field, field_validator
 from app.core.principal import Principal
 from app.core.roles import AccountKind, Role
 PASSWORD_MIN_LENGTH = 8
 PASSWORD_MAX_LENGTH = 128
 SPECIAL_CHARACTERS = "!@#$%^&*()-_=+[]{};:,.?"
 _MAJUSCULE = re.compile(r"[A-ZÀ-ÖØ-Þ]")
 _MINUSCULE = re.compile(r"[a-zà-öø-þ]")
 _CHIFFRE = re.compile(r"[0-9]")
 _SPECIAL = re.compile(r"[" + re.escape(SPECIAL_CHARACTERS) + r"]")
 def valide_complexite(mot_de_passe: str) -> str:
    manquants = [
        nom
        for nom, motif in (
            ("une majuscule", _MAJUSCULE),
            ("une minuscule", _MINUSCULE),
            ("un chiffre", _CHIFFRE),
            ("un caractère spécial", _SPECIAL),
        )
        if not motif.search(mot_de_passe)
    ]
    if manquants:
        raise ValueError(f"Le mot de passe doit contenir au moins {', '.join(manquants)}")
    return mot_de_passe
 class LoginRequest(BaseModel):
    email: EmailStr
    password: str = Field(min_length=1, max_length=PASSWORD_MAX_LENGTH)
 class PasswordChangeRequest(BaseModel):
    current_password: str = Field(min_length=1, max_length=PASSWORD_MAX_LENGTH)
    new_password: str = Field(min_length=PASSWORD_MIN_LENGTH, max_length=PASSWORD_MAX_LENGTH)
    @field_validator("new_password")
    @classmethod
    def _new_password_est_complexe(cls, valeur: str) -> str:
        return valide_complexite(valeur)
 class ForgotPasswordRequest(BaseModel):
    email: EmailStr
 class ResetPasswordRequest(BaseModel):
    token: str = Field(min_length=1)
    new_password: str = Field(min_length=PASSWORD_MIN_LENGTH, max_length=PASSWORD_MAX_LENGTH)
    @field_validator("new_password")
    @classmethod
    def _new_password_est_complexe(cls, valeur: str) -> str:
        return valide_complexite(valeur)
 class PrincipalResponse(BaseModel):
    model_config = ConfigDict(from_attributes=True)
    id: UUID
    email: str
    role: Role
    kind: AccountKind
    must_change_password: bool
    @classmethod
    def from_principal(cls, principal: Principal) -> Self:
        return cls.model_validate(principal)
 class ResetTokenValidationResponse(BaseModel):
    valid: bool
 class TokenResponse(BaseModel):
    access_token: str
    token_type: Literal["bearer"] = "bearer"  # noqa: S105
    expires_in: int
    principal: PrincipalResponse
@@ -1,23 +0,0 @@
 # Piège : ces modèles ne décrivent rien, ils publient. Ce sont eux que Swagger montre, donc ils
 # doivent suivre `validation_error_handler()` et `unhandled_error_handler()` d'`app/api/errors.py`
 # à la lettre. Un champ renommé là-bas sans l'être ici rend la documentation fausse en silence.
 from pydantic import BaseModel
 class ErrorResponse(BaseModel):
    detail: str
 class FieldError(BaseModel):
    champ: str
    type: str
 class ValidationErrorResponse(BaseModel):
    detail: list[FieldError]
 class InternalErrorResponse(BaseModel):
    detail: str
    correlation: str
@@ -1,19 +0,0 @@
 from typing import Literal
 from pydantic import BaseModel
 class LivenessStatus(BaseModel):
    status: Literal["ok"]
    service: str
    version: str
    environment: str
 # Contrainte : la sonde ne publie pas la version de TimescaleDB. Une version exacte de
 # composant, servie sans authentification, est de la reconnaissance gratuite pour qui
 # cherche une CVE. Elle part dans le journal, où elle sert au diagnostic.
 class ReadinessStatus(BaseModel):
    status: Literal["ready"]
    database: Literal["reachable"]
    timescaledb: Literal["loaded"]
@@ -1,45 +0,0 @@
 from datetime import datetime
 from decimal import Decimal
 from enum import StrEnum
 from typing import Any
 from pydantic import BaseModel, ConfigDict
 class ReadingSource(StrEnum):
    CSV = "csv"
    API_CURRENT = "api_current"
    API_HISTORY = "api_history"
 class ReadingDataQuality(StrEnum):
    GOOD = "good"
    PARTIAL = "partial"
    DEGRADED = "degraded"
    CRITICAL = "critical"
 class ReadingResponse(BaseModel):
    model_config = ConfigDict(from_attributes=True)
    reading_id: int
    site_id: str
    timestamp: datetime
    source: ReadingSource
    consumption_kw: float | None
    consumption_kwh: float | None
    # Piège : `Decimal` (miroir de `Numeric(14, 2)` en base, pour ne pas arrondir un montant)
    # sérialise en chaîne dans le JSON, pas en nombre — un consommateur qui ferait un `parseFloat`
    # naïf perdrait la précision que ce choix visait à garder.
    consumption_euros: Decimal | None
    voltage_v: float | None
    current_a: float | None
    power_factor: float | None
    temperature_celsius: float | None
    humidity_percent: float | None
    solar_irradiance_wm2: float | None
    is_working_hours: bool | None
    data_quality: ReadingDataQuality | None
    null_reasons: list[str] | None
    imputed_values: dict[str, Any] | None
    imputation_method: str | None
@@ -1,14 +0,0 @@
 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
@@ -1,42 +0,0 @@
 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]
@@ -1,12 +0,0 @@
 from pydantic import BaseModel, ConfigDict
 class SiteResponse(BaseModel):
    model_config = ConfigDict(from_attributes=True)
    site_id: str
    site_name: str
    site_type: str
    location: str | None
    capacity_kw: float | None
    status: str | None
@@ -1,26 +0,0 @@
 from datetime import datetime
 from typing import Literal
 from pydantic import BaseModel, ConfigDict
 class SiteSummaryResponse(BaseModel):
    model_config = ConfigDict(from_attributes=True)
    site_id: str
    site_name: str
    current_consumption_kw: float | None
    capacity_kw: float
    load_percent: float | None
    data_quality: Literal["good", "partial", "degraded", "critical"]
 class StatsSummaryResponse(BaseModel):
    model_config = ConfigDict(from_attributes=True)
    timestamp: datetime
    total_sites: int
    total_consumption_kw: float
    total_capacity_kw: float
    average_load_percent: float
    sites: list[SiteSummaryResponse]
@@ -1,41 +0,0 @@
 # Contrainte : les schémas de lecture et d'écriture sont séparés. Un modèle unique laisserait
 # passer `role` ou `is_active` depuis un corps de requête, et renverrait `password_hash` en
 # réponse. C'est l'attribution de masse, API3 du top 10 API.
 from datetime import datetime
 from uuid import UUID
 from pydantic import BaseModel, ConfigDict, EmailStr, Field
 from app.core.roles import AccountKind, Role
 class UserCreateRequest(BaseModel):
    email: EmailStr
    role: Role
    full_name: str | None = Field(default=None, max_length=200)
 class UserUpdateRequest(BaseModel):
    role: Role | None = None
    is_active: bool | None = None
 class UserResponse(BaseModel):
    model_config = ConfigDict(from_attributes=True)
    id: UUID
    email: str
    role: Role
    kind: AccountKind
    is_active: bool
    must_change_password: bool
    full_name: str | None
    last_login_at: datetime | None
    created_at: datetime
 class TemporaryPasswordResponse(BaseModel):
    # Affiché une seule fois : l'empreinte seule est conservée côté serveur.
    user: UserResponse
    temporary_password: str
@@ -1,14 +0,0 @@
 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)
@@ -1,464 +0,0 @@
 # Piège : les compteurs de limitation sont lus AVANT le hachage Argon2. Dans l'autre ordre,
 # chaque requête rejetée coûterait quand même 17 ms de processeur et 19 Mio de mémoire, et la
 # protection deviendrait l'amplificateur de déni de service qu'elle est censée empêcher.
 # Piège : quand l'email est inconnu, `verify_dummy()` consomme le même temps qu'une
 # vérification réelle. Sans lui, l'écart de temps de réponse est un oracle d'existence.
 # Piège : la tentative échouée est validée en base AVANT que l'erreur ne soit levée.
 # `get_session()` ne valide pas de lui-même, donc la preuve disparaîtrait avec la transaction.
 # Piège : dans `refresh()`, un jeton expiré ne révoque PAS la famille, un jeton déjà tourné si.
 # La rotation ne protège de rien par elle-même : elle rend la réutilisation détectable, et
 # c'est la détection qui termine le vol.
 from dataclasses import dataclass
 from datetime import UTC, datetime, timedelta
 from typing import NoReturn, Protocol
 from uuid import UUID, uuid4
 from fastapi import BackgroundTasks
 from app.core.hashing import Argon2Hasher
 from app.core.logging import get_logger
 from app.core.mailer import Mailer
 from app.core.principal import Principal
 from app.core.roles import AccountKind, Role
 from app.core.security import (
    TokenPolicy,
    encode_access_token,
    fingerprint_refresh,
    generate_refresh_secret,
 )
 from app.models.audit_log import AuditAction, AuditOutcome
 from app.models.login_attempt import LoginOutcome
 from app.models.refresh_token import RevocationReason
 from app.repositories.audit_log import AuditLogRepository
 from app.repositories.login_attempt import LoginAttemptRepository
 from app.repositories.password_reset_attempt import PasswordResetAttemptRepository
 from app.repositories.password_reset_token import PasswordResetTokenRepository
 from app.repositories.refresh_token import RefreshTokenRepository
 from app.repositories.user import UserRepository
 logger = get_logger(__name__)
 class Transaction(Protocol):
    async def commit(self) -> None: ...
 class AuthError(Exception):
    pass
 class InvalidCredentialsError(AuthError):
    pass
 class SessionRejectedError(AuthError):
    pass
 class RateLimitedError(AuthError):
    def __init__(self, retry_after: int) -> None:
        super().__init__("Trop de tentatives")
        self.retry_after = retry_after
 class InvalidOrExpiredResetTokenError(AuthError):
    pass
@dataclass(frozen=True, slots=True)
 class LoginPolicy:
    window_seconds: int
    max_failures_per_identifier_and_ip: int
    max_failures_per_ip: int
    max_failures_per_identifier: int
@dataclass(frozen=True, slots=True)
 class PasswordResetPolicy:
    window_seconds: int
    max_requests_per_identifier: int
    max_requests_per_ip: int
    token_ttl: timedelta
    frontend_reset_url: str
@dataclass(frozen=True, slots=True)
 class AuthenticatedSession:
    principal: Principal
    access_token: str
    expires_in: int
    refresh_secret: str
 class AuthService:
    def __init__(
        self,
        *,
        users: UserRepository,
        attempts: LoginAttemptRepository,
        refresh_tokens: RefreshTokenRepository,
        audit: AuditLogRepository,
        hasher: Argon2Hasher,
        transaction: Transaction,
        token_policy: TokenPolicy,
        login_policy: LoginPolicy,
        refresh_ttl: timedelta,
        reset_tokens: PasswordResetTokenRepository,
        reset_attempts: PasswordResetAttemptRepository,
        reset_policy: PasswordResetPolicy,
        mailer: Mailer,
    ) -> None:
        self._users = users
        self._attempts = attempts
        self._refresh = refresh_tokens
        self._audit = audit
        self._hasher = hasher
        self._transaction = transaction
        self._token_policy = token_policy
        self._login_policy = login_policy
        self._refresh_ttl = refresh_ttl
        self._reset_tokens = reset_tokens
        self._reset_attempts = reset_attempts
        self._reset_policy = reset_policy
        self._mailer = mailer
    async def authenticate(
        self, *, email: str, password: str, client_ip: str | None, user_agent: str | None
    ) -> AuthenticatedSession:
        await self._refuse_si_limite(email=email, client_ip=client_ip, user_agent=user_agent)
        compte = await self._users.get_by_email(email)
        if compte is None:
            await self._hasher.verify_dummy()
            await self._echoue(email, client_ip, LoginOutcome.IDENTIFIANTS_INVALIDES)
        if not await self._hasher.verify(compte.password_hash, password):
            await self._echoue(
                email, client_ip, LoginOutcome.IDENTIFIANTS_INVALIDES, user_id=compte.id
            )
        if not compte.is_active or compte.kind != AccountKind.HUMAIN.value:
            await self._echoue(
                email, client_ip, LoginOutcome.COMPTE_INDISPONIBLE, user_id=compte.id
            )
        if self._hasher.needs_rehash(compte.password_hash):
            await self._users.rehash_password(compte.id, await self._hasher.hash(password))
        await self._users.touch_last_login(compte.id)
        await self._attempts.record(
            email=email, client_ip=client_ip, outcome=LoginOutcome.SUCCES, user_id=compte.id
        )
        secret = await self._ouvre_une_famille(
            user_id=compte.id, client_ip=client_ip, user_agent=user_agent
        )
        await self._transaction.commit()
        return self._session(self._en_principal(compte), secret)
    async def refresh(
        self, *, secret: str, client_ip: str | None, user_agent: str | None
    ) -> AuthenticatedSession:
        empreinte = fingerprint_refresh(secret)
        revendique = await self._refresh.claim_for_rotation(empreinte)
        if revendique is None:
            await self._traite_rotation_refusee(empreinte, client_ip, user_agent)
        compte = await self._users.get_by_id(revendique.user_id)
        if compte is None or not compte.is_active:
            await self._refresh.revoke_family(revendique.family_id, RevocationReason.ADMINISTRATION)
            await self._transaction.commit()
            raise SessionRejectedError("Session révoquée")
        nouveau_secret = generate_refresh_secret()
        nouveau = await self._refresh.create(
            user_id=revendique.user_id,
            family_id=revendique.family_id,
            token_hash=fingerprint_refresh(nouveau_secret),
            expires_at=revendique.expires_at,
            client_ip=client_ip,
            user_agent=user_agent,
        )
        await self._refresh.link_replacement(revendique.id, nouveau.id)
        await self._transaction.commit()
        return self._session(self._en_principal(compte), nouveau_secret)
    async def logout(self, *, secret: str) -> None:
        ligne = await self._refresh.inspect(fingerprint_refresh(secret))
        if ligne is not None:
            await self._refresh.revoke_family(ligne.family_id, RevocationReason.DECONNEXION)
        await self._transaction.commit()
    async def change_password(
        self,
        *,
        principal: Principal,
        current_password: str,
        new_password: str,
        client_ip: str | None,
        user_agent: str | None,
    ) -> AuthenticatedSession:
        compte = await self._users.get_by_id(principal.id)
        if compte is None or not await self._hasher.verify(compte.password_hash, current_password):
            raise InvalidCredentialsError("Identifiants invalides")
        await self._users.update_password(
            principal.id, await self._hasher.hash(new_password), must_change_password=False
        )
        # Toutes les sessions tombent, puis on en rouvre une : l'appareil courant reste
        # connecté et tous les autres sont déconnectés.
        revoquees = await self._refresh.revoke_all_for_user(
            principal.id, RevocationReason.CHANGEMENT_MOT_DE_PASSE
        )
        secret = await self._ouvre_une_famille(
            user_id=principal.id, client_ip=client_ip, user_agent=user_agent
        )
        await self._audit.record(
            action=AuditAction.COMPTE_MOT_DE_PASSE_CHANGE,
            actor=principal,
            target_type="app_user",
            target_id=str(principal.id),
            client_ip=client_ip,
            user_agent=user_agent,
            detail={"sessions_revoquees": revoquees},
        )
        await self._transaction.commit()
        rafraichi = await self._users.get_by_id(principal.id)
        return self._session(self._en_principal(rafraichi or compte), secret)
    async def request_password_reset(
        self,
        *,
        email: str,
        client_ip: str | None,
        user_agent: str | None,
        background_tasks: BackgroundTasks,
    ) -> None:
        await self._refuse_si_limite_reset(email=email, client_ip=client_ip)
        compte = await self._users.get_by_email(email)
        # Piège : le hachage factice équilibre le temps de réponse sur un compte inconnu, comme
        # `authenticate()`. La réponse et sa forme restent identiques dans tous les cas : compte
        # inconnu, compte inactif, ou email envoyé avec succès. L'envoi SMTP lui-même est différé
        # en tâche de fond : le laisser dans le chemin de réponse rouvrirait le même oracle par le
        # temps (aller-retour réseau) et par la forme (500 si le relais SMTP échoue, contre 202).
        if compte is None or not compte.is_active or compte.kind != AccountKind.HUMAIN.value:
            await self._hasher.verify_dummy()
            await self._reset_attempts.record(email=email, client_ip=client_ip)
            await self._transaction.commit()
            return
        await self._reset_tokens.invalidate_all_for_user(compte.id)
        secret = generate_refresh_secret()
        await self._reset_tokens.create(
            user_id=compte.id,
            token_hash=fingerprint_refresh(secret),
            expires_at=datetime.now(UTC) + self._reset_policy.token_ttl,
            client_ip=client_ip,
            user_agent=user_agent,
        )
        await self._reset_attempts.record(email=email, client_ip=client_ip)
        await self._audit.record(
            action=AuditAction.MOT_DE_PASSE_OUBLIE_DEMANDE,
            actor_label=compte.email,
            target_type="app_user",
            target_id=str(compte.id),
            client_ip=client_ip,
            user_agent=user_agent,
        )
        await self._transaction.commit()
        lien = f"{self._reset_policy.frontend_reset_url}?token={secret}"
        background_tasks.add_task(self._envoie_email_reset, compte.email, lien)
    async def _envoie_email_reset(self, email: str, reset_url: str) -> None:
        try:
            await self._mailer.send_password_reset_email(to=email, reset_url=reset_url)
        except Exception:
            logger.exception("auth.password_reset.mail_failed")
    # Piège : lecture seule, pas d'appel à `consume()`. Aucune limitation de débit n'est
    # nécessaire ici : le jeton est un secret de 256 bits (`generate_refresh_secret`), donc
    # non brute-forçable, et cette route n'apprend rien sur l'existence d'un compte ou d'un
    # email, seulement si le lien déjà en main du visiteur est encore valide.
    async def is_reset_token_valid(self, token: str) -> bool:
        return await self._reset_tokens.exists_valid(fingerprint_refresh(token))
    async def confirm_password_reset(
        self, *, token: str, new_password: str, client_ip: str | None, user_agent: str | None
    ) -> AuthenticatedSession:
        revendique = await self._reset_tokens.consume(fingerprint_refresh(token))
        if revendique is None:
            raise InvalidOrExpiredResetTokenError("Lien invalide ou expiré")
        # Piège : le jeton peut avoir été émis avant une désactivation du compte. Sans cette
        # relecture, un lien encore valide (15 min) changerait quand même le mot de passe d'un
        # compte désactivé, réutilisable dès sa réactivation.
        compte = await self._users.get_by_id(revendique.user_id)
        if compte is None or not compte.is_active or compte.kind != AccountKind.HUMAIN.value:
            raise InvalidOrExpiredResetTokenError("Lien invalide ou expiré")
        await self._users.update_password(
            revendique.user_id, await self._hasher.hash(new_password), must_change_password=False
        )
        revoquees = await self._refresh.revoke_all_for_user(
            revendique.user_id, RevocationReason.CHANGEMENT_MOT_DE_PASSE
        )
        secret = await self._ouvre_une_famille(
            user_id=revendique.user_id, client_ip=client_ip, user_agent=user_agent
        )
        await self._audit.record(
            action=AuditAction.MOT_DE_PASSE_REINITIALISE_PAR_SOI,
            target_type="app_user",
            target_id=str(revendique.user_id),
            client_ip=client_ip,
            user_agent=user_agent,
            detail={"sessions_revoquees": revoquees},
        )
        await self._transaction.commit()
        compte = await self._users.get_by_id(revendique.user_id)
        if compte is None:
            raise SessionRejectedError("Compte introuvable")
        return self._session(self._en_principal(compte), secret)
    async def logout_all(self, principal: Principal) -> int:
        revoquees = await self._refresh.revoke_all_for_user(
            principal.id, RevocationReason.DECONNEXION
        )
        await self._audit.record(
            action=AuditAction.SESSIONS_REVOQUEES,
            actor=principal,
            detail={"sessions_revoquees": revoquees},
        )
        await self._transaction.commit()
        return revoquees
    def _session(self, principal: Principal, refresh_secret: str) -> AuthenticatedSession:
        jeton = encode_access_token(
            self._token_policy,
            subject=principal.id,
            role=principal.role.value,
            kind=principal.kind.value,
        )
        return AuthenticatedSession(
            principal=principal,
            access_token=jeton,
            expires_in=int(self._token_policy.access_ttl.total_seconds()),
            refresh_secret=refresh_secret,
        )
    def _en_principal(self, compte: object) -> Principal:
        return Principal(
            id=compte.id,  # type: ignore[attr-defined]
            email=compte.email,  # type: ignore[attr-defined]
            role=Role(compte.role),  # type: ignore[attr-defined]
            kind=AccountKind(compte.kind),  # type: ignore[attr-defined]
            must_change_password=compte.must_change_password,  # type: ignore[attr-defined]
        )
    async def _ouvre_une_famille(
        self, *, user_id: UUID, client_ip: str | None, user_agent: str | None
    ) -> str:
        secret = generate_refresh_secret()
        await self._refresh.create(
            user_id=user_id,
            family_id=uuid4(),
            token_hash=fingerprint_refresh(secret),
            expires_at=datetime.now(UTC) + self._refresh_ttl,
            client_ip=client_ip,
            user_agent=user_agent,
        )
        return secret
    async def _traite_rotation_refusee(
        self, empreinte: bytes, client_ip: str | None, user_agent: str | None
    ) -> NoReturn:
        ligne = await self._refresh.inspect(empreinte)
        if ligne is None:
            raise SessionRejectedError("Session inconnue")
        if ligne.expires_at <= datetime.now(UTC):
            raise SessionRejectedError("Session expirée")
        # Présenter un jeton déjà tourné est une preuve de compromission, pas un accident : toute
        # la famille tombe, y compris la session encore vivante du voleur ou de la victime.
        revoquees = await self._refresh.revoke_family(
            ligne.family_id, RevocationReason.REUTILISATION
        )
        await self._audit.record(
            action=AuditAction.REFRESH_REUTILISE,
            outcome=AuditOutcome.ECHEC,
            target_type="refresh_token",
            target_id=str(ligne.family_id),
            client_ip=client_ip,
            user_agent=user_agent,
            detail={"famille": str(ligne.family_id), "sessions_revoquees": revoquees},
        )
        await self._transaction.commit()
        raise SessionRejectedError("Session révoquée")
    async def _refuse_si_limite(
        self, *, email: str, client_ip: str | None, user_agent: str | None
    ) -> None:
        politique = self._login_policy
        compteurs = await self._attempts.count_recent_failures(
            email=email, client_ip=client_ip, window_seconds=politique.window_seconds
        )
        depasse = (
            compteurs.per_identifier_and_ip >= politique.max_failures_per_identifier_and_ip
            or compteurs.per_ip >= politique.max_failures_per_ip
            or compteurs.per_identifier >= politique.max_failures_per_identifier
        )
        if not depasse:
            return
        await self._attempts.record(email=email, client_ip=client_ip, outcome=LoginOutcome.LIMITE)
        # Un blocage déclenché par l'identifiant seul signe une attaque distribuée : lui seul
        # mérite une trace durable, les échecs ordinaires restent dans `login_attempt`.
        if compteurs.per_identifier >= politique.max_failures_per_identifier:
            await self._audit.record(
                action=AuditAction.LIMITE_PAR_IDENTIFIANT,
                outcome=AuditOutcome.ECHEC,
                actor_label=email.strip().lower(),
                client_ip=client_ip,
                user_agent=user_agent,
                detail={"motif": "seuil par identifiant depasse"},
            )
        await self._transaction.commit()
        raise RateLimitedError(politique.window_seconds)
    async def _refuse_si_limite_reset(self, *, email: str, client_ip: str | None) -> None:
        politique = self._reset_policy
        compteurs = await self._reset_attempts.count_recent(
            email=email, client_ip=client_ip, window_seconds=politique.window_seconds
        )
        depasse = (
            compteurs.per_identifier >= politique.max_requests_per_identifier
            or compteurs.per_ip >= politique.max_requests_per_ip
        )
        if not depasse:
            return
        await self._reset_attempts.record(email=email, client_ip=client_ip)
        await self._transaction.commit()
        raise RateLimitedError(politique.window_seconds)
    async def _echoue(
        self,
        email: str,
        client_ip: str | None,
        outcome: LoginOutcome,
        *,
        user_id: UUID | None = None,
    ) -> NoReturn:
        await self._attempts.record(
            email=email, client_ip=client_ip, outcome=outcome, user_id=user_id
        )
        await self._transaction.commit()
        raise InvalidCredentialsError("Identifiants invalides")
@@ -1,59 +0,0 @@
 from collections.abc import Sequence
 from datetime import UTC, datetime, timedelta
 from app.models.energy import Reading
 from app.repositories.reading import ReadingRepository
 FENETRE_PAR_DEFAUT = timedelta(hours=24)
 FENETRE_MAXIMALE = timedelta(days=90)
 class FenetreInverseeError(Exception):
    """`start` est postérieur ou égal à `end`."""
 class FenetreTropLargeError(Exception):
    """L'écart entre `start` et `end` dépasse `FENETRE_MAXIMALE`."""
 class ReadingService:
    def __init__(self, *, readings: ReadingRepository) -> None:
        self._readings = readings
    async def list_history(
        self,
        *,
        site_id: str | None = None,
        start: datetime | None = None,
        end: datetime | None = None,
        limit: int,
        offset: int,
    ) -> Sequence[Reading]:
        debut, fin = self._resoudre_fenetre(start, end)
        return await self._readings.list_history(
            site_id=site_id, start=debut, end=fin, limit=limit, offset=offset
        )
    @staticmethod
    def _resoudre_fenetre(
        start: datetime | None, end: datetime | None
    ) -> tuple[datetime, datetime]:
        # Piège : un datetime naïf (sans fuseau dans la chaîne ISO reçue) fait échouer la
        # comparaison à `reading.timestamp` (`timestamptz`) au niveau du pilote, en 500 plutôt
        # qu'un refus propre. On le traite comme de l'UTC plutôt que de le rejeter.
        debut = _vers_utc(start)
        fin = _vers_utc(end) or datetime.now(UTC)
        if debut is None:
            debut = fin - FENETRE_PAR_DEFAUT
        if debut >= fin:
            raise FenetreInverseeError
        if fin - debut > FENETRE_MAXIMALE:
            raise FenetreTropLargeError
        return debut, fin
 def _vers_utc(instant: datetime | None) -> datetime | None:
    if instant is None:
        return None
    return instant if instant.tzinfo is not None else instant.replace(tzinfo=UTC)
@@ -1,26 +0,0 @@
 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
@@ -1,137 +0,0 @@
 from dataclasses import dataclass
 from datetime import UTC, datetime
 from typing import Literal
 from app.models.energy import Reading, Site
 from app.repositories.reading import ReadingRepository
 from app.repositories.site import SiteRepository
 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
    )
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
copilot-swe-agent[bot]andGitHub	9ae7e924a7	Initial plan	2026-09-15 14:50:42 +00:00
PhyriosandGitHub	c3fd9327ea	Definition des jalons	2026-09-14 11:30:01 +02:00
		`@@ -1 +0,0 @@`
			`Generic single-database configuration with an async dbapi.`
		`@@ -1,3 +0,0 @@`
			`from app.schemas.health import LivenessStatus, ReadinessStatus`

			`__all__ = ["LivenessStatus", "ReadinessStatus"]`