Перейти к основному содержимому

Suppliers Layer — Поставщики, source boundaries и управление внешней реальностью

Версия: 2.0
Дата: 23.04.2026
Статус: Готов к обсуждению

Назначение документа​

Этот документ фиксирует suppliers layer не как набор технических адаптеров для XML, REST или GraphQL, а как полноценный платформенный контур управления внешними поставщиками данных и поставщиками продукта.

Его задача — определить:

  • какие роли вообще играют поставщики в платформе;
  • какие типы supplier-ов бывают;
  • что именно считается supplier reality;
  • где проходит граница между supplier truth и canonical truth;
  • как строить supplier relationships, intake модели, reliability policy и update discipline;
  • как suppliers layer связан с ingestion, storage, offers, booking и governance.

Иначе говоря, этот документ отвечает на вопрос не "как написать очередной адаптер", а "как промышленная travel-платформа должна обращаться с внешними поставщиками как с отдельной управляемой средой".

Опорные документы​

Что Второй Несущий Круг Требует От Suppliers Layer​

После появления второго круга документов suppliers.md уже нельзя считать просто хорошим документом о source boundaries и ingestion-facing работе.

Теперь suppliers layer обязан явно удерживать:

Практический вывод:

suppliers layer должен описывать не только подключение внешнего мира, но и правила того, как внешняя реальность может или не может становиться видимой, обещаемой и транзакционно значимой внутри платформы.

Что Исправляет Новый Подход​

Старый вариант документа описывал suppliers layer почти исключительно как:

  • набор адаптеров;
  • FTP/XML или GraphQL интеграции;
  • отправку данных в очередь;
  • кодовые примеры для отдельных поставщиков.

Это полезно как черновой инженерный материал, но недостаточно для реальной платформы.

Проблема не в том, что адаптеры не нужны. Проблема в том, что поставщик в реальной платформе — это не только формат данных. Это одновременно:

  • бизнес-отношение;
  • источник внешней правды;
  • источник ограничений и нестабильности;
  • источник цен, доступности и policy drift;
  • источник operational incidents;
  • источник contractual obligations и SLA-рисков.

Новый подход поднимает suppliers layer на правильный уровень:

  1. сначала типы поставщиков и их роль;
  2. затем supplier truth boundaries;
  3. затем ingestion and operational model;
  4. только потом адаптеры, transport и polling mechanics.

Что Такое Suppliers Layer В Контексте Платформы​

Suppliers layer — это контур, в котором платформа взаимодействует с внешней реальностью travel supply.

Именно здесь платформа сталкивается с тем, что:

  • внешний мир имеет разные форматы;
  • внешний мир меняется без предупреждения;
  • разные источники дают противоречивые данные;
  • availability, pricing и policies живут по разным ритмам;
  • не каждый поставщик одинаково надёжен;
  • supplier contract и supplier behavior — не одно и то же.

Задача suppliers layer — не растворить эти различия, а сделать их управляемыми.

Главный Принцип Suppliers Layer​

Платформа не должна подстраивать своё ядро под случайную форму данных поставщика, но и не должна притворяться, что все поставщики эквивалентны.

Из этого следуют два обязательных вывода:

  • supplier-specific reality должна сохраняться как trace и учитываться как отдельный слой истины;
  • canonical model платформы должна формироваться поверх supplier layer, а не быть прямым зеркалом одного из поставщиков.

Из этого также следует:

  • supplier limitation должна уметь становиться explicit platform constraint;
  • supplier freshness не должна маскироваться под platform certainty;
  • supplier booking behavior должен отражаться в booking promises and pending states;
  • supplier anomaly может блокировать publication, а не только создавать внутренний лог.
  • supplier commercial volatility должна уметь становиться explicit repricing or quote-invalidation trigger.

Роль Поставщиков В Платформе​

Поставщики играют разные роли. Это нужно фиксировать явно.

1. Content Suppliers​

Это источники относительно стабильного контента:

  • описания;
  • атрибуты;
  • amenities;
  • адреса;
  • геоданные;
  • медиа;
  • policies на уровне контентного слоя.

Эти данные могут быть важны для canonical content, но почти никогда не должны безусловно считаться финальной operational truth для booking-time decisions.

2. Inventory And Availability Suppliers​

Это источники динамической доступности и product availability.

Для них характерно:

  • высокая изменчивость;
  • короткий горизонт актуальности;
  • зависимость от окна запроса;
  • потенциальные расхождения между кэшем и live reality.

3. Pricing Suppliers​

Это источники pricing signals:

  • base rates;
  • taxes and fees inputs;
  • cancellation-related pricing implications;
  • dynamic pricing changes.

Такие поставщики критичны для offer/quote flows, но их truth почти всегда требует freshness discipline.

Для них особенно важно различать:

  • source price как supplier economics;
  • данные, влияющие на normalization;
  • поля, которые участвуют в commercial rule output;
  • изменения, которые должны приводить к repricing;
  • изменения, которые меняют settlement basis даже если visible price не поменялась.

4. Booking Suppliers​

Это поставщики, через которых происходит real booking placement, confirmation, cancellation or amendment.

Для них особенно важны:

  • booking state synchronization;
  • idempotency and retry behavior;
  • confirmation latency;
  • error semantics;
  • support and reconciliation readiness.

5. Meta-Suppliers And Derived Sources​

Это агрегаторы, каналы-посредники, внешние каталоги, рейтинговые источники, enrichment providers и иные external data contributors.

Они могут давать valuable signals, но их нельзя автоматически считать authoritative по всем полям.

Типология Supplier-ов По Модели Взаимодействия​

Поставщиков нужно различать не только по бренду, но и по способу жизни данных.

1. Batch Feed Suppliers​

Они дают:

  • file-based выгрузки;
  • периодические snapshots;
  • массивные bulk updates;
  • delayed freshness.

Такие поставщики хорошо подходят для content-heavy and catalog-heavy ingestion, но хуже для real-time transactional guarantees.

2. Pull API Suppliers​

Они дают:

  • REST/GraphQL/SOAP/XML APIs;
  • запросы по расписанию;
  • выборочную синхронизацию;
  • on-demand fetch patterns.

Их поведение сильно зависит от rate limits, timeout profile и качества их contract discipline.

3. Push / Webhook Suppliers​

Они дают:

  • event-driven updates;
  • near-real-time signals;
  • уведомления об изменениях;
  • потенциально неполную или out-of-order event delivery.

Их нельзя использовать без replay and reconciliation strategy.

4. Live Booking Interaction Suppliers​

Они нужны не только для data ingest, но и для transactional operations.

Для них обязательны:

  • confirm/cancel/amend semantics;
  • request deduplication;
  • booking correlation model;
  • support escalation path.

Supplier Reality И Source Boundaries​

Платформа должна чётко различать несколько уровней правды.

Supplier Truth​

Это то, что поставщик сообщил или разрешил получить на своём уровне.

Она может быть:

  • полезной;
  • частично устаревшей;
  • неполной;
  • противоречивой;
  • пригодной для одного домена и непригодной для другого.

В коммерческом контуре это означает, что supplier truth может быть достаточной:

  • для indicative price projection;
  • для normalized base price;
  • для repricing trigger;

но недостаточной:

  • для quoted commercial promise без нужной policy application;
  • для platform settlement truth без downstream interpretation.

Canonical Platform Truth​

Это уже управляемая модель платформы, сформированная после:

  • normalization;
  • mapping;
  • merge;
  • precedence rules;
  • governance decisions.

Operational Transaction Truth​

Это правда конкретного transactional момента:

  • offer snapshot;
  • quote validity;
  • booking submission result;
  • supplier confirmation state.

Нельзя путать supplier truth с operational transaction truth только потому, что оба пришли из внешнего мира.

Supplier Layer И Ingestion Layer​

Suppliers layer и ingestion layer тесно связаны, но это не одно и то же.

Suppliers Layer Отвечает За​

  • supplier connectivity;
  • supplier identity and configuration;
  • source-specific fetch strategies;
  • auth and access to external sources;
  • schedule and intake mode;
  • source reliability view;
  • supplier-level policy and constraints.

Ingestion Layer Отвечает За​

  • raw trace capture;
  • normalization;
  • matching and mapping;
  • merge and precedence;
  • anomaly detection;
  • governance handoff;
  • canonical update logic.

Практический Вывод​

Suppliers layer поставляет управляемую внешнюю реальность во вход ingestion. Он не должен сам по себе решать final canonical merge, но и ingestion не должен делать вид, что supplier behavior для него неважен.

То же самое верно для коммерческого контура:

  • suppliers layer не определяет final visible price платформы;
  • но он обязан поставлять signal-ы, от которых зависят repricing, quote validity и settlement divergence handling.

Supplier Identity And Configuration​

Для промышленной платформы каждый поставщик должен быть формализован как управляемый субъект, а не как набор секретов в конфиге.

Для Каждого Поставщика Нужно Фиксировать​

  • supplier key and display identity;
  • supplier type;
  • intake modes;
  • supported data domains;
  • auth model;
  • environment separation;
  • rate and concurrency constraints;
  • freshness expectations;
  • precedence hints;
  • operational owner внутри платформы;
  • support/escalation path;
  • SLA or expected response profile;
  • contractual notes and known limitations.

Это должно жить как часть persistent supplier model, а не только в коде адаптера.

Supplier Capability Model​

Не каждый поставщик одинаково полезен по всем направлениям. Поэтому платформе нужен supplier capability model.

Поставщик Может Быть Сильным В​

  • content;
  • images;
  • geo accuracy;
  • amenities richness;
  • pricing timeliness;
  • availability freshness;
  • booking confirmation speed;
  • cancellation support;
  • amendment support;
  • market coverage.

Поставщик Может Быть Слабым В​

  • структурной стабильности payload-ов;
  • rate limit discipline;
  • error transparency;
  • reliability of webhooks;
  • coverage consistency;
  • completeness of policies.

Это нужно не только для аналитики. Это влияет на precedence, governance and operational trust.

После фиксации коммерческого контура это также влияет на:

  • допустимость supplier price как базы для quoted promise;
  • aggressive или conservative repricing policy;
  • volume of publication-safe price exposure;
  • trust level для booking-time financial expectations.

Supplier Economics And Commercial Boundaries​

После фиксации Commercial Model — Коммерческая модель, цена, settlement и канальные условия suppliers layer обязан явно различать supplier economics и platform commercial reality.

Supplier Economics Может Включать​

  • raw base amount;
  • taxes and fees inputs;
  • cancellation penalties;
  • occupancy-driven changes;
  • currency-specific behavior;
  • booking-time surcharges or operational add-ons.

Что Нельзя Делать​

  • считать supplier-returned amount финальным platform promise;
  • считать любое изменение supplier price автоматически publishable наружу;
  • смешивать supplier penalties с platform-visible fee semantics;
  • подменять supplier settlement inputs quoted commercial promise.

Что Suppliers Layer Должен Уметь Сигнализировать​

  • price drift requiring repricing;
  • policy drift affecting quote validity;
  • booking-side economic change affecting settlement basis;
  • supplier limitation that blocks safe publication of a price view.

Publication Boundary Discipline​

Поставщики не должны напрямую определять, что именно публикуется наружу как offer, quote или booking-facing promise.

Suppliers Layer Должен Поддерживать​

  • supplier-side freshness signals;
  • capability-aware publication constraints;
  • flags for unsafe or low-confidence price/availability states;
  • quarantine or holdback for suspicious supplier updates;
  • explicit downstream signal when new data should trigger revalidation or repricing rather than immediate publication.

Практический Вывод​

Если supplier change не прошёл нужную commercial, governance or operational интерпретацию, он не должен превращаться в внешне видимую цену просто потому, что “данные уже приехали”.

Что Commercial Model Требует От Suppliers Layer​

После фиксации коммерческого слоя suppliers layer обязан удерживать:

  • различие между supplier price input и platform-visible price;
  • supplier-driven причины repricing;
  • supplier-driven причины settlement divergence;
  • surface-aware ограничения на публикацию monetary data;
  • traceability supplier economics для support, dispute and reconciliation сценариев.

Supplier Intake Models​

Suppliers layer должен поддерживать несколько intake моделей как first-class citizens.

Scheduled Batch Intake​

Подходит для:

  • catalog snapshots;
  • static content;
  • heavy bulk feeds;
  • overnight or periodic sync.

Incremental Pull Intake​

Подходит для:

  • selective updates;
  • region-based sync;
  • entity-based refresh;
  • targeted retries.

Event-Driven Intake​

Подходит для:

  • supplier notifications;
  • booking status callbacks;
  • urgent changes;
  • near-real-time delta feeds.

On-Demand Live Fetch​

Подходит для:

  • revalidation;
  • booking-time checks;
  • exception resolution;
  • support tooling.

Один и тот же поставщик может использовать несколько intake моделей одновременно. Это нужно считать нормой, а не исключением.

Supplier Data Domains​

Нужно различать, какие именно домены данных приходят от поставщика.

Stable Or Semi-Stable Domains​

  • property identity;
  • descriptions;
  • amenities;
  • address and geography;
  • media;
  • general policies.

Volatile Domains​

  • availability;
  • base prices;
  • taxes and fees inputs;
  • restrictions by date/occupancy;
  • booking feasibility;
  • cancellation windows with time sensitivity.

Transactional Domains​

  • booking create response;
  • booking confirmation;
  • booking failure;
  • cancellation confirmation;
  • amendment outcomes;
  • reference identifiers.

Эта классификация напрямую влияет на:

  • sync frequency;
  • storage class;
  • replay policy;
  • truth policy;
  • client-facing disclosure.

Freshness And Update Discipline​

Платформа не может обращаться со всеми supplier updates одинаково.

Для Suppliers Layer Нужно Явно Определять​

  • expected update cadence;
  • acceptable staleness;
  • revalidation triggers;
  • retry policy;
  • fallback behavior;
  • degradation mode при supplier outage.

Примеры Правильного Различения​

  • content feed раз в 24 часа может быть нормальным;
  • pricing feed раз в 24 часа для quote/booking сценариев уже недостаточен;
  • booking callback delay может быть допустим в одних supplier-моделях и критичен в других;
  • image sync и booking confirmation живут по принципиально разным SLA.

Reliability, Health And Operational Trust​

Для каждого поставщика платформа должна формировать не только техническое соединение, но и operational trust profile.

Нужно Измерять​

  • availability of endpoint/feed;
  • response latency;
  • payload validity rate;
  • rate-limit hit rate;
  • parse failure rate;
  • schema drift frequency;
  • anomaly rate;
  • booking confirmation delay;
  • reconciliation failure rate.

Зачем Это Нужно​

  • для routing and precedence decisions;
  • для alerting;
  • для supplier quality governance;
  • для правильных fallback policies;
  • для будущих partner/customer guarantees.

Supplier-Specific Constraints И Contract Boundaries​

Поставщики всегда приносят ограничения. Их нужно не прятать, а делать explicit.

Ограничения Могут Быть Такими​

  • low rate limits;
  • expensive live checks;
  • delayed confirmation;
  • coarse-grained location data;
  • unstable IDs;
  • weak cancellation semantics;
  • partial data coverage;
  • inconsistent taxes presentation;
  • environment mismatch between sandbox and production.

Supplier Layer Должен Делать Это Видимым​

  • ingestion and governance;
  • offer and quote logic;
  • booking flow;
  • internal operations;
  • partner/customer-facing promise boundaries.

Publication Boundary Discipline​

Платформа не должна публиковать supplier-derived changes downstream только потому, что они были успешно получены.

Supplier layer обязан быть способен:

  • задержать публикацию сомнительного delta;
  • передать в governance сигнал о manual review requirement;
  • уважить manual_lock или precedence restriction;
  • сообщить downstream контурам, что supplier data доступна только как limited-confidence signal.

Нельзя строить platform contract так, будто все поставщики одинаково предсказуемы.

Supplier Normalization Boundary​

Suppliers layer не должен сам превращать всё в финальную canonical model, но он обязан поставить ingestion-слою материал в управляемой source-aware форме.

Это Означает​

  • supplier-specific raw trace сохраняется;
  • source metadata не теряется;
  • важные external IDs и supplier references сохраняются;
  • transport and source context прикрепляются;
  • supplier semantics не уничтожаются чрезмерной ранней унификацией.

Иначе платформа потеряет возможность объяснять, откуда взялись конкретные поля или почему возник конфликт.

Supplier Layer И Storage​

Suppliers layer должен быть согласован с моделью хранения из Storage Layer — Модель хранения и жизненный цикл данных.

  • supplier registry;
  • supplier configs and environment bindings;
  • source credentials references;
  • sync runs;
  • supplier payload refs;
  • normalized supplier entities;
  • source mapping references;
  • health and quality metrics snapshots;
  • booking-side supplier correlation references.

Что Не Должно Жить Только В Runtime​

  • знание о последней успешной синхронизации;
  • supplier-specific capability profile;
  • supplier health history;
  • critical correlation identifiers;
  • retry/reconciliation context для важных процессов.

Supplier Layer И Booking Domain​

Поставщики особенно критичны в booking path.

Нужно Различать​

  • supplier that provides searchable content;
  • supplier that provides bookable offer;
  • supplier that is final merchant or booking processor;
  • supplier that returns eventual confirmation;
  • supplier that owns cancellation decision.

В некоторых случаях это может быть один и тот же субъект. В некоторых — нет. Платформа должна выдерживать обе модели.

Практический Вывод​

Booking flow нельзя проектировать так, будто supplier — это только upstream catalog. Для transactional reality supplier often is a stateful counterparty.

Supplier Layer И Governance​

Governance в платформе касается не только canonical data, но и supplier quality.

Governance-Действия По Supplier Layer Могут Включать​

  • marking supplier field as low-trust;
  • changing precedence policy;
  • quarantining problematic feeds;
  • forcing manual review for certain supplier domains;
  • pausing publication of suspicious deltas;
  • reviewing booking-side incident patterns;
  • adjusting fallback behavior.

Это делает suppliers layer частью управляемой платформы, а не пассивной интеграционной трубы.

Supplier Layer И API / Client Surfaces​

Suppliers layer не должен напрямую протекать в public API, но обязан влиять на contract semantics.

Через Что Это Проявляется​

  • freshness hints in offer responses;
  • revalidation requirements;
  • partner-specific coverage differences;
  • booking pending states;
  • partial availability disclosure;
  • support tooling visibility;
  • degraded mode behavior при supplier outages.

Клиентские и партнёрские поверхности не обязаны видеть supplier internal mechanics, но они должны честно отражать последствия этих mechanics.

Supplier Consequences Must Be Surface-Aware​

Одно и то же supplier limitation может по-разному проявляться в разных surface-ах:

  • internal operations должны видеть supplier identity, anomaly patterns и detailed constraints;
  • agency workspace должен видеть explainable freshness, revalidation and pending semantics;
  • partner API должен получать contract-safe visibility без внутреннего operational мусора;
  • B2C/presentation surfaces должны получать только честные последствия, а не сырой supplier noise.

Adding New Suppliers​

Подключение нового поставщика должно считаться не только инженерной задачей, но и платформенным решением.

Перед Подключением Нужно Понять​

  • какие домены данных он реально даёт;
  • насколько стабилен его contract;
  • есть ли booking support или только catalog support;
  • какова его freshness profile;
  • насколько прозрачно он возвращает errors and policies;
  • каков его identity strategy;
  • есть ли sandbox и насколько он похож на production;
  • какова стоимость retry/live revalidation;
  • нужен ли для него special governance mode.

После Подключения Нужно Зафиксировать​

  • supplier model;
  • intake strategy;
  • storage strategy;
  • monitoring profile;
  • anomaly policy;
  • precedence hints;
  • publication constraints;
  • booking/reconciliation implications.

Что Должно Быть Перепроверено После Этого Документа​

После фиксации новой supplier-логики нужно пересмотреть:

Роль Старых Черновиков​

Старый вариант документа полезен как архив ранних инженерных идей:

  • примеры адаптеров;
  • мысли о Stuba/HomeToGo;
  • transport patterns;
  • scheduler and retry sketches;
  • технические наброски по мониторингу.

Но его больше нельзя считать актуальным основанием, потому что он:

  • сводил suppliers layer к adapter implementation;
  • почти не различал supplier roles и data domains;
  • не фиксировал source boundaries;
  • слабо связывал suppliers layer с booking, governance и truth policy.

Старый текст сохранён в архивной версии:

Текущий Практический Вывод​

Suppliers layer в vitiana-api-platform должен мыслиться как управляемый слой внешней реальности: с типологией поставщиков, source boundaries, capability profile, reliability model, freshness discipline и booking-aware operational semantics.

Практически это означает:

  • supplier не равен просто формату данных;
  • адаптер — это лишь часть supplier model;
  • canonical platform truth строится поверх supplier truth, а не вместо неё;
  • supplier limitations должны явно влиять на offers, quotes, booking and client promises;
  • новые поставщики должны подключаться как управляемые платформенные субъекты, а не как случайные коннекторы.

Связанная Документация​

Уточнение под Фазы 4–6 (28.04.2026) — связь с правилом 00000, ingestion, governance​

Документ опубликован 23.04.2026 (Фаза 3). Suppliers layer — критическая точка правила 00000. После Фаз 4–6 интеграция требует фиксации.

Главный принцип — правило 00000​

development/Закон 00000 — платформа главенствует над поставщиками.md применяется напрямую:

  • поставщики — точка входа данных, не архитектурный ориентир;
  • любой поставщик отключаем без переделки ядра;
  • captive integrations (для одного supplier в общем коде) запрещены;
  • supplier capability profile — operational characteristic, не структурный приоритет;
  • Stuba — первый поставщик, не mainstream supplier; HomeToGo и все следующие — равноправные.

Связь с ingestion layer​

reference/ingestion.md — operational interface для supplier work. Этот документ описывает что есть supplier; ingestion — как их данные попадают в каноничную модель. Не путать.

Связь с governance​

reference/data-governance-and-matching.md — governance over supplier integrity:

  • supplier-specific anomaly detection;
  • supplier suppression при degradation (см. runbooks-incident-playbooks);
  • supplier capability changes — governance review;
  • mapping supplier entities to canonical — explicit MappingDecision per supplier.

Связь с tenant isolation​

reference/multi-tenant-isolation-strength.md (Фаза 5):

  • supplier credentials — per-tenant scoped (если supplier обслуживает только конкретного tenant);
  • supplier data — общая для tenants (canonical model unified), но access — tenant-scoped;
  • per-supplier reliability metrics могут быть partner-visible через analytics.

Связь с security architecture​

reference/security-architecture.md (Фаза 10) — supplier security:

  • Supplier credentials — secret class с automated rotation 90 дней;
  • Supplier signature verification — для production webhooks через HMAC;
  • Supplier-induced threats — T (Tampering), S (Spoofing): supplier может прислать malicious data; mitigation через input validation + governance review.

Связь с booking state machine​

reference/booking-state-machine.md (Фаза 5) — supplier critical для transitions:

  • supplier confirmation flow → pending_supplier_confirmation → supplier_confirmed;
  • supplier timeout → unknown_external_state (target SLI < 1%);
  • supplier-side cancellation propagation;
  • supplier-side amendment processing.

Supplier reliability метрика напрямую влияет на SLI 6 (unknown_external_state ratio).

Связь с supplier health prediction (ML)​

reference/ml-platform.md — ML use case supplier_health_prediction:

  • features: supplier response time distribution, error rate, unknown_external_state rate;
  • output: predicted supplier degradation;
  • triggers: governance review, automated rate limiting.

Связь с runbooks — supplier degradation​

operations/runbooks-incident-playbooks.md (Фаза 6) — incident class 1: Supplier degradation:

  • detection: anomaly metrics + ML predictions;
  • runbook: investigate supplier health → temporary suppress → governance decision → recovery;
  • escalation: SRE → Engineering Manager → Director.

Связь с api-as-product partner classes​

reference/api-as-product.md (Фаза 4) — partner class vs supplier:

  • partner потребляет платформу (downstream);
  • supplier поставляет данные (upstream);
  • эти роли не пересекаются в каноничной модели (один tenant может быть и partner для downstream и платформа для upstream — но это две разные сущности с разными credentials).

Связь с relation-to-implementation-baseline​

overview/relation-to-implementation-baseline.md — текущая реализация в home-to-go-api:

  • Stuba module — first adapter, в production;
  • HomeToGo HTG API — research stage, second supplier coming;
  • adapter pattern enforced — оба supplier через separate modules.

Каноничный итог уточнения​

Suppliers layer остаётся точкой входа данных, без архитектурных привилегий. Реализация:

Уточнение выполнено через no-destruction.