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

Закон 00000 — платформа главенствует над поставщиками

Версия: 1.0 Дата: 25.04.2026 Статус: Утверждён

⚠ Высший приоритет. Этот закон действует поверх Свода законов ИИ и любых других правил. При конфликте с любым другим правилом или формулировкой архитектурного документа — этот закон побеждает.

Зафиксирован 25.04.2026 прямым указанием владельца платформы. Имеет высший приоритет в архитектурных решениях vitiana-api-platform.

Главный тезис​

Платформа Vitiana — глобальный агрегатор верхнего уровня (top-tier global aggregator) с собственными поставленными целями.

Поставщики (Stuba, HomeToGo и сотни возможных в будущем) — это точка входа информации (data ingress point), а не архитектурный ориентир.

Зависимость:

  • Платформа не зависит от поставщиков.
  • Поставщики зависят от платформы как канала дистрибуции и точки коммерциализации их инвентаря.
  • Все поставщики — равноправные источники данных. Ни один не получает структурного приоритета.

Что это означает практически​

1. Архитектурные модели платформы — собственные, без подгонки под поставщиков​

Каноничная доменная модель (Property, Offer, Quote, Booking, TourDraft, Tenant, ApiClient) проектируется от целей Vitiana, а не от структур Stuba XML, HomeToGo HAPI или любых других внешних API.

Поставщики имеют свои особенности: разные форматы данных, разные модели тарифов, разные правила бронирования и отмены. Это их характеристики, не каноничные ограничения. Слой приёма данных (ingestion) переводит их представления в каноничную модель Vitiana, а не наоборот.

Запрещено:

  • Делать поля каноничного Property потому что «у Stuba так».
  • Подстраивать структуру Offer.cancellation_policy под формат HomeToGo.
  • Принимать решения о модели цены потому что «один поставщик возвращает её в одном формате».

Разрешено и обязательно:

  • Документировать особенности поставщиков как частные случаи входа данных в reference/suppliers.md и в supplier-specific приложениях.
  • Описывать матрицу возможностей поставщиков (supplier capability matrix) как fact-список, без влияния на canonical model.
  • Использовать самые лучшие практики мировой индустрии (best industry practices) как ориентир, но не как ограничение.

2. Слой приёма данных — это адаптер, не диктатор​

Слой приёма данных (ingestion) обязан переводить любые представления поставщиков в каноничную модель Vitiana. Поставщики со слабой прозрачностью (transparency), неполными данными, нестабильным API — попадают в этот слой как технический долг (technical debt) самого слоя приёма, не платформы.

Если поставщик не даёт нужного поля — платформа фиксирует это как класс отсутствующих данных (missing_data_class) и продолжает работать. Поставщик не диктует, какие поля должны быть в Property.

3. Поставщики могут быть отключены, заменены, переподключены — без переделки ядра​

Архитектура изначально проектируется так, что:

  • Любой поставщик может быть отключён без переделки доменной модели.
  • Новый поставщик может быть подключён без расширения каноничных полей.
  • Любой поставщик может быть заменён другим без миграции продуктовой логики.

Это базовое требование к слою приёма данных и слою нормализации (normalization layer).

4. Цена услуг платформы — динамическая, зависит от нагрузки на платформу​

Платформа сама определяет коммерческие условия для своих клиентов (партнёров с платным API доступом, агентств, B2C):

  • Динамическое ценообразование (dynamic pricing) услуг платформы зависит от потребления (consumption), нагрузки (load), типа поставщика, генерирующего трафик (supplier load profile), сложности запросов (query complexity).
  • Тариф партнёра API учитывает нагрузку, которую он создаёт на платформу через свои поиски, коммерческие фиксации (quotes) и бронирования.
  • Платформа взимает плату не за «hotel results», а за свой агрегационный труд: нормализация данных, governance, контроль целостности (integrity gating), проекция поиска (search projection), фиксация цены (quote fixation), гарантии взаиморасчёта (settlement guarantees).

Это переводит модель монетизации с «commission per booking» на динамическую модель доступа к платформе (platform access model).

5. Поставщики не получают доступа к внутренним данным платформы​

  • Поставщик не видит, как его данные используются внутри платформы.
  • Поставщик не видит, какие коммерческие фиксации (quotes) были созданы на основе его инвентаря.
  • Поставщик не видит cross-tenant аналитики.
  • Поставщик не видит других поставщиков и их инвентарь.
  • Платформа отдаёт поставщику только то, что необходимо для подтверждения бронирования (booking commit) и обработки post-booking lifecycle, на уровне обязательств перед поставщиком в цепочке merchant-of-record.

6. Поставщики — равноправные участники без структурного приоритета​

В архитектурных документах платформы запрещены формулировки:

  • «Stuba как primary supplier».
  • «Mainstream supplier» против «secondary supplier».
  • Захватная интеграция (captive integration) с любым отдельным поставщиком.

Допустимы только операционные характеристики:

  • Класс риска (risk class) поставщика (high-trust / standard / low-trust) — для governance и дисциплины публикации.
  • Профиль возможностей (capability profile) поставщика (что он умеет давать) — для специфики приёма данных.
  • Операционное здоровье (operational health) поставщика (uptime, latency, data freshness) — для observability.

Класс риска и профиль возможностей — операционные характеристики, не архитектурные приоритеты.

Конкретные следствия для документной архитектуры​

Что переписать или дополнить​

  • reference/suppliers.md — пересмотреть как «слой точек входа данных» (layer of data ingress points), без подразумеваемого основного поставщика. Добавить матрицу возможностей поставщиков как факт-список.
  • reference/ingestion.md — явно зафиксировать, что ingestion переводит произвольные представления в каноничную модель Vitiana, не наоборот.
  • reference/api-metering-and-usage-governance.md — расширить до полной модели динамического ценообразования услуг платформы по нагрузке, типу запроса, supplier load profile.
  • reference/commercial-model.md — добавить раздел «Платформа как коммерческий продукт» (platform commercial product) с описанием платных услуг для tenant и динамической тарификации доступа.
  • reference/api-as-product.md (новый) — обязательно содержит секцию «Pricing model: dynamic, load-aware, supplier-load-aware».
  • reference/economic-model.md (новый) — обоснование динамической модели в unit economics.

Что запрещено​

  • Создавать документы вида reference/stuba-integration.md или reference/home-to-go-integration.md как первоклассные. Эти материалы — приложения к suppliers.md (например, reference/suppliers/stuba.md или сноски в формате каталога).
  • Подстраивать domain-model.md или offer-pricing-booking-semantics.md под структуру конкретного поставщика.
  • Делать ingestion-решения, которые предполагают, что «один поставщик всегда есть».

Связь с существующей реализацией home-to-go-api​

Уже задеплоенные базы (hotels, geo, usr, events_themes) и работающий Stuba module — это первая реализация слоя приёма данных и каноничного хранилища (canonical store) платформы. Stuba — первый источник, не приоритет.

Задача архитектора — описать каноничную доменную модель так, чтобы:

  1. Текущая реализация (одна Stuba intake) была частным случаем.
  2. Подключение HomeToGo, Booking.com, Expedia EPS, Sabre, Amadeus, GDS — добавлялось как новые адаптеры без переписывания канонического слоя.
  3. Будущее отключение Stuba не повлияло на платформу.

Если уже задеплоенная схема hotels сейчас имеет следы Stuba-specific полей — это технический долг слоя приёма данных, который надо рефакторить, а не закреплять в каноничной модели.

Обоснование (тезисное)​

  1. Глобальная платформа не может быть заложницей одного API. Любая зависимость от поставщика — экзистенциальный риск (поставщик меняет условия, банкротится, отзывает доступ). Архитектура должна изначально предполагать оборот поставщиков (supplier turnover).

  2. Унификация — главный продукт агрегатора. Если платформа выдаёт наружу неунифицированные представления поставщиков, она не агрегатор, а прокси (proxy). Прокси не имеют ценности на верхнем уровне.

  3. Дисциплина каноничной модели — барьер для конкурентов. Подключение нового поставщика к Vitiana должно быть быстрее и дешевле, чем разработка собственной интеграции. Это создаёт сетевой эффект (network effect).

  4. Динамическое ценообразование услуг отражает реальный cost-to-serve. Партнёр, нагружающий платформу 1М searches/day с low-trust поставщиками, объективно дороже партнёра со 100K targeted queries. Тарификация должна это отражать.

  5. Современные лучшие практики платформ верхнего уровня (Stripe, Twilio, Algolia, Cloudflare) — все построены на этом принципе. Их API не подражают upstream-системам, они задают свой стандарт.

Как применять​

При написании любого архитектурного документа vitiana-api-platform задаю четыре вопроса:

  1. Не выводится ли это решение из структуры конкретного поставщика? Если да — переформулирую от целей платформы.
  2. Можно ли заменить любого поставщика без переписывания этого документа? Если нет — рефакторю формулировки.
  3. Описана ли в документе платформа как самостоятельный коммерческий продукт, не как «доступ к чужим данным»?
  4. Поддерживает ли архитектура добавление нового поставщика без расширения каноничной модели?

Каждое архитектурное решение — обоснование тезисами в самом документе. Подробности — в Тезисное обоснование архитектурных решений.

Альтернативы и почему отвергнуты​

Альтернатива 1. Captive integration с одним крупным поставщиком​

Подход: глубокая интеграция со Stuba, проектирование каноничной модели с учётом её ограничений и возможностей. Быстрее в краткосрочной перспективе.

Отвергнуто. Превращает Vitiana в прокси Stuba. Невозможно подключить других поставщиков без переписывания ядра. Экзистенциальный риск при изменении условий Stuba.

Альтернатива 2. Layered fallback (primary + secondary suppliers)​

Подход: один поставщик — primary, другие — fallback. Канонический формат ближе к primary.

Отвергнуто. Создаёт скрытую captive integration. Канонический формат всё равно подгоняется под одного поставщика. Невозможно вырастить multi-supplier marketplace, где конкурируют десятки источников.

Альтернатива 3. Supplier-mirror canonical model​

Подход: каноничная модель — общий знаменатель всех поставщиков, с union возможностей.

Отвергнуто. Канонический формат раздувается под каждого нового поставщика. Невозможно проектировать продуктовые фичи (Tour Builder, dynamic pricing), которые требуют семантики выше любого отдельного поставщика. Платформа не задаёт стандарт, а собирает чужие.

Принимаемые компромиссы​

  • Слой приёма данных сложнее, чем при captive integration — переводит произвольные форматы в каноничный, требует адаптеров, нормализации, governance. Это часть продукта, а не накладные расходы.
  • Скорость подключения первого поставщика медленнее, чем при naive интеграции — нужно сразу проектировать каноничный слой. Окупается на 2-м, 3-м, 10-м поставщике.
  • Часть данных поставщиков теряется при нормализации в каноничный формат. Это сознательное упрощение — платформа задаёт seasoned interface, не raw passthrough.

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

Корневые архитектурные документы​

Связанные правила работы​