ADR-0013: Поставщики как граф

Status: accepted Date: 2026-04-17 Deciders: команда проекта

Контекст

В реальной supply chain поставщик — не атомарная единица:

• Маркетплейсы агрегируют данные от дистрибьюторов.
• Дистрибьюторы перепродают товары многих производителей.
• Один поставщик может предоставлять только API, реальные склады — других юрлиц.
• Производители могут иметь свои API.
• Связи могут быть сложнее: цепочки длиной 3+, эксклюзивные представительства.

Плоская модель Supplier (один источник = один узел) не отражает реальность и не позволяет:

• Находить альтернативные источники одного товара.
• Объяснять структуру цены (наценки на каждом уровне).
• Корректно атрибутировать производителя.
• Применять Visibility Policy по реальному производителю, а не по последнему звену.

Альтернативы:

• A: Плоская модель Supplier.
• B: Иерархия (parent/child одиночная).
• C: Полноценный граф отношений с типизированными ролями и связями.

Решение

Variant C: Supplier как узел графа с типизированными SupplierRole и SupplierRelationship.

• Supplier имеет массив roles[] (api_provider, warehouse_operator, sales_agent, manufacturer, distributor, aggregator, logistics).
• SupplierRelationship соединяет двух suppliers с типом отношения (aggregates, resells, is_agent_of, uses_api_of, uses_warehouse_of, subsidiary_of, exclusive_for).
• Каждый SupplierOffer (и при необходимости observation) содержит вычисленный SupplyChainTrace — snapshot цепочки.
• Отношения вводятся вручную (declared), извлекаются из payload поставщиков (observed), или предлагаются ML/heuristics (inferred с модерацией).

Последствия

Плюсы

• Реалистичная модель: можно описать любую supply chain.
• Возможность выбирать оптимальный источник данных при наличии нескольких уровней credentials.
• Прозрачное pricing breakdown с реальной структурой маржи.
• Правильная атрибуция производителя.
• Visibility Policy и поиск могут работать по реальному manufacturer, а не “видимому” supplier.
• Подготовлено к Phase 6+ (оформление заказов через цепочку, маршрутизация исполнения).

Минусы

• Сложнее модель и UI админки (нужно визуализировать граф).
• Нужен фоновый rebuilder SupplyChainTrace.
• Inferred relationships требуют политики модерации.
• Для простых кейсов (один поставщик = одна цепочка из 1 узла) — лёгкое over-engineering, но компенсируется унифицированной обработкой.

Нейтральные последствия

• Manufacturer и Supplier остаются разными entity (разные грани одного бизнес-субъекта).

Рассмотренные альтернативы

A: Плоская модель

Не описывает реальность. Невозможно сделать pricing breakdown, нельзя различать API-провайдера и реального продавца.

B: Простая иерархия

Не описывает кросс-связи (один маркетплейс агрегирует много дистрибьюторов; один дистрибьютор продаётся через много маркетплейсов).

Ссылки

• ../../10-business/contexts/supplier-network.md
• ADR-0012 (data visibility policy).