Ядро каталога

NOTE

Статус: Target service boundary. Документ описывает целевую сервисную границу. Код либо полностью отсутствует, либо существует только как scaffold — смотрите секцию «Статус документа» ниже для точного указания на код. Правила маркировки — в 50-processes/documentation-standard.md.

Этот README описывает целевую сервисную границу catalog-core. Читайте его, когда нужно понять, где живут canonical products, классификаторы и event-sourced изменения каталога.

Назначение

Управление Canonical Product, характеристиками, производителями и Identity Profile, включая применение событий к агрегатам и публикацию изменений наружу.

Статус документа

• Тип знания: target service boundary
• Статус реализации: отдельный runtime и модуль catalog-core пока отсутствуют
• Текущее место кода: выделенного каталожного кода нет; в репозитории есть только базовый scaffold backend/cmd/api-server и backend/internal/httpserver
• Что читать дальше: ../../10-business/contexts/catalog.md, ../../20-architecture/event-sourcing.md, ../matching/README.md

Область действия

Входит:

• CRUD canonical products и словарей.
• Event sourcing для ключевых каталожных агрегатов.
• Публикация изменений через outbox/Kafka.
• Поддержка read-model для чтения каталожных сущностей.

Не входит:

• Матчинг supplier offer к canonical product.
• AI-обогащение контента.
• Поисковая индексация и ранжирование.

Публичный контракт

Вход

• Административные команды на управление canonical products и dictionary.
• События вроде offer.normalized.v1 и matching.decided.v1, которые могут влиять на каталог.

Выход

• Каталожные доменные события через canonical.events.v1.
• Read-model обновления для поиска, enrichment и связанных сервисов.

Внутренняя архитектура

В целевом состоянии catalog-core — ядро с event-sourced агрегатами и отдельными read-model. Техническая раскладка должна следовать ../../20-architecture/module-layout.md, а решение об event sourcing — ../../20-architecture/event-sourcing.md.

Зависимости

• PostgreSQL как primary store и event store.
• Kafka/outbox для публикации событий.
• Административный API и matching как upstream/downstream участники потока.

Хранилище

• event_store, snapshot_store, outbox.
• Read-model таблицы canonical entities и dictionary.
• Финальный состав таблиц должен фиксироваться в ../../20-architecture/schemas/postgres/README.md.

Конфигурация

Пока это целевой сервис; точный состав env-переменных будет определён вместе с реализацией. Базовые ожидания:

Env var	Default	Описание
CATALOG_CORE_DB_DSN	—	PostgreSQL DSN
CATALOG_CORE_KAFKA_BROKERS	—	список брокеров
CATALOG_CORE_LOG_LEVEL	info	уровень логирования

Локальный запуск

Выделенного процесса catalog-core в текущем репозитории нет. Локально можно поднять только инфраструктуру и минимальный API-scaffold:

make infra-up
make web-up

Тестирование

• Для будущей реализации обязательны unit-тесты агрегатов и команд.
• Нужны integration-тесты на event store, outbox и проекции.
• Стратегия тестирования и ограничения по мокам — в ../../50-processes/testing-strategy.md.

Наблюдаемость

В целевом состоянии нужны метрики по обработке команд, публикации событий, lag проекций и конфликтам версий. Сейчас отдельной observability-поверхности у catalog-core нет.

Открытые вопросы / TODO

• Спроектировать safe-merge canonical products.
• Спроектировать split canonical products.
• Определить стратегию rematch после изменения identity profile.

Связанные документы

• ../../10-business/product-identity.md
• ../../20-architecture/event-sourcing.md
• ../matching/README.md