Merge pull request #163 from ineszang/dev

Remontée dev vers main : import horaire de l'API Mock, une mesure à l'heure pile

docs/architecture/10-infra.md

@@ -89,7 +89,7 @@ l'[ADR 0008](../adr/0008-airflow-execute-le-code-du-backend.md).
 | `ml_score` | `0 * * * *` | `enervision_ml.score`, dans `/opt/ml/.venv` |
 | `alertes` | `15 * * * *` | `app.detection.internal_alerts` puis `app.cli generate-recommendations`, dans `/opt/backend/.venv` |
 | `historical_import` | manuelle | `app.etl.historical_import`, dans `/opt/backend/.venv` ; les fichiers de `data/raw` sont montés en lecture seule dans `/opt/data/raw` |
-| `mock_api_import` | `45 * * * *` | `app.etl.mock_api_import`, dans `/opt/backend/.venv` ; importe l'heure précédant son déclenchement depuis l'API Mock |
+| `mock_api_import` | `45 * * * *` | `app.etl.mock_api_import`, dans `/opt/backend/.venv` ; importe depuis l'API Mock la mesure de l'heure pile précédant son déclenchement |
 | `derive` | `30 5 * * *` | `app.monitoring.drift`, dans `/opt/backend/.venv` ; quotidien parce que sa fenêtre couvre 168 h, et sans reprise parce qu'une dérive n'est pas une panne passagère |
 
 Le DAG `historical_import` réutilise le pipeline historique existant sans dupliquer sa logique.

etl/README.md

@@ -669,13 +669,15 @@ des recommandations (`alertes`, issue #116), l'import historique (`historical_im
 issue #119) et l'import périodique de l'API Mock (`mock_api_import`, issue #15).
 
 Le DAG `mock_api_import` s'exécute chaque heure, à la minute `:45`. Il appelle
-`app.etl.mock_api_import` avec un intervalle explicite d'une heure et une limite de 1 000 lectures
+`app.etl.mock_api_import` sur l'intervalle qui va de l'heure pile à son déclenchement, avec une
-par site. Les deux pipelines normalisent leurs données vers les tables communes `site` et
+limite d'une lecture par site. L'API Mock génère autant de points que la limite demandée,
+répartis sur l'intervalle et le premier à son début : un seul donne la mesure de :00, au pas
+horaire du dataset historique, que les features ML supposent en décalant par ligne. Les deux pipelines normalisent leurs données vers les tables communes `site` et
 `reading`, tout en conservant leur source (`csv` ou `api_history`). La réconciliation globale
 des deux sources reste à compléter dans l'issue #15.
 
 Le DAG `mock_api_import` exécute `app.etl.mock_api_import` toutes les heures. Chaque exécution
-traite l'intervalle Airflow précédent. Les deux pipelines normalisent leurs données vers les
+importe la mesure de l'heure pile qui précède son déclenchement. Les deux pipelines normalisent leurs données vers les
 tables communes `site` et `reading`, tout en conservant leur source (`csv` ou `api_history`).
 
 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`, `ml_score.py`, `alertes.py`, `historical_import.py` et

etl/airflow/dags/mock_api_import.py

@@ -1,7 +1,7 @@
 """DAG d'import périodique des données de l'API Mock EnerVision (issue #15).
 
 Orchestre le pipeline existant `app.etl.mock_api_import` sans dupliquer sa logique ETL.
-Chaque exécution traite l'heure précédant son déclenchement.
+Chaque exécution importe la mesure de l'heure pile qui précède son déclenchement.
 
 Le pipeline backend reste responsable de la validation, de la normalisation, du suivi de la
 qualité, de l'idempotence et du chargement dans PostgreSQL/TimescaleDB.
@@ -18,9 +18,9 @@ from airflow.timetables.trigger import CronTriggerTimetable
 # Le backend possède son propre environnement uv dans l'image Airflow (ADR 0008).
 COMMANDE_BACKEND = "cd /opt/backend && env -u VIRTUAL_ENV uv run --no-sync python -m"
 
-# Le pipeline backend et l'API acceptent au maximum 1 000 lectures par site.
+# Contrainte : l'API Mock génère `limit` points répartis sur l'intervalle, le premier à son début.
-# Cette marge évite de perdre silencieusement une lecture si une heure en contient plus de 60.
+# Un seul, depuis l'heure pile, donne la mesure de :00 au pas du CSV que suppose `shift(168)`.
-LIMITE_LECTURES = 1000
+LIMITE_LECTURES = 1
 
 # Deux reprises donnent trois tentatives au total. Même dans le pire cas, l'exécution reste
 # inférieure au pas horaire du DAG.
@@ -51,7 +51,7 @@ with DAG(
         task_id="import_mock_api",
         bash_command=(
             f"{COMMANDE_BACKEND} app.etl.mock_api_import "
-            "--start-time \"{{ data_interval_start.strftime('%Y-%m-%dT%H:%M:%S') }}\" "
+            "--start-time \"{{ data_interval_end.strftime('%Y-%m-%dT%H:00:00') }}\" "
             "--end-time \"{{ data_interval_end.strftime('%Y-%m-%dT%H:%M:%S') }}\" "
             f"--limit {LIMITE_LECTURES}"
         ),

etl/airflow/tests/test_dags.py

@@ -113,12 +113,12 @@ def test_mock_api_import_calls_the_existing_backend_module(dagbag: DagBag) -> No
     assert "app.etl.mock_api_import" in commande
 
 
-def test_mock_api_import_uses_the_airflow_data_interval(dagbag: DagBag) -> None:
+def test_mock_api_import_asks_for_the_on_the_hour_reading(dagbag: DagBag) -> None:
     commande = dagbag.dags["mock_api_import"].get_task("import_mock_api").bash_command
 
-    assert "--start-time \"{{ data_interval_start.strftime('%Y-%m-%dT%H:%M:%S') }}\"" in commande
+    assert "--start-time \"{{ data_interval_end.strftime('%Y-%m-%dT%H:00:00') }}\"" in commande
     assert "--end-time \"{{ data_interval_end.strftime('%Y-%m-%dT%H:%M:%S') }}\"" in commande
-    assert "--limit 1000" in commande
+    assert commande.endswith("--limit 1")
 
 
 @pytest.mark.parametrize("task_id", ["detection", "recommandations"])