# Système de facturation

## Sommaire

- [Introduction](#introduction)
- [Motivation](#motivation)
- [Guide-level explanation](#guide-level-explanation)
- [Reference-level explanation](#reference-level-explanation)
- [Justification et alternative](#justification-et-alternatives)
- [Impacts si la situation reste ainsi](#impacts-si-la-situation-reste-ainsi)
- [Etat de l'art](#etat-de-l'art)
- [Questions non résolues](#questions-non-resolues)
- [Possibilités futures](#possibilites-futures)

## Introduction

Il est nécessaire d'avoir un module de facturation afin d'assister les organisations de notre application **Molink** dans ce processus.

## Motivation

Les raisons qui nous poussent à développer le module de facturation sont de permettre aux clients de :
- Générer et exporter des factures depuis Molink vers les services internes des organisations.
- Visualiser et gérer les factures générées.
- Automatiser cette gestion de factures via l'API Molink.

## Guide-level explanation

### Fonctionnalités

Les raisons qui ont poussé la rédaction du document est de simplifier et d'automatiser tous le processus de facturation des organisations aux déclarants, voici les étapes fonctionnelles visées :

- **Générer une facture**
Les organisations pourront, pour une période donnée ainsi qu'un déclarant affilié, générer une facture et l'exporter sous multi-format (PDF, JSON, XML)
- **Visualiser les factures**
Les organisations pourront visualiser leurs factures ainsi que leur statut afin de pouvoir les administrer sur une seule interface.
- **Automatiser le système de factures**
Notre API Molink permettra aux organisations d'automatiser toute cette gestion de facture (création, visualisation, envoi ...)

### Structure du système de facture

Une facture est composée de :
- Une organisation (envoyeur)
- Un déclarant (receveur)
- Une période donnée
- Des avis de décès
- Détailler avec l'existant

## Reference-level explanation

### Existant Single-Tenant

-- A remplir par Alexandre

### Format des données

Voici le format d'une facture de la table `invoices`

{
    "id": "uuidv7"
    "organization__id": "organization_fk"
    "operator__id": "operator_fk"
    "start_date": "timestamp"
    "end_date": "timestamp"
    "status": "pending" | "created" | "failed"
    "format": "pdf" | "xml" | "json"
    "url": "string" | null,
}

### Génération de facture

Pour générer une facture, une organization va faire un appel d'API ou sélectionner dans son interface Molink :
- `operator_id`: L'identifiant d'un déclarant
- `start_date`: La date de départ d'une période au format dd/mm/YYYY
- `end_date`: La date de fin d'une période au format dd/mm/YYYY
- `format`: Le format demandé de la facture

Une fois la génération demandée, une ligne va se créer dans la table `invoices` au `status = pending` et `url = null`

Un job asynchrone `GenerateInvoice` va alors être lancé qui aura comme responsabilité de :
- Récupérer les `commandes` effectuées pour la période et le déclarant donnés
- Formatter ces données sous le `format` demandé
- Stocker ce fichier dans *Amazon AWS*
- Mettre à jour la ligne `invoice` pour passer le `status` à "created" avec l'`url` qui pointera sur le fichier AWS

Pour gérer ces jobs, une solution de Message Queuing (existant ?) sera mis en place :
- Mettre en place un système de retry pour lancer `3` fois le job si nécessaire
- Si le message n'as pas été consommé :
- Il sera mis dans une Dead-Letter Queue, ce qui causera une alerte sur notre système de monitoring
- Le status de l'`invoice` passera en "failed"

### Export de factures

Pour ce qui est de l'export des factures, celle-ci se fera via appel d'API ou sur la page de visualisation des factures :
- Une organisation pourra voir ses factures générées, la période donnée, le format demandé, le déclarant associé ainsi que son statut
- Si la facture est créée, il pourra télécharger le fichier

### API Molink de factures

Pour automatiser ce système et permettre à nos organisations d'intégrer Molink à leurs solutions de factures actuelles, ces ressources seront accessibles via appel d'API sur ces routes suivantes :

POST /v2/invoices
    :operator_id
    :start_date
    :end_date
    :format
GET /v2/invoices
    ?filters[status]
    ?filters[operator_id]
    ?filters[between_date]
GET /v2/invoices/{id}/download

## Justification et alternatives

Dans notre souhait de fournir un service complet de multi-diffusion de faire-part, permettant aux organisations et déclarants d'internaliser l'intégralité de leur processus métier via Molink, il est nécessaire de comprendre dans ce service la génération de factures.

### Autres conceptions envisagées

#### Transmission de d'informations de facturation simple

Alors que nos organisations auraient déjà un système de facturation et de communication en interne, il est possible d'utiliser la plateforme Molink pour simplement :
- Résumer à une organisation ce qu'un déclarant lui doit pour une période donnée

##### Avantages

- Facile à implémenter

##### Inconvénients

- Nécessite aux organisations de remplir manuellement leurs factures

## Impacts si la situation reste ainsi

Le système de facturation actuel ne prend pas en charge le multi-tenant.

L'algorithme actuel n'est pas permissif pour aller dans le sens d'un Sass et doit être revu intégralement.

## Etat de l'art

Il existe déjà des modules de facturation très performants connus :

### Stripe

Stripe permet de générer des factures automatisés pour leur différents clients avec envoi automatique de celles-ci
aux clients finaux de l'entreprise.

## Questions non résolues

- Quel sera le canal de communication facture entre l'organisation et ses déclarants ?
- Est-ce Molink pourra faire office d'intermédiaire afin que les déclarants visualisent leurs coûts et factures ?

## Possibilités futures

### Système de template

Les organisations pourront créer leurs propres template de facture personnalisés avec leurs informations

Un template de facture est composé de :
- Un bloc contenant les informations de l'organisation (envoyeur)
- Un bloc contenant les informations du déclarant (receveur)
- Un bloc de résumé de la facture (titre, numéro de facture)
- Un bloc de détails de la facture (lignes de commande)
- Un bloc de références de la facture (TVA, date d'émission, jours avant règlement)

### Export de factures multi-support

Dans un premier temps, une facture sera exportée en HTTP, que ce soit via l'interface MOLINK ou lors d'un appel d'API.

Il est possible que l'ajout d'un multi-support d'envoi SSH / FTP soit nécessaire par la suite.