Files
Support-Agent/docs/superpowers/specs/2026-10-13-nouveaux-domaines-design.md
T

218 lines
19 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 sont arrivées pendant la conception : `data/WEISSHORN/` contient tous les champs de la caméra (voir « Jeu de travail »). On les explorera ensuite, pour voir ce qui mérite une notification. 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 l'exploration des 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 vont dans `data/<STATION>/` (D-029), à côté des CSV Energy de la même station.
## Jeu de travail des nouveaux domaines : WEISSHORN
- VERMONT (D-009) n'a ni métrique de disque ni métrique de modem. Pour `storage` et `cellular`, le jeu de travail est **WEISSHORN** : tout ce que contient `data/WEISSHORN/`, sans restriction de dates. Un export plus long le remplace ou le complète, et c'est souhaitable : la vitesse de remplissage du disque et la comparaison du signal à son propre passé demandent des fenêtres larges.
- L'export reçu le 2026-10-13 contient tous les champs de la caméra. Il couvre ce que l'extraction a fourni, du 2026-10-03 07:00 au 2026-10-13 07:00 UTC, soit 241 heures, sans trou.
- Ce que montre un premier profil, fait par script :
- **les métriques numériques** sont des moyennes horaires, comme pour VERMONT ;
- **les métriques texte** (`link`, `registration`, `network_technology`, `network_operator`, `BatteryState`) sont la **liste des échantillons de l'heure**, par exemple `['up', 'up', 'up', 'up']`, soit un toutes les 15 minutes. Ce ne sont pas des moyennes ;
- **`last_sync`** est la liste des heures de synchronisation de l'heure (toutes les 15 minutes). C'est une piste pour un futur domaine « Communication », hors du périmètre ici ;
- **9 copies** `… (1).csv`, `(2).csv`, `(3).csv` (`ShuntVoltage`, `rsrq_dB`, `rssi_dbm`, `sensor_thermal_deg_c`) sont identiques à l'octet près à leur original. Avec elles, `load_stations` s'arrête sur une erreur « doublon » ;
- **38 fichiers `…:Zone.Identifier`** ont été laissés par le téléchargement sous Windows ;
- `SIM_CCID` et `ip` sont des identifiants de station. Ils restent dans `data/` (dépôt privé, D-014) et ne sont jamais recopiés dans les notes ;
- `Battery Voltage` couvre la même plage que `BusVoltage`, mais les deux séries ne sont pas identiques. Point à éclaircir pour Energy, hors du périmètre ici.
- **Réception (étape 2 du skill, appliquée à WEISSHORN)** :
- supprimer les 9 copies identiques et les 38 `Zone.Identifier` ;
- ajouter `*:Zone.Identifier` à `.gitignore` ;
- versionner `data/WEISSHORN/`, comme `data/VERMONT/`.
Les métriques texte restent ignorées par le chargeur tant que l'exploration n'a pas montré qu'on en a besoin.
## Note de départ d'un domaine
Elle est rangée dans `docs/<domaine>/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 reçus et manquants**, par rapport à ce que le collecteur exporte.
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`.
- **WEISSHORN** (plages observées dans l'export du 2026-10-13) :
- `data_storage_free_gb` de 3,21 à 3,48 ; `data_storage_used_gb` de 2,17 à 2,45 ; `data_storage_total_gb` à 5,98 ;
- le label `state` du collecteur est aplati dans le nom de la métrique ;
- `data_storage_percent` n'est pas dans l'export, ni les métriques `*_disk_1k-blk` et `DB_*` de VERMONT.
- **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.
- **WEISSHORN** (plages observées dans l'export du 2026-10-13, moyennes horaires) :
- RSRP de −98,25 à −60,50 dBm ; RSRQ de −18,75 à −5,00 dB ; RSSI de −67,5 à −51,0 dBm (le plafond est atteint) ; BER de 0,53 à 13,00 % ;
- les échantillons texte montrent `link` à `up`, `registration` à `home`, `E-UTRAN` et un seul opérateur. L'exploration dira s'ils changent jamais ;
- toutes les métriques du modem de `SYNC_SPEC` sont là.
- **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`) : ce sont des listes d'échantillons par heure. `common.stations.load_csv` ne lit que des nombres et ignore ces fichiers ;
- **moyennes de codes** : `ber_percent` et `rssi_dbm` sont des codes AT (tables du collecteur) moyennés sur l'heure. Une moyenne comme 0,53 % ne correspond à aucun code ;
- **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>/domaine/point-de-depart.md`. S'il n'existe pas, le créer avec les sections ci-dessus, et créer `src/<domaine>/__init__.py`.
2. **Recevoir les données**
- Les CSV vont dans `data/<STATION>/`.
- 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>/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/<domaine>/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/<domaine>/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/<domaine>/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`.
- `CLAUDE.md`, prochaine étape : explorer WEISSHORN (étape 3 du skill) pour `storage` et `cellular`, et repérer les autres champs qui mériteraient une notification.
## 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.
- Après la réception, `load_stations(["data/WEISSHORN"])` charge le dossier sans erreur de doublon, et `git status` ne montre plus de `Zone.Identifier`.
## 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) ; précise D-009 (jeu de travail par domaine).
- **Décision** :
- deux nouveaux domaines, rangés comme Energy : `storage` (espace disque) et `cellular` (signal 4G : niveau radio, enregistrement, lien). Chacun a `src/<domaine>/` et une note de départ, `docs/<domaine>/domaine/point-de-depart.md`. Les analyses attendent l'exploration des données ;
- leur jeu de travail est **WEISSHORN** : tout `data/WEISSHORN/`, sans restriction de dates (tous les champs de la caméra ; l'export du 2026-10-13 couvre 10 jours, un export plus long le remplacera) : VERMONT (D-009) n'a ni métrique de disque ni métrique de modem ;
- 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`), qui sont des listes d'échantillons par heure ;
- les copies identiques et les `Zone.Identifier` de WEISSHORN sont supprimés, et `*:Zone.Identifier` est ignoré par git.