gigafibre-fsm/docs/ECOSYSTEM-OVERVIEW.md

# Gigafibre FSM — Ecosystem Overview

> Synthèse complète pour développeurs et sysadmins — Avril 2026

---

## 1. Vue d'ensemble

Gigafibre FSM est une plateforme de gestion d'opérations pour un fournisseur internet fibre (FTTH) desservant **6 600+ clients** au Québec. Elle remplace un système legacy PHP/MariaDB vieux de 15 ans par un écosystème moderne composé de :

- **4 applications web** (ops, field, client, website)
- **1 backend Node.js** (targo-hub) servant d'orchestrateur central
- **ERPNext v16** comme ERP et source de vérité des données
- **95+ scripts de migration** pour le transfert depuis le système legacy
- **Infrastructure Docker** avec Traefik, Authentik SSO, et monitoring

**Monorepo** : `git.targo.ca/louis/gigafibre-fsm`

```
gigafibre-fsm/
├── apps/
│   ├── ops/           → Quasar/Vue 3 PWA — outil interne (erp.gigafibre.ca/ops/)
│   ├── field/         → Quasar/Vue 3 PWA — app mobile techniciens
│   ├── client/        → Quasar/Vue 3 PWA — portail client (client.gigafibre.ca)
│   └── website/       → React/Vite — site vitrine (www.gigafibre.ca)
├── services/
│   └── targo-hub/     → Node.js 20 — backend API (msg.gigafibre.ca)
├── erpnext/           → Scripts de setup des doctypes custom
├── scripts/migration/ → Importation legacy → ERPNext
└── docs/              → Documentation architecture
```

---

## 2. Infrastructure serveur

### Serveur principal : 96.125.196.67 (hubdocker)

Tout roule sur un seul serveur Proxmox avec Docker. Le reverse proxy Traefik gère le TLS (Let's Encrypt) et le routage.

| Service | URL | Container | Auth |
|---------|-----|-----------|------|
| ERPNext v16 | erp.gigafibre.ca | erpnext-frontend-1 | Aucun (API token) |
| Ops App | erp.gigafibre.ca/ops/ | ops-frontend (nginx) | Authentik SSO |
| Portail client | client.gigafibre.ca | erpnext-frontend-1 | Authentik client |
| targo-hub | msg.gigafibre.ca | targo-hub | Authentik SSO |
| n8n | n8n.gigafibre.ca | erpnext-n8n-1 | Authentik (GUI) / aucun (webhooks) |
| Dispatch legacy | dispatch.gigafibre.ca | apps-dispatch-frontend-1 | Authentik SSO |
| Oktopus ACS | oss.gigafibre.ca | oktopus-frontend-1 | Authentik SSO |
| Site web | www.gigafibre.ca | apps-www-gigafibre-1 | Aucun |
| GPS tracking | tracker.targointernet.com | traccar | Basic auth |

### Réseaux Docker

| Réseau | Services connectés |
|--------|-------------------|
| `proxy` | Traefik, targo-hub, ops, dispatch, erpnext, n8n, authentik, oktopus, website, traccar |
| `erpnext_erpnext` | ERPNext (backend, DB, redis, workers), targo-hub, n8n |
| `fonoster_default` | Fonoster/Routr SIP (asterisk, postgres, nats, routr) |
| `authentik-client_authentik-client` | Authentik client (server, worker, postgresql, redis) |

### Bases de données

| DB | Host | Usage |
|----|------|-------|
| PostgreSQL (ERPNext) | erpnext-db-1:5432 | Toutes les données métier |
| PostgreSQL (targo_cache) | erpnext-db-1:5432 | Cache devices + hosts (targo-hub) |
| PostgreSQL (Fonoster) | fn-postgres:5432 | SIP routing (trunks, agents) |
| MongoDB (Oktopus) | oktopus-mongo-1:27017 | TR-069 ACS device management |

### SSO (Authentik)

- **Staff** : auth.targo.ca — protège ops, dispatch, n8n, hub
- **Client** : id.gigafibre.ca — protège le portail client
- Authentification via Traefik forwardAuth middleware

---

## 3. ERPNext — Modèle de données

ERPNext est le coeur du système. Tous les CRUD passent par son API REST.

### Doctypes custom (module FSM)

| Doctype | Rôle | Champs clés |
|---------|------|-------------|
| **Dispatch Job** | Tâche planifiée | tech, date, heure, durée, status, tags, published, is_recurring, recurrence_rule |
| **Dispatch Technician** | Ressource humaine/matérielle | fullName, phone, resource_type, weekly_schedule, extra_shifts, tags |
| **Dispatch Tag** | Compétence/catégorie | tag_name, color, category |
| **Dispatch Tag Link** | Lien tag↔job/tech | tag, level (1-5), required |
| **Dispatch Preset** | Preset de groupe partagé | preset_name, preset_type, preset_data (JSON) |
| **Dispatch Offer** | Offre de travail (pool Uber) | job, mode, pricing, status, responses |
| **Service Location** | Adresse de service | address, city, GPS, OLT port, network_id |
| **Service Equipment** | Équipement client | serial, MAC, IP, firmware, OLT info |

### Doctypes ERPNext standard enrichis

| Doctype | Champs custom ajoutés |
|---------|----------------------|
| Customer | legacy_customer_id, stripe_id, is_commercial, is_bad_payer, ppa_enabled |
| Subscription | custom_description, actual_price, service_location |
| Issue | linked dispatch jobs, legacy ticket ID |
| Sales Invoice | QR code, portal payment link |

---

## 4. Ops App — Application principale

### Stack technique

- **Framework** : Vue 3 (Composition API, `<script setup>`)
- **UI** : Quasar v2.19 (q-table, q-dialog, q-select, q-notify...)
- **State** : Pinia (2 stores : auth + dispatch)
- **Build** : Vite + Quasar CLI, output PWA
- **Cartes** : Mapbox GL JS
- **Style** : SCSS, thème adaptatif (dark pour dispatch, light pour le reste)
- **Déploiement** : `npx quasar build` → `scp dist/spa/* root@96.125.196.67:/opt/ops-app/`

### Pages (12)

| Page | Fonction |
|------|----------|
| DashboardPage | KPIs, contrôle scheduler, déclenchement facturation |
| ClientsPage | Liste clients avec recherche |
| ClientDetailPage | Vue 360° client : contacts, abonnements, équipements, tickets, factures |
| TicketsPage | Liste tickets avec filtres, détail en slide-over |
| **DispatchPage** | **Timeline dispatch complète (voir section 5)** |
| EquipePage | Gestion d'équipe |
| NetworkPage | Infrastructure réseau |
| TelephonyPage | Téléphonie/PBX |
| RapportsPage | Rapports et analytics |
| SettingsPage | Paramètres admin |
| OcrPage | OCR de factures (Gemini vision) |
| AgentFlowsPage | Workflows d'agent IA |

### Architecture composables (40 fichiers)

Chaque domaine métier est encapsulé dans un composable réutilisable :

```
composables/
├── useScheduler.js        — Calcul des segments timeline (shifts, absences, jobs)
├── useMap.js              — Intégration Mapbox, routes, géocodage
├── useDragDrop.js         — Drag-and-drop sur le timeline
├── useBottomPanel.js      — Panel jobs non-assignés
├── useResourceFilter.js   — Filtrage ressources (tags, groupes, recherche)
├── useTagManagement.js    — CRUD tags/compétences
├── usePeriodNavigation.js — Navigation jour/semaine/mois
├── useAutoDispatch.js     — Dispatch automatique par compétences
├── useBestTech.js         — Matching technicien optimal
├── useJobOffers.js        — Pool d'offres Uber-style
├── useAbsenceResize.js    — Resize absences par drag
├── useSelection.js        — Multi-sélection (lasso)
├── useUndo.js             — Undo/redo (Ctrl+Z)
├── useContextMenus.js     — Menus contextuels
├── useHelpers.js          — Utilitaires (RRULE, dates, couleurs)
├── useInlineEdit.js       — Édition inline Odoo-style
├── useClientData.js       — Chargement données client
├── useConversations.js    — Chat/messages
├── useDeviceStatus.js     — Statut devices GenieACS
├── useGpsTracking.js      — Tracking GPS temps réel (Traccar)
├── useSSE.js              — Server-sent events
├── usePhone.js            — Intégration téléphonie
├── useAddressSearch.js    — Autocomplétion adresse (Mapbox)
└── ...
```

### API modules (9 fichiers)

| Module | Cible | Fonction |
|--------|-------|----------|
| erp.js | ERPNext via nginx proxy | CRUD générique (listDocs, getDoc, updateDoc, searchDocs) |
| dispatch.js | ERPNext | Jobs, technicians, tags, publish |
| offers.js | ERPNext | Offres de travail (pool Uber) |
| presets.js | ERPNext | Presets de groupes partagés |
| sms.js | n8n webhook | Envoi SMS via Twilio |
| traccar.js | Traccar proxy | GPS tracking |
| ocr.js | Ollama proxy | OCR vision par IA |
| auth.js | ERPNext | Auth token, session |
| service-request.js | ERPNext | Requêtes de service |

### Composants partagés

| Composant | Fonction |
|-----------|----------|
| DetailModal.vue | Modal slide-over multi-doctype (facture, ticket, équipement, abonnement) |
| TagEditor.vue | Éditeur de tags universel avec couleurs, niveaux, autocomplete |
| RecurrenceSelector.vue | Sélecteur récurrence Google Calendar (RRULE) |
| InlineField.vue | Champ éditable inline (double-clic, Odoo-style) |
| UnifiedCreateModal.vue | Modal création unifiée (ticket, tâche, bon de travail) |
| ProjectWizard.vue | Assistant création projet/offre |
| ConversationPanel.vue | Panel de conversation (chat, SMS) |

---

## 5. Dispatch — Fonctionnalités détaillées

Le dispatch est le module le plus riche de l'application. C'est un planificateur de ressources complet avec timeline, cartes, et intelligence artificielle.

### 5.1 Vues

| Vue | Description |
|-----|-------------|
| **Jour** | Timeline horizontale par technicien, segments de jobs drag-and-drop |
| **Semaine** | Grille 7 jours × techniciens, résumé capacité/charge |
| **Mois** | Calendrier mensuel avec disponibilité par technicien sélectionné |

### 5.2 Timeline (vue jour)

- Chaque technicien = une rangée horizontale (6h → 22h)
- **Segments de jobs** : blocs colorés par type de service, drag-and-drop pour réassigner/redimensionner
- **Absences** : blocs rouges (vacances, maladie) — redimensionnables par drag des bords
- **Capacité** : barre de charge sous chaque rangée (vert < 80%, jaune < 100%, rouge > 100%)
- **Multi-sélection** : lasso ou Ctrl+clic pour sélectionner plusieurs jobs
- **Menu contextuel** : clic droit → déplacer, copier, désaffecter, offrir aux ressources
- **Undo/redo** : Ctrl+Z / Ctrl+Shift+Z

### 5.3 Mode planification

Activé par un toggle dans la toolbar. Ajoute une couche visuelle :

- **Shifts réguliers** : blocs de fond bleus translucides montrant les plages horaires de chaque technicien
- **Shifts de garde** : blocs ambrés avec hachures diagonales
- **Vue semaine** : bandes vertes (disponible) et jaunes (garde) sous les headers de jours
- **Vue mois** : blocs colorés par type (vert=disponible, jaune=garde, rouge=absence)
- **Clic sur un shift** → ouvre le modal d'édition d'horaire du technicien

### 5.4 Éditeur d'horaire technicien

Modal permettant de configurer pour chaque technicien :

- **Horaire hebdomadaire** : lundi → dimanche, heure début/fin, jour on/off
- **Presets rapides** : Temps plein (8-16), Soirs (16-00), Nuits (00-08)
- **Shifts de garde/urgence** : shifts additionnels avec :
  - Label personnalisé
  - Heures de début/fin
  - **Récurrence RRULE** via le composant RecurrenceSelector (Google Calendar-style)
  - Date de début
- Les shifts sont stockés en JSON dans le champ `extra_shifts` du Dispatch Technician

### 5.5 RecurrenceSelector (Google Calendar-style)

Composant réutilisable offrant des options contextuelles basées sur la date de référence :

- "Ne se répète pas"
- "Tous les jours"
- "Toutes les semaines le [jour]"
- "Tous les mois le [Nème jour]"
- "Tous les ans le [date]"
- "Tous les jours de semaine (lun–ven)"
- **"Personnalisé..."** → éditeur complet :
  - Fréquence : jour(s) / semaine(s) / mois / an(s)
  - Intervalle (chaque N)
  - Sélecteur de jours (pour hebdomadaire)
  - Jour du mois (pour mensuel)
  - Preview en temps réel du résultat

### 5.6 Système de tags/compétences

Chaque tag a un **niveau de compétence (1-5)** :
- Sur les techniciens : niveau de maîtrise (1=base, 5=expert)
- Sur les jobs : niveau minimum requis + flag obligatoire/optionnel
- **Auto-dispatch** : cherche le technicien avec compétence >= requise, choisit le plus bas adéquat (préserver les experts pour les jobs complexes)
- Tags existants : Fibre, Téléphonie, Fusionneur, Monteur, Installation, TV, Caméra IP, Urgence, Rive-Sud, Montréal...

### 5.7 Pool d'offres (Uber-style)

Système d'offres de travail inspiré d'Uber pour les ressources internes et externes :

- **3 modes** : Broadcast (tous), Targeted (techniciens spécifiques), Pool (compétences requises)
- **Tarification** : déplacement (150$) + taux horaire (125$/h) configurable
- **Flow** : créer offre → notifier par SMS → technicien accepte/décline → assignation automatique
- **Détection de surcharge** : alerte pulsante quand un technicien dépasse sa capacité
- **Panel latéral** : vue des offres actives avec statut de chaque réponse

### 5.8 Presets de groupes de ressources

- Sauvegarde de combinaisons de filtres de ressources (ex: "Équipe Montréal", "Techniciens fibre")
- **Stockés dans ERPNext** (Dispatch Preset doctype) → partagés entre superviseurs
- Barre rapide de presets sous la recherche
- Deux types : preset de groupe (filtre par groupe) et preset d'IDs (sélection spécifique)

### 5.9 Draft/Publish (brouillon/publié)

- Nouveau champ `published` sur Dispatch Job
- Jobs créés en mode brouillon (hachures diagonales)
- **Modal "Publier & Envoyer"** : sélection période + techniciens → publication en masse + envoi SMS résumé horaire
- Légende visuelle : solide = publié, hachuré = brouillon

### 5.10 Carte Mapbox

- Affichage des jobs géolocalisés avec couleurs par statut
- Routes optimisées par technicien (Mapbox Directions API)
- Géofixation : clic sur la carte pour positionner un job
- Tracking GPS temps réel via Traccar

### 5.11 Récurrence de jobs

- Toggle "Récurrence" sur chaque job
- Sélecteur RecurrenceSelector pour définir le pattern
- Date de fin de récurrence
- Pauses saisonnières (ex: hiver)
- Ghost blocks pour les occurrences futures (matérialisables individuellement)

---

## 6. targo-hub — Backend Node.js

Serveur Express central servant de passerelle entre les frontends et les services externes.

### Modules (30)

| Module | Connexion | Fonction |
|--------|-----------|----------|
| helpers.js | ERPNext REST | Wrapper erpFetch, httpRequest |
| sse.js | Navigateurs (EventSource) | Broadcast temps réel |
| devices.js | GenieACS NBI + PostgreSQL | Statut devices, cache, poller (5min) |
| device-extractors.js | — | Parsing TR-069 → objet résumé |
| device-hosts.js | GenieACS NBI | Topologie mesh WiFi |
| olt-snmp.js | OLT via SNMP v2c | Polling ONU, transitions d'état |
| twilio.js | Twilio API | SMS entrant/sortant, tokens voice |
| agent.js | Gemini API | Assistant IA SMS (tool-calling) |
| conversation.js | Disque local (JSON) | Persistence conversations |
| auth.js | Authentik API | Permissions RBAC (cache 60s) |
| pbx.js | 3CX API | Poller call logs (30s) |
| provision.js | ERPNext + n8n | Pré-autorisation OLT, scan/swap |
| telephony.js | Fonoster/Routr PostgreSQL | CRUD SIP (trunks, agents) |
| email.js | Nodemailer | Envoi emails |
| ical.js | — | Génération iCalendar |
| checkout.js | Stripe | Commandes, abonnements |
| magic-link.js | ERPNext | Authentification sans mot de passe |
| otp.js | Twilio SMS | Code OTP par SMS |

### SSE Topics

| Topic | Audience | Événements |
|-------|----------|------------|
| `customer:{name}` | Agents ops | Updates client temps réel |
| `conv:{token}` | Agents ops | Messages conversation |
| `conv-client:{token}` | Client web | Messages client |
| `conversations` | Agents ops | Feed global conversations |
| `sms-incoming` | Agents ops | Alerte nouveau SMS |

---

## 7. Applications secondaires

### Field App (apps/field/)

App mobile PWA pour les techniciens terrain :
- Liste des tâches du jour
- Scanner code-barres/QR (équipements)
- Diagnostic réseau et devices
- Mode offline avec sync différée

### Portail Client (apps/client/)

Self-service client :
- Consultation factures et paiements
- Gestion abonnements
- Tickets de support
- Catalogue produits/services
- Authentification via Authentik client (id.gigafibre.ca)

### Site Web (apps/website/)

Site vitrine React/Vite/Tailwind :
- Pages produits (Internet, TV, Téléphonie)
- Vérification d'éligibilité par adresse
- Commande en ligne
- FAQ et support

---

## 8. Migration depuis le legacy

### Données migrées

| Type | Volume | Script |
|------|--------|--------|
| Clients | 6 600+ | import_customers.py |
| Abonnements | ~8 000 | import_services_and_enrich.py |
| Factures | 115 000+ | import_invoices.py |
| Paiements | ~90 000 | import_payments.py |
| Tickets | 144 155 | migrate_tickets.py |
| Messages tickets | 448 379 | import_ticket_msgs.py |
| Équipements | 4 930+ | migrate_provisioning_data.py |
| Adresses | ~7 000 | migrate_locations.py |

### Pipeline de migration

```
Legacy MariaDB → Python scripts → ERPNext REST API → PostgreSQL
                                                      ↓
                                            Ops App (lecture/écriture)
```

---

## 9. Intégrations externes

| Service | Usage | Protocole |
|---------|-------|-----------|
| **GenieACS** (10.5.2.115) | TR-069 ACS, 7 560 CPEs | NBI REST (LAN, no auth) |
| **Twilio** | SMS entrant/sortant, voix | REST API (Basic auth) |
| **Mapbox** | Cartes, géocodage, routes | JS SDK + Directions API |
| **Gemini AI** | OCR factures, assistant SMS | REST (Bearer token) |
| **Stripe** | Paiements en ligne | Checkout Sessions + webhooks |
| **Traccar** | GPS tracking techniciens | REST API (Basic auth) |
| **3CX PBX** | Historique appels | REST API (Basic auth) |
| **Fonoster/Routr** | SIP trunking, voix | PostgreSQL direct |
| **n8n** | Webhooks SMS, automatisations | HTTP webhooks |
| **DocuSeal** | Signatures électroniques | Container Docker |
| **Cloudflare** | DNS gigafibre.ca | REST API |

---

## 10. Déploiement

### Ops App

```bash
cd apps/ops
npx quasar build                    # Build PWA
scp -r dist/spa/* root@96.125.196.67:/opt/ops-app/   # Deploy (pas de restart nécessaire)
```

### targo-hub

```bash
scp services/targo-hub/server.js services/targo-hub/lib/*.js root@96.125.196.67:/opt/targo-hub/
ssh root@96.125.196.67 'docker restart targo-hub'
```

### ERPNext Custom Fields

```bash
python erpnext/setup_fsm_doctypes.py   # Crée/met à jour les custom fields
```

---

## 11. Conventions de code

| Aspect | Convention |
|--------|-----------|
| Framework | Vue 3 Composition API, `<script setup>` exclusivement |
| State | Pinia stores (pas de Vuex) |
| UI | Composants Quasar (q-table, q-dialog, q-notify...) |
| Style | SCSS, variables CSS custom (--sb-*, --ops-*) |
| Thème | Light par défaut, dark pour dispatch uniquement |
| Langue UI | Français (labels, messages) |
| Langue code | Anglais (variables, fonctions, commentaires) |
| API | REST via authFetch (token injecté par nginx) |
| RRULE | RFC 5545 — FREQ/INTERVAL/BYDAY/BYMONTHDAY via buildRRule/parseRRule |
| Nommage | camelCase (JS), kebab-case (composants), UPPER_SNAKE (constantes) |
| Composables | Préfixe `use` (useScheduler, useMap, useResourceFilter...) |

---

## 12. Architecture des flux de données

```
┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  Browser     │────▶│  nginx       │────▶│  ERPNext    │
│  (Ops SPA)   │     │  (proxy+     │     │  REST API   │
│              │     │   token)     │     │  :8000      │
└──────┬───────┘     └──────────────┘     └──────┬──────┘
       │                                         │
       │ SSE + REST                         PostgreSQL
       ▼                                         │
┌──────────────┐     ┌──────────────┐     ┌──────▼──────┐
│  targo-hub   │────▶│  GenieACS    │     │  ERPNext DB │
│  :3300       │     │  NBI :7557   │     │  :5432      │
│              │────▶│  Twilio API  │     └─────────────┘
│              │────▶│  Gemini AI   │
│              │────▶│  3CX PBX    │
│              │────▶│  Authentik   │
└──────────────┘     └──────────────┘
```

---

## 13. Points d'attention opérationnels

1. **Traefik v2.11** — ne PAS upgrader à v3 (incompatible Docker 29)
2. **HTTP→HTTPS redirect** ne doit pas intercepter le challenge ACME
3. **MongoDB (Oktopus)** requiert AVX — CPU type "host" dans Proxmox
4. **Multi-network Docker** — conteneurs doivent avoir `traefik.docker.network=proxy`
5. **ERPNext PostgreSQL** — bugs GROUP BY/HAVING patchés manuellement
6. **Token API** — ne JAMAIS appeler `generate_keys` (invalide le token existant)
7. **Deploy SPA** — copier le CONTENU de dist/spa/*, pas le dossier
8. **Netplan** — peut overrider systemd-networkd, à supprimer si problème réseau