gilles
0fbca06d3d
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>
166 lines
8.6 KiB
Markdown
166 lines
8.6 KiB
Markdown
# Protocole de validation — Tâche 5 (backend, historique JSON et automatisations)
|
|
|
|
> **Type** : grille de validation. Utilisée après la mission décrite dans `tache5.md`.
|
|
> **But** : vérifier que le backend cible stocke, orchestre, expose et nettoie les données correctement.
|
|
> **Gate obligatoire** : cette validation doit être passée avant implémentation backend majeure.
|
|
> **Rappel** : la tâche 5 est une mission design backend, pas d'implémentation.
|
|
|
|
---
|
|
|
|
## 0. Quand lancer cette validation
|
|
|
|
- La mission `tache5.md` est annoncée terminée.
|
|
- API, jobs, stockage, rétention et intégration Hermes/app locale sont spécifiés.
|
|
|
|
---
|
|
|
|
## 1. Discipline & périmètre
|
|
|
|
- [ ] Aucun code backend modifié.
|
|
- [ ] Aucune migration BDD appliquée.
|
|
- [ ] Le design réutilise la couche SSH existante.
|
|
- [ ] Les jobs/actions passent par un modèle verrouillé/idempotent.
|
|
- [ ] Aucun secret ne sort du backend.
|
|
|
|
---
|
|
|
|
## 2. Stockage et historique
|
|
|
|
- [ ] Tous les échanges JSON machine ↔ serveur sont historisables.
|
|
- [ ] Snapshots et exécutions sont séparés.
|
|
- [ ] Rapports Markdown et logs bruts sont référencés.
|
|
- [ ] Messages importants extraits des logs sont stockés et consultables.
|
|
- [ ] Hardware/profil/métriques simples sont historisables.
|
|
- [ ] L'état courant machine est dérivé sans parser les logs.
|
|
|
|
---
|
|
|
|
## 3. Automatisations
|
|
|
|
- [ ] Schedules persistants définis.
|
|
- [ ] `apt_update_analyze` planifiable.
|
|
- [ ] `machine_metrics_simple` planifiable.
|
|
- [ ] Docker scan planifiable selon config.
|
|
- [ ] Verrous machine et idempotency keys spécifiés.
|
|
- [ ] Timeouts, retries et reprise serveur spécifiés.
|
|
|
|
---
|
|
|
|
## 4. API backend
|
|
|
|
- [ ] Endpoints machines/state/hardware/metrics/snapshots/executions/events/messages.
|
|
- [ ] Endpoints reports/artifacts/search.
|
|
- [ ] Endpoints schedules.
|
|
- [ ] Endpoints settings.
|
|
- [ ] Endpoints events/live output.
|
|
- [ ] `/api/capabilities` défini.
|
|
- [ ] Erreurs structurées, pagination, filtres, version API.
|
|
- [ ] Clients visés : web, Hermes/MCP, app Rust/GNOME.
|
|
|
|
---
|
|
|
|
## 5. Sécurité et clients API
|
|
|
|
- [ ] Auth API clients séparée des credentials machines.
|
|
- [ ] Scopes `read/operate/admin/debug_logs` ou équivalent.
|
|
- [ ] Tokens hashés/révocables/audités.
|
|
- [ ] Secrets SSH/sudo jamais exposés.
|
|
- [ ] Logs filtrés avant UI/Hermes/app locale.
|
|
|
|
---
|
|
|
|
## 6. Objectif final Docker Compose webserver
|
|
|
|
- [ ] Le backend est conçu pour tourner en container.
|
|
- [ ] DB SQLite persistée en volume.
|
|
- [ ] Reports/logs/artifacts persistés en volume.
|
|
- [ ] Configuration par variables d'environnement.
|
|
- [ ] `SU_MASTER_KEY` et tokens hors image.
|
|
- [ ] Le container backend peut joindre les machines en SSH.
|
|
- [ ] Un packaging Docker Compose final est explicitement compatible avec l'architecture.
|
|
|
|
---
|
|
|
|
## 7. Verdict
|
|
|
|
- **✅ Accepté** : backend cible cohérent et prêt à planifier.
|
|
- **🟡 Accepté avec réserves** : endpoints ou rétention à préciser.
|
|
- **❌ Rejeté** : secrets exposés, jobs non verrouillés, API instable ou incompatible Docker Compose.
|
|
|
|
---
|
|
|
|
## 8. Notes de validation
|
|
|
|
> Revue du 2026-06-05 — Gilles Soulier (orchestrateur, validation déléguée).
|
|
|
|
### Verdict global : 🟡 Accepté avec réserves
|
|
|
|
Le design `tache5.md` est cohérent dans ses grandes lignes et couvre la majorité des cases du gate. Les points fondamentaux (séparation snapshots/exécutions, état courant dérivé, machine_locks + idempotencyKey, scopes API clients, secrets hors backend, croner MVP) sont correctement traités. Deux réserves majeures et plusieurs points d'attention sont relevés ci-dessous.
|
|
|
|
---
|
|
|
|
### Réserves majeures
|
|
|
|
**R1 — Contrainte réseau Docker Compose non spécifiée**
|
|
|
|
La case « Le container backend peut joindre les machines en SSH » (section 6 du gate) n'est pas couverte dans `tache5.md`. Il n'est nulle part précisé que le container Docker doit avoir accès réseau aux machines cibles (réseau `host`, bridge avec routage LAN, ou VPN/overlay). Sans cette précision, un déploiement en container isolé sera en échec silencieux au premier refresh SSH. La spec doit ajouter au moins une note dans la checklist section 11 ou dans un sous-jalons Docker Compose.
|
|
|
|
**R2 — Exemple `capabilities` appauvri, incohérent avec le WIP**
|
|
|
|
La section 6 de `tache5.md` présente un exemple JSON de capabilities minimal (`machines`, `actions`, `terminalOutput`, `interactiveSsh`, `hermes`, `settings`) qui ne correspond pas au type `ServerCapabilities` déjà défini dans `shared/types.ts` et implémenté dans `server/services/capabilities.ts` (WIP non commité). Le WIP expose des features plus granulaires : `machineSnapshots`, `aptFullUpgrade`, `reboot`, `reports`, `docker`, `postInstall`, `scheduledJobs`, `authTokens`, et un bloc `endpoints` structuré. La spec doit référencer le type existant ou s'y aligner explicitement pour éviter une divergence à l'implémentation.
|
|
|
|
---
|
|
|
|
### Points d'attention (non bloquants)
|
|
|
|
**P1 — Réutilisation couche SSH non citée explicitement**
|
|
|
|
La section 0 « À lire avant de travailler » omettait `tache1.9.md` (corrigé en coquille) et ne cite pas `server/ssh/client.ts`. La spec backend qui planifie des jobs SSH devrait référencer la couche `runScriptSudo`/`runPlain` existante pour signaler explicitement qu'elle est réutilisée telle quelle et ne doit pas être réécrite.
|
|
|
|
**P2 — Verrou machine : granularité non tranchée**
|
|
|
|
Section 5 liste les règles de verrouillage (apt bloque pendant upgrade, Docker scan autorisé sauf action destructive, reboot bloque tout) mais ne tranche pas sur la représentation en BDD : utilise-t-on `machine_locks` (table tache1.9) avec un `lock_kind` (apt | docker | post_install | reboot | exclusive) ou un simple champ `running_job_id` dans `machine_state` ? Les deux approches sont citées (`table machine_locks ou statut job courant`) sans choix définitif. Acceptable en design préliminaire mais à trancher avant implémentation.
|
|
|
|
**P3 — Reprise après redémarrage serveur non détaillée pour croner**
|
|
|
|
Section 5 mentionne « reprise après redémarrage serveur selon le moteur choisi » mais le choix est `croner` in-process. Croner ne persiste rien : un job `running` au moment du crash restera bloqué en BDD. La spec doit préciser la procédure de récupération au démarrage (ex. : au boot, marquer `cancelled` les jobs `running` orphelins et libérer les `machine_locks` expirés).
|
|
|
|
**P4 — Pagination et filtres : non détaillés**
|
|
|
|
Section 6 mentionne pagination et filtres dans la liste à puces mais aucun endpoint n'est détaillé (pas de paramètres `?page`, `?limit`, `?status`, `?from`, `?to`). Acceptable pour un design préliminaire, mais à spécifier avant d'écrire les routes.
|
|
|
|
**P5 — `POST /api/machines/:id/actions` vs actions déjà existantes**
|
|
|
|
Le WIP `server/routes/actions.ts` expose `POST /:id/actions` qui n'accepte que `apt_full_upgrade` et `reboot`. La spec tache5.md liste des actions bien plus larges (apt_upgrade, apt_autoremove, apt_clean, docker_apply, docker_prune, post_install_profile, reboot_verified). La spec devrait explicitement noter que cet endpoint doit être élargi et protégé par les verrous machine, pas seulement validé par whitelist statique.
|
|
|
|
---
|
|
|
|
### Coquilles corrigées dans `tache5.md`
|
|
|
|
1. **Section 6, liste des endpoints** : `GET /api/ws/machines/:id/output` remplacé par `WS /api/ws/machines/:id/output` — alignement avec `server/services/capabilities.ts` WIP qui l'annote `"WS /api/ws/machines/:id/output"`.
|
|
|
|
2. **Section 0, liste « À lire avant de travailler »** : `tache1.9.md` ajouté — était absent alors que c'est le parent direct du schéma BDD consommé par la tâche 5.
|
|
|
|
---
|
|
|
|
### Cohérence avec l'existant (WIP capabilities)
|
|
|
|
| Point | tache5.md | WIP shared/types.ts + capabilities.ts | Verdict |
|
|
|---|---|---|---|
|
|
| Endpoint `/api/capabilities` | Présent | Implémenté (`api.get("/capabilities", ...)`) | Cohérent |
|
|
| `apiVersion: "1"` | Présent | Présent (`apiVersion: "1"` literal) | Cohérent |
|
|
| Features capabilities | Exemple minimal 6 features | 14 features granulaires + bloc `endpoints` | **Incohérent — R2** |
|
|
| Endpoint WS output | Noté `GET` (avant correction) | Noté `WS` | Corrigé |
|
|
| Auth tokens | Mentionnés section 6 | `authTokens: false` (WIP, à activer) | Cohérent en intention |
|
|
|
|
---
|
|
|
|
### Conclusion
|
|
|
|
Le design peut passer en plan d'implémentation **à condition de** :
|
|
1. Préciser la contrainte réseau SSH dans le packaging Docker Compose (R1).
|
|
2. Aligner l'exemple capabilities avec `ServerCapabilities` de `shared/types.ts` ou le mettre à jour dans le type partagé (R2).
|
|
3. Documenter la procédure de récupération des jobs orphelins au démarrage croner (P3).
|
|
|
|
Les autres points (P1, P2, P4, P5) peuvent être affinés en cours d'implémentation sans bloquer le plan.
|