Нормализация
NOTE
Статус: Target service boundary. Документ описывает целевую сервисную границу. Код либо полностью отсутствует, либо существует только как scaffold — смотрите секцию «Статус документа» ниже для точного указания на код. Правила маркировки — в
50-processes/documentation-standard.md.
Этот README описывает целевую сервисную границу normalization. Читайте его, когда нужно понять, как сырой поставщиковый payload превращается в внутренний формат supplier offer и observation.
Назначение
Парсинг сырых payload’ов поставщиков в структурированные внутренние сущности с приведением единиц, чисел, алиасов и ошибок в каноническую форму.
Статус документа
- Тип знания:
target service boundary - Статус реализации: отдельный runtime и код сервиса пока отсутствуют
- Текущее место кода: выделенного normalization-кода в репозитории нет; текущий backend ограничен минимальным API-scaffold
- Что читать дальше:
../ingestion/README.md,../matching/README.md,../../10-business/contexts/offers.md
Область действия
Входит:
- Schema-aware парсинг payload’ов.
- Нормализация единиц, диапазонов и чисел.
- Маппинг supplier aliases на внутренние dictionary.
- Валидация значений и публикация нормализованных событий.
Не входит:
- Получение payload’а от поставщика.
- Матчинг к canonical product.
Публичный контракт
Вход
- Потребляет
raw.supplier.<n>.payload.v1.
Выход
- Публикует
offer.normalized.v1,offer.price_changed.v1,offer.stock_changed.v1. - Для неизвестных алиасов может публиковать
moderation.requested.v1.
Внутренняя архитектура
В целевом состоянии normalization состоит из parser pipeline, dictionary lookup слоя и validation rule set. Он должен быть изолирован от connector-specific логики: поставщик задаёт контракт payload, а не внедряет свои правила в ядро.
Зависимости
- Kafka.
- Dictionary/read models из catalog-related подсистем.
- PostgreSQL для supplier offer storage.
Хранилище
- Читает:
supplier_attribute_alias,manufacturer_alias,characteristic,unit,unit_alias. - Пишет:
supplier_offer,supplier_offer_characteristic,supplier_offer_stock.
Конфигурация
| Env var | Default | Описание |
|---|---|---|
NORMALIZATION_DB_DSN | — | PostgreSQL DSN |
NORMALIZATION_KAFKA_BROKERS | — | список брокеров |
NORMALIZATION_LOG_LEVEL | info | уровень логирования |
Локальный запуск
Выделенного процесса normalization в текущем репозитории нет.
Тестирование
- Unit-тесты нужны на parser rules и value normalization.
- Нужны fixture-based contract tests на payload каждого поставщика.
- Нужны integration-тесты на публикацию downstream событий.
Наблюдаемость
В целевом состоянии нужны метрики доли нераспознанных алиасов, числа rejected payload, времени нормализации и числа moderation handoff. Сейчас отдельной observability-поверхности нет.
Открытые вопросы / TODO
- Определить полный набор канонических единиц и коэффициентов.
- Добавить fuzzy-парсер числовых значений.