# Vision, modularisation & optimisation — Plateforme TARGO / Gigafibre

> Document stratégique. Complète `overview.md`, `app-design.md`, `data-model.md`, `module-interactions.md`
> et `../ENGINEERING_PRACTICES.md`. Objectif : passer d'une croissance organique (god-files, modules plats)
> à une architecture **modulaire par domaine** avec des **sources de vérité** fiables — pour livrer vite ET sûr.

## 0. Vision en une phrase
Un **hub d'orchestration léger** (Node) au-dessus d'**ERPNext** (ERP/source de données), organisé en
**domaines métier autonomes** (bounded contexts), chacun avec sa **source de vérité canonique**, sa
**validation à la saisie** et ses **liens stables** — pendant qu'on **éteint progressivement le legacy**.

---

## 1. État actuel (audit chiffré, 2026-06-07)

| Composant | Volume | Plus gros fichiers (god-files) |
|---|---|---|
| **targo-hub** (Node) | 58 modules, ~23 000 lignes, 52 routes (lazy-require) | campaigns 2366 · payments 1376 · network-intel 1221 · contracts 1091 · roster 1040 · tech-mobile 961 · dispatch 852 |
| **Ops SPA** (Vue3/Quasar) | ~45 000 lignes | ProjectWizard 2891 · DispatchPage 2162 · PlanificationPage 1863 · NetworkPage 1829 · ClientDetailPage 1715 |

**Forces** : hub mono-process simple (routage `path.startsWith` + `require` paresseux), ERPNext comme socle
données, frappe_pg (PostgreSQL), intégrations riches (legacy MariaDB, Ministra, GenieACS, OLT SNMP, Stripe,
Mailjet, Authentik, Karrio), base d'adresses RQA **locale** (5,24 M) déjà branchée.

**Dettes techniques** (priorisées plus bas) :
1. **God-files** : 5 fichiers front >1700 lignes, 2 back >1300 — mélangent UI/état/règles métier/I/O.
2. **Modules plats sans frontière de domaine** : 58 fichiers `lib/*.js` au même niveau ; couplage implicite.
3. **Helpers réimplémentés** : `norm()` (accents), `cors()`, `haversine()`, `stripHtml()` dupliqués dans
   ~6 modules (address-*, legacy-dispatch-sync, roster, serviceability, tech-absence-sms). *(cors/pool : consolidés ✅)*
4. **Pas de tests** ni de **CI/CD** (déploiement = `scp` manuel + `docker restart`).
5. **Observabilité inégale** : `catch {}` muets par endroits ; heartbeat/réconciliation présents seulement
   sur le pont legacy. `erp.create/update` ne *throw* pas → des erreurs ont déjà été comptées comme succès.

---

## 2. Principe directeur : Domaines + Source de vérité

Deux règles structurent toute la suite :

**(A) Découper par DOMAINE (bounded context), pas par fichier.** Chaque domaine expose une interface
publique étroite (un `index` + des services) ; le reste est interne. Le routage du hub délègue au domaine.

**(B) Chaque entité a UNE source de vérité + validation à la saisie + lien stable.** On ne re-cherche pas
avec un processus complexe à chaque fois : on **résout une fois**, on **persiste le lien canonique**, le
downstream **lit le lien**. Modèle de référence : les **adresses** (cf. `reference/` + page Conformité) —
`rqa_addresses` (RQA local) ← `aq_address_id`/`linked_address`/`address_validation_status` sur Service Location.

---

## 3. Carte des domaines cible

Regroupement des 58 modules hub + pages Ops en **9 domaines**. (Refactor par déplacement progressif, pas big-bang.)

| Domaine | Hub (lib/…) | Ops (pages/modules) | Source de vérité |
|---|---|---|---|
| **Identité & Accès** | auth, (Authentik) | usePermissions, MainLayout | Authentik + Capabilities |
| **CRM / Clients** | store, **address-db/validate/conformity**, address-search | Clients, ClientDetail | Customer (ERPNext) · **Adresse = RQA** |
| **Dispatch & Terrain** | dispatch, roster, tech-mobile, legacy-dispatch-sync, (geo/routing Mapbox) | Dispatch, Planification, RendezVous, module tech | Dispatch Job · Shift/Roster |
| **Réseau & Infra** | network-intel, olt-snmp, devices, outage-monitor, oktopus, (genieacs) | Network | GenieACS (CPE) · OLT · device |
| **Facturation & Paiements** | payments, contracts, acceptance, store/checkout | Rapports, ContratBLB | **Legacy billing (autoritaire jusqu'au cutover)** → ERPNext |
| **Marketing & Campagnes** | campaigns, offers, ai (traduction) | module campaigns | Campaign · Gift (Giftbit) |
| **IA & Agent** | ai, agent, voice-agent, flow-runtime, conversation | Copilote, AgentFlows | Agent flows |
| **Intégrations & Legacy** | erp, legacy DB, Ministra, Karrio, Giftbit | — | Adaptateurs (anti-corruption layer) |
| **Plateforme** | helpers, config, observabilité | composables partagés, components/shared | — |

**Cible d'arborescence hub** (itératif) : `lib/<domaine>/<module>.js` + `lib/<domaine>/index.js` (interface
publique) ; `lib/util/` (norm, cors, geo, html) ; `server.js` route vers `require('./lib/<domaine>')`.

**Cible Ops** : `src/modules/<domaine>/` (pages + composants + composables + api du domaine), comme
`modules/campaigns` et `modules/tech` le font déjà — étendre ce pattern à dispatch, roster, clients, network.

---

## 4. Optimisations priorisées

### P0 — Hygiène (sûr, rapide, vérifiable au build)
- **Extraire les helpers partagés** dans `lib/util/` : `norm` (accents), `cors` ✅, `haversineKm`, `stripHtml`,
  `tzDate`. Remplacer les ~6 réimplémentations. *(cors + pool address déjà consolidés.)*
- **Uniformiser le contrat handler** : `erp.create/update` renvoient `{ok}` → tout appelant DOIT vérifier
  `r.ok` (déjà corrigé dans le pont ; auditer payments/contracts/store).
- **Supprimer le code mort** + `catch {}` muets → `log()`.
- **Boundary I/O** : un seul client `pg` partagé pour les lectures locales (address-db.pool, réutilisé ✅).

### P1 — Décomposition des god-files (par domaine, sans changer le comportement)
- Front : `ProjectWizard` (2891), `DispatchPage` (2162), `PlanificationPage` (1863), `ClientDetailPage` (1715)
  → extraire des **composables** (`use*`) + **sous-composants** (détail/sections). PlanificationPage : sortir
  packedDay/route-planner, le panneau d'assignation, l'éditeur de journée en composables dédiés.
- Back : `campaigns` (2366) et `payments` (1376) → sous-modules de domaine (envoi, matching, suivi / facturation, rapprochement).

### P2 — Fiabilité & vélocité
- **Tests** (vitest) sur les modules à risque : paiements, pont legacy, conformité adresses, roster solver.
- **CI/CD** : remplacer `scp + docker restart` manuel par un pipeline (Gitea Actions) build+déploiement+santé.
- **Observabilité closed-loop** : généraliser le pattern `_lastRun`/`/status` + réconciliation (déjà sur le
  pont) aux jobs critiques ; clés Uptime-Kuma.

---

## 5. Source de vérité — généralisation du pattern « Adresses »

| Entité | Source de vérité | Lien stable | État |
|---|---|---|---|
| **Adresse** | `rqa_addresses` (RQA local) + `fiber_availability` | `aq_address_id` + `linked_address` | ✅ FAIT (16 561 liées ; page Conformité) |
| **Client** | ERPNext Customer | `legacy_account_id` | partiel (matching legacy) |
| **Appareil/CPE** | GenieACS (serial/MAC réels) | MAC ↔ Service Equipment | piège connu (TPLG vs serial réel) |
| **Service TV** | Ministra (SID = id ligne `service` legacy) | `legacy_activation_url` | read-only (pas de 2e chemin d'écriture) |
| **Facturation** | **Legacy (autoritaire)** jusqu'au cutover | — | scheduler ERPNext en pause |

Prochaine application directe : finir le matching **Client** (legacy_account_id) et **Device** (MAC↔GenieACS)
sur le même modèle (résoudre une fois → persister → lire le lien).

---

## 6. Roadmap par phases

- **Phase 1 — Hygiène & fondations** : helpers partagés, code mort, `r.ok` partout, CI/CD minimal, tests des
  modules critiques. *(Risque faible, gros gain de fiabilité.)*
- **Phase 2 — Modularisation** : déplacer hub `lib/*` → `lib/<domaine>/` ; décomposer les god-files front/back.
- **Phase 3 — Sources de vérité** : généraliser (Client, Device, Service) + observabilité closed-loop partout.
- **Phase 4 — Vision produit** : cutover facturation legacy→ERPNext ; app terrain Capacitor (GPS live des
  unités, remplace le relevé manuel sur la carte) ; portail client self-service (abonnement + RDV + paiement).

---

## 7. Métriques de succès
- 0 fichier > 800 lignes (front et back).
- 0 helper dupliqué (`norm`/`cors`/`geo`/`html` centralisés).
- 100 % des entités clés avec source de vérité + validation à la saisie + lien persisté.
- Déploiement par pipeline (0 `scp` manuel) ; tests verts sur les modules critiques.
- Tout job inter-systèmes : idempotent + observable + réconcilié (cf. ENGINEERING_PRACTICES).