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

Обзор Ось 2 — Поверхности взаимодействия (резюме простыми словами)

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

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

Этот документ — резюме второй архитектурной оси платформы для непрофильного читателя. Он не заменяет каноничный документ Поверхности взаимодействия и контуры платформы (ось 2), а служит коротким и понятным введением для тех, кто не работает с архитектурой каждый день: руководителей, новых членов команды, внешних консультантов, партнёров на этапе знакомства.

Цель резюме — чтобы любой грамотный читатель за 10–15 минут понял, через какие двери платформа общается с миром, чем эти двери отличаются и почему их нельзя сводить к одной.

О чём документ​

Документ описывает вторую из шести архитектурных осей платформы — поверхности взаимодействия (surfaces). Простыми словами: это «двери», через которые платформа общается с миром. Через одну дверь заходят внутренние сотрудники, через другую — туристические агентства, через третью — партнёры по программному интерфейсу, через четвёртую — конечные клиенты, через пятую — внутренние сервисы платформы между собой, через шестую — пользователи конструктора туров.

Главный смысл: каждая дверь — это самостоятельный контракт со своими правилами. Это не «один и тот же интерфейс с разными настройками видимости», а разные интерфейсы.

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

Один программный интерфейс для всех — ложная идея. Разные стороны (партнёры, агентства, конечные клиенты, внутренние операторы) имеют разные потребности, разные ритмы изменений, разные правила видимости коммерческой информации. Платформа предоставляет разные контракты каждой стороне — а не одно API с фильтрами по ролям.

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

  • темп эволюции каждой двери — независимый;
  • набор разрешённых полей, политика видимости цен, политика согласия и аутентификация — своя для каждой двери;
  • одно и то же действие (например, поиск) на разных дверях может по-разному называться, по-разному вести себя и возвращать разный результат;
  • одно и то же доменное состояние (например, фиксированная цена) видно на разных дверях по-разному: клиент видит итоговую цену, агент — её структуру, партнёр — контракт-безопасные суммы, внутренний оператор — всю историю применения политик.

Шесть поверхностей платформы​

Поверхность 1. Внутренняя операционная (Internal Operational Surface)​

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

Что особенного:

  • Самая богатая модель данных — видны все поля, все источники, все следы изменений.
  • Полные операции изменения — те, которых нет ни на одной внешней двери (ручная переопределение, форсированная повторная публикация, ручное решение о маппинге).
  • Быстрый темп изменений — внешний контракт не нужен, внутренние пользователи следуют за платформой.
  • Прямая связь с внутренними процессами — отражает доменные сущности напрямую.

Что живёт здесь: очереди модерации данных, мониторинг поставщиков, обработка аномалий, исключительные ситуации бронирований, инструменты сверки и финансовой поддержки, ручная повторная проверка, переопределение коммерческих политик, аудит-журналы.

Что не должно жить здесь: ежедневная работа агентств, партнёрские интеграции, функции для конечных клиентов — у них свои двери.

Поверхность 2. Агентская рабочая (Agency Working Surface)​

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

Что особенного:

  • Полноценная рабочая система продаж и сопровождения — это не «сайт поиска отелей», а полная рабочая среда.
  • Рабочее пространство как единица — единицей измерения здесь не только пользователь, но и его рабочее пространство. Черновики, фиксации, предложения принадлежат рабочему пространству, не лично пользователю.
  • Объяснимость данных — агент видит применённую коммерческую политику, срок действия фиксации, причины пересчёта цены.
  • Контекст клиента — агент работает в контексте конкретного клиента, ведёт его историю.
  • Долгие сессии — черновик, предложение, бронирование сопровождаются длительными сессиями.
  • Журналируемость решений — следы решений сохраняются для последующего разбора.

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

Поверхность 3. Партнёрский программный интерфейс (Partner API Surface)​

Кто использует: партнёры с платным доступом — B2B-интеграторы, белые-лейблы (white-label), реселлеры, корпоративные системы для путешествий, внешние агрегаторы.

Что особенного:

  • Узкий стабильный контракт — строже и стабильнее внутренней и агентской дверей.
  • Жёсткое версионирование — крупные и мелкие версии с явной политикой совместимости.
  • Окно совместимости — старые версии поддерживаются заданное время после выхода новых.
  • Аутентификация и разрешения — программные ключи с явными разрешениями, разделение тестовой и боевой среды, ротация ключей.
  • Квоты и тарифные уровни — каждый тариф имеет явные лимиты.
  • Изоляция сред — отдельные тестовая и боевая точки входа.
  • Контракт-безопасные суммы — партнёр не видит внутренней структуры цены, только то что зафиксировано контрактом.
  • Webhook-доставка как первоклассная — асинхронные уведомления с подписью, политикой повторов, версионированием полезной нагрузки.

Главные сценарии: поиск через партнёрский запрос, получение проекций предложений, создание коммерческой фиксации с партнёр-специфичной политикой, инициирование бронирования от имени конечного клиента партнёра, получение событий жизни бронирования через webhook, работа с конструктором туров через закрытый интерфейс (если тариф позволяет), партнёрская аналитика и отчёты потребления.

Что не должно утекать сюда: сырые данные поставщиков, внутренние детали модерации, внутренние коммерческие детали, информация о других партнёрах.

Это самая важная коммерческая дверь платформы — основной продукт по якорю «B2B-маркетплейс программных интерфейсов».

Поверхность 4. Витрина для конечных клиентов (B2C Storefront Surface)​

Кто использует: конечные клиенты сайта vitrip.store, конечные клиенты партнёров через белые-лейбловые интеграции (если архитектура такого витриного типа разрешена тарифом партнёра).

Что особенного:

  • Высокий объём чтения — много запросов на просмотр с эффективным кешированием.
  • Презентационная безопасность — никаких операционных и маржинальных деталей.
  • Ориентация на конверсию — интерфейс оптимизирован под превращение посетителя в покупателя.
  • Минимизация внутренних деталей — пользователь видит только то, что ему нужно для решения о покупке.
  • Ограниченная видимость цены — итоговая сумма без разбивки на наценки и комиссии.
  • Регуляторное соответствие — для EU обязательное согласие на cookie, при оплате — усиленная аутентификация (PSD2 SCA), при продаже пакетных туров — обязательная информация по директиве о пакетных путешествиях.
  • Скорость и поисковая оптимизация — для своих сайтов критичны время загрузки и видимость в поисковиках.

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

Что не должно утекать сюда: агентская и партнёрская маржа и структура цены, внутренние идентификаторы поставщиков, технические детали приёма данных и модерации, любая информация других тенантов.

Поверхность 5. Сервис-к-сервису (Service-to-Service Surface)​

Кто использует: внутренние сервисы платформы между собой, внутренние фоновые задачи, потребители и производители событий, машинные идентичности для внутренней автоматизации.

Что особенного:

  • Сильная связь с внутренней доменной моделью — может работать с богатыми наборами данных, не обязательно контракт-безопасными.
  • Богатый набор контекста — больше деталей, чем во внешних дверях.
  • Идемпотентность — все критические операции безопасны при повторе.
  • Безопасность повторного воспроизведения — потребители безопасны для повторных проигрываний событий.
  • Дисциплина схем — все события и команды имеют явные схемы.
  • Сильная наблюдаемость — каждое взаимодействие порождает трассы и метрики.
  • Аутентификация через сервисную идентичность и взаимный TLS — никаких неявных доверий между сервисами.

Главные классы взаимодействий: доменные события через шину сообщений, синхронные команды между сервисами, асинхронная координация через очереди работы, широковещание через потоки событий.

Поверхность 6. Закрытая поверхность конструктора туров (Tour Builder Closed Surface)​

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

Что особенного:

  • Закрытый программный интерфейс — не публичный, не доступен в свободной тестовой среде; доступ через близкую к партнёрской поверхность, но с отдельной коммерческой моделью.
  • Модульный программный интерфейс композиционных примитивов — низкоуровневые модули как первичные единицы:
    • модуль размещения,
    • модуль переезда (авто, авиа, ж/д, водный),
    • модуль активности или впечатления,
    • модуль услуги (гид, страховка, виза),
    • модуль аренды транспорта,
    • модуль страхования,
    • пользовательский модуль,
    • информационный модуль.
  • Сборка с состоянием — черновик становится вариантом, потом предложением, потом версией, потом материализованным артефактом.
  • Проверки совместимости — соответствие модулей по времени, географии, вместимости, политикам.
  • Отслеживание изменений — что изменилось в исходных предложениях и как это влияет на собранный тур.
  • Цепочка ответственности на уровне тура — определяется составом модулей и поставщиками.
  • Цена на уровне всего тура — отдельная коммерческая логика, не сумма цен компонентов (наценка на тур, скидка пакета, всё-включено).

Двойное использование:

  1. Платформа собирает собственные туры от своего имени (платформа = упаковщик и продавец).
  2. Партнёры с платным тарифом проектируют туры под свои каналы продаж (платформа = агрегатор и сервис конструктора туров).

Девять рабочих контуров​

Поверхности — это «как стороны общаются». Контуры — это «как контракты группируются по доменным процессам». Один контур может проявляться на нескольких поверхностях с разной видимостью.

  1. Контур приёма данных — адаптеры приёма данных от поставщиков. Видна только на внутренней поверхности.
  2. Контур публикации — решение о готовности предложения к показу. Видна на всех поверхностях, на которые публикуется.
  3. Контур поиска и обнаружения — приём поискового намерения, ранжирование, возврат результатов. Видна на агентской, партнёрской, B2C, в конструкторе туров.
  4. Контур фиксации обещаний — создание коммерческой фиксации с применённой политикой, сроком действия, пересчётом, аннулированием. На разных поверхностях — разная видимость структуры цены.
  5. Контур транзакционного коммита — фиксация бронирования, подтверждение поставщика, жизненный цикл после бронирования. Видна на агентской, партнёрской, B2C и внутренней.
  6. Контур композиции тура — сборка многокомпонентного тура с проверкой совместимости и отслеживанием изменений. Главная — закрытая поверхность конструктора туров.
  7. Контур взаиморасчётов — партнёрские балансы, кредитные лимиты, записи клиринга, расчёты с поставщиками, агентские комиссии. Видна на внутренней, партнёрской, агентской.
  8. Контур управления данными — модерация, решения о маппинге, обработка аномалий, разрешение конфликтов. Видна только на внутренней.
  9. Контур наблюдаемости и инцидентов — метрики, трассы, журналы, дашборды, оповещения, реагирование на инциденты. Видна на внутренней, партнёрской (часть аналитического продукта), агентской.

Пять перекрёстных правил​

Правило 1. Каноничные сущности не дублируются для разных поверхностей​

Один и тот же объект размещения, предложение, коммерческая фиксация, бронирование, тур существуют в одном экземпляре в каноничной модели. На разных поверхностях их видимость разная, но сущность одна.

Правило 2. Кросс-поверхностные изменения статуса разрешены только через управление данными​

Если действие на одной двери должно повлиять на видимость на другой (например, оператор внутренней двери приостановил публикацию предложения для всех внешних) — это идёт через контур управления данными, не напрямую.

Правило 3. Контракт-безопасное представление коммерческих сумм для внешних дверей​

Внешние двери (партнёрский интерфейс, витрина для клиентов) не получают доступа к маржинальной структуре, следам применения коммерческой политики, контексту подготовки взаиморасчётов. Только то, что зафиксировано контрактом.

Правило 4. Видимость по поверхностям — первоклассное правило​

Модель видимости — не runtime-фильтр на готовых данных, а часть контракта поверхности. Документируется явно для каждого поля доменной сущности.

Правило 5. У каждой поверхности своё соглашение об уровне обслуживания​

Время безотказной работы, задержки ответа, актуальность данных — разные для каждой двери. Партнёрский интерфейс имеет жёстче требования чем внутренний, витрина для клиентов — самые строгие к задержкам и доступности для конверсии.

Поверхности и тарификация​

Каждая дверь имеет свою коммерческую модель:

  • Партнёрский программный интерфейс — главная поверхность тарификации. Цена зависит от объёма поисковых запросов, фиксаций, бронирований, инференса машинного обучения, бюджета вызовов поставщиков, сложности запросов.
  • Закрытая поверхность конструктора туров — отдельная коммерческая модель (платный тариф), цена за композиционные операции.
  • Агентская рабочая — подписка плюс комиссия с продаж.
  • Витрина для конечных клиентов — собственный канал, монетизация через маржу платформы на туристических продуктах.
  • Внутренняя и сервис-к-сервису — нет внешней тарификации, внутренние операционные расходы.

Связь с шестью осями архитектуры​

Поверхности проявляются на других пяти осях:

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

Связь с реальной реализацией​

В уже работающем коде существующей реализации сейчас:

  • Адаптер приёма данных от поставщиков реализован, но это адаптер приёма, не партнёрский интерфейс — не путать.
  • Сайт vitrip.store — зачаточная витрина для клиентов (фронтенд на лёгких технологиях, бэкенд на PHP).
  • Агентская поверхность — в концепции, не реализована.
  • Партнёрский программный интерфейс — в концепции, не реализована.
  • Внутренняя операционная поверхность — частично через административную панель сайта.
  • Закрытая поверхность конструктора туров — в концепции, не реализована.

Транспорт и протоколы — производный уровень​

Документ намеренно не фиксирует:

  • конкретный шлюз программного интерфейса;
  • выбор стиля программного интерфейса (REST, gRPC, GraphQL) для каждой двери;
  • точную сетевую топологию.

Главный тезис: транспорт — производный уровень. Сначала контракт двери, затем выбор транспорта.

Что разумно зафиксировать как направление:

  • партнёрский программный интерфейс — REST с описанием в стандарте OpenAPI плюс webhook'и в стандарте AsyncAPI;
  • сервис-к-сервису — gRPC и события через шину сообщений;
  • внутренняя операционная — REST плюс WebSocket для интерактивности;
  • витрина для клиентов — HTTP/HTML плюс REST для динамики;
  • агентская рабочая — REST плюс WebSocket для интерактивности;
  • закрытая поверхность конструктора туров — REST плюс webhook'и, возможно gRPC для S2S-вариантов.

Это направление, не догма. Окончательные решения — на стадии создания контрактных документов.

Две таксономии поверхностей​

В проекте существуют две взаимодополняющие таксономии поверхностей, и важно их не путать:

  • Контракты поверхностей (этот документ) — разделение по типу контракта, который платформа предоставляет миру. Фокус — на формальном уровне: что отдаётся как стабильный контракт, как он версионируется, какая коммерческая модель.
  • Клиентские поверхности (другой каноничный документ) — разделение по продукту, который видит пользователь или машинная интеграция. Фокус — на потребителе: какие приложения, машинные интеграции, встраиваемые виджеты существуют как продуктовые единицы.

Эти таксономии не противоречат — они проецируются друг на друга. Например, партнёрский программный интерфейс в этом документе — это контрактный слой, который обслуживает двух разных типов клиентов: машинные интеграции и интерфейс/комплект разработчика для партнёров-операторов.

Что нельзя делать с этой картой поверхностей​

  • Делать вид, что поверхности — просто разные представления одного программного интерфейса.
  • Подражать структуре конкретных поставщиков при дизайне партнёрской двери.
  • Объединять закрытую поверхность конструктора туров с партнёрским программным интерфейсом в одну дверь — у них разные коммерческие модели.
  • Допускать утечку маржинальной структуры на внешние двери.
  • Вводить временные поверхности «пока запустим, потом разделим» — каждая поверхность первоклассная сразу.

Итог​

Документ закрепляет карту дверей платформы — шесть отдельных поверхностей с разными контрактами, ритмами изменений, правилами видимости и коммерческими моделями. Главное послание простое: разные стороны взаимодействия требуют разных контрактов, и попытка свести их к одному «универсальному API» — архитектурная ошибка, ведущая к компромиссам со всеми сторонами одновременно. Каждая дверь — самостоятельный продукт с собственным жизненным циклом, и платформа сразу проектируется под эту реальность.

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