Catalogues multi-devises

(Section : Opérations et gestion)

1) Tâche et domaine d'application

• une vitrine correcte des prix (UX, confiance),
• reproductibilité des calculs (audit, retours),
• prévisibilité économique (marges/impôts),
• conformité (fiscalité, sanctions, restrictions monétaires).

2) Modèle de données (référence)

• Product/SKU: `{sku_id, title, attributes, region_policies[]}`
• PriceList: `{pricelist_id, base_currency, effective_from, effective_to, version}`
• PriceItem: `{sku_id, base_price, base_currency, tax_class, pricing_model, promo_refs[]}`
• FXRate: `{pair: EUR→USD, rate, source, method, precision, effective_from, version}`

• `minor_units` (ISO 4217; Par exemple JPY = 0, USD/EUR = 2, KWD = 3 ; pour crypto - jusqu'à 8)
• 'Rounding _ mode ':' HALF _ UP '(détail),' BANKERS '(finances),' FLOOR '/' CEIL '(impôts/régulateurs)

3) Sources et politiques FX (taux de change)

Sources : fournisseurs de cours (banques commerciales/centrales), propre TWAP/médiane.
Politique de renouvellement : fréquence (1-15 min pour les volatiles, 1 fois/jour pour les stables), publication retardée.
Markaps : 'rate (1 + fx_markup_bps)' côté client ; règles transparentes par canal/région.
Fenêtre de devis garantie (rate lock) : 5-30 min avec 'fx _ version'dans la commande.
Anti-saut : changements de cap pour le teck, circuits-breakers, fallback à la dernière cotation validée.
Versioning : chaque publication de cours a « version », « effective _ from » ; conserver l'historique pour les retours/différends.

4) Stratégies de tarification

Base + FX : stocker le prix de base dans le « noyau » (par exemple, EUR), convertir sur la vitrine.
Feuilles per-currency : prix calculés à l'avance pour les devises clés (meilleur UX, prévisibilité).
Mixed : le top 10 des monnaies est prévisionnel, la « longue queue » est on-the-fly.
Charm-pricing: `X. 99/95/90 'par région, contrôler l'accumulation des erreurs d'arrondi.
Commissions/frais : payment fee, cross-border fee, network fee (crypto) - dans le catalogue ou à l'étape « Checkout Pricing ».

5) Taxes et « inclusions »

TVA/TPS incluse/exclue : UE - plus souvent TVA inclusive ; B2B peut être hors TVA.
Catégories d'impôts : fédéral/État/local ; pour les jeux en ligne - frais spécifiques.
Taux de seuil : la taxe change de chiffre d'affaires/catégorie/région (threshold).
Arrondir les impôts : per-item vs per-basket ; les modes d'arrondi et l'ordre de calcul doivent être déterministes.
Yur. déclaration : stockez 'tax _ rule _ version' dans le chèque/reçu.

6) Arrondis et précision

Arrondir à la dernière étape de l'affichage ; dans les calculs, conservez la « haute précision » (jusqu'à 8-9 caractères).
Pour crypto, utilisez la librairie decimal (sans flottant binaire).
Panier anti-dérive : « bankers rounding » pour les montants, mais arrondi UX pour l'affichage ; fixez 'rounding _ scope'.
Règle du montant : la somme des arrondis après construction doit correspondre au total - utilisez la distribution des derniers centimes/cents (distribution penny).

7) Catalogues, promos et bandles

Promo-правила: `if region=A and currency in [EUR,USD] then discount=10% cap=50`.
Procédure d'application : (1) prix de base → (2) rabais → (3) taxes → (4) frais → (5) arrondis.
Distribution groupée : proportionnelle à l'onglet des articles avant le rabais ; un intrus pour les retours.
Threshold-promo : livraison gratuite/bonus à la total≥X dans la devise du panier ; gardez l'équivalent dans la devise de base, mais fixez la version FX.

8) Intégration avec les paiements et la conformité

Disponibilité des devises : toutes les devises ne sont pas disponibles pour chaque joueur/région/fournisseur de paiement.
Guaranteed FX : préfixe d'autorisation par 'fx _ version'fixé ; lors de l'exportation - demande de confirmation du nouveau prix.
CUS/sanctions : listes des devises/banques/tokens, restrictions de conversion.
Retours/chargeback : recalculer sur l'historique 'fx _ version' de la commande ; frais de retour - par catalogue à la date de la transaction.

9) Architecture et contrat API

• `GET /catalog/prices? sku=…¤cy=…®ion=…&pricelist=…`
• Ответ: `{unit_price, currency, fx_version, pricelist_version, tax_breakdown[], fees[], display_price, rounding_mode}`

• `POST /pricing/quote { items[], region, currency, buyer_type }`
• Ответ: `{items_priced[], subtotal, discounts, taxes[], fees[], total, fx_version, lock_ttl, signature}`

• 'POST/pricing/commit {quote_id, signature} '→ reçu avec le hachage et les signatures.

• `PriceListUpdated`, `FXRatePublished`, `TaxRuleChanged`, `PromoChanged` — с `version/effective_from`.

10) Mise en cache et performances

Cache Edge : clé 'pricelist : region : currency : sku : version' ; TTL pour les devises stables est plus élevé.
Warmup : échauffement des catégories supérieures pour lancer la campagne.
SWR (stale-while-revalidate) : pour les vitrines ; checkout - seulement fresh.
Invalidation partielle : invalidation par les étiquettes 'sku', 'category', 'pricelist _ version'.
SLO : p95 ≤ 120 ms pour la vitrine, p95 ≤ 250 ms pour quote, ≥99. 95 % de disponibilité.

11) Observation et audit

Trace : 'trace _ id', 'pricelist _ version', 'fx _ version', 'tax _ rule _ version' dans tous les événements.
Immutabilité : Journaux WORM des publications des listes de prix/cours ; Merkle-tranches, signatures de sortie (DSSE).
Receipts : chèque/reçu avec l'alignement complet et le hachage de la charge utile ; garder 7-10 ans (selon le régulateur).
Dashboards : écart de vitrina↔checkout, taux d'arrondi « haut/bas », erreurs FX, temps de verrouillage du cap (TTL), ROI promo.

12) Localisation de l'affichage

Format de monnaie : symbole/code (₴, €, $, AED), position du symbole, séparateurs, espace.
Règles locales : "₴ 1 234,56" vs "1,234 $. 56”.
Psychologie : les étiquettes de prix magiques ('.99') ne sont pas toujours appropriées dans les jeux/fintech ; tester par région.
Signatures légales : « Le prix comprend la TVA », « La commission du réseau est facturée séparément ».

13) Cas particuliers

Devises non fractionnaires : JPY/ISK - minor_units=0.
Unités mineures à trois parties : KWD/BHD = 3.
Crypto : BTC/ETH/USDT - jusqu'à 8 caractères, réseau fee séparément ; stablecoins ≠ « cours 1-1 » en cross-border.
Double prix : « monnaie du catalogue » ≠ « monnaie de la passation par profits et pertes » (taux de change bancaire du merchant). Documenter le spread.
Sport/jeux : limites pour les gains maximaux dans la monnaie du catalogue - stocker les équivalents de 'fx _ version' du tour.

14) SLO/SLI et métriques de succès

Exactitude : proportion de commandes où total_checkout = total_quote (± 1 unité mineure aux règles d'allocation) ≥ 99. 99%.
Stabilité FX : la part des opérations dans la fenêtre de lock rate est ≥ 99 %.
Économie : marge/unité vs plan ; déviations dues à FX/arrondis (bps).
UX : vitesse quote p95, part de détournement sur le prix calculé, vitrines NPS.
Audit : 100 % des chèques avec '_ version' et signature enregistrés.

15) Pleybooks d'incidents

1. freeze cache invalidants, 2) forcer la liste de prix refresh, 3) comparer 'pricelist _ version '/' fx _ version', 4) compensation par politique.

1. activer les rabais markup/cap, 2) réduire la TTL lock, 3) passer à la source fallback.

1. vérifiez 'tax _ rule _ version', 2) la validation des règles rounding_scope, 3) hotfix et le reprix des paniers.

1. règles de protection (min_price), 2) désactiver l'empilement, 3) recalculation et audit.

16) Sécurité et conformité

Policy-as-code : contrôle des modifications des listes de prix/FX/taxes via les signatures PR + des versions.
Rôles/accès : Principe à 4 yeux sur la publication des prix/FX.
Logs/reçus : événements de publication signés et checkout.
Restrictions régionales : interdiction de certaines monnaies/tokens ; la géopolitique.

17) Expérimentation et optimisation

A/B : charm-pricing, prix préqualifiés vs on-the-fly, format d'affichage.
Markup dynamique : dépendance à la volatilité du couple/heure de la journée.
Analyse de cohorte : retours/chargeback par devises, sensibilité à l'arrondi.
Stratégies de cache : impact de SWR/TTL sur la conversion et la précision.

18) Chèque de mise en œuvre

• Définir la monnaie de base et la politique per-currency des feuilles.
• Personnaliser la collecte/publication FX avec versioning, markaps et lock TTL.
• Formaliser TaxRule et l'ordre des calculs/arrondis (per-item ou per-basket).
• Implémenter l'API catalogue/quote/commit + reçus signés.
• Inclure le cache edge et l'invalidité granulaire ; SWR pour vitrines.
• Faire des dashboards (erreurs de vitrina↔checkout, FX, impôts, marge bps).
• Entrez les rôles/signatures sur les publications de prix/cours, les revues WORM.
• Préparer les playbooks : pas de prix, bond de FX, accord fiscal.
• Réaliser « Catalogue GameDay » : désactivation de la source FX, bourst promotionnel, changement de taxe.
• Revigorer régulièrement les minor_units/otobrazheniye par région.

19) FAQ

Dois-je garder les prix dans chaque devise ?
Pas forcément. Combinez le prépaiement pour les principales monnaies et la conversion pour la « queue » - c'est ainsi que l'UX et les coûts sont équilibrés.

Pourquoi total après les arrondis « ne bat pas » ?
En raison des différences per-item vs per-basket. Fixez une approche et utilisez « distribution penny ».

Comment faire un retour dans un mois ?
Selon l'historique 'pricelist _ version', 'fx _ version' et 'tax _ rule _ version'enregistrés dans le reçu.

Qu'en est-il de crypto ?
Utilisez la précision decimal, réseau fee séparément, ne promettez pas 1:1 à fiat ; fixez le cap et la fenêtre d'action.

Résumé : Le catalogue multi-devises est une combinaison de mathématiques exactes, de politiques strictes et de mise en cache intelligente. Versez tout (prix/cours/taxes), fixez la fenêtre de cotation, déterminez l'ordre des calculs et des arrondis, signez les artefacts de contrôle et gardez les dashboards visibles. C'est ainsi que vous obtiendrez une vitrine honnête, des calculs reproductibles et une économie gérée dans toutes les monnaies et régions.