system_update/validation_tache5.md

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.