Мультивалютні каталоги

(Розділ: Операції та Управління)

1) Завдання і область застосування

• коректну вітрину цін (UX, довіра),
• відтворюваність розрахунків (аудит, повернення),
• економічну передбачуваність (маржа/податки),
• комплаєнс (оподаткування, санкції, обмеження валют).

2) Модель даних (референс)

• 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; напр. JPY = 0, USD/EUR = 2, KWD = 3; для crypto - до 8)
• `rounding_mode`: 'HALF _ UP'( роздріб),'BANKERS'( фінанси),'FLOOR '/' CEIL'( податки/регулятори)

3) Джерела та політика FX (курсів валют)

Джерела: провайдери курсів (комерційні/центробанки), власний TWAP/медіана.
Політика оновлення: частота (1-15 хв для волатильних, 1 раз/день для стабільних), затримка публікації.
Маркапи: 'rate (1 + fx_markup_bps)'на бік клієнта; прозорі правила per-канал/регіон.
Гарантоване вікно котирування (rate lock): 5-30 хв з'fx _ version'в замовленні.
Анти-стрибок: кап зміни за тік, circuit-breakers, fallback на останню валідну котирування.
Версіонування: кожна публікація курсів має «version», «effective _ from»; зберігайте історію для повернення/суперечок.

4) Стратегії ціноутворення

Base + FX: зберігати базову ціну в «ядрі» (наприклад, EUR), конвертувати на вітрині.
Per-currency листи: заздалегідь розраховані ціни для ключових валют (кращий UX, передбачуваність).
Mixed: топ-10 валют - передрозрахунок, «довгий хвіст» - on-the-fly.
Charm-pricing: `X. 99/95/90'по регіону, контролюйте накопичення помилок округлення.
Комісії/збори: payment fee, cross-border fee, network fee (crypto) - в каталозі або на етапі «Checkout Pricing».

5) Податки і «включеність»

VAT/GST включений/виключений: EU - частіше VAT-inclusive; B2B може бути без ПДВ.
Верстви податків: федеральний/штат/місцевий; для онлайн-ігор - специфічні збори.
Порогові ставки: податок змінюється від обороту/категорії/регіону (threshold).
Округлення податків: per-item vs per-basket; режими заокруглення і порядок обчислень повинні бути детерміновані.
Юр. звітність: зберігайте'tax _ rule _ version'в чеку/квитанції.

6) Округлення і точність

Округлюйте на останньому кроці показу; в розрахунках зберігайте «високу точність» (до 8-9 знаків).
Для crypto використовуйте decimal-бібліотеки (без двійкової плаваючої).
Анти-дрифт кошика: «bankers rounding» для сум, але UX-округлення для відображення; фіксуйте'rounding _ scope'.
Правило суми: сума построчних після округлень повинна збігатися з total - використовуйте розподіл останніх копійок/центів (penny distribution).

7) Каталоги, промо і бандли

Promo-правила: `if region=A and currency in [EUR,USD] then discount=10% cap=50`.
Порядок застосування: (1) базова ціна → (2) знижки → (3) податки → (4) збори → (5) округлення.
Bundle-розподіл: пропорційно вкладці позицій до знижки; враппер для повернень.
Threshold-промо: безкоштовна доставка/бонус при total≥X у валюті кошика; зберігайте еквівалент у базовій валюті, але фіксуйте версію FX.

8) Інтеграція з платежами та комплаєнсом

Валютна доступність: не кожна валюта доступна кожному гравцеві/регіону/провайдеру платежів.
Guaranteed FX: префікс-авторизація за зафіксованим'fx _ version'; при експірації - запит підтвердження нової ціни.
КУС/санкції: блок-листи валют/банків/токенів, обмеження на конвертацію.
Повернення/chargeback: перерахунок за історичним'fx _ version'замовлення; комісія повернення - за каталогом на дату транзакції.

9) Архітектура і контракт 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}'→ квитанція з хешем і підписами.

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

10) Кешування і продуктивність

Edge-кеш: ключ'pricelist:region:currency:sku:version`; TTL для стабільних валют вище.
Warmup: прогрівши топ-категорій по запуску кампанії.
SWR (stale-while-revalidate): для вітрин; checkout - тільки fresh.
Partial invalidation: інвалідація за тегами «sku», «category», «pricelist _ version».
SLO: p95 ≤ 120 мс для вітрини, p95 ≤ 250 мс для quote, ≥99. 95% доступності.

11) Спостережуваність і аудит

Трасування: 'trace _ id','pricelist _ version','fx _ version','tax _ rule _ version'у всіх подіях.
Іммутабельність: WORM-журнали публікацій прайс-листів/курсів; Merkle-зрізи, підписи релізів (DSSE).
Receipts: чек/квитанція з повним розкладом і хешем корисного навантаження; зберігати 7-10 років (за регулятором).
Дашборди: розбіжність vitrina↔checkout, частота округлень «вгору/вниз», помилки FX, час блокування курсу (lock TTL), ROI промо.

12) Локалізація відображення

Формат валюти: символ/код (₴, €, $, AED), позиція символу, роздільники, пробіл.
Локальні правила: «₴ 1 234,56» vs “$1,234. 56”.
Психологія: магічні цінники ('.99') не завжди доречні у фінтех/іграх; тестуйте per-регіон.
Юридичні підписи: «Ціна включає ПДВ», «Комісія мережі стягується окремо».

13) Особливі випадки

Валюти без дробової частини: JPY/ISK — minor_units=0.
Тризнакові minor units: KWD/BHD=3.
Крипто: BTC/ETH/USDT - до 8 знаків, network fee окремо; stablecoins ≠ "курс 1:1" при крос-бордері.
Подвійна ціна: «валюта каталогу» ≠ «валюта списання» (банківський курс мерчанта). Документуйте spread.
Спорт/ігри: ліміти на максимальні виграші у валюті каталогу - зберігати еквіваленти по'fx _ version'раунду.

14) SLO/SLI і метрики успіху

Коректність: частка замовлень, де total_checkout = total_quote (± 1 minor unit при правилах розподілу) ≥ 99. 99%.
Стабільність FX: частка операцій у вікні rate lock ≥ 99%.
Економіка: маржа/одиницю vs план; відхилення через FX/округлень (bps).
UX: швидкість quote p95, частка відвалів на перерахунку ціни, NPS вітрини.
Аудит: 100% чеків зі збереженими'_ version'і підписом.

15) Плейбуки інцидентів

1. freeze кеш-інвалідатори, 2) примусовий refresh прайс-листа, 3) порівняти'pricelist _ version '/' fx _ version', 4) компенсація по політиці.

1. включити підвищений markup/кап знижок, 2) скоротити lock TTL, 3) переключитися на fallback-джерело.

1. перевірити'tax _ rule _ version', 2) валідація rounding_scope, 3) hotfix правил і репрайс кошиків.

1. захисні правила (min_price), 2) відключити стікання, 3) recalculation і аудит.

16) Безпека та комплаєнс

Policy-as-code: контроль змін прайс-листів/FX/податків через PR + підписи релізів.
Ролі/доступи: 4-очний принцип на публікації цін/FX.
Логи/квитанції: підписані події публікацій і checkout.
Регіональні обмеження: заборона окремих валют/токенів; гео-політики.

17) Експерименти та оптимізація

A/B: charm-pricing, передрозраховані ціни vs on-the-fly, формат відображення.
Динамічний markup: залежність від волатильності пари/часу доби.
Когортний аналіз: повернення/chargeback по валютах, чутливість до округлення.
Кеш-стратегії: вплив SWR/TTL на конверсію і точність.

18) Чек-лист впровадження

• Визначити базову валюту і політику per-currency листів.
• Налаштувати збір/публікацію FX з версіонуванням, маркапами і lock TTL.
• Формалізувати TaxRule і порядок обчислень/округлень (per-item або per-basket).
• Реалізувати API каталогу/quote/commit + підписані квитанції.
• Включити edge-кеш і гранулярну інвалідацію; SWR для вітрин.
• Завести дашборди (vitrina↔checkout, FX помилки, податки, маржа bps).
• Ввести ролі/підписи на публікації цін/курсів, WORM-журнали.
• Підготувати плейбуки: несхід ціни, стрибок FX, податкові неузгодження.
• Провести «GameDay каталогу»: відключення джерела FX, промо-бурст, зміна податку.
• Регулярно ревізувати minor_units/отображение по регіонах.

19) FAQ

Чи потрібно зберігати ціни в кожній валюті?
Не обов'язково. Комбінуйте передрозрахунок для топ-валют і конверсію для «хвоста» - так балансуються UX і витрати.

Чому total після округлень «не б'ється»?
Через відмінності per-item vs per-basket. Зафіксуйте один підхід і використовуйте «penny distribution».

Як робити повернення через місяць?
За історичними'pricelist _ version','fx _ version'і'tax _ rule _ version', збереженим в квитанції.

Що з crypto?
Використовуйте decimal-точність, network fee окремо, не обіцяйте 1:1 до фіату; фіксуйте курс і вікно дії.

Резюме: Мультивалютний каталог - це поєднання точної математики, строгих політик і розумного кешування. Версіонуйте все (ціни/курси/податки), фіксуйте вікно котирування, детермінуйте порядок обчислень і округлень, підписуйте чек-артефакти і тримайте дашборди видимими. Так ви отримаєте чесну вітрину, відтворювані розрахунки і керовану економіку у всіх валютах і регіонах.