ADR-0005 — Card number marchand 8 caractères avec préfixe env

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

Contexte

Initialement, chaque marchand avait un merchants.merchant_code à 6 chiffres affiché en magasin pour qu’un client tape ce code pour payer. Limitations :

• 6 chiffres = 10⁶ = 1 million de codes — saturation à long terme.
• Un seul code par marchand, donc impossible d’identifier le POS qui encaisse.
• Pas de support physique (carte) pour les marchands itinérants.

Besoin : permettre une carte physique par POS marchand, scannable ou avec un code saisissable, identifiable rapidement.

Décision

1. Remplacer merchants.merchant_code par cards.card_number 8 caractères imprimés sur la carte physique marchand.
2. L’utilisateur tape les 6 derniers chiffres ; le serveur préfixe avec MERCHANT_CARD_PREFIX (variable d’environnement, default 63) pour reconstruire le card_number 8 caractères complet.
3. cards.pos_id — relation 1-1 avec un POS (UNIQUE PARTIAL sur card active par POS).
4. CreateIntent persiste metadata.posId pour le routage downstream (ledger, audit).
5. merchants.merchant_code déprécié (colonne kept nullable pour data historique). MerchantsRepository.findAllWithPagination continue de l’ILIKE pour lookup legacy.

Conséquences

Positives

• Identification précise du POS qui encaisse (audit, reconciliation, commissions).
• Espace de codes ×100 (8 chars vs 6).
• Carte physique = marketing tangible pour le merchant.
• Préfixe env permet de réserver un namespace par environnement (staging vs prod) ou par batch d’émission.

Négatives / risques

• Migration des merchants legacy : merchant_code reste en lecture pour ne pas casser l’historique.
• Vulnérabilité brute-force sur les 6 chiffres saisis : à rate-limiter côté API. Mitigation : guard rate-limit sur lookupCardByNumber.
• Si le préfixe change, les cartes physiques émises avant deviennent invalides — règle : on ne change pas MERCHANT_CARD_PREFIX en cours d’opération sans plan de migration.

Alternatives écartées

• 8 chiffres entiers saisis — UX trop lourde pour les utilisateurs au comptoir.
• QR code seul, pas de code numérique — exclut les feature phones et les contextes sans caméra fiable.
• Code alphanumérique 6 chars — encore plus d’espace mais saisie hétérogène (clavier multilingue, ambiguïté O/0).

Suivi

• Code : services/ledger-wallets/src/cards/ pour les entities et lookup.
• Voir /architecture/services-catalog pour la mention dans le contexte multi-utilisateurs marchand.
• Flow merchant-card à documenter dans /flows/ au Lot 3.