Aller au contenu principal

Guide de Validation de la Facturation et Conformité

Ce document décrit comment valider le fonctionnement de la facturation et assurer la conformité du système.

Table des matières​

  1. Vue d'ensemble
  2. Validations Fonctionnelles
  3. Validations de Conformité
  4. Tests Automatisés
  5. Checklist de Validation

Vue d'ensemble​

Le système de facturation doit respecter:

  • Validations fonctionnelles: règles métier, calculs corrects, intégrité des données
  • Validations de conformité: sécurité, audit trail, propriété des ressources
  • Validations légales: format des factures, règles fiscales (selon la juridiction)

Validations Fonctionnelles​

1. Validation des Schémas (Zod)​

Les factures sont validées via des schémas Zod définis dans backend/src/quotes-invoices/dto/create-invoice.dto.ts.

Règles de validation:​

  • title: Requis, min 1 caractère, max 255 caractères
  • amount: Nombre >= 0 (par défaut 0)
  • status: Enum (DRAFT, SENT, PAID, OVERDUE), par défaut DRAFT
  • session_id ou contact_id: Au moins un des deux doit être fourni
  • due_date: Date valide (optionnelle), doit être >= created_at
  • items: Array d'items (optionnel, par défaut [])

Items de facture:​

  • item_type: Enum requis (PRODUCT, SERVICE, DISCOUNT)
  • price_without_tax: Nombre >= 0
  • price_with_tax: Nombre >= 0
  • quantity: Nombre >= 0 (par défaut 1.0)
  • vat_percentage: Nombre entre 0 et 100 (par défaut 0)
  • discount_percentage: Nombre entre 0 et 100 (par défaut 0)
  • discount_amount: Nombre >= 0 ou null
  • discount_type: Enum (PERCENTAGE_OF_TOTAL, FIXED_WITH_TAX, FIXED_WITHOUT_TAX) ou null

2. Calculs​

Calcul des totaux (frontend et backend)​

Les totaux sont calculés selon la logique suivante:

  1. Sous-total: Somme de (price_without_tax * quantity * (1 - discount_percentage / 100)) pour tous les items sauf les discounts
  2. Taxes: Somme de (item_subtotal * vat_percentage / 100) pour tous les items sauf les discounts
  3. Réductions:
    • PERCENTAGE_OF_TOTAL: (subtotal + taxes) * discount_amount / 100
    • FIXED_WITH_TAX ou FIXED_WITHOUT_TAX: discount_amount
  4. Total: subtotal + taxes - discountAmount

Montant automatique​

Le montant total de la facture (invoice.amount) est automatiquement recalculé depuis les items lors de:

  • Création de la facture avec items
  • Mise à jour des items
  • Suppression de tous les items (montant = 0)

3. Règles Métier​

Propriété des ressources​

  • Un utilisateur ne peut créer/modifier/supprimer que ses propres factures
  • session_id, contact_id, et quote_id doivent appartenir à l'utilisateur
  • Vérification via verifyResourceOwnership() avant toute opération

États de facture​

  • DRAFT: Brouillon, peut être modifié librement
  • SENT: Envoyée au client, modifications limitées
  • PAID: Payée, statut final (ne peut pas être modifiée)
  • OVERDUE: En retard de paiement (mise à jour automatique possible)

Dates​

  • due_date doit être >= created_at
  • paid_at est défini lors du paiement (via Stripe/PayPal)

Validations de Conformité​

1. Sécurité​

Vérification de propriété (Ownership)​

Toutes les opérations CRUD vérifient que:

  • L'utilisateur est propriétaire de la facture
  • Les ressources liées (session, contact, quote) appartiennent à l'utilisateur

Audit Trail​

Toutes les actions sont enregistrées dans audit_logs:

  • CREATE: Création de facture
  • UPDATE: Modification de facture
  • DELETE: Suppression de facture

Les logs incluent:

  • user_id: Utilisateur qui a effectué l'action
  • entity_type: INVOICE
  • entity_id: ID de la facture
  • resource_owner_id: Propriétaire de la facture
  • action: Type d'action
  • metadata: Détails supplémentaires

2. Intégrité des Données​

Contraintes de base de données​

  • amount DECIMAL(10, 2) NOT NULL DEFAULT 0
  • status CHECK (status IN ('DRAFT', 'SENT', 'PAID', 'OVERDUE'))
  • Clés étrangères vers users, sessions, contacts, quotes
  • Index pour performances (owner_id, session_id, status)

Cohérence​

  • Le montant de la facture doit correspondre à la somme des items
  • Les items sont automatiquement recalculés à chaque modification

3. Conformité Légale​

Format des factures​

  • Titre obligatoire
  • Date de création automatique
  • Date d'échéance optionnelle
  • Montant en euros (format décimal)

Informations requises​

  • Identité du client (via contact_id ou session_id → contact)
  • Description des prestations (via items)
  • Montant total TTC
  • TVA (via vat_percentage dans les items)

Note: Les exigences légales peuvent varier selon la juridiction. Consultez un expert-comptable pour valider la conformité complète selon votre juridiction.

Tests Automatisés​

Structure des tests​

Les tests sont organisés dans backend/src/__tests__/quotes-invoices/:

quotes-invoices/
├── invoices-crud.service.spec.ts       # Tests CRUD
├── invoices-validation.spec.ts         # Tests de validation
├── invoices-calculations.spec.ts       # Tests de calculs
├── invoices-compliance.spec.ts         # Tests de conformité
└── invoices-items.service.spec.ts      # Tests des items

Types de tests​

1. Tests Unitaires (Validation)​

Testent les schémas Zod et les règles de validation:

describe("createInvoiceSchema", () => {
  it("should validate invoice with session_id", () => {});
  it("should validate invoice with contact_id", () => {});
  it("should reject invoice without session_id or contact_id", () => {});
  it("should reject invoice with invalid due_date", () => {});
  it("should validate invoice items", () => {});
});

2. Tests Unitaires (Calculs)​

Testent les calculs de totaux:

describe("calculateDocumentTotals", () => {
  it("should calculate subtotal correctly", () => {});
  it("should calculate taxes correctly", () => {});
  it("should apply percentage discounts", () => {});
  it("should apply fixed discounts", () => {});
  it("should handle empty items array", () => {});
});

3. Tests d'Intégration (CRUD)​

Testent les opérations complètes avec la base de données:

describe("QuotesInvoicesInvoicesCrudService", () => {
  it("should create invoice with items and calculate total", () => {});
  it("should update invoice and recalculate total", () => {});
  it("should prevent access to other user's invoices", () => {});
  it("should verify session ownership", () => {});
  it("should verify contact ownership", () => {});
});

4. Tests de Conformité​

Testent la sécurité et l'audit:

describe("Invoice Compliance", () => {
  it("should enforce ownership checks", () => {});
  it("should create audit logs on CREATE", () => {});
  it("should create audit logs on UPDATE", () => {});
  it("should create audit logs on DELETE", () => {});
  it("should maintain data integrity", () => {});
});

Exécution des tests​

# Tous les tests de facturation
npm test -- quotes-invoices

# Tests spécifiques
npm test -- invoices-validation
npm test -- invoices-calculations
npm test -- invoices-compliance

# Avec couverture
npm test -- --coverage quotes-invoices

Checklist de Validation​

Tests Automatisés​

  • Tests unitaires de validation (schémas Zod)
  • Tests unitaires de calculs (totaux)
  • Tests d'intégration CRUD
  • Tests de conformité (sécurité, audit)
  • Couverture de code >= 80%

Validations Fonctionnelles​

  • Création de facture avec session_id
  • Création de facture avec contact_id
  • Rejet si ni session_id ni contact_id
  • Calcul automatique du montant depuis les items
  • Mise à jour du montant lors de modification des items
  • Validation de due_date >= created_at
  • Validation des statuts (DRAFT, SENT, PAID, OVERDUE)
  • Calcul correct des totaux (sous-total, taxes, réductions)
  • Gestion des items avec réductions
  • Gestion des items avec TVA

Validations de Conformité​

  • Vérification de propriété sur toutes les opérations
  • Vérification de propriété des ressources liées (session, contact, quote)
  • Audit logs pour CREATE
  • Audit logs pour UPDATE
  • Audit logs pour DELETE
  • Intégrité des données (contraintes DB)
  • Cohérence montant facture = somme items

Tests Manuels​

  • Création de facture via l'interface
  • Modification de facture existante
  • Suppression de facture
  • Ajout/modification d'items
  • Calcul automatique des totaux
  • Export PDF de facture
  • Envoi d'email de facture
  • Paiement en ligne (Stripe/PayPal)

Documentation​

  • Guide de validation (ce document)
  • Documentation des schémas de validation
  • Documentation des calculs
  • Guide de conformité légale (selon juridiction)

Ressources​

  • Schémas de validation: backend/src/quotes-invoices/dto/
  • Service CRUD: backend/src/quotes-invoices/quotes-invoices-invoices-crud.service.ts
  • Service Items: backend/src/quotes-invoices/quotes-invoices-items.service.ts
  • Calculs frontend: frontend/src/utils/document-totals.utils.ts
  • Controllers: backend/src/quotes-invoices/invoices.controller.ts
  • Tests: backend/src/__tests__/quotes-invoices/

Support​

Pour des questions sur la conformité légale, consultez un expert-comptable ou un avocat spécialisé dans le droit fiscal de votre juridiction.