diff --git a/docs/superpowers/specs/2026-10-13-nouveaux-domaines-design.md b/docs/superpowers/specs/2026-10-13-nouveaux-domaines-design.md new file mode 100644 index 0000000..4f9fa5f --- /dev/null +++ b/docs/superpowers/specs/2026-10-13-nouveaux-domaines-design.md @@ -0,0 +1,185 @@ +# Nouveaux domaines de notification : Storage, Cellular, et une procédure pour les suivants + +- **Date** : 2026-10-13 +- **Statut** : design validé en conversation, spec à relire. +- **Décision projet qui en découle** : D-030 (texte en fin de document). + +## Objectif + +- Faire pour d'autres points d'attention **le même travail qu'Energy** : des analyses sans LLM, un verdict du jour, une notification au client et au support (D-020, D-022, D-025). +- Deux premiers domaines : **l'espace disque restant** et **la qualité du signal 4G**. D'autres suivront peut-être. +- Les données viendront plus tard. Aujourd'hui, on prépare : + - une **procédure réutilisable**, pour ajouter vite un nouveau domaine, donc une nouvelle notification ; + - pour chacun des deux domaines, une **note de départ** : ce qu'on sait déjà, et ce qu'il faudra demander aux données. +- **Critère de réussite** : quand les CSV arrivent, on sait quoi faire, dans quel ordre, et où ranger chaque chose. + +## Ce qui ne change pas + +- Le code et les pages d'Energy, les maquettes et les données (`data/`). +- Aucune analyse ni aucun seuil n'est écrit avant les données : pas de données synthétiques (D-003), aucun seuil sans source. + +## Les domaines + +Les noms sont en anglais, en un mot, comme `energy` : + +- **`storage`**, l'espace disque. C'est le mot du collecteur (`data_storage_*`). +- **`cellular`**, le signal 4G : niveau radio, enregistrement au réseau et lien, c'est-à-dire tout ce que rapporte le modem. Le VPN (`ip_nebula1`) et les envois de données n'en font pas partie : la doc AIMsight les range sous « Communication » (§ « Likely high-value future signals »), qui pourra devenir un domaine plus tard. + +## Ce qui est créé maintenant + +| Fichier | Contenu | +|---|---| +| `src/storage/__init__.py`, `src/cellular/__init__.py` | vides, comme `src/energy/__init__.py` : la place du code, qui viendra avec la première analyse | +| `docs/storage/domaine/point-de-depart.md` | note de départ du domaine (≈ 50 l), voir plus bas | +| `docs/cellular/domaine/point-de-depart.md` | idem | +| `.claude/skills/nouveau-domaine/SKILL.md` | la procédure (≈ 80 l), voir plus bas | + +- Les autres dossiers du domaine (`analyses/`, `guide/`, matrice) ne sont pas créés : git ne suit pas les dossiers vides. Le skill les crée quand ils ont un contenu. +- Les CSV des nouvelles métriques iront dans `data//` (D-029), à côté des CSV Energy de la même station. + +## Note de départ d'un domaine + +Elle est rangée dans `docs//domaine/`, avec le savoir du domaine qui y restera, et elle se complète au fil des étapes. Sections : + +1. **Question du domaine**, en une phrase. +2. **Ce que mesure le collecteur** : métriques, unités, ligne source dans `docs/aimsight/collecteur_system_info.py`, nom exporté (`SYNC_SPEC`). +3. **Ce que montrent les instantanés** de `data/metadata.md` (WILDSTRUBEL et VERMONT), sans les identifiants (SIM, IP). +4. **Ce qu'en disent les docs AIMsight** : le manuel de la station et la FAQ. +5. **Pièges déjà connus.** +6. **CSV à demander.** +7. **Pistes d'analyses** : ce sont des pistes, pas des décisions. Elles passent dans les fiches au moment où les analyses s'écrivent. + +### Storage : ce qu'on sait déjà + +- **Collecteur** (`get_proc_info`) : `psutil.disk_usage('/data')`, la partition des données. Il produit `data_storage_percent` [%], et `data_storage_free_gb`, `_used_gb` et `_total_gb` [GiB, ÷ 1024³]. Dans `SYNC_SPEC`, les trois derniers sont exportés sous une seule métrique `data_storage_gb`, avec un label `state` qui vaut `free`, `used` ou `total`. +- **Instantanés** : + - WILDSTRUBEL : total 5,98, libre 5,61, utilisé 0,04 GiB ; + - VERMONT expose d'autres noms, absents de notre copie du collecteur : `total_disk_1k-blk`, `used_disk_1k-blk`, `avail_disk_1k-blk` (blocs de 1 kio), `DB_file_size`, `DB_total_entries`, `DB_uploaded`, `DB_not_uploaded`. +- **Manuel de la station** (§ Disk) : « Monitor available capacity, especially for frequent schedules, long time series, or image-heavy acquisitions ». +- **Pièges** : + - **utilisé + libre ≠ total** (5,65 contre 5,98 GiB chez WILDSTRUBEL ; 3,46 contre 3,67 GiB chez VERMONT, soit 3 623 856 contre 3 849 952 blocs de 1 kio). Un écart de 5 à 6 % est cohérent avec les blocs réservés d'ext4, mais ce n'est pas vérifié. `psutil.percent` se calcule sur utilisé / (utilisé + libre), pas sur le total ; + - **deux familles de métriques**, selon la version du logiciel ou la partition mesurée. Laquelle est exportée pour chaque station ? Question à poser ; + - les **totaux diffèrent** d'une station à l'autre (3,67 et 5,98 GiB ; peut-être pas la même partition) : raisonner en espace libre et en vitesse de remplissage, pas sur un pourcentage fixe. +- **Pistes** : l'espace libre du jour ; la vitesse de remplissage et les jours avant saturation (libre ÷ pente) ; les purges (sauts vers le haut). + +### Cellular : ce qu'on sait déjà + +- **Collecteur** (`get_modem_info`, commandes AT, une lecture du modem tous les 10 cycles, sinon la dernière réponse est réutilisée) : + - `rssi_dbm` (AT+CSQ, de −113 à −51 dBm par pas de 2 ; 99 signifie inconnu) ; + - `ber_percent` (AT+CSQ, une table de codes 0 à 7) ; + - `rsrq_dB` (AT+CESQ, de −19,5 à −2,5 dB par pas de 0,5) ; + - `rsrp_dBm` (AT+CESQ, de −140 à −43 dBm) ; + - `network_operator`, `network_technology` (GSM, UMTS, LTE, E-UTRAN) ; + - `registration` (AT+CEREG : home, roaming, searching, denied, not_registered, unknown) ; + - `link` (`up` si le contexte PDP a une adresse IP, sinon `down`). + + Tout cela est exporté (`SYNC_SPEC`, rubrique `modem`), sauf `ip`, exporté à part en `ip_address{interface="modem"}`. +- **Instantanés** : + - WILDSTRUBEL : RSRP −81 dBm, RSRQ −13,5 dB, RSSI −51 dBm, BER 2,4 %, E-UTRAN, home, link up ; + - VERMONT : RSRP −105 dBm, RSRQ −10 dB. +- **Manuel de la station et FAQ** : + - le « Link status » doit passer à « Up » ; + - une connexion 4G peut mettre quelques minutes à s'établir après le démarrage ; + - une installation en intérieur, en sous-sol, ou derrière du béton ou du métal affaiblit la réception ; + - **« Loss of remote connectivity does not necessarily mean that the measurement station itself has stopped operating »**. +- **Pièges** : + - **une donnée absente peut être l'anomalie elle-même**, comme pour Energy : quand le lien tombe, les mesures du modem n'arrivent plus. Distinguer : + - un trou pendant une coupure d'énergie, à croiser avec Energy ; + - un trou avec la station alimentée, qui fait penser à un problème de lien ; + - un trou rempli plus tard par une remontée différée ; + - **RSSI à −51 dBm veut dire « −51 dBm ou plus »** : la valeur sature ; + - si la lecture du modem échoue, le collecteur rapporte `link = down` avec toutes les valeurs vides : un lien `down` sans mesures n'est pas un signal faible ; + - **métriques texte** (`registration`, `link`, `network_technology`) : `common.stations.load_csv` ne lit que des nombres et ignore ces fichiers ; + - **moyennes horaires** de grandeurs en dB : la moyenne de valeurs en dB n'est pas la moyenne des puissances, et elle aplatit les décrochages brefs ; + - **aucun seuil de qualité** (« bon » ou « faible ») n'a encore de source : il en faudra une (doc du module radio, opérateur, expert), ou bien comparer la station à son propre passé. +- **Pistes** : + - le niveau du jour (médiane du RSRP) comparé au passé de la station ; + - la part des heures avec `link = up` ; + - les heures sans mesure alors que la station est alimentée. + +## Le skill `nouveau-domaine` + +Il se déclenche quand l'utilisateur apporte les données d'un nouveau point d'attention, ou veut une nouvelle notification. Il décrit sept étapes, et **chacune s'arrête pour l'avis de l'utilisateur**, qui décide si la suivante est utile (mémoire « simple d'abord »). + +1. **Situer le domaine** + - Un nom en anglais, en un mot, et la question du domaine en une phrase. + - Lire `docs//domaine/point-de-depart.md`. S'il n'existe pas, le créer avec les sections ci-dessus, et créer `src//__init__.py`. +2. **Recevoir les données** + - Les CSV vont dans `data//`. + - Vérifier qu'ils se chargent avec `common.stations.load_stations`. Une métrique texte demande d'adapter le chargeur commun à ce moment-là. + - Relever la couverture, le pas de temps et les trous. +3. **Explorer** + - Explorer par script, jamais en affichant les CSV. + - Compléter la note avec les faits observés : plages, cycles, sauts. + - Croiser avec Energy : un trou pendant une coupure d'énergie n'appartient pas à ce domaine. +4. **Recueillir les cas de référence** + - Demander à l'expert des périodes annotées, normales ou à problème, et les ranger dans `docs//domaine/cas-annotes-par-l-expert.md`. + - Sans cas annotés, pas de verdict livré. +5. **Écrire les analyses** + - Une analyse par question, avec le skill `nouvelle-analyse` : fiche, code embarquable, constantes sourcées. + - La première crée la page de comparaison du domaine, `src//all_analyses.py` (D-016). +6. **Produire le verdict du jour**, c'est-à-dire le contrat de notification, ci-dessous. + - Ce que veut dire Red pour ce domaine se décide avec l'utilisateur, et la combinaison des analyses aussi (une matrice tenue par l'utilisateur si elle est utile, comme pour Energy). +7. **Livrer et documenter** + - Écrire la figure `src//final.py` (D-021). + - Ajouter la notification sur la maquette Home du support et un bloc dans la section Diagnostic du client. Pour les maquettes, proposer, puis attendre les consignes de l'utilisateur (mémoire « attendre les instructions »). + - **Si les maquettes ne parcourent pas encore une liste de domaines, faire ce passage d'abord, une seule fois** (voir plus bas). + - Écrire le guide `docs//guide/`, en deux couches, client et support (D-020). + - Mettre à jour `CLAUDE.md` (tableau des analyses du domaine, état, commandes, carte) et ajouter une entrée dans `docs/decisions.md` pour le nouveau domaine. + +Le skill renvoie vers `nouvelle-analyse` pour tout ce qui touche à une analyse, sans le répéter. En retour, `nouvelle-analyse` §1 renvoie vers `nouveau-domaine` quand le domaine est nouveau. + +## Le contrat de notification + +Chaque domaine livré expose le même contrat que `src/energy/day_color.py` : + +- `run(series) -> {analysis, rule, points}`, avec un point par jour UTC, causal, `anomaly = None`, et la couleur dans `facts.color` : `GREEN`, `ORANGE`, `RED`, ou `None` (inconnu, gris) ; +- `HEADLINE = {"RED": "...", "ORANGE": "..."}` : une phrase en anglais par couleur notifiée (D-023). Green ne notifie rien (D-025). + +Energy le respecte déjà, à un détail près : sa `HEADLINE` est aujourd'hui dans `maquettes/support/home.py`. + +## Le passage des maquettes à plusieurs domaines (reporté) + +- **Quand** : au premier nouveau domaine qui atteint l'étape 7. +- **Quoi** : + - déplacer `HEADLINE` d'Energy dans `src/energy/day_color.py` ; + - dans `maquettes/support/home.py` et la vue client, remplacer l'appel direct à `energy.day_color` par une liste `DOMAINS = {"Energy": energy.day_color, "Storage": storage.day_color, …}`, parcourue pour les notifications. +- **Ensuite**, ajouter un domaine revient à ajouter une ligne. +- **Pourquoi pas maintenant** : ce serait une liste à un seul élément, et il n'y aurait pas de second domaine pour vérifier que le contrat tient. +- Le design s'y prête déjà : côté client, la section Diagnostic prévoit « un rectangle repliable par notification » (D-022), et côté support, chaque notification affiche son domaine (D-025). + +## Documentation à mettre à jour + +- `docs/decisions.md` : D-030, ci-dessous. +- `CLAUDE.md` : + - « État et prochaine étape » : Storage et Cellular ont leur structure et attendent les données ; + - « Carte du dépôt » : `docs/storage/`, `docs/cellular/`, `src/storage/`, `src/cellular/`, le skill `nouveau-domaine`. +- `.claude/skills/nouvelle-analyse/SKILL.md` §1 : une phrase qui renvoie vers `nouveau-domaine`. + +## Vérification + +- Il n'y a pas de code de calcul. On relit les deux notes de départ en les confrontant au collecteur, au manuel, à la FAQ et à `metadata.md` : chaque fait cite sa source, et aucun identifiant de station (SIM, IP) n'est recopié. +- `python3 src/energy/final.py` et `python3 src/energy/all_analyses.py` tournent toujours : les nouveaux paquets ne cassent pas les imports. + +## Options écartées + +- **La procédure dans un document de `docs/`** : Claude ne le trouve pas tout seul, et il recouvre en partie le skill `nouvelle-analyse`. +- **La procédure ajoutée au skill `nouvelle-analyse`** : elle mélangerait deux échelles (une analyse, un domaine entier), et ce skill se charge à chaque nouvelle analyse. +- **Le nom `network`** : il engloberait le VPN et les envois de données, qui relèvent de « Communication ». +- **Le passage des maquettes à plusieurs domaines dès maintenant** : une liste à un seul élément, sans second domaine pour vérifier le contrat. +- **Créer tout de suite `analyses/`, `guide/` ou des fiches vides** : de l'échafaudage sans contenu, que git ne suit pas. + +## Texte de la décision D-030 + +## D-030 — 2026-10-13 — Nouveaux domaines Storage et Cellular ; procédure `nouveau-domaine` ; contrat de notification +- **Statut** : active. Complète D-026 (structure par domaine) et D-025 (notifications support). +- **Décision** : + - deux nouveaux domaines, rangés comme Energy : `storage` (espace disque) et `cellular` (signal 4G : niveau radio, enregistrement, lien). Chacun a `src//` et une note de départ, `docs//domaine/point-de-depart.md`. Les analyses attendent les données ; + - la procédure pour ajouter un domaine, donc une notification, est le skill `nouveau-domaine` (sept étapes, de la réception des données à la livraison). Il renvoie vers `nouvelle-analyse` pour chaque analyse ; + - **contrat de notification** : chaque domaine livré expose `day_color.run(series)`, un point par jour avec `facts.color` (`GREEN` / `ORANGE` / `RED` / `None`), et une `HEADLINE` en anglais par couleur notifiée ; + - le passage des maquettes à une liste de domaines se fait au premier nouveau domaine livré, pas avant. +- **Pourquoi** : demande de l'utilisateur, qui veut le même travail qu'Energy pour d'autres points d'attention, et pouvoir ajouter vite de nouvelles notifications. Le collecteur mesure déjà l'espace disque et le signal du modem. +- **Options écartées** : la procédure dans un document de `docs/` (Claude ne le trouve pas seul) ou dans `nouvelle-analyse` (deux échelles mêlées) ; le nom `network` (VPN et envois relèvent de « Communication ») ; le passage multi-domaines dès maintenant (une liste à un seul élément, contrat non vérifié). +- **Conséquence** : + - `HEADLINE` d'Energy quittera `maquettes/support/home.py` pour `src/energy/day_color.py` lors du passage multi-domaines ; + - le chargeur commun ne lit que des métriques numériques : il faudra l'adapter si l'on retient les métriques texte du modem (`link`, `registration`).