Нормализация спортивных данных: единая модель событий

Одинаковое слово не всегда означает одинаковое состояние

Два поставщика могут одинаково назвать market status, но по-разному трактовать переходы. Поэтому нормализация — не rename полей, а анти-коррупционный слой. Каноническая модель должна описывать смысл, который нужен продукту, и явно хранить «не знаем».

Исходный пакет рядом с нормализованным событием

Сначала сохраняется минимальный raw envelope: provider, sequence, received_at, payload reference/hash. Затем mapping превращает его в каноническое событие. При ошибке нормализации мы можем вернуться к исходному сообщению, а не гадать по обрезанному логу.

Не пытаться впихнуть всё в единое перечисление

Слишком подробная каноническая модель начинает копировать самый сложный provider API. Слишком бедная теряет важную семантику. Практический критерий: поле попадает в core model, если от него зависит продуктовый переход или downstream-контракт. Остальное может жить в provider extension.

Неизвестное значение — валидный технический результат

Mapping не должен молча подставлять ближайший enum. Для нового значения создаётся UNKNOWN с provider_raw_value, событие попадает в отдельный поток наблюдения, а критичная функциональность деградирует безопасно. Это лучше, чем неверная уверенность.

Конфликт в справочнике идентификаторов

Даже корректный enum не спасает, если provider event_id сопоставлен не тому внутреннему событию. ID mapping и semantic mapping контролируются раздельно. Для рискованных автоматических матчей полезна confidence-модель и ручная верификация пограничных случаев.

Где сохранять исходную семантику

Нормализация не должна уничтожать то, что система пока не умеет интерпретировать. Raw envelope или ссылка на исходный payload полезны для разбора спорных статусов, новых типов рынков и расхождений между поставщиками. Каноническая модель отвечает за стабильный контракт продукта, а raw-данные — за возможность проверить перевод.

При появлении нового значения лучше временно вернуть unknown с telemetry, чем молча приравнять его к ближайшему знакомому enum. Так продукт может безопасно ограничить функциональность, а команда увидит масштаб нового случая и добавит осмысленное правило нормализации.

• Версионировать mapping-правила и сохранять источник преобразования.
• Не смешивать identity объекта и отображаемое название.
• Считать долю unknown/unsupported значений по provider и спорту.

Неизвестное значение лучше честного «похожего» маппинга

Поставщик добавил новый status. Самая опасная реакция — автоматически приравнять его к ближайшему знакомому enum и продолжить. Интерфейс будет выглядеть нормально, но продуктовая семантика может оказаться неверной. Безопаснее сохранить raw value, выставить controlled unknown и поднять диагностический сигнал.

EventNormalizer должен быть местом, где такие исключения становятся видимыми. Downstream получает стабильную каноническую модель, а команда может обновить mapping без поиска provider-specific строк по frontend и аналитике.

Fixture set стоит собирать из реальных форм сообщений для разных видов спорта и фаз события. Он особенно ценен во время upgrade provider API: diff показывает не только новые поля, но и изменения значений, которые формально не ломают JSON schema, но меняют поведение продукта.

Сигналы качества фида

Считаются unknown enum, mapping miss, out-of-order sequence и reconciliation diff. Эти метрики описывают качество входных данных. Они не подменяют SLA поставщика, но быстро показывают, где downstream начал получать неполную картину.