docs: spec — back to a table, health bar as a column

L'utilisateur revient sur la forme liste et retient la proposition
initiale : tableau HomarrDataTable avec la bande de santé en colonne.

La bande reste dans la v1 (D4 inchangée) — c'est la forme qui change,
pas le périmètre. Le tableau rend le tri et la visibilité responsive,
absorbe la croissance du nombre de sites, et correspond à ce que fait
l'interface Ubiquiti.

Contrepartie consignée : dans une colonne la bande est étroite, ce qui
fait de l'infobulle par segment le moyen principal de lire une tranche
plutôt qu'un confort.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
zacharyandClaude Opus 5 committed 2026-10-08 00:24:05 +02:00
1 parent 5736f9ac4e
commit 29390a0cc8
1 file changed
+22 -22
@@ -25,7 +25,7 @@ console, donc un site. Le Site Manager voit tous les sites d'un compte.
|---|---|---|
| D1 | **Deux intégrations indépendantes** | `unifiOs` garde sa clé cloud optionnelle pour son bloc ISP ; `unifiSiteManager` a la sienne. Chacune reste installable et supprimable seule. Coût accepté : la clé est saisie deux fois si l'utilisateur emploie les deux, et deux appelants interrogent le cloud. |
| D2 | **Vue d'ensemble des sites d'abord** | Les captures fournies montrent trois vues — liste des sites, métriques ISP historisées, topologie SD-WAN. Ce sont trois projets. Celui-ci construit aussi le socle (intégration, client, routeur) dont les deux autres dépendront. |
| D3 | **Liste d'état, pas tableau** | La bande de santé est l'élément qu'on lit en premier ; un tableau la réduirait à une colonne parmi d'autres. Une ligne par site : nom, bande pleine largeur, puis une ligne de chiffres discrète. Coût assumé : pas de tri, et la lisibilité se dégrade au-delà de cinq ou six sites (§12). |
| D3 | **Tableau, la bande en colonne** | Réutilise `HomarrDataTable`, le composant partagé déjà employé par les widgets beszel, docker et downloads. Tri par colonne gratuit, visibilité responsive documentée par la skill `datatable-migration` du dépôt, et lisible bien au-delà de dix sites. C'est aussi la forme qu'emploie l'interface Ubiquiti. La bande devient une colonne parmi d'autres : elle ne domine plus la lecture, mais elle reste présente et le widget tient à l'échelle. |
| D4 | **La bande « Internet Health » EST dans la v1** | Décision inversée en cours de conception. Elle avait été écartée au motif que `internetIssues` est un tableau creux dont il faudrait reconstituer les périodes saines. C'est vrai de cette source — mais `isp-metrics` fournit la même information **déjà dense** (§3.3). La bande coûte alors une boucle de coloration, pas un moteur de graphe. |
| D5 | **Rafraîchissement 5 min** | Les compteurs cloud n'évoluent pas plus vite. À contraster avec `unifiOs`, dont la source locale a justifié 5 s. |
@@ -245,24 +245,28 @@ Un compte réellement sans site est un cas distinct et légitime : il affiche un
## 8. Widget
Une liste, pas un tableau. Une entrée par site :
`HomarrDataTable`, une ligne par site.
```
● Nom du site 11 ms · 0 %
████████████░░░░████████████████████████████████
Nom FAI · 203.0.113.10 6/6 équipements · 1 maj · console à jour
```
| Colonne | Source | Rendu |
|---|---|---|
| Site | `name` | toujours visible, jamais masquée en responsive |
| Santé | `health` | bande de 24 segments d'une heure, du plus ancien au plus récent |
| Latence | `latencyMs`, `packetLossPct` | `11 ms · 0 %` ; `—` si aucune mesure |
| ISP | `ispName` | `—` si `null` |
| IP publique | `externalIps` | joint par ` · ` ; `—` si vide |
| Équipements | `deviceCount`, `offlineDeviceCount` | `en ligne / total`, en rouge si des équipements sont hors ligne |
| Mises à jour | `pendingUpdateCount` | en jaune si > 0 ; `0` affiché normalement, c'est une vraie mesure |
| Console | `consoleUpdateAvailable` | `—` si `null` — l'absence de host correspondant n'est pas « à jour » |
- **Pastille d'état** en tête : couleur de la tranche la plus récente.
- **Bande de santé** pleine largeur, vingt-quatre segments d'une heure, du plus
ancien au plus récent. Vert sain, orange dégradé, rouge coupé, gris inconnu.
Segments jointifs avec un filet de séparation, pour qu'on distingue deux
tranches consécutives de même couleur.
- **Latence et perte** à droite du nom, en encre atténuée. `—` si aucune mesure.
- **Ligne de détail** discrète : FAI, IP publique, équipements en ligne / total,
mises à jour d'équipements en attente, état de mise à jour de la console.
Colonnes triables. Visibilité responsive selon la largeur de tuile, suivant la
convention documentée par la skill `datatable-migration` : les colonnes les moins
essentielles disparaissent en premier, `Site` et `Santé` jamais.
Chaque valeur inconnue s'affiche `—`, jamais zéro ni « à jour ».
**La bande de santé.** Vingt-quatre segments jointifs séparés par un filet, pour
qu'on distingue deux tranches consécutives de même couleur. Vert sain, orange
dégradé, rouge coupé, gris inconnu. Dans une colonne de tableau elle sera étroite :
c'est le prix de la forme tableau, et c'est ce qui rend l'infobulle nécessaire
plutôt que confortable.
**Couleurs.** À valider par le validateur de palette avant écriture, en thème
clair et sombre, comme pour le graphe de débit. Les quatre états doivent rester
@@ -276,11 +280,6 @@ aussi ce qui rend la bande lisible sans distinguer les couleurs.
**Badge de fraîcheur** en tête de widget, alimenté par `updatedAt`, comme sur le
widget `unifiOs`.
**Limite assumée.** La forme liste se dégrade au-delà de cinq ou six sites : la
tuile devient un long défilement. C'est le prix de mettre la santé au centre
plutôt que dans une colonne, et c'est un choix explicite (D3). Au-delà, la forme
tableau redeviendrait préférable.
## 9. Tests
| Niveau | Couvre | Réseau |
@@ -333,6 +332,7 @@ passer — dont un qui empêchait l'application de démarrer.
| La clé cloud voit tous les sites du compte, y compris non possédés | Sécurité | Assumé et **voulu** ici : c'est une vue multi-sites. Contrairement à `unifiOs`, aucun filtrage n'est souhaitable — mais la documentation du widget doit dire ce qu'il expose |
| Limitation de débit sur `api.ui.com` | Fiabilité | Cadence 5 min, deux appels par cycle |
| Deux intégrations interrogent le cloud en parallèle | Fiabilité | Conséquence acceptée de D1 ; caches indépendants, ~24 requêtes/heure au total |
| Le nombre de sites croît | Interface | Limite connue et assumée (D3) : au-delà de cinq ou six sites la liste devient un long défilement. Le basculement vers une forme tableau est le remède, et reste possible sans toucher au contrat |
| Le nombre de sites croît | Interface | Le tableau absorbe la croissance là où des cartes ou une liste se dégraderaient ; visibilité responsive des colonnes, `Site` et `Santé` toujours conservées |
| La bande est étroite dans une colonne | Lisibilité | Conséquence directe de D3. L'infobulle par segment n'est donc pas un confort mais le moyen principal de lire une tranche |
| Quatre états de santé distingués par la seule couleur | Accessibilité | Palette validée avant écriture ; infobulle par segment rendue obligatoire si le jeu à quatre états ne passe pas les contrôles de vision déficiente |
| Une tranche sans mesure affichée comme saine | Justesse | État `"unknown"` explicite au contrat, testé ; la fenêtre porte toujours 24 entrées |