Services et contrats d'API
Principes
- Lecture et écriture CRUD via l'API REST générée par Supabase (PostgREST), toujours sous RLS, avec le jeton de session de l'utilisateur ; la clé publique « anon » n'ouvre aucun droit sans session (RNF-12).
- La logique métier sensible (moteur de projection, transitions d'échéances, export PDF) passe exclusivement par des fonctions serverless qui revalident les droits et écrivent en transaction.
- Toutes les erreurs suivent l'enveloppe
{ code, message, details?, request_id }; le request_id est propagé dans les journaux (RNF-27) et joignable au support via « Contacter ».
Lecture type (PostgREST)
GET /rest/v1/clients?select=id,prenom,nom,profil_investisseur,statut_kyc,
patrimoine_estime,objectif_annee,note_risque&order=nom.asc&limit=25
Authorization: Bearer <jeton_session> apikey: <cle_publique>
GET /rest/v1/echeances?simulation_id=eq.<uuid>
&select=id,date_echeance,type,montant,statut&order=date_echeance.asc
&limit=4&offset=0 (en-tete Prefer: count=exact pour « 1-4 sur 24 »)
Fonctions serverless (contrats)
| Fonction | Entrée (JSON) | Sortie et règles |
|---|---|---|
POST /functions/v1/simuler | { simulation_id } | { series: { prudent, equilibre, dynamique }, kpis: { capital_estime, total_verse, tri_annualise, plus_value, plus_value_pct }, hypotheses_version }. Recalcule les 3 scénarios (RG-03), remplace les projections, retourne les séries annuelles. Erreurs : 403, 404, 422. |
POST /functions/v1/echeance-transition | { echeance_id, action: valider | annuler | rejeter | replanifier, nouvelle_date? } | { echeance }. Applique la machine à états RG-11, journalise, notifie le conseiller si l'action vient d'un tiers. |
POST /functions/v1/export-pdf | { simulation_id } | { document_id, url_signee, expire_le }. Vérifie RG-14 (KYC), génère le PDF (gabarit SFD §12), dépose dans le bucket privé « rapports », crée la ligne documents, URL signée 10 minutes. |
POST /functions/v1/generer-occurrences | { } (appel planifié quotidien) | { occurrences_creees }. Applique RG-12 ; idempotente (unicité simulation + mois). |
Référentiel des codes d'erreur
| HTTP | Code | Signification | Message utilisateur |
|---|---|---|---|
| 400 | SAISIE_INVALIDE | Validation de champ échouée (bornes de la modale). | Le formulaire contient des erreurs : vérifiez les champs signalés. |
| 401 | NON_AUTHENTIFIE | Session absente ou expirée. | Votre session a expiré : reconnectez-vous. |
| 403 | ACCES_REFUSE | RLS ou rôle insuffisant. | Accès non autorisé. |
| 404 | INTROUVABLE | Ressource inexistante ou hors périmètre. | Élément introuvable. |
| 409 | CONFLIT | État concurrent (simulation active existante, transition invalide). | L'élément a changé : actualisez la page. |
| 422 | REGLE_VIOLEE | Règle de gestion (RG-04, RG-11, RG-14). | Message spécifique à la règle. |
| 500 | ERREUR_INTERNE | Défaillance serveur. | Une erreur est survenue : réessayez, l'incident est enregistré. |
Matrice rôles et permissions
| Action | Conseiller | Administrateur | Conformité | Direction |
|---|---|---|---|---|
| Voir les clients | Affectés | Tous | Tous | Agrégats |
| Créer et modifier un client | Oui (affectés) | Oui | Non | Non |
| Créer, modifier, archiver une simulation | Oui (affectés) | Oui | Non | Non |
| Valider / annuler une échéance | Oui (affectés) | Oui | Non | Non |
| Exporter un rapport PDF | Oui (affectés) | Oui | Oui | Non |
| Marquer un contrôle KYC | Non | Oui | Oui | Non |
| Consulter le journal d'audit | Non | Oui | Oui | Non |
| Gérer utilisateurs, affectations, hypothèses | Non | Oui | Non | Non |
Recherche globale et notifications
- Recherche (EF-011) : déclenchement dès 2 caractères, anti-rebond 200 ms, insensible à la casse et aux accents (index unaccent + trigrammes) ; 8 résultats maximum groupés par nature (clients, produits) ; résultats sous RLS ; clavier : flèches, Entrée, Échap ; raccourci « / ».
- Notifications (EF-013) : insertion en table par les fonctions serverless ; panneau alimenté à l'ouverture et par abonnement temps réel ; pastille plafonnée à 9+. Événements : occurrence passée En cours, échéance rejetée, KYC à renouveler, rapport prêt, transfert d'affectation.
Gabarit du rapport PDF (EF-070)
| Page / zone | Contenu |
|---|---|
| Page 1 : couverture | Logotype de l'organisation, « Rapport de simulation d'épargne », client (prénom, nom, profil, risque), conseiller, date, référence de la simulation. |
| Page 2 : synthèse | Les 4 indicateurs (valeurs et définitions courtes), paramètres de la simulation, version des hypothèses. |
| Page 2 : projection | Courbe du scénario retenu avec versements en pointillés ; tableau comparatif des trois scénarios aux années 1, 5 et N. |
| Page 3 : allocation et échéancier | Anneau d'allocation, classes et poids, frais, périodicité ; les 12 prochaines échéances. |
| Pied de chaque page | Mention RG-16 « Simulation non contractuelle : valeurs projetées à titre indicatif, hors fiscalité », pagination, identifiant, horodatage. |
A4 portrait, marges 18 mm, polices embarquées, graphiques vectoriels ou 2x, poids inférieur à 1,5 Mo ; génération côté serveur avec les mêmes tokens de couleur que l'application.