ADR-0006 — Intent comme représentation canonique d’une transaction

Status : Accepted Date : 2026-04 (NEX-438) Deciders : équipe Nex (ticket NEX-438) Tickets : NEX-438

Contexte

Initialement, les clients pouvaient déclencher une transaction via POST /v1/transactions qui validait, débitait, et créditait en un seul appel synchrone. Limitations :

• Pas de vue préalable du résultat (frais, limites, refus) avant validation.
• Difficulté à insérer une étape risk-engine, KYC complémentaire, ou maker-checker.
• Pas d’idempotence native (chaque retry crée une transaction).
• Couplage fort entre client et logique métier.

Décision

1. Représentation canonique d’une transaction = un intent (Stripe-style).
2. Cycle de vie : pending → confirmed → completed. Branches : failed, pending_review.
3. Flow en deux temps :
   • POST /v1/intents : crée l’intent, calcule frais et limites, évalue le risk preflight, retourne au client un snapshot complet (flow_snapshot).
   • POST /v1/intents/:id/confirm : confirme l’intent → exécution ledger.
4. POST /v1/transactions direct est déprécié. Toutes les transactions passent par intent.
5. Idempotence : l’intent porte une clé d’idempotence côté client (Idempotency-Key header) pour absorber les retries réseau.
6. flow_snapshot embarque le FlowSchema actif au moment du create — permet au client de rendre le bon écran sans re-fetch.

Conséquences

Positives

• UX bien meilleure : le client voit le résultat avant de confirmer.
• Insertion d’étapes intermédiaires (risk preflight, KYC, maker-checker) sans casser le contrat.
• Idempotence native, plus de double-débits sur retry.
• Audit trail riche : un intent persiste même s’il échoue.
• Découplage client / logique : le FlowSchema peut évoluer sans déploiement client.

Négatives / risques

• Deux requêtes au lieu d’une (latence et coût réseau légèrement supérieurs). Mitigation : design écrans qui exploitent les deux phases (preview puis confirm).
• Complexité du state machine — risque de transitions illégales. Mitigation : guards et tests sur chaque transition.
• Intents pending qui ne se confirment jamais — politique de TTL et de cleanup à mettre en place.

Alternatives écartées

• Garder POST /v1/transactions — pas évolutif, pas d’étape preview.
• Webhooks de pre-validation — complexifierait le client mobile.

Suivi

• Voir /architecture/transactions pour le détail du state machine.
• Voir /architecture/transaction-flows-config-driven pour le DSL FlowSchema.
• Voir ADR-0015 pour la décision config-driven associée.
• Voir ADR-0007 pour la trust boundary risk-engine.