From f489213c9c66dfb822c4f2b0388f4cbb3526d593 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Th=C3=A9o=20Gastinel?= <264859180+gastinelt@users.noreply.github.com> Date: Fri, 16 Oct 2026 20:09:53 +0200 Subject: [PATCH] README Co-Authored-By: Claude Opus 5.5 --- README.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..309cbae --- /dev/null +++ b/README.md @@ -0,0 +1,75 @@ +# meteo-collecte + +Collecteur du site météo public (weather.gastinel.me). Python 3, bibliothèque standard seulement +(aucune dépendance à installer ; `pytest` est facultatif pour lancer les tests). + +Conception : `Gastinel-Projets/site-meteo-architecture-2026-10-15.md`. +Ce dépôt ne touche ni `weather-collector` ni `weather-db`. + +## Ce que fait un tick + +Lancé toutes les 5 min (hh:x4 et hh:x9) par le minuteur systemd : + +1. **ROMMA** (`romma.py`) : au plus une requête `type=live&global=1` toutes les 10 min, toutes stations d'un coup. +2. **Infoclimat** (`infoclimat.py`) : passage principal à hh:x4 seulement si une station est due (rythme + mesuré dans la base), rattrapage ciblé à hh:x9, requêtes groupées par lots de 25, fenêtre d'un jour. + Plafonds : 1000 requêtes/jour pour le site (jour de Paris **et** 24 h glissantes) et quota commun + `~/gws-collecte/quota.json` (4999). Alerte à 80 % (envoi ntfy désactivé par défaut). +3. **Stockage** (`stockage.py`) : SQLite `var/mesures.sqlite`, une ligne par (source, station, instant UTC), + 14 jours glissants. Les sources ne sont jamais mélangées. +4. **Publication** (`publier.py`) : fichiers statiques écrits de façon atomique sous `/data/` : + `stations.json`, `station/-.json` (48 h), `etat.json`. + +Toute erreur réseau ou de statut pose une pause de 15 min sur la source concernée ; l'autre source et la +publication continuent. Un verrou empêche deux ticks simultanés. + +## Configuration (variables d'environnement) + +| Variable | Rôle | Défaut | +|---|---|---| +| `MC_BASE` | dossier d'état (var/, base, journal) | `~/meteo-collecte` | +| `MC_PUBLIC` | racine servie par le serveur web | `$MC_BASE/public` | +| `MC_QUOTA_COMMUN` | compteur commun Infoclimat | `~/gws-collecte/quota.json` | +| `MC_STATIONS` | liste des stations Infoclimat | `config/stations.json` | +| `MC_PLAFOND_SITE` / `MC_PLAFOND_COMMUN` | plafonds Infoclimat | 1000 / 4999 | +| `MC_LOT_MAX` | stations par requête | 25 | +| `MC_COMPTE_PAR_STATION` | compter une requête par station | 0 | +| `MC_ROMMA_ACTIF` / `MC_INFOCLIMAT_ACTIF` | activer une source | 1 / 1 | +| `MC_ALERTE_ACTIVE`, `MC_NTFY_URL` | alerte quota | 0, vide | +| `MC_DIRECT_COMPAT` | écrire aussi l'ancien `direct.json` | vide | + +### Secrets + +Uniquement par variables d'environnement, lues au moment de l'appel, jamais écrites ni affichées : + +* `MC_JETON_INFOCLIMAT` : jeton Infoclimat (lié à l'IP du VPS) ; +* `MC_CLE_ROMMA` : clé API ROMMA. + +Sans la variable, la source ne fait aucun appel (`sans_jeton` / `sans_cle`). Tout message de journal passe +par `scrub` (masque `token=`, `apikey=` et la valeur, en clair ou encodée). + +## Commandes + +```sh +python3 -m meteo_collecte.ordonnanceur # un tick +python3 -m meteo_collecte.ordonnanceur --publier # republie depuis la base, sans aucun appel réseau +python3 -m meteo_collecte.ordonnanceur --config # configuration ; secrets : « définie » ou « absente » +``` + +## Tests (hors ligne) + +```sh +python -m pytest -q # ou : python -m unittest discover -s . -p "test_*.py" +python -m pytest -q -s tests/test_hors_ligne.py # affiche les compteurs de requêtes simulés +``` + +`tests/__init__.py` coupe le réseau (DNS et connexions hors boucle locale lèvent une erreur) : aucun test ne +peut joindre une API. Les réponses viennent de `tests/fixtures/` ou de petits serveurs simulés ; les secrets +sont des valeurs fictives passées dans un environnement en mémoire. `tests/test_hors_ligne.py` simule +plusieurs jours de ticks (fonctionnement normal, plafond, panne longue, sans secrets, purge, heure d'hiver). + +## Déploiement + +`deploiement/meteo-collecte.service` et `.timer` sont des **exemples non installés** (unité utilisateur). +Points à vérifier avant installation par Théo : voir les commentaires `[À VÉRIFIER]` en tête du service +(emplacement du code, linger, arrêt de `meteo-direct.timer` pour ne pas compter deux fois le quota).