docs: plan + spec finition cosma-nav (superpowers)

docs/superpowers/specs/2026-04-24-cosma-qc-platform-design.md

@@ -0,0 +1,90 @@
+# COSMA QC Platform — Design Spec
+**Date:** 2026-04-24  
+**Statut:** Approuvé
+
+## Objectif
+
+Plateforme QC complète pour les missions COSMA AUV sur cosma-vm (.83), combinant gestion pipeline (cosma-qc) et visualisation QC (cosma-nav) : carte GPS/USBL, viewer 3D reconstruction, graphes nav.
+
+## Architecture — Option B : Microservices
+
+### Services
+
+| Service | Port | Rôle |
+|---------|------|------|
+| cosma-qc | :3849 | Pipeline jobs/stitches, dashboard extraction/reconstruction |
+| cosma-nav | :5051 | QC viewer : carte, 3D, graphes nav |
+| Caddy | :80 | Reverse proxy → / (cosma-qc) et /nav/ (cosma-nav) |
+
+### Machine cible
+- **cosma-vm (.83)** — VM Proxmox
+- Ressources actuelles : 4 vCPU / 3.8 GB RAM / 38 GB disk
+- Expansion si nécessaire : +4 GB RAM si open3d décimatation locale
+
+### Stockage
+
+```
+ml-stack (.84)                     NAS .156 (1.34 TB libre)
+/root/cosma-qc-frames/        ──►  /cosma-archive/
+  job_N/frame_*.jpg (65 GB)          job_N/frames/     (archivé)
+  job_N/reconstruction.ply           job_N/ply_brut/   (archivé)
+
+ml-stack post-job               cosma-vm (.83)
+pré-décimer PLY            ──►  /data/cosma/
+  185M pts → ~200k pts (~7 MB)     job_N_decimated.ply
+  rsync poses.npz                   job_N_poses.npz
+  rsync sparse_fixes.h5             sparse_fixes.h5
+```
+
+- Frames JPG et PLY bruts → archivés sur NAS .156 (SMB, admin) après job done
+- Données légères → copiées sur cosma-vm pour le viewer
+- Rien n'est supprimé avant confirmation archivage NAS
+
+## cosma-nav — Fonctionnalités QC Viewer
+
+### 1. Carte GPS/USBL (Leaflet + OpenStreetMap)
+- Track AUV (trajectory_world.h5 → x_m/y_m converti en lat/lon)
+- Fixes USBL/GPS plotés avec couleur RTK (fix=vert, float=jaune, 3D=rouge)
+- Fixes USV (navire surface) en overlay
+- Sélecteur de mission/job
+
+### 2. Viewer 3D reconstruction (Three.js — existant)
+- PLY décimé (~200k pts) chargé depuis /data/cosma/
+- Frustums caméra orientés nadir
+- Trajectoire lingbot locale
+- Toggle layers (PLY, frustums, trajectory)
+
+### 3. Graphes nav (Plotly.js ou Chart.js)
+- Profondeur (depth_m depuis pression)
+- Altitude fond (altitude_m Kogger)
+- Qualité RTK (fix_type timeline)
+- Vitesse USV
+
+### 4. Intégration cosma-qc
+- Bouton "QC →" dans la table jobs de cosma-qc → ouvre cosma-nav sur le job sélectionné
+- API cosma-nav : GET /api/job/{id}/trajectory, /api/job/{id}/nav, /api/job/{id}/ply
+
+## Pipeline post-job (dispatcher cosma-qc)
+
+Après chaque job done :
+1. `open3d` pré-décimation sur ml-stack → PLY ~7 MB
+2. `rsync` PLY décimé + poses.npz → cosma-vm:/data/cosma/
+3. `rsync` frames JPG + PLY brut → NAS .156:/cosma-archive/ (async, non-bloquant)
+4. Mise à jour DB cosma-qc : `decimated_ply_path`, `nav_ready=true`
+
+## Vérification PLY/poses existants
+
+Avant déploiement : valider les 11 jobs actuels (jobs 9-21) :
+- PLY lisible par open3d ✓ (vérifié, 185M pts)
+- poses.npz shape (N, 3, 4) ✓ (1217-1349 frames)
+- PLY utile : early-save ≠ final-save → re-vérifier si demo.py a fini proprement
+
+## Déploiement
+
+1. Monter NAS .156 sur ml-stack et cosma-vm (CIFS)
+2. Cloner cosma-nav sur cosma-vm
+3. Installer deps (Flask, open3d, h5py) dans venv
+4. Adapter server.py : servir depuis /data/cosma/, ajouter routes map + nav
+5. Caddy config sur cosma-vm
+6. Modifier dispatcher cosma-qc : ajouter step post-job (décimation + sync)
+7. Ajouter bouton "QC →" dans _jobs_table.html cosma-qc