Règles métier et moteur de projection

Registre des règles de gestion

Id	Règle
RG-01	Toute création ou modification de simulation est atomique : validation complète des champs puis écriture en transaction unique ; tout échec annule l'ensemble.
RG-02	Un client possède au plus une simulation active de référence par type de simulateur ; l'activation d'une simulation archive automatiquement la précédente (trace d'audit).
RG-03	Chaque exécution du moteur persiste les séries mensuelles par scénario, la version des hypothèses, l'horodatage et l'auteur. Une projection historisée est rejouable à l'identique (CA-12).
RG-04	La somme des poids d'allocation vaut exactement 100,00 % (contrôle interface + contrainte en base) ; poids entre 0 et 100, deux décimales.
RG-05	Capital estimé = valeur de la série du scénario sélectionné au mois courant de la simulation active.
RG-06	Total versé = somme algébrique des échéances au statut Validé (les arbitrages comptent pour zéro).
RG-07	Rendement annualisé = TRI annualisé des flux validés (capital estimé en valeur terminale), résolu par itération (Newton, repli bissection), arrondi à 0,1 point.
RG-08	Plus-value latente = capital estimé moins total versé ; pourcentage associé = plus-value / total versé (si total versé positif).
RG-09	Le libellé du badge profil provient du référentiel de profils de l'organisation (prudent, défensif, équilibré, offensif, dynamique par défaut) ; la note de risque (1 à 10) est saisie indépendamment.
RG-10	Une échéance d'arbitrage ne porte pas de montant (null) mais référence une allocation cible ; affichage : tiret + « € ».
RG-11	Machine à états des échéances (ci-dessous) ; toute transition est journalisée ; aucune autre transition n'est permise.
RG-12	Les occurrences mensuelles sont générées sur 12 mois glissants par tâche quotidienne (une par mois au jour de prélèvement, ajusté au 28) ; la modification du montant ne réécrit que les occurrences futures Planifiées.
RG-13	Progression vers l'objectif d'une échéance = min(100, capital projeté à la date de l'échéance selon le scénario par défaut / objectif de capital × 100), arrondi à l'entier ; sans objectif, tiret. À valider (AMB-01)
RG-14	Statut KYC : « à renouveler » à partir de M-2 avant l'échéance de validité, « expiré » au-delà ; l'export PDF est bloqué si expiré (« Export indisponible : KYC expiré »), la simulation reste consultable.
RG-15	Journal d'audit en ajout seul : auteur, horodatage UTC, organisation, entité, action, contenu avant/après (JSON) ; alimenté par déclencheurs base.
RG-16	Tout rapport PDF et tout écran de projection portent la mention « Simulation non contractuelle : valeurs projetées à titre indicatif, hors fiscalité ».
RG-17	Formats des montants : moins de 100 000 € en unités (« 5 000 € ») ; patrimoine et échelles de graphique en k€ avec une décimale si nécessaire (« 320 k€ », « 12,5 »).

Hypothèses de scénarios (paramétrables, versionnées)

Scénario	Rendement annuel brut	Commentaire
Prudent	1,8 %	Dominante fonds en euros et obligations courtes.
Équilibré	3,8 %	Réglé pour produire un rendement net d'environ 3,1 % avec 0,60 % de frais, en cohérence avec la maquette.
Dynamique	6,0 %	Dominante actions ; volatilité supérieure, mentionnée dans le rapport.

À valider (R-01) Valeurs administrables par organisation et versionnées : chaque projection référence la version utilisée (RG-03).

Formules du moteur

Pas mensuel sur H années (M = 12 × H), euros au centime (arrondi bancaire), à partir de : versement initial V0, versement mensuel Vm, versements exceptionnels datés, frais annuels f, rendement brut r du scénario.

Taux net annuel   : r_net = (1 + r) * (1 - f) - 1
Taux net mensuel  : i = (1 + r_net)^(1/12) - 1
Initialisation    : K(0) = V0 ; C(0) = V0
Pour chaque mois m de 1 a M :
  flux(m) = Vm + somme des versements exceptionnels du mois m
  K(m) = K(m-1) * (1 + i) + flux(m)      (capital projete)
  C(m) = C(m-1) + flux(m)                (cumul des versements, serie pointillee)
Arbitrage : flux nul ; changement d'allocation memorise (sans effet sur r en v1).
Sorties : series {mois, K, C} par scenario ; points annuels affiches.

La forme multiplicative (1 + r)(1 - f) reflète des frais prélevés sur encours ; l'alternative soustractive (r - f) est documentée et activable par paramètre si le métier la préfère. Les trois scénarios sont calculés à chaque exécution pour figer l'échelle du graphique et alimenter le rapport PDF. Cette implémentation est reprise à l'identique dans assets/donnees-demo.js (fonction projeter) et exécutée par le prototype.

Machine à états des échéances (RG-11)

            creation (versement programme / exceptionnel / arbitrage)
                               |
                               v
        +-------------------- PLANIFIE ----------------------+
        | annulation (conseiller)        echeance J0 / manuel |
        v                                                     v
     ANNULE                                               EN COURS
                                                              |
                        rejet (incident de paiement) <--------+--------> validation
                               |                                            |
                               v                                            v
                            REJETE ------ replanification ------>        VALIDE
                                                                        (final)

Droits : validation et annulation par le conseiller affecté ou l'administrateur ; rejet automatique (intégration paiement future) ou administrateur ; replanification par le conseiller. Validé et Annulé sont terminaux.

Cas de calcul de référence (contrat minimal du moteur)

Cas	Paramètres	Résultat attendu (exact)
B-01 : capital inerte	V0 = 1 000 € ; Vm = 0 ; r = 0 % ; f = 0 % ; H = 10 ans.	K(m) = 1 000,00 € pour tout m.
B-02 : versements purs	V0 = 0 ; Vm = 100 € ; r = 0 % ; f = 0 % ; H = 1 an.	K(12) = C(12) = 1 200,00 €.
B-03 : intérêts purs	V0 = 1 000 € ; Vm = 0 ; r = 12 % ; f = 0 % ; H = 1 an.	K(12) = 1 120,00 € (composition mensuelle équivalente).
B-04 : effet des frais	B-03 avec f tel que (1+r)(1-f) = 1.	K(12) = 1 000,00 € : les frais annulent exactement le rendement.
B-05 : flux exceptionnel	B-02 + versement de 500 € au mois 6.	K(12) = C(12) = 1 700,00 €.
B-06 : arbitrage neutre	B-03 + arbitrage au mois 6.	Séries strictement identiques à B-03 (RG-10).

États d'interface et messages

Situation	Comportement spécifié
Chargement	Squelettes sur les cartes (KPI, graphique, tableau) ; jamais d'écran blanc ; délai perçu masqué jusqu'à 400 ms.
Vide	Illustration légère + phrase d'action (« Aucune simulation active : créez une simulation ») + bouton primaire.
Erreur réseau	Bandeau non bloquant « Connexion interrompue : nouvelle tentative... » avec reprise automatique (3 essais, délai exponentiel).
Erreur serveur	Carte en état d'erreur avec bouton « Réessayer » ; request_id joignable au support.
Confirmation destructive	Modale explicite pour annulation d'échéance, archivage de simulation ou de client (« Cette action est journalisée »).
Succès	Toast discret 4 secondes (« Simulation créée », « PDF exporté »), jamais bloquant.

Ces six états sont démontrables dans le prototype (panneau « États de démo ») et documentés composant par composant dans le design system.