Aller au contenu

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é

🔄 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 :

  1. Créer XxxTaxStrategy implémentant TaxStrategy
  2. Créer XxxComplianceValidator implémentant ComplianceValidator
  3. Créer template PDF invoice-template-xx.html
  4. 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

  • 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 : 30 janvier 2026