From 92ad9a7277e493a3930bba99c190b992a787509f Mon Sep 17 00:00:00 2001 From: Floppyrj45 Date: Sat, 25 Apr 2026 17:32:49 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20spec=20finition=20cosma-nav=20+=20qc=20?= =?UTF-8?q?=E2=80=94=20audit=20=E2=86=92=20issues=20=E2=86=92=20livraison?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../specs/2026-04-25-cosma-finition-design.md | 148 ++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 docs/superpowers/specs/2026-04-25-cosma-finition-design.md diff --git a/docs/superpowers/specs/2026-04-25-cosma-finition-design.md b/docs/superpowers/specs/2026-04-25-cosma-finition-design.md new file mode 100644 index 0000000..6cef2e7 --- /dev/null +++ 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`