gilles/system_update
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: roadmap tâches 1.9-8 (briefs, gates de validation, designs tâche 2) + plans d'implémentation

Browse Source 
Cartographie complète (liste_taches/coherence_taches), briefs tacheN + gates
validation_tacheN, design tâche 2 (docs/design/tache2/), specs/plans jalon 1-2
et tâche 1.9/2 (Phase 1, Phase 2, SJ-0→3). Validations consignées (1.9 ✅, 2-8 🟡).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
gilles soulier
2026-06-05 19:50:25 +02:00
parent f9ce991ec5
commit 0fbca06d3d
39 changed files with 11916 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tache8.md
+374
View File
@@ -0,0 +1,374 @@
# Consigne de dev — App locale Rust/GNOME connectée au serveur
> **Type** : mission de **développement progressif** après validation utilisateur du 2026-06-05.
> **Langue** : français.
> **Livrable final attendu** : app locale Rust/GNOME développée par jalons, en commençant par un client API minimal.
---
## 0. Contexte
La webapp `system_update` pilote des machines Linux via un backend central :
- SSH agentless ;
- snapshots JSON ;
- exécutions ;
- logs/rapports ;
- Hermes/MCP ;
- terminal ;
- paramètres ;
- schedules.
La tâche 8 vise une évolution : créer une **application locale native** en Rust, style GNOME/libadwaita, qui se connecte au serveur `system_update` via API et reprend une partie de l'UI du frontend, sans nécessiter de navigateur web.
Validation utilisateur :
- 2026-06-05 : le démarrage du développement est validé.
- La première phase crée un scaffold Rust compilable et un client API minimal.
- L'UI GTK4/libadwaita attend l'installation des bibliothèques système `gtk4` et `libadwaita-1`.
---
## 1. Objectif
Concevoir une application locale :
- développée en Rust ;
- UI GTK4/libadwaita ou équivalent GNOME moderne ;
- thème aligné avec le design system Gruvbox seventies ;
- communication API avec le backend `system_update` ;
- affichage des machines, tuiles, rapports, logs, paramètres ;
- exécution des actions via le backend, jamais SSH direct par défaut ;
- support optionnel Hermes via le backend ;
- mode desktop local plus confortable qu'un navigateur pour usage quotidien.
---
## 2. Périmètre fonctionnel
### MVP app locale
- configuration URL serveur ;
- authentification par token/API key ;
- liste des machines ;
- vue état courant machine ;
- tuiles machine compactes ;
- détail machine ;
- lancement `apt_update_analyze` ;
- affichage actions en cours ;
- lecture rapports ;
- lecture logs réduits ;
- notifications desktop simples.
### Fonctions avancées
- terminal de logs live via WebSocket/SSE ;
- vrai terminal SSH interactif via backend, si activé ;
- vue Hermes native ;
- paramètres frontend/app ;
- scripts post-install ;
- Docker Compose ;
- mode offline partiel : cache lecture seule des derniers états ;
- tray icon ;
- notifications GNOME ;
- import/export configuration serveur.
---
## 3. Architecture cible
```text
┌──────────────────────────────────────────────┐
│ App locale Rust/GNOME │
│ - UI libadwaita │
│ - stockage config local │
│ - client HTTP/WebSocket │
│ - cache lecture seule │
└───────────────────┬──────────────────────────┘
│ HTTPS / WS / SSE
┌───────────────────▼──────────────────────────┐
│ Backend system_update │
│ - API REST stable │
│ - événements live │
│ - auth clients │
│ - stockage JSON/logs/rapports │
│ - orchestration SSH │
│ - proxy Hermes/MCP │
└───────────────────┬──────────────────────────┘
│ SSH
┌───────────────────▼──────────────────────────┐
│ Machines Linux │
└──────────────────────────────────────────────┘
```
Règle :
> L'app Rust ne fait pas de SSH direct au MVP. Elle demande au backend de lancer les actions et consomme les JSON, logs et événements.
---
## 4. Stack technique à étudier
### Rust
- `gtk4` ;
- `libadwaita` ;
- `glib`/`gio` ;
- `reqwest` ou client HTTP async compatible ;
- `tokio` si retenu ;
- WebSocket via crate adaptée ;
- `serde`/`serde_json` ;
- `keyring` pour stocker le token localement ;
- `directories` pour chemins de config/cache ;
- `tracing` pour logs app.
Alternative à comparer :
- `relm4` pour architecture UI plus structurée ;
- `iced` si GTK/libadwaita devient trop contraignant, mais moins GNOME natif.
### Design system GNOME
Réutiliser :
- `design_system/tokens/tokens.gnome.css` ;
- `design_system/tokens/tokens.json`.
À concevoir :
- mapping tokens CSS web → libadwaita ;
- widgets équivalents aux tuiles ;
- couleurs dark/light ;
- icônes SVG compatibles GTK ;
- densité proche du frontend.
---
## 5. API backend nécessaire
L'API doit rester commune au frontend web, Hermes/MCP et app locale.
Endpoints à utiliser :
```text
GET /api/system/status
GET /api/system/metrics
GET /api/machines
GET /api/machines/:id/state
GET /api/machines/:id/hardware
GET /api/machines/:id/metrics
GET /api/machines/:id/snapshots
GET /api/machines/:id/executions
GET /api/machines/:id/reports
GET /api/machines/:id/messages
POST /api/machines/:id/actions
GET /api/reports
GET /api/reports/:id
GET /api/artifacts/:id/important-lines
GET /api/settings
PATCH /api/settings
GET /api/events
GET /api/ws/machines/:id/output
```
À ajouter ou clarifier côté backend :
- version d'API ;
- pagination ;
- erreurs structurées ;
- auth token dédiée client local ;
- droits par action ;
- révocation token ;
- audit des clients ;
- limitation de débit ;
- endpoint capabilities.
Exemple capabilities :
```json
{
"apiVersion": "1",
"features": {
"machines": true,
"actions": true,
"terminalOutput": true,
"interactiveSsh": false,
"hermes": true,
"settings": true
}
}
```
---
## 6. Sécurité
Règles :
- token stocké dans le trousseau local via `keyring`, pas en clair dans un fichier ;
- HTTPS recommandé hors localhost ;
- permissions minimales par token ;
- actions dangereuses confirmées dans l'app ;
- les secrets SSH/sudo restent uniquement côté backend ;
- l'app locale ne reçoit jamais les credentials machines ;
- logs locaux sans secret ;
- blocage si certificat/host inconnu selon politique choisie.
Profils de token :
- lecture seule ;
- opérateur : refresh + actions non destructives ;
- admin : actions dangereuses + paramètres ;
- debug : accès logs étendus.
---
## 7. UX native proposée
### Layout desktop
```text
┌────────────────────────────────────────────────────────────────────┐
│ HeaderBar System Update [search] [refresh] [settings] │
├───────────────┬────────────────────────────────────────────────────┤
│ Sidebar │ Machines │
│ │ ┌────────────────────────────────────────────────┐ │
│ Overview │ │ ● vm_mqtt debian · vm · APT 4 · Docker 1 │ │
│ Machines │ │ CPU 0.08 · RAM 26% · / 29% │ │
│ Reports │ │ [analyze] [upgrade] [reboot] [report] │ │
│ Hermes │ └────────────────────────────────────────────────┘ │
│ Settings │ │
├───────────────┴────────────────────────────────────────────────────┤
│ StatusBar connected · 4 machines · jobs 1 · hermes ok · 06:42 │
└────────────────────────────────────────────────────────────────────┘
```
### Détail machine
```text
┌────────────────────────────────────────────────────────────────────┐
│ vm_mqtt debian 13 · vm · qemu │
├────────────────────────────────────────────────────────────────────┤
│ Summary APT 4 · reboot no · Docker 1 · warnings 1 │
│ Health CPU 0.08/4c · RAM 26% · / 29% │
│ │
│ Tabs: [System] [Docker] [Post-install] [Hardware] [Logs] [Reports] │
│ │
│ System │
│ packages to update... │
└────────────────────────────────────────────────────────────────────┘
```
### Paramètres
```text
┌────────────────────────────────────────────────────────────────────┐
│ Settings │
├───────────────┬────────────────────────────────────────────────────┤
│ Server │ Server URL [ https://10.0.0.X:8787 ] │
│ Appearance │ API token [ ************* ] [test] │
│ Actions │ Theme [ Gruvbox dark ] │
│ Notifications │ Cache [ enabled ] │
│ Security │ Notifications [ enabled ] │
└───────────────┴────────────────────────────────────────────────────┘
```
---
## 8. Différences avec la webapp
L'app locale ne doit pas être une copie exacte.
À garder :
- logique métier backend ;
- contrats JSON ;
- tuiles machine ;
- design tokens ;
- rapports/logs ;
- validations actions.
À adapter :
- navigation GNOME avec HeaderBar/Sidebar ;
- notifications desktop ;
- stockage token via trousseau ;
- raccourcis clavier natifs ;
- possibilité de tray icon ;
- fenêtres modales natives.
---
## 9. Livrables attendus
À produire sous `docs/` :
1. Architecture app locale ↔ backend.
2. Choix stack Rust/GNOME argumenté.
3. Contrat API nécessaire.
4. Modèle de sécurité/token.
5. Mapping design system web → GNOME.
6. Maquettes ASCII vues principales.
7. Plan de cache/offline lecture seule.
8. Découpage en sous-jalons.
---
## 10. Définition de terminé
- L'app locale peut être développée sans modifier la logique SSH.
- Le backend expose les API nécessaires.
- Les credentials machines restent côté backend.
- L'UI native respecte le thème Gruvbox seventies.
- Les actions dangereuses restent validées.
- La webapp et l'app Rust partagent les mêmes contrats JSON.
- Le scaffold Rust est compilable.
- Le client API peut tester `/api/capabilities`.
- L'UI GNOME est développée ensuite, sans déplacer la logique SSH hors du backend.
---
## 11. Technos à utiliser — checklist
- [ ] Rust.
- [ ] GTK4.
- [ ] libadwaita.
- [ ] `gtk4-rs` / bindings GNOME.
- [ ] `serde` / `serde_json` pour contrats JSON.
- [ ] Client HTTP Rust (`reqwest` ou équivalent).
- [ ] WebSocket/SSE Rust selon choix backend.
- [ ] `keyring` pour stockage token local.
- [ ] `directories` pour config/cache.
- [ ] `tracing` pour logs app.
- [ ] Tokens `design_system/tokens/tokens.gnome.css`.
- [ ] Backend `system_update` comme source de vérité.
## 12. URLs utiles
- Rust : https://www.rust-lang.org/
- Rust Book : https://doc.rust-lang.org/book/
- GTK Rust bindings : https://www.gtk.org/docs/language-bindings/rust/
- gtk4-rs book : https://gtk-rs.org/gtk4-rs/stable/latest/book/
- libadwaita Rust : https://gtk-rs.org/gtk4-rs/stable/latest/book/libadwaita.html
- GNOME Human Interface Guidelines : https://developer.gnome.org/hig/
- reqwest : https://docs.rs/reqwest/
- serde : https://serde.rs/
- keyring crate : https://docs.rs/keyring/
- Flatpak docs : https://docs.flatpak.org/
## 13. Liens parent/enfant avec les autres tâches
- Parents :
- `tache5.md` pour API/capabilities/events.
- `tache1.9.md` pour `api_clients`.
- `tache3.md` pour reprise UX/tuiles.
- `tache7.md` pour sécurité token/cache/metrics.
- `design_system/tokens/tokens.gnome.css` pour thème natif.
- Enfants :
- aucune tâche enfant immédiate ; c'est une évolution future après webapp serveur stable.
- Validation : `validation_tache8.md`.