Cycle de Vie des Documents de Facturation

Ce document définit les états et transitions autorisées pour les factures, devis, et avoirs.

Vue d'ensemble

Une facture émise doit être immutable (pas de modification destructive). Les corrections se font via des avoirs ou une annulation + réémission.

États des Factures

États Principaux

État	Description	Modifiable	Émis
DRAFT	Brouillon en cours de création	✅ Oui	❌ Non
ISSUED	Facture émise (immutable)	❌ Non	✅ Oui
SENT	Facture envoyée au client	❌ Non	✅ Oui
PARTIALLY_PAID	Paiement partiel reçu	❌ Non	✅ Oui
PAID	Facture entièrement payée	❌ Non	✅ Oui
OVERDUE	Facture en retard de paiement	❌ Non	✅ Oui
CANCELLED	Facture annulée	❌ Non	❌ Non
CREDIT_NOTE_ISSUED	Avoir émis (total ou partiel)	❌ Non	✅ Oui

Règles par État

DRAFT (Brouillon)

• Modifiable : Tous les champs peuvent être modifiés librement
• Supprimable : Oui
• Émission : Non encore émise
• Numérotation : Aucun numéro
• PDF : Pas de PDF définitif

ISSUED (Émise)

• Modifiable : ❌ AUCUNE modification possible (immutable)
• Supprimable : Non (seulement annulation possible)
• Émission : ✅ Émise, numérotée, PDF hashé
• Numérotation : Numéro séquentiel unique attribué
• PDF : PDF généré et hashé (SHA-256)
• Snapshots : Toutes les données figées (montants, taxes, client, vendeur)

Actions déclenchées lors du passage DRAFT → ISSUED :

1. Validation compliance (mentions obligatoires)
2. Attribution numéro séquentiel unique
3. Calcul et figement des totaux (HT, TVA, TTC)
4. Création snapshots (vendeur, client, conditions de paiement)
5. Génération PDF définitif
6. Calcul hash PDF (SHA-256)
7. Enregistrement issued_at et issued_by
8. Création événement audit INVOICE_ISSUED

SENT (Envoyée)

• Modifiable : Non (hérite d'ISSUED)
• État intermédiaire : Optionnel, indique que la facture a été envoyée au client
• Transition : ISSUED → SENT (via envoi email ou action manuelle)

PARTIALLY_PAID (Paiement Partiel)

• Modifiable : Non
• Calcul automatique : Si balance_due > 0 et balance_due < total_ttc
• Transition : ISSUED/SENT → PARTIALLY_PAID (automatique lors enregistrement paiement partiel)

PAID (Payée)

• Modifiable : Non
• Calcul automatique : Si balance_due <= tolerance (tolérance configurable pour frais)
• Transition : ISSUED/SENT/PARTIALLY_PAID → PAID (automatique lors paiement complet)

OVERDUE (En Retard)

• Modifiable : Non
• Calcul automatique : Si due_date < today et status != PAID et status != CANCELLED
• Transition : ISSUED/SENT/PARTIALLY_PAID → OVERDUE (automatique via job périodique)

CANCELLED (Annulée)

• Modifiable : Non
• Raison : Doit avoir une raison d'annulation
• Transition : DRAFT/ISSUED/SENT → CANCELLED (action manuelle)
• Note : Une facture annulée peut être réémise (nouvelle facture avec nouveau numéro)

CREDIT_NOTE_ISSUED (Avoir Émis)

• Modifiable : Non
• Transition : ISSUED/SENT/PARTIALLY_PAID/PAID → CREDIT_NOTE_ISSUED (après création avoir total)
• Note : Avoir partiel ne change pas le statut (reste ISSUED/PARTIALLY_PAID)

Diagramme de Transitions

stateDiagram-v2
    [*] --> DRAFT: Création
    
    DRAFT --> DRAFT: Modification
    DRAFT --> ISSUED: Émission<br/>(compliance OK)
    DRAFT --> CANCELLED: Annulation
    
    ISSUED --> SENT: Envoi email/client
    ISSUED --> PARTIALLY_PAID: Paiement partiel
    ISSUED --> PAID: Paiement complet
    ISSUED --> OVERDUE: Échéance dépassée<br/>(auto)
    ISSUED --> CREDIT_NOTE_ISSUED: Avoir total
    ISSUED --> CANCELLED: Annulation
    
    SENT --> PARTIALLY_PAID: Paiement partiel
    SENT --> PAID: Paiement complet
    SENT --> OVERDUE: Échéance dépassée<br/>(auto)
    SENT --> CREDIT_NOTE_ISSUED: Avoir total
    
    PARTIALLY_PAID --> PAID: Paiement complémentaire
    PARTIALLY_PAID --> OVERDUE: Échéance dépassée<br/>(auto)
    PARTIALLY_PAID --> CREDIT_NOTE_ISSUED: Avoir total/partiel
    
    PAID --> CREDIT_NOTE_ISSUED: Avoir/remboursement
    
    OVERDUE --> PARTIALLY_PAID: Paiement partiel
    OVERDUE --> PAID: Paiement complet
    
    CREDIT_NOTE_ISSUED --> [*]
    CANCELLED --> [*]
    
    note right of ISSUED
        Immutable
        Numérotée
        PDF hashé
    end note
    
    note right of CANCELLED
        Peut être réémise
        avec nouveau numéro
    end note

Table des Transitions Autorisées

État Source	État Cible	Condition	Automatique	Action Déclenchée
DRAFT	DRAFT	Modification manuelle	❌	-
DRAFT	ISSUED	Compliance OK + émission	❌	Numérotation, snapshots, PDF, hash, audit
DRAFT	CANCELLED	Annulation manuelle	❌	Audit
ISSUED	SENT	Envoi email/client	❌	Audit INVOICE_SENT
ISSUED	PARTIALLY_PAID	balance_due > 0 et < total_ttc	✅	Recalcul balance_due
ISSUED	PAID	balance_due <= tolerance	✅	Mise à jour statut
ISSUED	OVERDUE	due_date < today et non payée	✅	Job périodique
ISSUED	CREDIT_NOTE_ISSUED	Avoir total créé	❌	Audit CREDIT_NOTE_ISSUED
ISSUED	CANCELLED	Annulation manuelle	❌	Audit INVOICE_CANCELLED
SENT	PARTIALLY_PAID	Paiement partiel	✅	-
SENT	PAID	Paiement complet	✅	-
SENT	OVERDUE	Échéance dépassée	✅	Job périodique
SENT	CREDIT_NOTE_ISSUED	Avoir total	❌	Audit
PARTIALLY_PAID	PAID	Paiement complémentaire	✅	-
PARTIALLY_PAID	OVERDUE	Échéance dépassée	✅	Job périodique
PARTIALLY_PAID	CREDIT_NOTE_ISSUED	Avoir	❌	Audit
PAID	CREDIT_NOTE_ISSUED	Remboursement/avoir	❌	Audit
OVERDUE	PARTIALLY_PAID	Paiement partiel	✅	-
OVERDUE	PAID	Paiement complet	✅	-

Transitions Interdites

Les transitions suivantes sont strictement interdites :

• ❌ ISSUED → DRAFT (une fois émise, impossible de revenir en brouillon)
• ❌ PAID → ISSUED (une facture payée ne peut pas revenir à émise)
• ❌ CREDIT_NOTE_ISSUED → ISSUED (une fois avoir émis, pas de retour en arrière)
• ❌ CANCELLED → ISSUED (annulation définitive, réémission = nouvelle facture)

Immutabilité

Règles d'Immutabilité

Une facture ISSUED (ou supérieur) est immutable :

• ❌ Pas de modification des montants
• ❌ Pas de modification des items
• ❌ Pas de modification des taxes
• ❌ Pas de modification des snapshots (vendeur, client)
• ❌ Pas de modification du numéro
• ❌ Pas de régénération PDF (sauf endpoint admin explicitement auditée)

Corrections

Les corrections se font via :

1. Avoir (credit note) : Pour corriger une facture émise

   • Avoir partiel : ajuste le montant restant dû
   • Avoir total : annule complètement la facture

2. Annulation + Réémission : Pour une facture avec erreurs majeures

   • Annuler la facture (CANCELLED)
   • Créer une nouvelle facture (DRAFT → ISSUED) avec nouveau numéro

Validation des Transitions

Validateur de Cycle de Vie

Un validateur doit être créé pour vérifier les transitions :

class BillingLifecycleValidator {
  canTransition(from: InvoiceStatus, to: InvoiceStatus): boolean {
    // Implémentation de la table des transitions autorisées
  }
  
  requiresCompliance(status: InvoiceStatus): boolean {
    return status === 'ISSUED';
  }
  
  isImmutable(status: InvoiceStatus): boolean {
    return ['ISSUED', 'SENT', 'PARTIALLY_PAID', 'PAID', 'OVERDUE', 'CREDIT_NOTE_ISSUED'].includes(status);
  }
}

Guards API

• Vérifier que la transition est autorisée avant mise à jour
• Bloquer toute modification si isImmutable(status) === true
• Retourner erreur 400/403 si tentative de modification sur facture immutable

États des Avoirs (Credit Notes)

Les avoirs suivent un cycle de vie similaire mais simplifié :

État	Description
DRAFT	Brouillon
ISSUED	Avoir émis (immutable)

Transitions avoirs :

• DRAFT → ISSUED : Émission (avec numérotation, PDF, hash)
• ISSUED : État final (immutable)

Notes d'Implémentation

• Les transitions automatiques (PARTIALLY_PAID, PAID, OVERDUE) sont gérées par des jobs/services
• Le calcul de balance_due détermine les transitions automatiques de paiement
• Un job périodique vérifie les factures OVERDUE
• Les transitions manuelles nécessitent des permissions appropriées