Taxonomy

NOTE

Статус: Live (HEAD 5e4ce54, 2026-05-06). BC введён в Cycle 4 (DKC adapter + federated taxonomy, ADR-0050) и работает в production.

Этот README описывает BC taxonomy, отвечающий за federated dictionary классификационных стандартов (ETIM, ECLASS — потенциально в будущем). Читайте, когда нужно понять, как платформа управляет наборами classes/features/values поставщиков-публикантов и как они связываются с canonical-product’ами.

Назначение

Импорт, хранение и обслуживание справочников ETIM/ECLASS-подобных стандартов. Адаптеры поставщиков (DKC сейчас, Systeme/Russvet — потенциально позже) поставляют свои dictionary-снимки; taxonomy BC хранит их под standard_code и связывает с canonical-product’ами через canonical_external_identities.

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

• Тип знания: current service
• Статус реализации: код в backend/internal/core/taxonomy/ + import jobs в cmd/api-server через taxonomy.Module(). supplier-sync использует OtelMetricsModule() отдельно (см. follow-up в tracium_next_session.md).
• Текущее место кода: backend/internal/core/taxonomy/{api,app,domain,infra} + миграции 0050+. Importer запускается фоном через Importer.Run ticker. Federated identities — таблица canonical_external_identities.
• Что читать дальше: ../../20-architecture/adr/0050-dkc-adapter-and-taxonomy.md, ../../20-architecture/adr/0028-federated-identity-taxonomies.md (auto-classification deferred).

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

Входит:

• Импорт классов/features/values ETIM (или ECLASS, когда появится) от поставщиков.
• Хранение taxonomy-снимка per standard_code (versioning через snapshot revision).
• Federated identity attribution: запись canonical_id ↔ (standard_code, class_code) с источником manual | source | auto_llm.
• Manual-protection: ручная привязка модератора не перезаписывается ingestion’ом.

Не входит:

• LLM-присвоение ETIM-class на основе canonical assignments — отдельный auto-classification cycle (deferred). Infra ready, executor не запущен.
• Trust-tier weighting — отдельный механизм в pricing/visibility BC.

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

Вход

HTTP (admin):

• GET /admin/taxonomy/standards — список загруженных standards.
• GET /admin/taxonomy/standards/{code}/classes — классы стандарта.

Background jobs:

• Importer.Run ticker — поднимает таксономии из taxonomy_import_queue (наполняется когда supplier выгружает свой dictionary).

Выход

• Чтение через repo для catalog/canonical при resolve canonical-product → ETIM-class.
• Read-side для admin UI.

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

Clean architecture (api/http/, app/, domain/, infra/pg/).

• domain/standard.go — Standard aggregate (code + revision).
• domain/class.go — Class (code + name + parent).
• domain/identity.go — federated identity (canonical_id ↔ external_code).
• app/Importer — пайплайн импорта (snapshot diff, manual-protect, auto/source guard).
• infra/pg/ — два repo: standards/classes/features/values и identities.

Зависимости

• PostgreSQL — main store.
• DKC adapter — публикует ETIM dictionary snapshot через taxonomy_import_queue.

Хранилище

• taxonomy_standard (revision, supplier_origin)
• taxonomy_class (standard_id, code, parent_id)
• taxonomy_feature (class_id, code, type)
• taxonomy_value (feature_id, code, label)
• canonical_external_identities (canonical_id, standard_code, class_code, source, locked_by_moderator_at)

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

Env var	Default	Описание
TAXONOMY_IMPORT_TICK_INTERVAL	5m	Шаг ticker’а для Importer.Run
TAXONOMY_IMPORT_BATCH_SIZE	500	Размер батча на одно поднятие

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

make local-prod-up

Taxonomy-эндпоинты доступны через api-server. Background Importer — внутри api-server’а.

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

• Unit: go test ./internal/core/taxonomy/...
• Integration: go test -tags=integration ./internal/core/taxonomy/infra/pg/... (testcontainers PG).
• E2E (Cycle 4): C2 taxonomy import scenario — e2e/taxonomy_import_test.go.

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

• Metrics: taxonomy_import_queue_depth, taxonomy_import_runs_total{outcome}, taxonomy_classes_imported_total{standard}.
• Phase logs: taxonomy.import.phase через platform/observability.StartPhase.

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

• Importer.MarkInactive для soft-delete classes при re-import (TODO-маркеры в коде).
• Repo-level integration test для CursorObservationWriter (write-путь покрыт через C1).
• OtelMetricsModule для supplier-sync (fx.Replace, ~1 commit).
• ECLASS-12 importer — federated infra ready; нужен второй стандарт.
• Auto-classification executor — LLM-присвоение ETIM-class.

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

• Бизнес-контекст: ../../10-business/contexts/catalog.md
• ADR: ../../20-architecture/adr/0050-dkc-adapter-and-taxonomy.md, ../../20-architecture/adr/0028-federated-identity-taxonomies.md
• DKC connector: ../ingestion/connectors/... — публикант ETIM-снимков.
• Catalog canonical: ../catalog/ — потребитель federated identities.