gigafibre-fsm/docs/MIGRATION-PLAN.md

Plan de migration — Legacy Facturation → ERPNext

1. Portrait du système legacy

Base de données : gestionclient (MariaDB sur 10.100.80.100)

Table	Records	Description
account	15,303	Clients (6,510 actifs, 8,594 terminés)
delivery	17,114	Adresses d'installation (GPS inclus)
service	66,879	Abonnements (39,624 actifs)
product	833	Catalogue forfaits/produits
product_cat	34	Catégories produits
invoice	629,944	Factures
invoice_item	1,859,260	Lignes de facture
payment	540,522	Paiements
payment_item	684,778	Application paiements → factures
compta_journal_ecriture	1,211,991	Écritures comptables
compta_comptes	48	Plan comptable
ticket	242,618	Tickets support/install/facturation
ticket_msg	784,290	Messages tickets (8,123 avec images base64)
device	10,377	Équipements réseau
fibre	16,057	Raccordements fibre (OLT, VLAN, ports)
staff	155	Employés
bon_travail	14,472	Bons de travail technicien
tax	4	TPS/TVQ

Revenu mensuel actif (~$742K/mois)

Catégorie	Services actifs	Revenu mensuel
Mensualités fibre	17,050	$454,364
Mensualités sans fil	4,200	$189,799
Mensualités télévision	2,001	$46,360
Téléphonie	2,236	$34,004
Installation fibre	10,926	$7,285
Adresse IP fixe	138	$3,485
Autres	~70	~$7K

Relations entre tables

account (client)
  ├── 1:N delivery (adresses d'installation, GPS)
  │     └── 1:N fibre (raccordement OLT, VLAN, ports)
  ├── 1:N service (abonnements actifs)
  │     ├── N:1 product (forfait, prix, vitesses)
  │     ├── N:1 delivery (lieu du service)
  │     └── N:1 device (équipement assigné)
  ├── 1:N invoice (factures)
  │     └── 1:N invoice_item (lignes → product)
  ├── 1:N payment (paiements)
  │     └── 1:N payment_item (répartition sur factures)
  └── 1:N ticket (support, install, réparation)
        └── 1:N ticket_msg (messages, images base64)

product
  ├── N:1 product_cat (catégorie → num_compte)
  └── vitesses (download_speed, upload_speed, quota)

compta_comptes (plan comptable, 48 comptes)
  └── 1:N compta_journal_ecriture (1.2M écritures)

staff (155 employés)
  └── ticket.assign_to, bon_travail.tech1/tech2

---

2. Mapping Legacy → ERPNext

Phase A : Données maîtres (référence)

Legacy	ERPNext	Notes
account	Customer	customer_id, company, group_id, statut, PPA, Stripe
account (adresse)	Address	address1, city, zip, linked to Customer
account (contact)	Contact	first_name, last_name, email, tel, cell
delivery	Address (type=Shipping) + Service Location (FSM)	GPS, name, lié au Customer
product	Item (type=Service)	SKU, prix, vitesses dans custom fields
product_cat	Item Group	Hiérarchie catégories, num_compte pour comptabilité
tax / tax_group	Tax Template	TPS 5% + TVQ (8.925% → 9.975%)
staff	Employee	username, email, dept
device	Asset ou Service Equipment (FSM)	SN, MAC, modèle, parent device
fibre	Champs dans Service Location	OLT info, VLAN, frame/slot/port
compta_comptes	Chart of Accounts	48 comptes → plan comptable ERPNext
ticket_dept	Issue Type ou Department	21 départements de tickets

Phase B : Données transactionnelles

Legacy	ERPNext	Volume	Notes
invoice + invoice_item	Sales Invoice + Items	630K factures	Importer seulement les 2-3 dernières années ?
payment + payment_item	Payment Entry + References	540K	Idem — soldes historiques en opening balance
service (actifs)	Subscription	39,624	Critique — abonnements récurrents en cours
compta_journal_ecriture	Journal Entry	1.2M	Opening balance uniquement — pas d'import ligne par ligne
ticket + ticket_msg	Issue ou import dans HD	242K	Les fermés → archive, ouverts → migration
bon_travail	Dispatch Job (FSM)	14K	Historique tech

Phase C : Fichiers et images

Source	Volume	Stratégie
ticket_msg base64 images	~8,123 messages	Extraire → fichier → upload ERPNext File → remplacer dans texte
intranet_doc attachments	~33 docs	Copier fichiers → ERPNext File
uploads/ directory	À vérifier	Copier vers ERPNext sites/[site]/public/files/

---

3. Stratégie de migration

Principes

1. Ne pas tout migrer — Les données historiques fermées (factures payées, tickets clos) restent consultables dans le legacy en lecture seule
2. Opening balance — Un seul Journal Entry avec les soldes de chaque compte au jour J de migration
3. Services actifs = priorité #1 — Les 39,624 abonnements actifs doivent être fonctionnels dans ERPNext avant le cutover
4. Coexistence temporaire — Les deux systèmes roulent en parallèle pendant la phase de validation (1-2 mois)
5. Images base64 — Extraites en fichiers, uploadées dans ERPNext, lien URL dans le champ texte

Phases d'exécution

Phase 1 : Fondations (Semaine 1-2)

• Créer le Chart of Accounts dans ERPNext (48 comptes)
• Configurer les Tax Templates (TPS 5% + TVQ 9.975%)
• Créer les Item Groups (34 catégories produits)
• Importer les 833 Items (produits/forfaits) avec custom fields (vitesses, quota, profils OLT)
• Configurer les Pricing Rules si nécessaire

Phase 2 : Clients et adresses (Semaine 2-3)

• Importer les Customers actifs (6,510) avec mapping group_id → Customer Group
• Importer les Addresses (delivery) avec GPS → Service Location (FSM)
• Importer les Contacts (email, téléphones)
• Lier fibre data aux Service Locations (OLT, VLAN, ports)
• Importer les Employees (155 staff)

Phase 3 : Abonnements actifs (Semaine 3-4)

• Créer les Subscription Plans dans ERPNext
• Importer les 39,624 services actifs comme Subscriptions
• Valider : chaque service → bon Customer, bon Item, bon prix, bonne adresse
• Gérer les hijack (prix spéciaux par service) → Pricing Rule ou custom field

Phase 4 : Soldes et comptabilité (Semaine 4-5)

• Calculer les soldes de chaque compte client (factures - paiements)
• Créer l'Opening Balance dans ERPNext (1 Journal Entry)
• Valider que le total des comptes à recevoir correspond
• Importer les factures des 12 derniers mois (optionnel, pour historique)

Phase 5 : Cutover (Semaine 5-6)

• Freeze le legacy (lecture seule)
• Run final delta sync (nouvelles transactions depuis dernier import)
• Activer la facturation récurrente dans ERPNext
• Rediriger les flux PPA/Stripe vers ERPNext
• Formation utilisateurs
• Go-live

Phase 6 : Post-migration (Semaine 7+)

• Migrer les tickets ouverts (904 open + 487 pending)
• Extraire et uploader les images base64 des ticket_msg
• Legacy en mode archive (consultation seulement)
• Supprimer les accès écriture au legacy

---

4. Risques et décisions

Décisions à prendre

1. Historique des factures — Combien d'années importer ? Suggestion : 2 ans pour référence, opening balance pour le reste
2. Tickets historiques — Garder le legacy en consultation ou tout migrer vers Issue ?
3. PPA (pré-autorisé bancaire) — ERPNext supporte GoCardless/Stripe mais pas AccesD directement. Middleware requis ?
4. Numérotation — Garder les IDs legacy (customer_id, invoice_id) dans un champ legacy_id pour traçabilité ?
5. Portail client — account_profile (659 profils) → ERPNext Portal ou www.gigafibre.ca custom ?
6. Camping — Tables camping_* encore utilisées ?
7. RADIUS — Les services ont radius_user/radius_pwd. Intégration FreeRADIUS → ERPNext ?

Risques

Risque	Impact	Mitigation
Soldes incorrects après migration	Clients facturés en double ou manquant	Réconciliation avant/après avec rapport
PPA cassé pendant cutover	Perte de revenus	Coexistence : legacy facture, ERPNext prend le relais progressivement
Abonnements manquants	Client sans service	Script de validation : service legacy actif → Subscription ERPNext existe
Images base64 perdues	Contexte tickets perdu	Extraction batch avant cutover
Performance ERPNext avec 630K factures	Lenteur	Import seulement 2 ans, opening balance pour le reste

---

5. Scripts de migration (à développer)

migration/
  01_chart_of_accounts.py     # compta_comptes → Chart of Accounts
  02_tax_templates.py          # tax → Tax Templates
  03_item_groups.py            # product_cat → Item Group
  04_items.py                  # product → Item
  05_customers.py              # account → Customer + Address + Contact
  06_service_locations.py      # delivery + fibre → Service Location
  07_employees.py              # staff → Employee
  08_equipment.py              # device → Service Equipment
  09_subscriptions.py          # service (actifs) → Subscription
  10_opening_balance.py        # Soldes calculés → Journal Entry
  11_recent_invoices.py        # invoice (2 ans) → Sales Invoice
  12_recent_payments.py        # payment (2 ans) → Payment Entry
  13_open_tickets.py           # ticket (ouverts) → Issue
  14_extract_base64_images.py  # ticket_msg base64 → fichiers
  15_validation.py             # Réconciliation legacy vs ERPNext

Chaque script utilise le MCP ERPNext (Frappe Assistant Core) pour créer les documents directement, avec validation et rollback en cas d'erreur.

---

6. Données à NE PAS migrer

• compta_journal_ecriture complet (1.2M) → opening balance seulement
• invoice > 2 ans → opening balance
• ticket fermés (241K) → consultables dans legacy
• ticket_msg fermés → consultables dans legacy
• conso_* (consommation RADIUS) → données opérationnelles, pas comptables
• phonecall_log_* → historique téléphonique
• tmp*, *_bk, *_archive → backup tables
• camping_* → à confirmer si encore utilisé
• passwords_manager* → ne jamais migrer les mots de passe tiers