Контекст: обогащение

NOTE

Статус: Target design. Документ описывает целевую доменную модель. Соответствующий код реализован частично (см. backend/internal/core/) или пока не начат. Правила маркировки — в 50-processes/documentation-standard.md.

Назначение

Дополняет недостающие данные канонического товара: извлекает характеристики из описаний, генерирует/улучшает контент (описание, тэги), создаёт embeddings для семантического поиска. Использует LLM, rule-engines, периодически — оператора.

Enrichment — только источник для Catalog (через события). Он сам не правит canonical напрямую.

Главный смысл

Enrichment предлагает значения с confidence и source, но НИКОГДА не объявляет их critical attribute без явной верификации (manual или multi-supplier consensus). AI-данные не попадают в identity_signature без apply-policy от Catalog.

Агрегаты / сущности / value objects

Имя	Тип	Назначение
EnrichmentTask	🟨 Aggregate	Задача обогащения для конкретного canonical / offer / батча.
EnrichmentResult	VO	Извлечённые поля + confidence + source.
EnrichmentSource	VO enum	llm / rule_calculated / manual / vendor_doc.
LlmModelRef	VO	(model_name, version, prompt_hash) — для воспроизводимости.
EmbeddingVector	VO	Dense vector для семантического поиска.
EnrichmentScope	VO	(target_kind: canonical | offer, target_id, fields[]).
EnrichmentPolicy	E	Конфигурация: какие поля чем обогащать.

Доменные события

Событие	Причина
ЗадачаОбогащенияСоздана (EnrichmentTaskCreated)	Policy: пустые critical attrs / новый canonical
ХарактеристикаОбогащенаAI (CharacteristicEnrichedByAI)	LLM извлёк значение из описания
ЗначениеРассчитано (ValueCalculated)	Rule-engine: например, объём из габаритов
КонтентСгенерирован (ContentGenerated)	Описание / SEO-текст / медиа alt
EmbeddingПостроен (EmbeddingComputed)	Vector для нового описания
ОбогащениеОтклонено (EnrichmentRejected)	Низкая confidence, конфликт с verified value
ВерификацияТребуется (EnrichmentReviewRequired)	Policy: critical attr хочет manual confirm

Команды

Команда	Актор	Целевой агрегат	Результат
СоздатьЗадачуОбогащения (CreateEnrichmentTask)	Policy	EnrichmentTask	EnrichmentTaskCreated
ПрименитьLLMИзвлечение (RunLlmExtraction)	Worker	EnrichmentTask	CharacteristicEnrichedByAI / EnrichmentRejected
ПостроитьEmbedding (ComputeEmbedding)	Worker	—	EmbeddingComputed
ПрименитьПравило (ApplyRule)	Worker	—	ValueCalculated
ОтправитьНаAIПроверку (SendForModeration)	Policy	EnrichmentTask	EnrichmentReviewRequired (publish для Moderation BC)
ПрименитьРешениеМодерации (ApplyModerationDecision)	Moderation BC consumer	EnrichmentTask	CharacteristicEnrichedByAI (accepted) или EnrichmentRejected + ack

Политики

Триггер	Реакция
CanonicalCreated (Catalog) + есть пустые critical attrs	→ CreateEnrichmentTask{kind=extract_critical}
OfferCharacteristicsUpdated (Offers) + новые поля в описании	→ CreateEnrichmentTask{kind=extract_supplementary}
EnrichmentTaskCreated + поля можно посчитать формулой	→ ApplyRule (раньше LLM)
EnrichmentTaskCreated + поля только в тексте	→ RunLlmExtraction
CharacteristicEnrichedByAI + critical attr	→ SendForModeration → AI-агент enrichment_critical_attr_review в Moderation BC
CharacteristicEnrichedByAI + non-critical + confidence ≥ threshold	→ publish событие, Catalog применит без модерации
ProposedAction(AcceptEnrichment) от Moderation	→ ApplyModerationDecision → emit CharacteristicEnrichedByAI для Catalog + ack
ContentUpdated (Catalog)	→ ComputeEmbedding

Read-модели

• 🟩 enrichment_task_queue (PG).
• 🟩 enrichment_history (CH) — для audit и обучения моделей.
• 🟩 embedding_index (Elasticsearch dense_vector / pgvector) — для Search semantic.

Инварианты

1. AI-значения не попадают в identity_signature (см. Catalog invariants).
2. Каждый EnrichmentResult имеет (source, confidence, model_ref) — иначе rejected.
3. Изменение prompt или model_version логируется в LlmModelRef. Производит pre-prod evaluation перед раскаткой.
4. Если новое значение конфликтует с manually verified — EnrichmentRejected + alert.
5. Embedding пересчитывается при изменении description или characteristics canonical’а.

Интеграционные события (публикуем)

Топик: enrichment.events.v1. Partition key: target_id.

Имя	Когда
CharacteristicEnrichedByAI	LLM-извлечение принято (либо напрямую non-critical, либо после Moderation)
ValueCalculated	Правило отработало
ContentGenerated	Сгенерированный текст принят
EmbeddingComputed	Vector готов
EnrichmentReviewRequired	Кейс enrichment_critical_attr_review для Moderation BC
DecisionApplied{case_id}	Ack для Moderation после применения её ProposedAction

Подписанные интеграционные события

Источник	Событие	Реакция
Catalog	CanonicalCreated	Полное обогащение
Catalog	CanonicalCharacteristicsChanged	Embedding rebuild + пересмотр
Offers	OfferCharacteristicsUpdated	Извлечение из новых описаний
Matching	MatchDecided=probable	Embedding similarity как second signal
Moderation	ProposedAction(AcceptEnrichment|RejectEnrichment) для case.kind=enrichment_critical_attr_review	ApplyModerationDecision

Связи в context map

BC	Паттерн	Назначение
Catalog	PL (Enrichment → Catalog)	Публикует CharacteristicEnrichedByAI; Catalog применяет через policy
Search	PL (Enrichment → Search)	Публикует embeddings
Matching	OHS (Matching consumes embedding similarity)	Сигнал для probable
Offers	Customer/Supplier (Offers — supplier)	Слушает изменения товарных канв
Moderation	Customer/Supplier (Enrichment → Moderation, обратно через PL ProposedAction)	Все ручные проверки critical attrs делегированы AI-агентам
Moderation	SK (LlmModelRef)	Общий kernel для model versioning

Мини event storming

flowchart LR
    subgraph C["Catalog"]
        E1["🟧 CanonicalCreated"]
    end
    subgraph EN["Enrichment"]
        P1["🟪 Policy: пустые critical?"]
        CMD1["🟦 CreateEnrichmentTask"]
        T["🟨 EnrichmentTask"]
        E2["🟧 EnrichmentTaskCreated"]
        D1{"🟪 Можно правилом?"}
        CMD2["🟦 ApplyRule"]
        CMD3["🟦 RunLlmExtraction"]
        E3["🟧 CharacteristicEnrichedByAI"]
        E4["🟧 EmbeddingComputed"]
    end
    subgraph M["Matching"]
        SM["🟪 Policy: signal для probable"]
    end
    subgraph S["Search"]
        IDX["🟩 embedding_index"]
    end

    E1 -.PL.-> P1 --> CMD1 --> T --> E2
    E2 --> D1
    D1 -->|да| CMD2
    D1 -->|нет| CMD3
    CMD3 --> E3
    E3 -.PL.-> C
    E3 -.signal.-> SM
    E1 --> CMD3
    CMD3 -.parallel.-> E4
    E4 --> IDX

Связанные файлы

• catalog.md, matching.md, search.md, offers.md, moderation.md.
• ADR (TBD) — LLM provider абстракция.
• Сценарий: ../scenarios/matching-flow.md, ../scenarios/analog-search.md, ../scenarios/ai-moderation-flow.md.