ADR-0017: Event-driven пересчёт SupplyChainTrace через Kafka
Status: accepted Date: 2026-04-17 Deciders: команда проекта
Контекст
SupplyChainTrace — вычисленный snapshot цепочки supply chain для каждого offer. При изменении графа (Supplier / Role / Relationship / Kind dictionary) — затронутые traces должны пересчитываться. Альтернативы:
- A: По расписанию (раз в N часов).
- B: Lazy при чтении (recalc on demand).
- C: Event-driven через Kafka.
Пользователь явно выбрал C: “по событию изменения, событийная модель через kafka”.
Решение
Event-driven recalc через Kafka.
- Все изменения графа эмитят события в
supplier.graph.events.v1(compacted topic). - Отдельный consumer
supply-chain-recalculatorподписан на топик. - При получении события: определяет затронутые suppliers → находит offers → пересчитывает trace → пишет обновлённое значение → эмитит
SupplyChainTraceRecomputed. - Idempotent (дедупликация по version).
Дополнительно: scheduled rebuilder раз в сутки сравнивает фактические traces с ожидаемыми, исправляет расхождения, алертит при значимых отклонениях (защита от пропущенных событий).
Последствия
Плюсы
- Свежесть trace: обновляется в течение секунд после изменения графа.
- Прозрачность: всё через event log, аудит.
- Совместимость с общей архитектурой (event-driven через Kafka — наша основа).
- Возможность подписки других consumers на эти же события (search-projection, ws-server для realtime админки).
Минусы
- Risk пропущенных событий → mitigated scheduled rebuilder.
- Потенциальная задержка при больших каскадах (изменение semantic_handler глобально → много recalcs) → batch-mode.
- Нужна корректная дедупликация на consumer.
Нейтральные последствия
- Recalcs могут идти параллельно с другими операциями над offers — нужен оптимистический locking или последняя-запись-побеждает на trace JSONB.
Рассмотренные альтернативы
A: Scheduled-only
Отложенное обновление (часы), плохо для актуальности pricing breakdown.
B: Lazy on-read
Latency на горячем пути запросов; нагрузка непредсказуема.
C-альтернатива: Direct call (синхронно из admin при изменении)
Тесная связность admin с supply-chain-recalculator; не масштабируется при больших каскадах; нет аудита через event log.
Ссылки
- ADR-0002 (Kafka).
- ADR-0013 (suppliers as graph).