# 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`