docs: spec finition cosma-nav + qc — audit → issues → livraison

2026-04-25 17:32:49 +02:00
parent 8ef1c3d8a6
commit 92ad9a7277
1 changed files with 148 additions and 0 deletions
--- a/docs/superpowers/specs/2026-04-25-cosma-finition-design.md
+++ b/docs/superpowers/specs/2026-04-25-cosma-finition-design.md
@@ -0,0 +1,148 @@
+# Spec — Cosma Nav + QC : Audit → Issues → Livraison
+
+**Date :** 2026-04-25
+**Repo issues :** `192.168.0.82:3000/floppyrj45/cosma-qc`
+**Cible déploiement :** cosma-vm `.83`
+**Approche :** Audit live d'abord, puis issues Gitea pour les gaps réels uniquement.
+
+---
+
+## Objectif
+
+Livrer cosma-nav pleinement intégré à cosma-qc sur la VM `.83` :
+- Route `/nav` (viewer Three.js 3D trajectoires AUV/USV)
+- Route `/map` (Leaflet GPS/USBL)
+- Hook post-job dans dispatcher cosma-qc (pré-décimation PLY → SCP → rsync NAS)
+- Archivage NAS `.156`
+- Test end-to-end avec vraies données de mission
+
+Critère de succès : un job GoPro déclenche la pipeline complète, le PLY est archivé sur NAS, la trajectoire est visible dans le viewer Chrome.
+
+---
+
+## Phase 1 — Audit live .83
+
+### 1.1 SSH .83 — état infra
+
+Vérifier point par point :
+
+| Composant | Commande | Attendu |
+|-----------|----------|---------|
+| cosma-qc dispatcher | `systemctl status cosma-qc-dispatcher` | active (running) |
+| Docker app | `docker ps \| grep cosma-qc-app` | port 3849 exposé |
+| Caddy | `systemctl status caddy` + `cat /etc/caddy/Caddyfile` | config actuelle |
+| NAS .156 | `mount \| grep nas` ou `ls /mnt/nas` | monté |
+| cosma-nav | `ls ~/cosma-nav` ou `systemctl status cosma-nav` | existe ou absent |
+| Workers | `ssh gpu "nvidia-smi"` depuis .83 | .84 et .87 accessibles |
+
+### 1.2 Chrome — Gitea cosma-qc
+
+- Ouvrir `http://192.168.0.82:3000/floppyrj45/cosma-qc`
+- Issues existantes ? Labels existants ?
+- Créer labels si absents : `infra`, `backend`, `frontend`, `deploy`, `test`
+
+### 1.3 Sortie Phase 1
+
+Liste des gaps réels. Chaque gap devient une issue.
+
+---
+
+## Phase 2 — Issues Gitea
+
+Une issue par gap identifié. Format titre : `[label] Description courte`.
+
+### Labels et priorités
+
+| Label | Couleur | Exemples d'issues attendus |
+|-------|---------|---------------------------|
+| `infra` P1 | vert | NAS .156 non monté, worker .84 inaccessible |
+| `backend` P2 | bleu | pre_decimate.py manquant, archive_job.sh manquant, check_jobs.py manquant, hook dispatcher absent |
+| `frontend` P2 | jaune | map.html, nav.html, map.js, nav_charts.js manquants |
+| `deploy` P3 | orange | systemd cosma-nav absent, Caddy routes /nav /map manquantes |
+| `test` P4 | violet | E2E avec vraies données |
+
+### Issues probables (à confirmer après audit)
+
+Issues issues du plan `2026-04-24-cosma-qc-platform.md` — à créer seulement si confirmées manquantes :
+
+1. `[infra]` Monter NAS .156 sur cosma-vm et ml-stack
+2. `[backend]` Créer pre_decimate.py (open3d, PLY → décimation sur ml-stack)
+3. `[backend]` Créer archive_job.sh (rsync PLY décimé vers NAS .156)
+4. `[backend]` Créer check_jobs.py (vérification intégrité jobs)
+5. `[frontend]` Implémenter map.html + map.js (Leaflet GPS/USBL)
+6. `[frontend]` Implémenter nav.html + nav_charts.js (Chart.js profondeur/RTK)
+7. `[deploy]` Déployer cosma-nav sur .83 (git clone + requirements)
+8. `[deploy]` Créer service systemd cosma-nav (port 5051)
+9. `[deploy]` Configurer Caddy : routes /nav et /map → :5051
+10. `[deploy]` Intégrer hook post-job dans dispatcher cosma-qc
+11. `[test]` Test E2E avec données réelles (MCAP + CSV mission)
+
+---
+
+## Phase 3 — Résolution par ordre de dépendances
+
+```
+[infra] NAS + workers
+    ↓
+[backend] pre_decimate.py → archive_job.sh → check_jobs.py
+    ↓
+[frontend] map.html/js → nav.html/js
+    ↓
+[deploy] cosma-nav clone → systemd → Caddy → hook dispatcher
+    ↓
+[test] E2E
+```
+
+Chaque fix :
+- Commit message : `fix: closes #N — description`
+- Issue fermée automatiquement sur merge main
+
+### Conventions code
+
+- cosma-nav : Python 3, PEP8, pas de dépendances nouvelles sans discussion
+- Scripts deploy : bash, pas de root requis (user `cosma`)
+- Caddy : reload sans redémarrage (`caddy reload`)
+- systemd : `User=cosma`, `Restart=on-failure`, `WorkingDirectory=/home/cosma/cosma-nav`
+
+---
+
+## Phase 4 — Test E2E + produit fini
+
+### Scénario de test
+
+1. Déposer un job GoPro dans cosma-qc (fichier `GX010*.MP4`)
+2. Dispatcher lance extraction frames (FFmpeg)
+3. Post-job hook déclenche :
+   - `pre_decimate.py` sur ml-stack (.84) → PLY décimé
+   - SCP PLY vers cosma-vm `/home/cosma/cosma-qc-data/jobs/{id}/`
+   - `archive_job.sh` → rsync vers NAS `.156`
+4. Chrome ouvre `http://192.168.0.83/nav` → trajectoire 3D visible
+5. Chrome ouvre `http://192.168.0.83/map` → GPS/USBL sur carte
+
+### Critères de succès
+
+- [ ] Toutes issues Gitea fermées
+- [ ] `systemctl is-active cosma-nav` → `active`
+- [ ] `http://192.168.0.83/nav` répond 200
+- [ ] `http://192.168.0.83/map` répond 200
+- [ ] PLY job test présent sur NAS `.156`
+- [ ] Trajectoire visible dans Three.js viewer
+- [ ] Aucune erreur dans logs systemd cosma-nav
+
+---
+
+## Périmètre exclu
+
+- Migration / refactoring du code core cosma-nav (extract/fuse/viz) — déjà complet
+- Authentification / accès externe (hors LAN)
+- Nouvelles features viewer (au-delà de map + nav)
+- COSMA Log (projet séparé)
+
+---
+
+## Dépendances externes
+
+- SSH accès `.83` (user `cosma` ou `floppyrj45`)
+- SSH accès `.84` (alias `gpu`) depuis `.83`
+- NAS `.156` accessible réseau LAN
+- Gitea `.82:3000` token auth `floppyrj45`