gigafibre-fsm/docs/design/activation-billing-automation.md

Automatisation : Installation → Approbation → Facturation

Statut : PLAN (2026-06-18). Touche F (live, autoritatif) → tout changement F = test-first. Décisions validées : (1) approbation explicite dans Ops ; (2) encaissement immédiat à l'approbation.

Objectif

Chaîne 100 % automatisée après un seul point de contrôle humain (l'approbation) : installation complétée (tech) → approuvée (dispatcher/admin dans Ops) → facturation prorata consolidée, émise et encaissée immédiatement, sans double-débit, F restant la source de vérité de facturation.

Principe de sécurité central — UN seul chargeur, DEUX déclencheurs

F ne charge pas « une facture » : stripe_ppa.php charge sum(total_amt - billed_amt) — le reste impayé, facture par facture. Donc :

• Déclencheur A — à l'approbation (immédiat) : on charge le prorata off-session puis on pose billed_amt = total sur cette facture.
• Déclencheur B — balayage du 15 (stripe_ppa.php) : charge le reste impayé ; le prorata déjà réglé (billed_amt = total) contribue 0 → jamais rechargé.

Les deux écrivent le même registre billed_amt → le reste impayé d'une facture est chargé exactement une fois. Pas de double-débit par construction — surtout ne PAS bâtir un 2ᵉ chargeur OPS (cause de l'incident de juin 2026, cf feedback_ppa_double_charge_incident).

Pipeline cible

[Tech] complète le job TERMINAL de la chaîne
        │  (existant : setJobStatusWithChain → _isChainTerminal → activateSubscriptionForJob)
        ▼
État « À approuver »  (abonnements restent 'En attente' ; aperçu prorata calculé, AUCUNE écriture)
        │
        ▼
[Dispatcher/Admin] révise l'install + l'aperçu prorata → clique « Approuver la facturation »
        │
        ▼  séquence atomique-idempotente (clé = job/approbation)
   a. Construire le prorata consolidé (moteur : récurrent proraté, ponctuel/install plein,
      rabais selon le type, arrondi plus-grand-reste)
   b. Créer la facture dans F (table `invoice`, date_orig = date d'approbation)   ← push-to-F
   c. Charger immédiatement off-session via Stripe (clé d'idempotence = id facture)
   d. Sur succès : poser billed_amt = total (règlement) → exclu du balayage du 15
   e. Activer les abonnements (Actif, start_date = lendemain — jour d'activation gratuit)
   f. Re-synchro miroir ERPNext
        │
        ▼
Récurrent : cycle normal de F (émission le 1er via task_charge_recurrent, balayage le 15)

État actuel (acquis — P0)

• Moteur services/targo-hub/lib/proration.js : consolidation type-aware (récurrent proraté / ponctuel-install plein / rabais selon le type), arrondi plus-grand-reste (somme exacte, 0 résidu), écriture brouillon double-gatée (commit:true + env PRORATION_WRITE=on, OFF par défaut). Endpoints POST /billing/prorate-preview et POST /billing/activation-preview (lecture seule).
• dispatch.js activateSubscriptionForJob : déjà branché sur le moteur → UNE facture consolidée (au lieu d'une par abonnement) ; filtre strict En attente (ne re-facture jamais les actifs) ; gaté PRORATION_WRITE (n'écrit rien tant que non armé).
• F : stripe_ppa.php (balayage du 15, sum(total_amt-billed_amt)), task_charge_recurrent.php (émission le 1er, due_date 16), payment_apply.php / credit_creance.php (règlent billed_amt), pay_*/payment_add.php (paiement d'une facture précise).

Composants à bâtir

A. Ops — la porte d'approbation

• Nouvel état sur Dispatch Job (ou doctype léger « Approbation Facturation ») : À approuver → Approuvé.
• Vue Ops : installs complétées en attente, avec aperçu de la facture prorata (via /billing/activation-preview, lecture seule) — l'approbateur voit exactement ce qui sera facturé.
• Action « Approuver la facturation » (permission dispatcher/admin) → POST hub. Idempotente.

B. Hub — l'orchestrateur

• POST /billing/approve-activation { job | customer + service_location } (staff-gated).
• Séquence b→f ci-dessus, idempotente (clé = job/approbation/mois), avec reprise sur échec partiel (ex. facture créée mais charge échouée → reprend à la charge, ne recrée pas la facture).

C. F — charge immédiate scoped (test-first)

• Réutiliser la logique off-session de stripe_ppa.php + le règlement de payment_apply.php, mais scoped à UNE facture (le prorata) au lieu du solde complet.
• Clé d'idempotence Stripe par facture ; billed_amt = total + billing_status = 1 sur succès.

D. Push facture (hub/ERPNext → F)

• Le prorata DOIT exister dans la table invoice de F (sinon ni chargé, ni balayé). Relié au chantier project_sales_sync_f (push-to-F). Reco : créer en ERPNext (déjà bâti) puis pousser vers F.

Garde-fous (non négociables)

• Idempotence : clé Stripe par facture + reprise. (Leçon juin : charge OK mais règlement échoue sous charge → recharge. Ici : clé idempotence + règlement fiable.)
• PRORATION_WRITE off jusqu'à validation ; brouillon → revue → armement.
• Test-first : Stripe test mode + client C-LPB4, puis 1 client réel, puis rollout.
• Pas de carte au dossier → courriel (comme stripe_ppa.php), NE PAS marquer payé.
• Échec de charge → facture reste due (billed_amt inchangé) → rejoint le balayage du 15 (filet)
  • alerte ; NE JAMAIS activer « payé » sans confirmation Stripe.
• Dernier jour du mois → prorata 0 (le récurrent du 1er couvre) — pas de facture prorata.
• Ré-approbation / double-clic → idempotent : ne pas créer 2 factures prorata pour la même activation (clé = service_location + job + mois).
• CRTC 2026-43 : frais d'installation facturables (exception) — la ligne installation au plein est conforme (cf project_crtc_2026_43).

Phasage (incrémental, réversible)

Phase	Contenu	Risque facturation
P0 ✅	Moteur + facture consolidée brouillon (gaté, ERPNext)	nul
P1	Porte d'approbation Ops : état + aperçu lecture seule + action (sans facturer)	nul
P2	Push prorata → F (créer la facture dans F, sans charger) ; valider qu'elle serait balayée le 15	faible (filet 15)
P3	Charge immédiate scoped dans F (test mode → C-LPB4 → 1 client) + règlement billed_amt + idempotence	contrôlé
P4	Câbler approbation → orchestrateur complet (auto) + monitoring/alertes	contrôlé
P5	Armer en prod (PRORATION_WRITE=on) après revue d'un cycle complet	go-live

Décisions ouvertes restantes

• Locus de création de la facture : F-direct vs ERPNext+push. Reco : ERPNext d'abord (déjà bâti) puis push-to-F.
• Ce que l'approbateur révise (checklist d'install, photos ?) — hors scope facturation pour l'instant.
• Mapping client F↔ERPNext pour le push (legacy_account_id / stripe_id) — à confirmer via project_sales_sync_f.