Service Configuration
Référentiel central de la plateforme Nex. Stocke et expose toutes les données de référence et règles métier qui paramètrent le comportement des autres microservices : pays, devises, frais, limites, commissions, moyens de paiement, conformité KYC, agents, zones.
| Attribut | Valeur |
|---|---|
| Package | @nex/service-configuration |
| Port | 3006 |
| Base URL (interne) | http://configuration:3000/v1 |
| Schéma DB | configuration (PostgreSQL) |
| Swagger | actif |
| Owner | @platform-team |
Pourquoi ce service existe
- Centraliser toutes les règles métier en un seul endroit.
- Modifier les paramètres sans toucher au code.
- Garantir la cohérence entre tous les services downstream.
- Faciliter l'ajout de nouveaux pays, devises ou types de transactions.
Plan de la documentation
La référence complète du service est éclatée en sept pages thématiques. Pick celle qui correspond à ton besoin :
| Page | Contenu |
|---|---|
| Modèle de données | Les 26 entités, leurs relations, leurs colonnes clés. |
| Géographie, transactions, frais et limites | Pays/devises supportés, types de transactions, canaux autorisés, calcul des frais (paliers), TVA par type, remises négociées par entreprise, moteur de tarification unifié (preview), limites par entité et par période. |
| Commissions | Règles de redistribution des frais entre plateforme, marchand, agent. |
| Moyens de paiement et règles inter-pays | Mobile Money / cartes / virements par pays + corridors CEMAC/UEMOA. |
| Conformité KYC et agents | Documents d'identité acceptés, professions à risque, types d'agents, zones. |
| Paramètres système et notifications | Setting (global) vs ServiceConfig (par service), canaux de notification. |
| Patterns API et intégration | Conventions HTTP, pagination, erreurs, exemples d'intégration. |
Clarification des concepts clés
Quelques distinctions importantes pour éviter les confusions courantes.
TransactionType vs TransactionLimit (limites)
Il y a deux niveaux de limites différents dans le système.
| Concept | Où ? | Rôle | Exemple |
|---|---|---|---|
TransactionType.min_amount / max_amount | Dans la définition du type | Limites globales techniques du type de transaction | TRANSFER : min = 100, max = 5 000 000 |
TransactionLimit | Entité séparée | Limites par entité (user, merchant, role, global) et par période (per_transaction, daily, monthly) | User123 : 500 k par transaction, 2 M par jour |
TransactionType "TRANSFER" : min = 100 XAF, max = 5 000 000 XAF (technique)
↓
TransactionLimit "utilisateur non vérifié" : max = 50 000 XAF par transaction (métier)
↓
TransactionLimit "Jean (user123)" : max = 500 000 XAF par jour (personnalisé)
→ Jean peut faire un TRANSFER entre 100 XAF et 50 000 XAF (limite la plus restrictive),
avec un cumul ≤ 500 000 XAF / jour.TransactionChannel vs AuthorizedChannel
| Concept | Rôle | Exemple |
|---|---|---|
TransactionChannel | Référentiel de tous les canaux existants | MOBILE_MONEY, CARD, BANK_TRANSFER, CASH, NXPAY_WALLET |
AuthorizedChannel | Matrice d'autorisation : quel canal pour quel type de transaction | TRANSFER autorisé sur MOBILE_MONEY et NXPAY_WALLET, pas sur CASH |
TransactionBetween (autorisations entre rôles)
Définit qui peut envoyer de l'argent à qui.
TransactionType: TRANSFER
├── user → user ✓ autorisé (P2P classique)
├── user → merchant ✓ autorisé (paiement)
├── merchant → user ✓ autorisé (remboursement)
├── user → agent ✗ interdit (un client utilise CASH_OUT, pas TRANSFER)
└── agent → agent ✗ interditPaymentMethodType vs PaymentMethod
| Concept | Où ? | Rôle | Exemple |
|---|---|---|---|
PaymentMethodType | service Configuration | Template des moyens de paiement disponibles | MTN_CG, VODAFONE_CG, VISA, MASTERCARD |
CountryPaymentMethodType | service Configuration | Disponibilité par pays + capacités | MTN_CG au Congo : peut payer, recharger, retirer |
PaymentMethod | service Ledger-Wallets | Instance d'un moyen de paiement pour un utilisateur | Le compte MTN de Jean (+242 06 123 4567) |
AgentType
Définit les capacités et rôles des agents.
| Code | Description | has_commission | is_field_agent | can_be_zoned | requires_merchant |
|---|---|---|---|---|---|
distribution | Cash in/out | ✓ | ✓ | ✓ | ✓ |
compliance | Vérification KYC | ✗ | ✓ | ✓ | ✗ |
internal | Agent interne Nex | ✓ | ✗ | ✗ | ✗ |
field | Terrain générique | ✓ | ✓ | ✓ | ✗ |
master | Gère d'autres agents | ✓ | ✗ | ✓ | ✓ |
Détails dans Conformité KYC et agents.
Setting vs ServiceConfig
| Concept | Portée | Usage |
|---|---|---|
Setting | Global plateforme | Paramètres partagés (maintenance_mode, platform_name, support_email) |
ServiceConfig | Par service et environnement | orchestrator.timeout = 30000 (production), auth.jwt_expiry = 3600 (development) |
Détails dans Paramètres système et notifications.
Les 26 entités du service
Vue d'ensemble par groupes (détail complet : Modèle de données).
Géographie et devises (5)
Country · Currency · CountryCurrency · City · CountryPaymentMethodType
Transactions (4)
TransactionType · TransactionChannel · AuthorizedChannel · TransactionBetween
Frais (3)
FeeType · TransactionTypeFee · FeeTier
Limites (1)
TransactionLimit
Commissions (2)
CommissionRule · AgentType
Moyens de paiement (1)
PaymentMethodType
Règles inter-pays (2)
CountryTransactionRule · CountryTransactionThreshold
Conformité et KYC (2)
IdentityDocumentType · Profession
Agents et zones (2)
Zone · ActivitySector
Paramètres système (2)
Setting · ServiceConfig
Notifications et services (2)
NotificationChannel · SystemServiceType