Guide Technique Complet

Flux de données

# Bénéficiaire
app/wallet → GET /api/v1/vouchers/me → PostgreSQL (table vouchers)

# Validation QR commerçant
/pos/scan → POST /api/v1/vouchers/validate
  → SELECT FOR UPDATE (atomique)
  → UPDATE vouchers (remainingValue, status)
  → INSERT voucher_transactions (displayRef, amount, commission)
  → INSERT ledger_entries ×2 (VOUCHER_LIABILITY → MERCHANT_PAYABLE)

# Reversement T+1
Cron 23h00 UTC → Bull Queue → Wave API / Orange Money API
  → INSERT merchant_settlements + ledger_entries (SETTLE)

Workflow standard

# 1. Développer en local
npm run dev                     # API (3001) + Web (3000) en parallèle

# 2. Vérifier les types et le lint
npm run typecheck && npm run lint

# 3. Créer une nouvelle migration si le schéma a changé
npx prisma migrate dev --name "description_courte"
# ⚠ Créer aussi prisma/migrations/{nom}/down.sql immédiatement

# 4. Commit et push → Railway redéploie automatiquement
git add . && git commit -m "feat: ..."
git push origin main

# 5. Suivre les logs de déploiement
railway logs --tail

Convention down.sql

-- Exemple : prisma/migrations/20260430_xxx/down.sql

-- Toujours dans l'ordre inverse du up.sql :
-- 1. Supprimer les contraintes étrangères
ALTER TABLE "voucher_transactions" DROP CONSTRAINT IF EXISTS "voucher_transactions_vendorId_fkey";

-- 2. Supprimer les index
DROP INDEX IF EXISTS "voucher_transactions_merchantId_createdAt_idx";

-- 3. Supprimer les colonnes
ALTER TABLE "voucher_transactions" DROP COLUMN IF EXISTS "vendorId";

-- 4. Supprimer les tables
DROP TABLE IF EXISTS "vendors";

Écritures types

Commandes

# Rollback complet (code + DB) — interactif
npm run rollback

# Rollback base de données uniquement
npm run rollback:db

# Rollback code uniquement (sans toucher à la DB)
npm run rollback:code

# Ou directement :
bash scripts/rollback.sh
bash scripts/rollback.sh --db-only
bash scripts/rollback.sh --code-only

Ce que fait le script

# ── Développement local ──────────────────────────────────────
npm run dev                        # API + Web en parallèle
docker-compose up -d               # PostgreSQL + Redis
npx prisma studio                  # Interface graphique DB
npx prisma migrate dev             # Nouvelle migration locale
npx prisma db seed                 # Fixtures de test

# ── Tests ────────────────────────────────────────────────────
npm run test:unit                  # Vitest avec coverage
npm run test:e2e                   # Playwright E2E
npm run test:load                  # k6 — 100 validations simultanées

# ── Production Railway ───────────────────────────────────────
railway logs --tail                # Logs en temps réel
railway variables                  # Variables d'environnement
railway run npx prisma migrate deploy # Migration manuelle en prod

# ── Rollback ─────────────────────────────────────────────────
npm run rollback                   # Rollback interactif (code + DB)
npm run rollback:db                # DB uniquement
npm run rollback:code              # Code uniquement

# ── Génération clés JWT RS256 ────────────────────────────────
openssl genrsa -out private.pem 4096
openssl rsa -in private.pem -pubout -out public.pem
openssl rand -hex 32               # HMAC_VOUCHER_SECRET

Erreurs bons (vouchers)

Erreurs provisions & émission

Erreurs transactions & paiements

Erreurs authentification (OTP / JWT)

Erreurs webhooks paiement

Erreurs système

Authentification

Bons (vouchers)

Commerçants (espace POS)

PENDING   → ISSUED    (webhook EME confirme emeConfirmedAt)
ISSUED    → PARTIAL   (paiement partiel — remainingValue > 0)
ISSUED    → USED      (paiement total — remainingValue = 0)
ISSUED    → EXPIRED   (cron 00h01 UTC — expiresAt dépassé)
ISSUED    → CANCELLED (annulation RH — remboursement provision)
PARTIAL   → USED      (solde épuisé)
PARTIAL   → EXPIRED   (cron expiration)
USED      → terminal (aucune transition)
EXPIRED   → terminal (aucune transition)
CANCELLED → terminal (aucune transition)

Wave Checkout API — recharge provision entreprise

Quand une entreprise recharge sa provision via Wave, kado utilise l'API Wave Checkout (pas l'API EME directe). Le flux est le suivant :

// Payload webhook Wave Checkout (exemple)
{
  "checkout_status": "complete",
  "client_reference": "uuid-company-payment-id",
  "amount": 50000,          // en XOF (FCFA)
  "currency": "XOF"
}

// Payload webhook Wave EME direct (exemple — activation voucher)
{
  "event": "checkout.session.completed",
  "data": { ... }
}

Reversements commerçants

Modèle A — Le commerçant scanne le QR bénéficiaire (legacy)

Le commerçant utilise le scanner du POS pour lire le QR affiché sur l'écran du bénéficiaire. Il saisit le montant et valide. Flux : POST /vouchers/validate depuis le compte MERCHANT.

Modèle B — Le bénéficiaire scanne le terminal (conforme BCEAO)

Le commerçant saisit le montant sur son POS (POST /merchants/me/transaction-request) qui génère un token Redis (TTL 180s) et un QR. Le bénéficiaire scanne ce QR avec son app, consulte le détail (GET /vouchers/transaction-request/:token), entre son mot de passe kado, et confirme (POST /vouchers/confirm-pay). La validation est effectuée côté bénéficiaire — il est l'initiateur.

Multi-PSP configurable

Architecture multi-prestataires de paiement — Bictorys, Wave Direct, Orange Money, extensible

Configuration centralisée

Les configurations PSP sont stockées dans la table PlatformSettings sous la clé payment_provider_{nom}. Chaque entrée contient :

Comparaison des PSP intégrés

Endpoints admin

Demande d'intégration nouveau PSP

L'admin peut demander l'intégration d'un nouveau PSP depuis l'interface (ex: PayDunya, CinetPay). La demande crée automatiquement un ticket support de catégorie TECHNICAL qui notifie l'équipe dev par email.

Payouts groupés

Système de reversement par cron jobs (DAILY/WEEKLY/BIWEEKLY) — réduction des frais agrégateurs jusqu'à 95% vs INSTANT

Enum PayoutSchedule

enum PayoutSchedule {
  INSTANT     // Au fil de l'eau — payout immédiat (option premium)
  DAILY       // Tous les jours à 09h Africa/Dakar
  WEEKLY      // Tous les lundis à 09h (défaut)
  BIWEEKLY    // 1er et 15 du mois à 09h
}

Cron jobs (timezone Africa/Dakar)

Logique de calcul du solde dû

// Pour chaque commerçant ayant la fréquence cible :
totalDue = SUM(VoucherTransaction.netAmount WHERE merchantId = X)
totalPaid = SUM(MerchantSettlement.amount WHERE merchantId = X AND status = CONFIRMED)
balanceDue = MAX(0, totalDue - totalPaid)

// Si balanceDue > 0 : enqueue Bull job avec retry exponentiel
// Reference idempotente : SETTLE-{merchantId[:8]}-{timestamp}

Choix de la fréquence par commerçant

Chaque commerçant choisit sa propre fréquence depuis son dashboard POS via PATCH /merchants/me/payout-schedule. Le champ payoutSchedule est sur le modèle Merchant (défaut WEEKLY).

Simulateur admin

Page admin /admin/dashboard?tab=payouts-simulator permet de simuler en temps réel les 4 modèles selon :

• Volume mensuel total
• Nombre de commerçants
• Commission kado (%)
• Frais agrégateur (variable + fixe)
• Nombre moyen de transactions par commerçant par jour

Le simulateur affiche pour chaque modèle : payouts/mois, frais totaux, marge nette, % marge conservée, et recommande automatiquement le modèle optimal.

Géolocalisation

Système de géolocalisation bénéficiaire et commerçant — recherche de proximité, itinéraires Google Maps

Backend — modèle Merchant

Le modèle Merchant a deux champs optionnels :

latitude   Float?
longitude  Float?

Endpoints

Algorithme haversine

Calcul de distance entre deux coordonnées GPS (formule haversine). Approximation valide jusqu'à ~50 km avec une erreur < 0,5%.

// Approximation utilisée pour la recherche par rayon
deltaLat = radiusMeters / 111_000
deltaLng = radiusMeters / (111_000 * cos(lat * PI / 180))

// Bounding box puis vérification haversine exacte

Frontend bénéficiaire

• Popup explicatif au premier login (localStorage geo_intro_seen)
• Rayons configurables : 1 / 2 / 5 / 10 km (défaut 2 km)
• Bouton "Itinéraire" → ouvre Google Maps avec navigation directe
• Composant GeoHelpModal adaptatif iOS/Android/macOS/Desktop

Frontend commerçant POS

• Capture manuelle de la position (bouton dans le dashboard)
• Pas de popup automatique au login (UX moins intrusive)
• Section permanente "Localisation du magasin"

Types de bons adaptés au Sénégal

11 catégories culturellement pertinentes — fin mai 2026

Liste finale

Valeurs dépréciées (rétrocompatibilité)

Les valeurs suivantes restent dans l'enum Prisma pour ne pas casser les bons existants en base, mais ne sont plus proposées à l'émission depuis le 23 mai 2026 :

• BONUS — remplacé par AIDE_SOCIALE ou GIFT_VOUCHER selon le contexte
• INDEMNITE — remplacé par AIDE_SOCIALE
• RECOMPENSE — remplacé par GIFT_VOUCHER
• BEAUTE — remplacé par BIEN_ETRE

Support admin enrichi

Onglet support amélioré pour la gestion efficace des tickets — templates, appels directs, notifications email

Templates de réponses pré-rédigées

6 templates accessibles en 1 clic depuis la zone de réponse (mode "Envoyer au contact" uniquement) :

Boutons d'appel direct

Trois boutons d'action rapide affichés dans la fiche ticket (si numéro/email renseignés) :

• Appeler — protocole tel:
• WhatsApp — wa.me/{numéro nettoyé}
• Email — mailto: avec sujet pré-rempli [{ref}] {sujet}

Notifications email automatiques

Chaque nouveau ticket (toutes sources confondues : merchant, company, beneficiary, internal) déclenche un email automatique vers SUPPORT_ADMIN_EMAIL (défaut support@kado.sn) avec template HTML pro :

• Référence + sujet en en-tête violet kado
• Badge priorité coloré (LOW/MEDIUM/HIGH/URGENT)
• Source + catégorie traduites en français
• Informations contact si renseignées
• Description complète avec formatage préservé
• Bouton "Ouvrir dans l'admin"

Lookup utilisateur intelligent

L'onglet "Accès & Comptes" permet de rechercher un utilisateur par téléphone ou email. La fonction normalizeIdentifier() supprime les espaces des numéros avant le lookup (ex: +221 77 358 88 28 → +221773588828) pour éviter les "Aucun utilisateur trouvé" injustifiés.

Reset password intelligent

Après réinitialisation, le backend renvoie { hasCompanyAccess, role }. Le frontend affiche conditionnellement :

• Bénéficiaire pur (BENEFICIARY) → redirection auto vers /app/login
• RH multi-rôles (COMPANY_ADMIN ou COMPANY_VIEWER avec companyId) → choix d'espace