Чому 0.1 + 0.2 != 0.3, або як ваш код краде гроші бізнесу

💡 Усі статті, обговорення, новини про Python — в одному місці. Приєднуйтесь до Python спільноти!

Це продовження першої частини про Multi-tenancy, RLS та Headless Service Layer у SmartHire.

Модулі, багаторівнева ізоляція та сувора Headless-архітектура — це бетонний фундамент. З таким фундаментом можна спати спокійно, знаючи, що дані клієнтів у безпеці, а база витримає будь-який наплив трафіку.

Але навіть найчистіший код не врятує бізнес, якщо він не вміє рахувати гроші.

У цій частині я розкажу про чотири теми:

• Чому я заборонив float для грошей на рівні лінтера
• Чому webhook’ам від платіжних систем не можна вірити і як я побудував idempotency
• Які 4 метрики у Grafana дозволяють контролювати здоров’я 1000+ ботів
• Zero-downtime deploy без Kubernetes: blue-green на docker + Caddy

Гроші: чому я заборонив float і перейшов на копійки

Якщо у вашій кодовій базі для грошей використовується float або Decimal без чіткої політики — у вас вже є баг. Ви просто його ще не помітили.

Класичний приклад, який має знати кожен:

>>> 0.1 + 0.2
0.30000000000000004
>>> round(2.5)
2  # banker's rounding в Python 3 — сюрприз для тих, хто чекав 3

У мене float для грошей жив у коді певний час. Коли я почав проєктувати reconciliation з банком — зрозумів: рано чи пізно накопичені rounding errors стануть проблемою. Не чекав поки це станеться на реальних грошах — зробив рефакторинг превентивно. ADR-0014 («Money must be int kopecks») з’явився саме після цього рішення.

У SmartHire діє жорстке правило: гроші — це int у мінімальній одиниці валюти. Для UAH — копійки. Для USD — центи. Усі обчислення всередині — цілочисельна арифметика. Конвертація в Decimal або str відбувається тільки на границях системи: при відображенні користувачу або при відправці у webhook платіжного провайдера.

Для відсотків — basis points (1/10000). Комісія 2.5% записується як commission_bp: int = 250. Множення amount_kopecks * commission_bp // 10000 дає точний результат без жодного float.

Money Pydantic-модель — конвертація в копійки

# money.py:21-74
def to_kopecks(amount: int | float | str | Decimal) -> int:
    """Convert amount to integer kopecks (cents) safely."""
    if amount is None:
        msg = "Amount cannot be None"
        raise MoneyError(msg)
    try:
        if isinstance(amount, Decimal):
            decimal_amount = amount
        elif isinstance(amount, str):
            decimal_amount = Decimal(amount)
        elif isinstance(amount, int | float):
            decimal_amount = Decimal(str(amount))  # Float → string first!
        kopecks_decimal = decimal_amount * 100
        return int(kopecks_decimal.quantize(Decimal("1"), rounding=ROUND_HALF_UP))
    except (InvalidOperation, ValueError, TypeError) as e:
        msg = f"Failed to convert amount to kopecks: {amount!r} ({e})"
        raise MoneyError(msg) from e

Ключовий момент: float перетворюється в str перед Decimal — це єдиний безпечний спосіб уникнути накопиченої похибки IEEE 754.

Hypothesis property-based тест

Ось тест який падає на float і проходить на int:

# test_billing_kopecks_hypothesis.py
@given(a=st.integers(0, 10_000_000), b=st.integers(0, 10_000_000))
def test_add_subtract_invariant(a: int, b: int) -> None:
    assert (a + b) - b == a  # Float: 0.1 + 0.2 - 0.2 = 0.10000000000000003
@given(kop=kopecks_strategy)
@settings(max_examples=200, suppress_health_check=[HealthCheck.too_slow], deadline=None)
def test_kopecks_round_trip_via_uah(kop: int) -> None:
    """kopecks → to_uah → to_kopecks must return the original value."""
    uah = to_uah(kop)
    back = to_kopecks(str(uah))
    assert back == kop, f"Round-trip failed: {kop} → {uah} → {back}"

Hypothesis генерує 200 випадкових сум і перевіряє інваріант round-trip. Якщо де-небудь є похибка округлення — тест знайде її за секунди.

Заборона float для грошових типів реалізована як кастомний ruff-rule в core/payments/. Якщо напишете amount: float — pre-commit падає з повідомленням "Money must be int kopecks, see ADR-0014".

Платежі: чому webhook’у вірити не можна

Жоден платіжний провайдер у світі — ні Stripe, ні WayForPay, ні LiqPay — не гарантує exactly-once delivery webhook’а. У SLA пишуть «best effort», «at least once», «до 7 спроб з exponential backoff».

Що це означає на практиці? На дистанції в рік на тисячах транзакцій частина webhook’ів не дійде або прийде двічі. Якщо ваш білінг працює виключно на webhook’ах — ви або недоотримуєте гроші, або нараховуєте подвійні доступи.

Три класичні проблеми:

Дубль webhook’а. Провайдер зробив повтор через timeout на своїй стороні — і платіж зараховується двічі.

Пропуск webhook’а. Ваш сервер перезапустився під час deploy’у, webhook прилетів і отримав 502. Клієнт заплатив, доступу нема.

Підробка webhook’а. Зловмисник POST’ить на ваш /webhook довільний JSON з status: "paid" — і отримує преміум-доступ безкоштовно.

У SmartHire всі три проблеми закриті двома механізмами.

HMAC-верифікація + Redis idempotency

# wayforpay_provider.py:121-147
@staticmethod
def verify_callback_signature(
    data: dict[str, Any], signature: str, secret: str | None = None
) -> bool:
    """Verify WayForPay callback signature."""
    if secret is None:
        from core import config
        secret = config.WAYFORPAY_MERCHANT_SECRET or ""
    try:
        expected = WayForPayProvider._compute_hmac(
            data, WayForPayProvider._CALLBACK_SIGNATURE_FIELDS, secret
        )
        return hmac.compare_digest(expected, signature)  # Timing-safe!
    except (TypeError, ValueError, AttributeError) as e:
        logger.error("Callback signature verification error: %s", e)
        return False

hmac.compare_digest() — обов’язково. Звичайне == вразливе до timing attack: за різницею у часі відповіді можна підібрати підпис побайтово.

# billing_webhook.py:118-143
# Idempotency через Redis:
async with redis_entity_lock("webhook", order_id, ttl_seconds=60):
    claim = await service.claim_webhook_idempotency(
        provider="wayforpay",
        order_id=order_id,
        event_type=event_type,
        tenant_id=tenant_id,
        request_hash=request_hash,
    )
    if claim is None:
        # Already processed — idempotent duplicate
        return web.json_response({"status": "ok", "message": "Already processed"})

Логіка проста: перед обробкою перевіряємо чи вже бачили цей order_id. Якщо так — повертаємо 200 OK без повторної обробки. TTL 60 секунд достатньо для захисту від retry-storm.

Reconciliation як страховка

Webhook — це тільки половина рішення. Друга половина — щоденна reconciliation.

О 9:00 ранку стартує APScheduler-job, який тягне з API WayForPay/LiqPay усі транзакції за минулу добу, порівнює з нашою БД і генерує Excel-звіт з трьома листами:

• Paid — все ОК
• Pending — платіж у банку є, у нас нема (webhook пропущено)
• Розбіжності — суми не сходяться або дублікат

Звіт прилітає оператору в Telegram (див. нижче). Якщо листи Pending і розбіжності пусті — день минув добре.

BillingLifecycle FSM

Стан тенанта — це не функція від webhook’а. Це окремий FSM зі станами та timeout-переходами через APScheduler:

TRIAL → ACTIVE (activate())
ACTIVE → GRACE_PERIOD (payment_fail())
GRACE_PERIOD → PAUSED (grace_expired())
PAUSED → ACTIVE (resume())

Якщо платіж не прийшов до дедлайну — переходимо в GRACE_PERIOD (3 дні), потім PAUSED. Webhook — лише один з тригерів переходу, не єдиний.

Observability: 4 метрики замість двохсот

«Ми додали Prometheus» не дорівнює observability. Питання не в кількості метрик, а в тому, скільки з них ви відкривали минулого тижня. Якщо у вас 200 dashboard’ів і всі вони — graveyard з останнім оновленням півроку тому, у вас немає observability.

У SmartHire є чотири метрики, на які я дивлюсь щоранку:

smarthire_active_tenants — Gauge, кількість тенантів з активністю за останні 24 години. Падіння на цього показника за добу — привід відкрити Sentry.

smarthire_bot_messages_total{tenant_id, module_name} — Counter повідомлень з розбивкою по тенантах і модулях. Якщо один тенант видає 10x навантаження — або у нього успіх, або запустився bot-loop.

smarthire_payments_total{status} — Counter платежів. Якщо status="failed" росте швидше за status="success" — ламається інтеграція з провайдером.

smarthire_db_query_duration_seconds{query_type} — Histogram з OLTP-бакетами. p99 повзе вгору — десь з’явився N+1 або забутий індекс.

Prometheus екпортер з tenant labels

# metrics_exporter.py:70-120
ACTIVE_TENANTS = Gauge(
    "smarthire_active_tenants",
    "Number of currently active tenants",
)
BOT_MESSAGES_TOTAL = Counter(
    "smarthire_bot_messages_total",
    "Total number of bot messages, per tenant and module",
    ["tenant_id", "module_name"],  # ← tenant-aware labels
)
PAYMENTS_TOTAL = Counter(
    "smarthire_payments_total",
    "Total number of payment transactions",
    ["status"],
)
DB_QUERY_DURATION = Histogram(
    "smarthire_db_query_duration_seconds",
    "Duration of database queries in seconds",
    buckets=(0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0),
)
# Використання:
metrics.inc_bot_messages(tenant_id="acme_corp", module_name="ankety")
metrics.inc_payments(status="success")

Tenant-aware labels — ключова деталь. Без них при інциденті незрозуміло: «це у всіх погано чи в одного клієнта?» З ними — за 30 секунд бачиш що проблема в конкретному тенанті.

Окремо про алерти. Поганий алерт — CPU > 80%. Спрацьовує на третій секунді деплою при rolling restart, всі його ігнорують. Хороший алерт — p99 latency > 500ms протягом 5 хвилин AND error rate > 1%. Спрацьовує тільки при справжніх проблемах.

OpenTelemetry traces летять у Tempo, trace_id інжектиться в structlog — у Logtail можна знайти всі логи одного запиту через всю систему. Sentry — тільки для unhandled exceptions, не для warning’ів. Шум вбиває сигнал.

Zero-downtime deploy: blue-green без Kubernetes

Якщо ваш deploy = downtime — у вас немає SaaS. Multi-tenant система мусить оновлюватись без переривання сесій.

Класичний flow, який я переріс: git pull && systemctl restart bot — 30 секунд downtime, користувачі бачать «бот не відповідає».

Зараз це працює через blue-green deploy на рівні docker + Caddy:

1. Збираємо і запускаємо новий контейнер (api-blue або api-green)
2. Чекаємо readiness probe (/readiness) — поки всі залежності не зелені, трафік не переключаємо
3. Чекаємо поки Caddy визначить healthy upstream
4. Переключаємо трафік на новий контейнер
5. Gracefully зупиняємо старий з stop_grace_period=60s

Kubernetes Helm chart з HPA — наступний крок масштабування, не поточна реальність. Але blue-green на docker вже дає zero-downtime для поточного навантаження.

Graceful shutdown handler

# shutdown.py:46-112
async def _wait_for_tasks(self) -> None:
    """Wait for active tasks or cancel after 30s timeout."""
    current_task = asyncio.current_task()
    tasks = [t for t in asyncio.all_tasks() if t is not current_task and not t.done()]
    if not tasks:
        return
    logger.info("Waiting for %s active tasks (max 30s)...", len(tasks))
    _, pending = await asyncio.wait(tasks, timeout=30.0)
    if pending:
        logger.warning("%s tasks did not complete. Forcing cancel.", len(pending))
        for task in pending:
            task.cancel()
async def shutdown(self, sig: signal.Signals | None = None) -> None:
    """Graceful shutdown sequence."""
    if self.is_shutting_down:
        return
    self.is_shutting_down = True
    logger.warning("Received %s. Starting Graceful Shutdown...", sig.name if sig else "Shutdown")
    await self._wait_for_tasks()      # 1. Drain in-flight requests
    await self._close_postgres()       # 2. Close DB pool
    await self._close_redis()          # 3. Close Redis
    logger.info("Graceful Shutdown complete.")

SIGTERM прилітає — маємо 30 секунд на drain: зупиняємо прийом нових запитів, чекаємо завершення активних, закриваємо пули БД і Redis. Якщо за 30 секунд не встигли — SIGKILL. Тому всі довгі операції (reconciliation, batch jobs) запускаються в окремих контейнерах через CronJob, а не у головному боті.

Що я зробив би інакше: чесний розділ про граблі

Стаття без визнання помилок — маркетинговий буклет.

SQLite на старті. Класична пастка — «спочатку MVP, потім мігрую». Міграція на PostgreSQL зайняла більше місяця. Якби починав зараз — Postgres з нульового дня, навіть якщо здається overkill. Невелика економія на старті коштувала місяця роботи.

RLS додав не одразу. Перший час жив на «я ж завжди пишу WHERE tenant_id». Потім зрозумів що покладатись на власну дисципліну — антипатерн. RLS — це не «оптимізація на потім», це базова гігієна з першої міграції.

Float для грошей. Зробив рефакторинг превентивно, не чекаючи реальних розбіжностей у reconciliation. Але якби почав з class Money з першого дня — заощадив би час на рефакторинг.

Idempotency для webhook’ів. Додав на етапі проєктування платіжного модуля, не після інциденту. Але якщо ви ще не додали — додайте зараз, не чекайте першого дублю.

OTEL додав не одразу. Якби починав зараз — OpenTelemetry з першого тижня, навіть якщо здається, що проєкт ще маленький.

Висновок: п’ять речей, які забрати з собою

Якщо немає часу на весь текст вище — ось summary:

Float для грошей — баг за визначенням. int у копійках, basis points для відсотків, Decimal тільки на границях системи. Перевіряється кастомним lint-rule.

Webhook ≠ source of truth. Жоден провайдер не гарантує exactly-once delivery. HMAC + idempotency на вході, щоденна reconciliation з API банку як страховка, окремий FSM для стану білінгу — три механізми які закривають всі сценарії.

Observability — це 4 метрики на які реально дивишся, а не 200 dashboard’ів яких ніхто не відкривав. Tenant-aware labels обов’язково — інакше при інциденті незрозуміло де шукати.

Zero-downtime можливий без Kubernetes. Blue-green на docker + Caddy + readiness probe вже дає deploy без переривання сесій.

Починайте з вибору правильних інструментів для масштабу задачі. Postgres замість SQLite, RLS з першої міграції, Money як int з першого рядка — це не overkill, це інвестиція яка окупається через місяць.

Якщо є досвід з фінансовою інженерією в Python або альтернативні підходи до idempotency — буду вдячний за коментарі.

Репозиторій SmartHire — приватний, але архітектурні рішення та showcase доступні на GitHub.

Підписуйтесь на LinkedIn — там анонсую наступні частини.