Сервис каталога
NOTE
Статус: Target service boundary. Документ описывает целевую сервисную границу
catalog. Правила маркировки — в50-processes/documentation-standard.md.
Этот README описывает сервисную границу catalog. Читайте его, когда нужно понять, как система хранит и управляет каноническими продуктами, характеристиками, производителями и категориями.
Назначение
Управление каталогом канонических продуктов: хранение, поиск, версионирование характеристик и управление идентичностью продуктов.
Статус документа
- Тип знания:
target service boundary - Текущее место кода:
backend/internal/core/catalog/ - Что читать дальше:
canonical-characteristic-value.md,viewable-id.md
Область действия
Входит:
- Хранение и управление canonical products.
- Характеристики продуктов (canonical characteristics).
- Справочники производителей и категорий.
- Назначение человекочитаемых viewable ID.
Не входит:
- Матчинг offer → canonical →
../matching/. - Загрузка сырых данных от поставщиков →
../ingestion/.
Операционное обслуживание
Canonical product должен оставаться уникальным по устойчивой товарной
идентичности. В текущем production-контуре основная детерминированная
сигнатура для supplier offer с артикулом производителя — MPN canonical ID,
который строится из нормализованного manufacturer article. Fallback
supplier|<supplier>|<sku> допустим только пока артикул производителя
неизвестен.
Когда detail-догрев позже приносит manufacturer_article, offer переезжает
на MPN canonical. offers/infra/postgres в этой же транзакции закрывает старый
deterministic supplier fallback, если он стал orphan (active, но без offers):
копирует недостающие characteristic/category assignments на survivor, пишет
canonical_aliases, переводит fallback в replaced, ставит dirty flags для
assignment/embedding и enqueue-ит reconcile.requested для Elasticsearch.
Такие fallback canonical не должны оставаться активными карточками.
Если после догрева данных появились fallback canonical без активных offers,
которые дублируют MPN canonical с тем же нормализованным названием, используйте
backend/cmd/canonical-dedupe-repair:
cd backend
go run ./cmd/canonical-dedupe-repair -scan-offers=250000
go run ./cmd/canonical-dedupe-repair -scan-offers=250000 -applyDry-run печатает план кандидатов. Apply переносит offers на survivor canonical,
копирует отсутствующие characteristic/category assignments, пишет
canonical_aliases, переводит alias canonical в replaced и ставит dirty flags
для canonical_assignment_dirty_canonicals, canonical_embedding_dirty и
catalog_projector_queue.
Если alias canonical содержит несколько разных manufacturer article, repair не сливает весь canonical: это могло бы склеить разные устойчивые товарные идентичности. Вместо этого apply переносит только evidence-offers с текущим MPN в соответствующий MPN canonical, оставляет mixed alias активным для оставшихся offers и ставит dirty flags на обе стороны. Характеристики после такого split не копируются вслепую; assignment/embedding/projector workers должны пересобрать карточки из фактических offers. После apply карточки в админке и Elasticsearch index обновляются через эти очереди.