Tracium

время чтения ~10 мин.

Глоссарий

Единый источник определений доменных и технических терминов. Если термин используется в документации в формате Term (bold) или Term — он должен быть здесь.

При изменении определения — только через PR с обсуждением.

Структура: тематические группы вместо плоского списка. Если термин логично относится к нескольким группам, он живёт в одной и упоминается ссылкой из смежных.

Оглавление

Каталог и товары

Canonical Product

Наша единая нормализованная единица товара. Агрегирует характеристики, контент (описание, фото, видео) и связи. Источник истины для поиска и формирования смет. Не путать с Supplier Offer.

Identity Profile

Шаблон, описывающий, какие характеристики являются критическими для определения идентичности товара. Применяется предикатом (matcher) к набору характеристик товара. Приходит на смену привязке к категории. См. 10-business/product-identity.md.

Critical Attribute

Характеристика, изменение значения которой создаёт новый Canonical Product в рамках данного Identity Profile. Противоположность — некритические атрибуты (цвет упаковки, страна производства).

Identity Signature

Хэш от (manufacturer, mpn, identity_profile_id, {critical_attributes}). Уникальный идентификатор канонического товара в системе.

Equivalence Class

Группа канонических товаров, взаимозаменяемых по критическим характеристикам (с учётом правил типа “не хуже чем”). Отличается от идентичности: это “решают ту же задачу”, не “тот же товар”.

Lifecycle Status

Статус Canonical Product: new / active / deprecated / discontinued / replaced_by.

Characteristic

Определение атрибута: ключ, тип значения, единица измерения, правила валидации. Хранится в классификаторе.

Unit

Единица измерения с размерностью и коэффициентом перевода к канонической единице размерности. Позволяет унифицировать значения (“50мм” = “5см”).

Better Direction

Атрибут Characteristic в контексте поиска аналогов: указывает, в какую сторону “лучше” — higher (например, мощность), lower (например, потери), neutral (равноценно — требуется точное совпадение). Используется фильтром “не хуже чем”.

Kind Dictionary

Расширяемый БД-словарь типов (например, supplier_role_kind, supplier_relationship_kind). Каждая запись имеет code + display_name + semantic_handler (известная коду семантика). См. ADR-0016.

Semantic Handler

Машинное значение в Kind Dictionary, определяющее, как код обрабатывает данный kind. Известные значения для supplier_role_kind: MANUFACTURER, WAREHOUSE_OPERATOR, API_PROVIDER, SALES_AGENT, DISTRIBUTOR, AGGREGATOR, LOGISTICS, GENERIC. Для supplier_relationship_kind: AGGREGATES, RESELLS, IS_AGENT_OF, USES_API_OF, USES_WAREHOUSE_OF, SUBSIDIARY_OF, EXCLUSIVE_FOR, GENERIC.

Raw Supplier Payload

Сырой ответ от API поставщика, сохраняемый иммутабельно в объектном хранилище. Основа для replay парсинга и для аудита.

Supplier Offers и наблюдения

Supplier Offer

Нормализованное предложение конкретного поставщика — товарная канва (характеристики, mpn, lifecycle, медиа, упаковка). НЕ содержит цены и остатки — те живут в Supplier Offer Observation, привязанной к конкретной Supplier Credential. Связано с Canonical Product через матчинг с определённой степенью уверенности (Match Confidence).

Supplier Offer Observation

Наблюдение цены, остатков и условий по конкретной паре (SupplierOffer, SupplierCredential). Append-only: каждый fetch создаёт новое observation. Текущее = самое свежее.

Match Confidence

Уровень уверенности в привязке offer к canonical: exact / strong / probable / weak / unmatched. Влияет на то, может ли offer автоматически попасть в смету.

Orphan Offer / Orphan Pool

Supplier Offer, не привязанный ни к одному Canonical Product (нет матча достаточной уверенности). Хранится в orphan pool — очереди на классификацию (AI или ручная модерация) и/или на создание нового canonical. Не участвует в результатах поиска до резолюции.

Rematching

Повторный матчинг существующих offers против canonical-каталога, инициированный изменением Identity Profile, появлением нового canonical, или новой версии характеристик. Не идемпотентен по времени: вчерашний probable сегодня может стать exact.

Matching Engine

Подсистема, привязывающая supplier offer к canonical product. Работает в трёх режимах: детерминированный, эвристический, ML/LLM.

Normalization

Приведение сырых данных поставщика к внутреннему формату: парсинг единиц, маппинг атрибутов, нормализация производителя.

Connector

Модуль, реализующий интерфейс connector.Connector ядра и обеспечивающий получение данных от конкретного поставщика. Плагин к ядру. См. 30-services/ingestion/connectors/AGENTS.md.

Ingestion

Процесс получения данных от поставщика: fetch → raw storage → parse → normalize → emit event.

Enrichment

Процесс обогащения canonical product дополнительными данными (характеристики из описаний через LLM, медиа, сертификаты) с отметкой источника.

EnrichmentJob

Унифицированный async job к поставщику: discovery, refresh_observation, refresh_characteristics, rebuild_supply_chain, full_catalog, etc. Дедуплицируются и троттлятся.

Async Supplier Job

Длительная задача у поставщика (генерация отчёта, выгрузка прайса). У нас — отдельная сущность с polling’ом.

Поставщики (сеть)

Supplier (network node)

Узел графа поставщиков. Имеет kind, массив roles[] (api_provider, warehouse_operator, sales_agent, manufacturer, distributor, aggregator, logistics), trust_level, опциональный api_endpoint и connector_ref.

SupplierRole

Одна из ролей supplier’а. Например, ETM имеет роли api_provider, sales_agent, distributor, warehouse_operator одновременно.

SupplierRelationship

Направленное ребро графа поставщиков. kind: aggregates, resells, is_agent_of, uses_api_of, uses_warehouse_of, subsidiary_of, exclusive_for. Может быть declared, observed (из payload поставщика), или inferred (ML/heuristics).

SupplyChainTrace

Вычисленная snapshot цепочки supply chain для конкретного offer / observation: observed_via, api_provider, sales_agent, distributor, warehouse_operators, manufacturer, chain_depth.

Trust Level

Атрибут supplier: origin (производитель напрямую) > tier_1 (официальный дистрибьютор) > tier_2 (агрегатор / переторговщик) > unverified. Фиксированный enum (расширение через ADR). Влияет на conflict resolution и приоритет в ML.

Credentials

Supplier Credential

Учётная запись доступа к API поставщика. Имеет Credential Scope (system или customer), Auth Schema (формат: login_password, api_key, oauth2, bearer_token, custom). Секретные поля шифруются app-level encryption. Связана с Customer для customer-scope.

Credential Scope

system — наша системная учётка у поставщика (для catalog discovery, B2C, fallback в pricing). customer — учётка клиента, переданная клиентом для работы от его имени.

Auth Schema

Формат авторизации credential. Расширяемый. Стартовый набор: login_password, api_key, oauth2, bearer_token, custom.

Credential Fingerprint

Стабильный hash от стабильных полей auth_payload для конкретной auth_schema. Используется для дедупликации.

Supplier Credential Group

Группа credentials с одинаковым fingerprint (= одна учётка у поставщика, используемая разными клиентами). Опрашивается через primary credential один раз; observations доступны всем members.

Credential Routing

Стратегия выбора credential для конкретного типа запроса. Pricing для customer X → его credential или group → fallback на системную; catalog discovery → round-robin по всем active credentials.

Pricing и сметы

Price Rule

Функция, преобразующая базовую цену в финальную с учётом контекста (количество, тип клиента, регион, специальные соглашения). Логистическая стоимость — тоже price rule особого типа.

Pricing Mode

Режим ценообразования offer: fixed (цена известна) или on_request (индивидуальная цена по запросу). Не путать с Customer Pricing Group — это разные концепции.

Customer Pricing Group

Группа клиентов, объединённая общими Price Rules: b2c_retail, b2b_standard, b2b_contract_<id>, partner_<name>_tier_<n>. Один customer — одна базовая customer_pricing_group + опциональные временные промо-группы. Не путать с Pricing Mode (атрибут offer).

Custom Pricing Handler

Plugin-расширение для Pricing engine. Применяет ценовые правила, когда API поставщика их не возвращает (например, договорная скидка офлайн). Регистрируется через HandlerRegistration с trigger_condition. Выполняется в sandbox с SLA 50 мс. См. 10-business/contexts/pricing.md.

Pricing Adjustment

Возврат от Custom Pricing Handler — список дополнительных Price Rules для применения в общей цепочке.

Estimate / Смета

Документ-запрос клиента на набор позиций с количествами. Мета-поиск превращает грязный estimate в оптимизированный с привязанными supplier offer’ами.

Estimate Version

Иммутабельная версия Estimate. Любое изменение пользователем создаёт новую версию; старые сохраняются для аудита и replay.

Customer Type

individual (физлицо, B2C) или legal_entity (юрлицо, B2B). Определяет применение price rules и UX.

ILP / MIP Optimizer

Optimization solver на базе Integer Linear Programming (Mixed Integer Programming) для сборки оптимальной сметы при размере ≤ N позиций (стартовое значение N=200, конфигурируемо). Для бóльших смет используется greedy-эвристика. См. 10-business/scenarios/estimate-end-to-end.md.

Модерация и AI

Moderation Queue

Очередь кейсов для AI-агентов Moderation BC (не для людей). Содержит: probable/weak match, orphans, inferred SupplierRelationships, AI-extracted critical attributes, price rule overlaps, credential group candidates, ИНН-edge cases, manufacturer alias proposals. Реализуется через топик moderation.events.v1 + автоматический pipeline (gather → LLM → validate → emit ProposedAction). Человек подключается только при escalation. См. 10-business/contexts/moderation.md.

Moderation Case

Кейс модерации с lifecycle queued → analyzing → decided → applied / escalated. Атомарная единица работы AI-агента.

Case Kind

Категория Moderation Case — определяет AgentRunner, prompt template, evidence query, output schema, threshold. Стартовый набор: match_review, orphan_resolution, inferred_relationship_review, enrichment_critical_attr_review, priority_overlap_review, credential_group_candidate, legal_info_verification_edge, manufacturer_alias_proposal, identity_profile_proposal.

Agent Runner

Конфигурация AI-агента per Case Kind: model_ref, prompt template, tools (function calling), evidence query, JSON output schema, confidence threshold, SLA latency, escalation policy. Версионируется; изменения требуют pre-prod evaluation на 200 ранее resolved кейсов.

Agent Decision

Возврат AI-агента: (verdict, confidence ∈ [0,1], reasoning, citations[], proposed_action). Output принудительно валидируется JSON schema перед применением.

Proposed Action

VO команды для source BC, опубликованной Moderation BC. Source BC consumer применяет через ApplyModerationDecision и подтверждает DecisionApplied{case_id} ack-loop.

Case Escalation

Переход кейса на человека. Триггеры: confidence < threshold, повторные AgentRunFailed, circuit breaker сработал, case.kind ∈ security_critical (для последних — всегда human, AI только анализатор).

LLM Sandbox

Изолированная среда запуска модерационного LLM-вызова: temperature=0, timeout 30 сек, no network outside whitelisted RAG, no creds, redact PII в logs/responses. Гарантирует детерминизм и privacy.

Data Visibility

Data Visibility Policy

Правило управления видимостью данных. Содержит subject (кому), target_kind (что фильтруется), effect (allow / deny / transform), predicate (DSL). Применяется во всех точках выдачи данных. См. ADR-0012.

Visibility Predicate DSL

Язык описания условий применимости policy. Поддерживает логические операторы (and/or/not), сравнения (eq/in/between/…), специальные операции (matches_tag, characteristic_eq, …).

Visibility Transform

Тип effect, не отбрасывающий запись, а изменяющий её: redact_field, price_to_range, hide_warehouse, round_value, и т.д.

Архитектурные принципы

No-proxy architecture

Архитектурный принцип: мы не транзитный шлюз к поставщикам. Клиентские запросы получают данные только из нашего хранилища. Все запросы к поставщикам — в фоновых задачах (scheduled / async on-demand). Клиентский ответ никогда не блокируется ожиданием поставщика. См. ADR-0011 + ADR-0014.

Graceful degradation

Принцип ответа на основе имеющихся данных: при отсутствии — “не найдено” + async DiscoveryJob; при stale — возвращаем с пометкой + async RefreshJob; при partial — возвращаем что есть с пометкой “incomplete”. SLA на ответ и SLA на свежесть — независимые.

Multi-protocol API

Архитектурное решение: внешний API экспонируется тремя протоколами (REST, gRPC, WebSocket) поверх общего ядра use cases. См. ADR-0015.

Subscription Channel

В WebSocket API — типизированный канал подписки клиента (entity_changes, price_updates, stock_updates, estimate_updates, enrichment_job, discovery_results).

Cache + Actualize + Watch

Унифицированный паттерн API: read cache (текущее состояние из хранилища) + trigger refresh (создание EnrichmentJob) + watch updates (подписка на изменения). Доступен на всех трёх протоколах.

DDD-паттерны

Bounded Context

Граница согласованности модели: внутри — единый язык, снаружи — другой. Tracium разложен на 12 BC; см. 10-business/domain-model.md.

Context Map

Карта отношений между Bounded Contexts: какие из них взаимодействуют и через какие DDD-паттерны (ACL, PL, OHS, SK, Conformist, Customer/Supplier).

Anti-Corruption Layer (ACL)

DDD-паттерн: контекст изолирует свою модель от внешней «грязной» модели через слой перевода. В Tracium Matching — ACL между Offers и Catalog.

Published Language (PL)

DDD-паттерн: контекст публикует стабильную схему интеграционных событий, на которые подписываются другие BC. Все Kafka-топики Tracium — PL.

Open Host Service (OHS)

DDD-паттерн: контекст предоставляет стабильный API нескольким потребителям (например, Credentials → Ingestion + Pricing через CredentialContext).

Shared Kernel (SK)

DDD-паттерн: маленький общий kernel из VO, разделяемый между BC (SupplyChainTrace, SessionContext, Money, CredentialContext). Изменение требует RFC.

Domain Event

Факт, произошедший в прошлом (past tense). Внутри BC — для согласования агрегатов; через границу BC — Integration Event.

Integration Event

Доменное событие, опубликованное в Kafka для подписки другими BC. Контракт описан в ../20-architecture/schemas/events/.

Event Storming

Метод моделирования: визуально раскладывает домен через события (orange), команды (blue), агрегаты (yellow), policies (pink), read models (green), actors (brown). Используется в domain-model.md (Big Picture).

Shared Kernel VOs

Session Context

Shared Kernel VO, передаваемый Customer’ом во все downstream BC после login: (customer_id, customer_type, pricing_group, roles, session_id). Используется как Subject в Visibility, как ключ в Pricing cache.

Credential Context

Shared Kernel VO, выдаваемый Credentials BC для опроса API: (credential_id, scope, customer_id?, secret_ref, rate_limit_bucket, warehouse_scope). Connector работает только с этим VO, не с самим SupplierCredential aggregate.

Инфраструктурные паттерны

Event Sourcing

Паттерн хранения состояния агрегата как последовательности иммутабельных событий. Применяется для canonical product и manufacturer dictionary. Не применяется для цен/остатков.

Snapshot

Сохранённое состояние агрегата на определённой версии, используется для ускоренного восстановления без проигрывания всех событий.

Outbox Pattern

Паттерн, обеспечивающий транзакционную публикацию событий: запись события в таблицу outbox в той же транзакции, что и изменение состояния; отдельный процесс публикует события из outbox в Kafka.

Rate Budget

Политика ограничения частоты запросов к внешнему поставщику, конфигурируемая per-connector. Реализуется через Redis token bucket.

Blue-Green Index

Паттерн для Elasticsearch: два индекса (_v7, _v8), alias переключается на новый после завершения реиндексации.

Вид графа

Обратные ссылки