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

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

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

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