FISCAL — Facturation et compliance multi-juridiction

Application DYNORS de facturation conforme (Sénégal, France, extensible) utilisée par les projets internes (RAGNAR, TAKKU, etc.) et les produits (SuperGest, Mediconnect, TRACIUM, DAWALALE, YOBALÉ…).

1. Rôle dans l’écosystème

graph LR
    CORE[dynors-core] --> FISCAL[FISCAL<br/>Facturation]

    RG[RAGNAR] --> FISCAL
    SG[SuperGest] --> FISCAL
    MC[Mediconnect] --> FISCAL
    TR[TRACIUM] --> FISCAL
    DW[DAWALALE] --> FISCAL
    YB[YOBALÉ] --> FISCAL

    SLY[SelebeYone (SLY)] --- FISCAL

FISCAL centralise :
la facturation conforme (TVA, règles par pays) ;
la numérotation des factures ;
la compliance (contrôles avant finalisation) ;
l’export (PDF, Factur-X) et les intégrations externes (ex. Chorus Pro).
Tous les projets qui “émettent” de la facturation passent via FISCAL.

2. Architecture interne

FISCAL repose sur une dépendance unique partagée (invoicing-core, dans dynors-extensions) et implémente toute la logique métier dans son propre backend.

graph TD
    subgraph Lib partagée
      IC[invoicing-core<br/>(dynors-extensions)]
    end

    subgraph App FISCAL
      FCore[invoicing.core<br/>FiscalInvoiceService]
      Tax[invoicing.tax<br/>TaxCalculatorService<br/>Senegal/France strategies]
      Num[invoicing.numbering<br/>SequentialNumberingStrategy]
      Comp[invoicing.compliance<br/>ComplianceValidationService]
      Exp[invoicing.export<br/>PdfExportService<br/>FacturXExportService]
      Int[invoicing.integration<br/>ChorusProIntegrationService]
    end

    IC --> FCore
    FCore --> Tax
    FCore --> Num
    FCore --> Comp
    FCore --> Exp
    FCore --> Int

invoicing-core : modèles country-agnostic (Invoice, InvoiceLine, InvoiceParty, InvoiceStatus) et interface InvoiceService.
FISCAL backend :
invoicing.core : FiscalInvoiceService, repository basé sur invoicing-core ;
invoicing.tax : stratégies de TVA par pays (SenegalTaxStrategy, FranceTaxStrategy) + TaxCalculatorService ;
invoicing.numbering : SequentialNumberingStrategy (INV-YYYY-NNNNN), InvoiceNumberingService ;
invoicing.compliance : ComplianceValidationService + validateurs par pays ;
invoicing.export : PdfExportService, FacturXExportService (stubs à brancher sur dynors-pdf) ;
invoicing.integration : ChorusProIntegrationService (stub).

3. Flux principaux

3.1 Création d’une facture

sequenceDiagram
    participant App as App appelante (ex. RAGNAR)
    participant FIS as FISCAL<br/>FiscalInvoiceService
    participant NUM as InvoiceNumberingService
    participant DB as InvoiceRepository

    App->>FIS: createInvoice(Invoice)
    FIS->>NUM: generateNextInvoiceNumber()
    NUM-->>FIS: numéro INV-YYYY-NNNNN
    FIS->>DB: save(invoice DRAFT)
    DB-->>FIS: invoice DRAFT
    FIS-->>App: invoice DRAFT (avec numéro)

3.2 Finalisation d’une facture

sequenceDiagram
    participant App as App appelante
    participant FIS as FISCAL
    participant TAX as TaxCalculatorService
    participant COMP as ComplianceValidationService
    participant DB as InvoiceRepository

    App->>FIS: finalizeInvoice(invoiceNumber)
    FIS->>DB: load(invoice)
    DB-->>FIS: invoice DRAFT
    FIS->>TAX: calculateTax(invoice, pays)
    TAX-->>FIS: montants TVA
    FIS->>COMP: validate(invoice, pays)
    COMP-->>FIS: OK / erreurs
    FIS->>DB: save(invoice FINALIZED)
    DB-->>FIS: invoice FINALIZED
    FIS-->>App: invoice FINALIZED

3.3 Export (PDF / Factur-X)

sequenceDiagram
    participant App as App appelante
    participant FIS as FISCAL
    participant EXP as PdfExportService / FacturXExportService

    App->>FIS: export(invoiceId, format)
    FIS->>EXP: generate(invoice, format)
    EXP-->>FIS: binaire (PDF / Factur-X)
    FIS-->>App: fichier à télécharger

À date, les services d’export sont encore des stubs (UnsupportedOperationException) et doivent être branchés sur dynors-pdf + templates.

4. Multi-juridiction

Pays supportés (état actuel) :

Sénégal (SN) : TVA 18%
France (FR) : TVA 20%

Extension à un nouveau pays :

Créer XxxTaxStrategy implémentant TaxStrategy.
Créer XxxComplianceValidator implémentant ComplianceValidator.
Ajouter le pays dans application.yml (supported-countries).
Ajouter les tests de bout-en-bout pour ce pays.

5. Démarrage & versions

5.1 Démarrage local

Résumé (voir README backend pour les détails) :

Prérequis : Java 17+, PostgreSQL 15+.
Démarrage type :

# Démarrer PostgreSQL (exemple docker-compose)
docker-compose up -d postgres

# Démarrer FISCAL
./gradlew bootRun

URL : http://localhost:8082/fiscal
Health : /fiscal/actuator/health

5.2 Gestion versions `dynors-core`

FISCAL consomme le BOM dynors-core :

par défaut, une version RELEASE (ex. 1.0.2) ;
mise à jour recommandée via le script racine update-dynors-version.sh dans dynors-internal ;
possibilité de tester ponctuellement une version -SNAPSHOT en surchargeant la propriété Gradle dynors.core.version.

6. Backlog fonctionnel (extraits Jira)

Principales épiques (simplifiées) :

EPIC-1 : Core Invoicing — service de facturation, entités, repositories.
EPIC-2 : Tax Strategies — stratégies par pays (SN, FR) + extension à d’autres pays.
EPIC-3 : Numbering — numérotation séquentielle + variantes.
EPIC-4 : Compliance — règles de validation par pays.
EPIC-5 : Export — PDF, Factur-X, templates.

Backlog technique (extraits) :

FIS-001 Compléter FiscalInvoiceService.
FIS-002 Implémenter PdfExportService.
FIS-003 Implémenter FacturXExportService.
FIS-004 Intégration Chorus Pro.
FIS-005 Tests complets (unitaires + intégration).

7. Références & docs sources

Guide d’utilisation FISCAL (contrats, intégration POS/produits) : voir Documentation source core.
Architecture backend FISCAL détaillée : ARCHITECTURE.md dans le repo dynors-internal (lien GitLab depuis l’annexe Liens vers docs originaux).
Backlog complet FISCAL : jira/fiscal/TICKETS.md (lien GitLab).

Pour les liens directs vers les .md historiques, se référer à l’annexe : Liens vers documents techniques originaux.

FISCAL - Facturation Multi-Juridiction

Application interne DYNORS - Moteur de facturation technique multi-pays

🎯 Objectif

FISCAL est le moteur de facturation technique de DYNORS. Il gère la création de factures conformes aux réglementations de plusieurs pays (Sénégal, France, extensible), avec calcul automatique des taxes, numérotation séquentielle et export multi-formats.

📋 Informations Générales

Propriété	Valeur
Nom	FISCAL
Code Application	`FIS`
Type	Application interne
Domaine	Facturation, Compliance, Taxes
Port	8082
Repository	`dynors-internal/applications/fiscal`
Status	⏳ Développement

🏗️ Architecture

Stack Technique

Backend : Java 17, Spring Boot 3.2
Base de données : PostgreSQL 15
Export PDF : dynors-pdf (templates Thymeleaf)
Modules CORE : commons, security, db

Architecture Modulaire

FISCAL/
├── invoicing-core/          # Service principal (FiscalInvoiceService)
├── invoicing-tax/           # Calcul taxes par pays
│   ├── TaxStrategy
│   ├── SenegalTaxStrategy (18%)
│   ├── FranceTaxStrategy (20%)
│   └── TaxCalculatorService
├── invoicing-numbering/     # Numérotation séquentielle
│   ├── NumberingStrategy
│   ├── SequentialNumberingStrategy
│   ├── InvoiceSequence (entité)
│   └── InvoiceNumberingService
├── invoicing-compliance/    # Validation compliance
│   ├── ComplianceValidator
│   ├── SenegalComplianceValidator
│   ├── FranceComplianceValidator
│   └── ComplianceValidationService
├── invoicing-export/        # Export formats
│   ├── PdfExportService
│   └── FacturXExportService
└── invoicing-integration/   # Intégrations externes
    └── ChorusProIntegrationService

✨ Fonctionnalités Principales

1. Création Factures

✅ Génération numéro séquentiel (INV-2025-001, INV-2025-002)
✅ Structure complète (client, fournisseur, lignes, totaux)
✅ Statuts (DRAFT, FINALIZED, PAID, CANCELLED)
✅ Multi-tenant (isolation par tenant)

2. Calcul Taxes Multi-Juridiction

✅ Sénégal : TVA 18%
✅ France : TVA 20%
📋 Extensible : Stratégie par pays

3. Compliance Automatique

✅ Validation par pays (règles fiscales)
✅ Détection erreurs compliance
⏳ Intégration Chorus Pro (France)

4. Export Multi-Formats

⏳ PDF : Templates par pays (dynors-pdf)
📋 Factur-X : Format électronique B2B
📋 XML : Pour intégrations
📋 CSV : Pour comptabilité

5. Modes d’usage

Certification POS : ticket de caisse (preuve de vente) sans facture formelle automatique.
Facture formelle : génération à la demande du client (ou selon règles métier).
Les adresses (émetteur, client) sont fournies par l’application appelante ; celle-ci peut s’appuyer sur SN Adresse (géocodage, autocomplétion) — voir doc API interne SN Adresse dans le repo.

🔄 Intégrations

Service	Type	Usage
RAGNAR	Consommateur	Appelle FISCAL pour générer factures
dynors-pdf	SDK	Export PDF avec templates pays
dynors-media	REST API	Logos clients + stockage PDF générés
Chorus Pro	REST API	Dépôt factures France (à venir)

🚀 Flux Métier : Génération Facture

1. RAGNAR → FISCAL : createInvoice()
   ↓
2. FISCAL : génère numéro séquentiel (INV-2025-001)
   ↓
3. FISCAL : calcule taxes (SN: 18%, FR: 20%)
   ↓
4. FISCAL : valide compliance
   ↓
5. FISCAL : finalise facture (status: FINALIZED)
   ↓
6. FISCAL → dynors-pdf : génère PDF
   ├─ Récupère logo depuis dynors-media
   ├─ Template HTML + données
   └─ Convertit HTML → PDF
   ↓
7. FISCAL → dynors-media : stocke PDF
   ↓
8. FISCAL → RAGNAR : retourne Invoice + URL PDF

🌍 Multi-Juridiction

Pays Supportés

Pays	Code	TVA	Status
Sénégal	SN	18%	✅ Implémenté
France	FR	20%	✅ Implémenté
Côte d'Ivoire	CI	18%	📋 Planifié
Mali	ML	18%	📋 Planifié

Extension Nouveau Pays

Pour ajouter un nouveau pays :

Créer XxxTaxStrategy implémentant TaxStrategy
Créer XxxComplianceValidator implémentant ComplianceValidator
Créer template PDF invoice-template-xx.html
Ajouter dans application.yml : supported-countries

📊 Modèle de Données

Invoice (Facture)

@Entity
public class Invoice {
    private String invoiceNumber;      // INV-2025-001
    private String tenantCode;         // Tenant
    private InvoiceParty client;       // Client
    private InvoiceParty supplier;     // Fournisseur (DYNORS)
    private List<InvoiceLine> lines;   // Lignes facture
    private BigDecimal subtotal;       // HT
    private BigDecimal totalTax;       // TVA
    private BigDecimal totalAmount;    // TTC
    private String country;            // SN, FR
    private InvoiceStatus status;      // DRAFT, FINALIZED, PAID
    private LocalDate invoiceDate;
    private LocalDate dueDate;
}

🔐 Sécurité & Tenants

Multi-tenancy

Mode : Schema partagé (SHARED)
Isolation : Par tenantCode
Numérotation : Séquence par tenant

Permissions

Seules les apps internes DYNORS (RAGNAR) peuvent appeler FISCAL
Authentification JWT + tenant header

📚 Documentation

Specs & Architecture

Guide d’utilisation : core/GUIDE_UTILISATION_FISCAL.md (certification POS, facture formelle, PDF/Factur-X, adresses)
Architecture : dynors-internal/applications/fiscal/backend/ARCHITECTURE.md
README : dynors-internal/applications/fiscal/backend/README.md
Spécifications : core/INTEGRATION_FACTURATION_SPECIFICATIONS.md
Mécanisme complet : core/MECANISME_COMPLET_FACTURATION_PDF_MEDIA.md

APIs

REST API : http://localhost:8082/fiscal/api/invoices
Swagger : http://localhost:8082/fiscal/swagger-ui.html

🎯 Roadmap

⏳ Phase 1 (En cours)

✅ Création factures
✅ Taxes multi-juridiction (SN, FR)
✅ Compliance
✅ Numérotation séquentielle
⏳ Export PDF (implémentation en cours)
⏳ Intégration dynors-media

📋 Phase 2 (Planifié)

Export Factur-X
Intégration Chorus Pro (France)
Pays additionnels (CI, ML)
Factures récurrentes

📋 Phase 3 (Future)

Avoirs (credit notes)
Multi-devises
Factures proforma

🚀 Démarrage Rapide

Prérequis

Java 17+
PostgreSQL 15+

Backend

cd dynors-internal/applications/fiscal/backend
./gradlew bootRun

URL : http://localhost:8082/fiscal
Health : http://localhost:8082/fiscal/actuator/health

👥 Équipe

Product Owner : Direction DYNORS
Tech Lead : À définir
Développeurs : Équipe DYNORS

📞 Contact

Support : support@dynors.com
Issues : GitLab dynors-internal/fiscal

Dernière mise à jour : 2026-03-05