Merge remote-tracking branch 'origin/dev' into feat/dag-ml-train-score

2026-09-21 10:39:07 +02:00
parent b941880c22 cc3e38efa3
commit 6f6f451eb4
31 changed files with 2857 additions and 107 deletions
@@ -2,9 +2,10 @@

 ## Objectif

-Le pipeline ETL EnerVision permet d'intégrer les données énergétiques historiques dans PostgreSQL/TimescaleDB.
+Le pipeline ETL EnerVision permet d'intégrer les données énergétiques dans PostgreSQL/TimescaleDB à partir de deux sources :

-Cette première étape du pipeline Data permet de charger le dataset fourni dans le cadre du projet, contenant les mesures énergétiques de 7 sites sur la période du 1er janvier 2023 au 31 décembre 2024.
+- le dataset historique CSV/JSON fourni dans le cadre du projet ;
+- l'API Mock EnerVision.

 Le pipeline assure :

@@ -12,12 +13,15 @@ Le pipeline assure :
 - la validation de leur structure et de leur cohérence ;
 - la normalisation des données nécessaires au stockage ;
 - le suivi de la qualité des données ;
- la traçabilité du dataset importé ;
+- la traçabilité des données importées ;
 - le chargement des données dans PostgreSQL/TimescaleDB ;
+- la conservation des valeurs manquantes et des informations de qualité ;
 - l'idempotence du chargement afin d'éviter la création de doublons.

 ## Données sources

+### Dataset historique
+
 Le dataset est fourni par le formateur dans le cadre du projet EnerVision.

 Il contient les deux fichiers suivants :
@@ -29,7 +33,7 @@ dataset_metadata.json

 Ces fichiers sont nécessaires une seule fois pour initialiser les données historiques de l'environnement.

-Ils ne sont pas versionnés dans Git. Chaque membre de l'équipe récupère manuellement une fois les fichiers fournis par le formateur et les place dans :
+Ils ne sont pas versionnés dans Git. Chaque membre de l'équipe récupère manuellement les fichiers fournis par le formateur et les place dans :

 ```text
 data/raw/
@@ -47,14 +51,26 @@ data/

 Le fichier `.gitkeep` est versionné afin de conserver le répertoire `data/raw/` dans Git. Les fichiers CSV et JSON sont ignorés par Git.

+### API Mock
+
+La deuxième source est l'API Mock EnerVision.
+
+Elle permet de récupérer :
+
+- les informations des sites avec `GET /api/v1/sites` ;
+- les mesures simulées avec `GET /api/v1/readings`.
+
+L'API Mock est utilisée pour compléter les données historiques avec des mesures simulées récupérées sur une période donnée.
+
 ## Technologies utilisées

 | Technologie | Utilisation |
 |---|---|
 | Python | Développement du pipeline ETL |
-| Pandas | Lecture, validation et transformation des données |
-| JSON | Lecture des métadonnées du dataset |
-| hashlib / SHA-256 | Identification, intégrité et traçabilité du dataset |
+| Pandas | Lecture, validation et transformation du dataset historique |
+| JSON | Lecture des métadonnées et conservation des données sources |
+| HTTPX | Appels HTTP asynchrones vers l'API Mock |
+| hashlib / SHA-256 | Identification, intégrité et traçabilité du dataset historique |
 | SQLAlchemy Async | Connexion et chargement asynchrone en base |
 | PostgreSQL | Stockage relationnel |
 | TimescaleDB | Stockage des séries temporelles énergétiques |
@@ -62,11 +78,14 @@ Le fichier `.gitkeep` est versionné afin de conserver le répertoire `data/raw/
 | Alembic | Gestion des migrations du schéma |
 | uv | Gestion et exécution de l'environnement Python |
 | Ruff | Contrôle de la qualité du code |
+| mypy | Vérification du typage |
 | Pytest | Tests automatisés |

-## Fonctionnement du pipeline
+## Import du dataset historique

-Le script principal d'import se trouve dans :
+### Fonctionnement du pipeline historique
+
+Le script d'import se trouve dans :

 ```text
 apps/backend/app/etl/historical_import.py
@@ -96,14 +115,14 @@ CSV + métadonnées JSON
 PostgreSQL / TimescaleDB
 ```

-### 1. Extraction
+#### 1. Extraction

 Le pipeline charge :

 - `all_sites_combined.csv` avec Pandas ;
 - `dataset_metadata.json` avec le module JSON de Python.

-### 2. Validation
+#### 2. Validation

 Avant toute écriture en base, le pipeline contrôle notamment :

@@ -117,7 +136,7 @@ Avant toute écriture en base, le pipeline contrôle notamment :

 Une incohérence détectée pendant cette étape interrompt l'import avant le chargement.

-### 3. Dry-run
+#### 3. Dry-run

 Un mode `--dry-run` permet d'exécuter les contrôles sans écrire de données dans PostgreSQL.

@@ -130,7 +149,7 @@ Il permet notamment de vérifier :
 - les valeurs NULL ;
 - l'empreinte SHA-256.

-### 4. Traçabilité
+#### 4. Traçabilité

 Une empreinte SHA-256 est calculée à partir du fichier CSV afin d'identifier le dataset utilisé.

@@ -142,7 +161,7 @@ Empreinte SHA-256 du dataset validé :

 Cette empreinte participe à la traçabilité du dataset chargé.

-### 5. Transformation
+#### 5. Transformation

 Les timestamps sont normalisés avec la timezone :

@@ -161,7 +180,7 @@ imputed_values = NULL
 imputation_method = NULL
 ```

-### 6. Chargement
+#### 6. Chargement

 Le chargement est réalisé avec SQLAlchemy Async dans PostgreSQL/TimescaleDB.

@@ -188,7 +207,7 @@ dataset_id = identifiant du dataset

 Cette représentation respecte les contraintes définies dans le schéma de la base.

-## Dataset validé
+### Dataset validé

 Le dataset traité contient :

@@ -207,7 +226,7 @@ Valeurs manquantes identifiées :
 | `humidity_percent` | 3 423 |
 | `solar_irradiance_wm2` | 3 964 |

-## Exécution en dry-run
+### Exécution historique en dry-run

 Depuis le dossier :

@@ -227,7 +246,7 @@ uv run python -m app.etl.historical_import `

 Aucune donnée n'est écrite dans la base pendant cette exécution.

-## Chargement réel
+### Chargement historique réel

 Depuis `apps/backend/` :

@@ -249,7 +268,7 @@ Chargement : 2000/122647
 Chargement : 122647/122647
 ```

-## Résultats obtenus
+### Résultats obtenus pour le dataset historique

 Après le chargement initial, les contrôles en base ont confirmé :

@@ -266,7 +285,7 @@ Le premier import a créé :
 nouvelles lectures : 122647
 ```

-## Idempotence
+### Idempotence du dataset historique

 Le pipeline a été exécuté une deuxième fois avec exactement le même dataset afin de vérifier son idempotence.

@@ -280,7 +299,7 @@ nouvelles lectures : 0

 Une nouvelle exécution du même import ne crée donc pas de mesures supplémentaires pour le dataset testé.

-## Vérifications SQL
+### Vérifications SQL du dataset historique

 Depuis la racine du projet, vérifier le nombre d'enregistrements avec :

@@ -302,21 +321,251 @@ Vérifier la source des mesures avec :
 docker compose exec db psql -U enervision -d enervision -c "SELECT source, COUNT(*) FROM reading GROUP BY source ORDER BY source;"
 ```

-Résultat attendu :
+Résultat attendu pour le dataset historique :

 ```text
 csv | 122647
 ```

+## Import depuis l'API Mock
+
+### Fonctionnement
+
+Le script d'import de l'API Mock se trouve dans :
+
+```text
+apps/backend/app/etl/mock_api_import.py
+```
+
+Le flux est le suivant :
+
+```text
+        API Mock
+           |
+     +-----+------+
+     |            |
+     v            v
+   /sites      /readings
+     |            |
+     +-----+------+
+           |
+           v
+ mock_api_import.py
+           |
+           v
+ Transformation
+ + qualité data
+           |
+           v
+PostgreSQL / TimescaleDB
+     |          |
+     v          v
+   site       reading
+```
+
+Le pipeline commence par récupérer les sites avec :
+
+```text
+GET /api/v1/sites
+```
+
+Il récupère ensuite les mesures de chaque site avec :
+
+```text
+GET /api/v1/readings
+```
+
+Les paramètres envoyés à `/api/v1/readings` sont :
+
+```text
+site_id
+start_time
+end_time
+limit
+```
+
+Le paramètre `limit` doit être compris entre 1 et 1000.
+
+### Configuration de l'API Mock
+
+La connexion à l'API Mock est configurée avec les variables d'environnement suivantes :
+
+```text
+APP_MOCK_API_BASE_URL
+APP_MOCK_API_USERNAME
+APP_MOCK_API_PASSWORD
+APP_MOCK_API_TIMEOUT_SECONDS
+```
+
+Les identifiants réels ne sont pas versionnés dans Git.
+
+Les fichiers `.env.example` indiquent uniquement les variables nécessaires à l'exécution.
+
+### Transformation des mesures API
+
+Les mesures provenant de l'API Mock sont enregistrées dans `reading` avec :
+
+```text
+source = "api_history"
+dataset_id = NULL
+```
+
+Les mesures provenant de l'API ne sont donc pas rattachées à un dataset historique.
+
+Le timestamp reçu depuis l'API est converti en `datetime` avec timezone avant le chargement.
+
+La réponse source est conservée dans :
+
+```text
+raw_data
+```
+
+afin de préserver la donnée reçue et faciliter la traçabilité.
+
+### Qualité des données API
+
+Les valeurs `NULL` fournies par l'API sont conservées telles quelles.
+
+Une valeur manquante n'est pas transformée en zéro et la mesure n'est pas supprimée.
+
+Le pipeline conserve également :
+
+```text
+data_quality
+null_reasons
+```
+
+Les niveaux de qualité possibles sont :
+
+```text
+good
+partial
+degraded
+critical
+```
+
+Ce sont les quatre seules valeurs que la contrainte `ck_reading_quality` accepte. Toute autre
+valeur renvoyée par l'API est remplacée par `NULL` plutôt que de faire échouer le lot entier.
+
+Aucune imputation n'est réalisée pendant l'ingestion :
+
+```text
+imputed_values = NULL
+imputation_method = NULL
+```
+
+Cette stratégie permet de distinguer une véritable valeur nulle ou manquante d'une consommation égale à zéro et de conserver les informations liées aux défaillances de capteurs.
+
+### Bornes physiques et frontière de confiance
+
+La réponse de l'API Mock est traitée comme une entrée hostile : l'API n'a pas
+d'authentification et expose un endpoint mutatif à quiconque. Voir API10 dans
+`docs/architecture/owasp-traceabilite.md`.
+
+Les plages acceptées sont déclarées dans `PHYSICAL_BOUNDS` :
+
+| Grandeur | Plage acceptée |
+|---|---|
+| `consumption_kw` | 0 à 100 000 |
+| `consumption_kwh` | 0 à 100 000 |
+| `voltage_v` | 0 à 1 000 |
+| `current_a` | 0 à 10 000 |
+| `power_factor` | 0 à 1 |
+| `temperature_celsius` | -90 à 60 |
+| `humidity_percent` | 0 à 100 |
+| `capacity_kw` | 0 à 100 000 |
+
+Une valeur hors plage, d'un type inattendu, `NaN` ou infinie devient `NULL` :
+
+```text
+null_reasons += "out_of_physical_bounds:<colonne>"
+data_quality = "degraded"
+```
+
+L'import ne s'interrompt pas pour autant : le mock émet des anomalies par construction, et
+`raw_data` conserve la réponse d'origine.
+
+La taille des réponses est plafonnée : au plus `MAX_SITES` sites, et au plus `--limit` mesures
+par site. Au-delà, l'import échoue au lieu de charger.
+
+Enfin, seuls les champs attendus sont recopiés vers la base. Une clé supplémentaire renvoyée par
+l'API n'atteint jamais une colonne.
+
+### Dry-run de l'API Mock
+
+Le mode `--dry-run` permet de tester la connexion, la récupération des sites et la récupération des mesures sans écrire dans PostgreSQL.
+
+Depuis `apps/backend/` :
+
+```powershell
+uv run python -m app.etl.mock_api_import `
+  --start-time "2024-06-15T12:00:00" `
+  --end-time "2024-06-15T13:00:00" `
+  --limit 60 `
+  --dry-run
+```
+
+### Chargement réel depuis l'API Mock
+
+Depuis `apps/backend/` :
+
+```powershell
+uv run python -m app.etl.mock_api_import `
+  --start-time "2024-06-15T12:00:00" `
+  --end-time "2024-06-15T13:00:00" `
+  --limit 60
+```
+
+### Résultat validé pour l'API Mock
+
+Le scénario de validation utilisé couvre la période :
+
+```text
+15/06/2024 12:00 UTC
+à
+15/06/2024 13:00 UTC
+```
+
+avec une limite de 60 lectures par site.
+
+Résultat obtenu :
+
+```text
+sites récupérés       : 7
+lectures par site     : 60
+lectures récupérées   : 420
+source                : api_history
+dataset_id            : NULL
+```
+
+Les contrôles effectués directement dans PostgreSQL/TimescaleDB ont confirmé :
+
+- l'enregistrement des mesures dans `reading` ;
+- la présence des 7 sites ;
+- `source = "api_history"` ;
+- `dataset_id = NULL` ;
+- la conservation des valeurs `NULL` ;
+- la conservation de `data_quality` ;
+- la conservation de `null_reasons` ;
+- la conservation de la donnée source dans `raw_data`.
+
+### Idempotence de l'import API Mock
+
+Le même import a été exécuté plusieurs fois afin de vérifier qu'une mesure déjà présente n'est pas créée une seconde fois.
+
+L'idempotence repose sur la contrainte d'unicité de la table `reading` et sur la gestion des conflits lors de l'insertion.
+
+Un test d'intégration automatisé vérifie également ce comportement.
+
 ## Tests et qualité

-Les tests automatisés du pipeline sont situés dans :
+Les tests automatisés des pipelines ETL sont situés dans :

 ```text
 apps/backend/tests/etl/
 ```

-Ils couvrent notamment :
+Les tests de l'import historique couvrent notamment :

 - la validation du dataset ;
 - les colonnes obligatoires ;
@@ -328,22 +577,94 @@ Ils couvrent notamment :
 - la construction des mesures destinées à la BDD ;
 - le respect des contraintes du modèle de données.

+Les tests de l'import API Mock couvrent notamment :
+
+- la récupération des sites ;
+- l'appel à `/api/v1/readings` ;
+- les paramètres `site_id`, `start_time`, `end_time` et `limit` ;
+- la gestion des erreurs HTTP ;
+- la validation du format de la réponse ;
+- la transformation des mesures ;
+- la conservation des valeurs `NULL` ;
+- la conservation de `data_quality` et `null_reasons` ;
+- `source = "api_history"` ;
+- `dataset_id = NULL` ;
+- la conservation de `raw_data` ;
+- l'idempotence du chargement.
+
 Exécuter les tests ETL :

 ```powershell
 uv run pytest tests\etl -v
 ```

+Exécuter les tests unitaires de l'import API Mock :
+
+```powershell
+uv run pytest tests\etl\test_mock_api_import.py -v
+```
+
+Exécuter le test d'intégration de l'import API Mock :
+
+```powershell
+uv run pytest tests\etl\test_mock_api_import.py -m integration -v
+```
+
 Contrôler la qualité du code :

 ```powershell
 uv run ruff check app\etl tests\etl
 ```

+Contrôler le typage :
+
+```powershell
+uv run mypy app
+```
+
+Exécuter la suite complète avec le seuil de couverture :
+
+```powershell
+uv run pytest --cov-fail-under=85
+```
+
+Lors de la validation de l'import API Mock :
+
+```text
+8 tests unitaires passés
+1 test d'intégration passé
+```
+
+La suite backend complète a également été validée avec une couverture supérieure au seuil de 85 %.
+
 ## Suite du pipeline Data

-L'import historique constitue la première brique du pipeline Data EnerVision.
+Deux sources de données sont maintenant prises en charge :

-Airflow tourne désormais réellement (`etl/airflow/`, `make airflow-up`), mais orchestre pour l'instant le pipeline ML (`ml_train`/`ml_score`, issue #115), pas encore ce pipeline ETL : orchestrer `historical_import.py` (normalisation et chargement micro-batch, issues #15/#16) reste à faire.
+```text
+Dataset CSV/JSON
+      |
+      v
+historical_import.py
+      |
+      +-----------------+
+                        |
+                        v
+             PostgreSQL / TimescaleDB
+                        ^
+                        |
+      +-----------------+
+      |
+mock_api_import.py
+      ^
+      |
+   API Mock
+```

-Le principe reste le même que documenté à l'origine : Airflow orchestre les traitements existants sans remplacer leur logique métier, cf. `etl/airflow/dags/ml_train.py`/`ml_score.py` pour un exemple concret de ce patron (des `BashOperator` qui invoquent le script tel quel).
+La logique d'extraction, de transformation et de chargement est donc disponible pour les deux sources de données du MVP.
+
+Airflow tourne désormais réellement (`etl/airflow/`, `make airflow-up`), mais il orchestre pour l'instant le pipeline ML (`ml_train`/`ml_score`, issue #115), pas encore ces deux imports : orchestrer `historical_import.py` et `mock_api_import.py` (normalisation et chargement micro-batch, issues #15/#16) reste à faire.
+
+Airflow permet de planifier les traitements, gérer leur ordre d'exécution, suivre leur état et remonter les erreurs. Il ne remplace pas la logique ETL Python existante : les scripts actuels restent responsables de l'extraction, de la validation, de la transformation et du chargement. `etl/airflow/dags/ml_train.py` et `ml_score.py` montrent le patron retenu (des `BashOperator` qui invoquent le script tel quel).
+
+Le pipeline Data servira ensuite à préparer les données nécessaires au modèle de Machine Learning.