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