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

Поверхности взаимодействия и контуры платформы (ось 2)

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

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

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

Документ читается после главной архитектурной оси (overview/index.md) и манифеста переосмысления (overview/platform-vision-and-manifest.md).

Версия 2.0 этого документа сохранена как overview/layers-old-2026-04-25.md (статус Черновик, архивная). Решения, зафиксированные в архивной версии, остаются валидными для тех частей, которые не противоречат текущей версии.

Главный принцип поверхностей​

Поверхность (surface) — это полностью самостоятельный контракт со своими правилами, не разные представления одного и того же API. Принцип «один API для всех» отвергнут как ложный.

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

  • разные субъекты получают разные контракты, не разные «view» одного контракта;
  • темп эволюции каждой поверхности независим;
  • набор допустимых полей, политика видимости коммерческой информации, политика согласия и аутентификации — всё это per surface;
  • одно и то же действие (например, поиск) на разных поверхностях может отличаться не только полями, но и семантикой;
  • одно и то же доменное состояние (например, Quote) проявляется на разных поверхностях с разной видимостью: B2C-витрина видит цену, агент видит структуру цены и applied policy, партнёр видит контракт-безопасные суммы, внутренний оператор видит трассу применения политики и подготовку взаиморасчётов.

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

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

Кто использует: внутренние команды Vitiana — операторы, governance reviewers, support, finance, ручной review, внутренние административные инструменты.

Главные характеристики:

  • Богатая модель данных — видимость lineage (происхождение полей), source precedence (приоритет источников), review state, anomaly flags;
  • Полные mutation-операции — те, которых нет ни на одной внешней поверхности (manual override, force re-publication, manual mapping decision);
  • Быстрый темп изменений контрактов — внешний контракт не нужен, внутренние пользователи следуют за платформой;
  • Сильная связь с внутренними доменными процессами — поверхность напрямую отражает доменные сущности.

Что строго ЗДЕСЬ:

  • governance review queues и решения;
  • supplier monitoring consoles;
  • anomaly handling screens;
  • booking exception handling;
  • reconciliation и finance support tools;
  • partner management consoles;
  • manual revalidation и переопределение коммерческих политик;
  • audit-friendly поверхности с полным lineage.

Что НЕ должно жить здесь:

  • агентский ежедневный workflow (это другая поверхность);
  • партнёрские интеграции (это другая поверхность);
  • B2C-функции (это другая поверхность).

Связи:

  • Ось 1 (Domain) — самый полный набор сущностей и lineage.
  • Ось 4 (Data) — главный потребитель аналитики и BI для внутренних команд.
  • Ось 5 (Operational) — runbooks, инциденты, manual recovery — здесь.

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

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

Главные характеристики:

  • Полноценная рабочая система продаж и сопровождения туристического продукта, не «сайт поиска отелей»;
  • Workspace-as-a-unit — рабочей единицей является не только пользователь, но и workspace / tenant context. Quote, draft, proposal принадлежат рабочему пространству;
  • Объяснимость данных — agency surface видит applied commercial policy, quote validity, причины repricing;
  • Customer context — агент работает в контексте конкретного клиента, ведёт его историю;
  • Stateful workflow — draft, proposal, booking lifecycle поддерживаются длительными сессиями;
  • Audit-friendly — следы решений сохраняются для последующего разбора.

Главные сценарии:

  • поиск туристических продуктов;
  • сравнение вариантов;
  • создание quote с явной видимостью applied commercial policy;
  • собственная агентская надбавка к цене;
  • инициирование booking и сопровождение его жизненного цикла;
  • работа с Tour Builder для составных продуктов;
  • generation и share клиентского proposal;
  • ведение customer context и истории;
  • agency-scoped reporting (свои продажи, своя комиссия, свои клиенты).

Связи:

  • Ось 1 (Domain) — все сущности, кроме чисто внутренних (Anomaly, ReviewCase в их «сыром» виде);
  • Ось 2 — главная human-facing поверхность платформы;
  • Ось 3 (Platform as Product) — agency tier структуры, agency tier pricing;
  • Ось 4 (Data) — agency-scoped analytics для собственных продаж;
  • Ось 5 (Operational) — у agency surface свой SLA, отличный от B2C.

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

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

Главные характеристики:

  • Узкий стабильный контракт — поверхность строже и стабильнее внутренних/агентских;
  • Жёсткое версионирование (versioning) — major/minor с явной политикой совместимости (compatibility policy);
  • Окно совместимости (compatibility window) — старые версии поддерживаются заданный срок после выхода новых;
  • Аутентификация и scope — API keys с явными scope, environment binding (sandbox vs production), ротация ключей;
  • Квоты и тарифные уровни (quotas and tiers) — каждый тарифный уровень имеет явные envelope;
  • Изоляция окружений — отдельные sandbox и production endpoint;
  • Контракт-безопасное представление коммерческих сумм — без раскрытия внутренней структуры цены, только то, что зафиксировано контрактом;
  • Webhook-доставка как first-class — асинхронные уведомления с подписью, политикой повторной доставки, версионированием полезной нагрузки.

Главные сценарии:

  • поиск через партнёрский запрос с явным scope;
  • получение offer-проекций;
  • создание quote с partner-specific commercial policy;
  • инициирование booking от имени downstream-клиента;
  • получение booking lifecycle событий через webhook;
  • работа с Tour Builder через закрытый API (если партнёр имеет соответствующий тариф);
  • получение partner-facing analytics и usage reports.

Что НЕ должно утекать на эту поверхность:

  • raw supplier payloads;
  • внутренние governance details;
  • внутренние коммерческие детали (только контракт-безопасные суммы);
  • информация о других партнёрах или их данных.

Это самая важная коммерческая поверхность платформы под якорем B2B API marketplace.

Связи:

  • Ось 1 (Domain) — узкая контракт-безопасная проекция сущностей;
  • Ось 3 (Platform as Product) — главная коммерческая поверхность; tariff tiers, dynamic pricing, billing;
  • Ось 4 (Data) — partner-facing analytics product;
  • Ось 5 (Operational) — самые строгие SLA с credits для премиум-тарифов;
  • Compliance — DPA (Data Processing Agreement), KYC/AML, sub-processor lists.

Поверхность 4. B2C Storefront Surface (B2C-витрина)​

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

Главные характеристики:

  • Read-heavy traffic — высокий объём чтения с высоким cache-hit ratio;
  • Презентационная безопасность — нет операционных и маржинальных деталей;
  • Conversion-ориентация — UX оптимизирован под conversion rate;
  • Минимизация внутренних деталей — пользователь видит только то, что ему нужно для решения о покупке;
  • Ограниченная видимость цены — finalprice, без структуры (markup, fee, commission);
  • Регуляторное соответствие — для EU GDPR cookie consent, для PSD2 SCA при оплате, для Package Travel Directive — обязательная информация о пакетных продуктах;
  • Оптимизация под latency и SEO — для собственных сайтов критичны время загрузки и индексация поисковиками.

Главные сценарии:

  • поиск туристических продуктов;
  • просмотр property content и галерей;
  • сравнение цен и условий;
  • создание booking от своего имени с оплатой;
  • просмотр истории своих бронирований;
  • self-service отмена и изменение бронирования;
  • вход в proposal по share-ссылке от агента.

Что НЕ должно утекать:

  • агентская/партнёрская маржа и структура цены;
  • внутренние identifier поставщиков;
  • технические детали ingestion и governance;
  • любая cross-tenant информация.

Связи:

  • Ось 1 (Domain) — самая ограниченная проекция сущностей;
  • Ось 3 (Platform as Product) — собственный канал продаж + opcionально partner white-label;
  • Ось 4 (Data) — самый интенсивный источник tracking events для conversion analytics, A/B тестирования, recommendation;
  • Ось 5 (Operational) — самые жёсткие требования к latency и uptime для conversion;
  • Compliance — основной фокус GDPR cookie consent, PSD2 SCA, Package Travel Directive.

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

Кто использует: внутренние сервисы платформы между собой; внутренние workers, jobs, event consumers/producers; service identities для внутренних автоматизаций.

Главные характеристики:

  • Сильная связность с внутренней доменной моделью — может работать с богатыми payloads, не контракт-безопасными;
  • Богатый event/context payload — больше деталей, чем во внешних поверхностях;
  • Idempotency — все critical S2S-операции идемпотентны;
  • Replay safety — потребители (consumers) безопасны для повторного воспроизведения;
  • Schema discipline — все события и команды имеют явные схемы;
  • Strong observability — каждое S2S-взаимодействие порождает trace и метрики;
  • Аутентификация через service identity и mTLS — никаких неявных доверий между сервисами (zero-trust networking).

Главные классы взаимодействий:

  • доменные события (domain events) — между сервисами через event bus (Kafka);
  • команды (commands) — синхронные RPC между сервисами или через job queue;
  • async coordination — через очереди работы (work queues);
  • broadcast — через event streams для fan-out.

Связи:

  • Ось 1 (Domain) — самая полная связность с доменом;
  • Ось 4 (Data) — каждое S2S-событие — потенциальный источник tracking;
  • Ось 5 (Operational) — observability + reliability — критичны;
  • Современная практика — паттерн hexagonal architecture / ports & adapters.

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

Кто использует: собственные интерфейсы Vitiana (vitrip.store, agency working surface); партнёры с платным тарифом, дающим доступ к Tour Builder API.

Главные характеристики:

  • Закрытый API — не публичный, не доступен в свободном sandbox; доступ через quasi-Partner API surface, но с отдельной коммерческой моделью;
  • Модульный composition primitives API — низкоуровневые модули композиции как первичные единицы:
    • модуль размещения (accommodation segment);
    • модуль переезда (transfer segment) — авто, авиа, ж/д, водный;
    • модуль активности (activity, experience);
    • модуль услуги (service) — гид, страховка, виза;
    • модуль аренды транспорта (transport rental);
    • модуль страхования (insurance);
    • пользовательский модуль (custom block);
    • информационный модуль (informational block).
  • Stateful composition — Draft → Variant → Proposal → Version → Artifact;
  • Compatibility checks — проверка совместимости модулей по времени, географии, capacity, политике;
  • Drift handling — отслеживание изменений в исходных offers и эффект на собранный тур;
  • Per-tour merchant-of-record — определяется по составу модулей и поставщикам;
  • Tour-level pricing — отдельная коммерческая логика, не сумма offer prices (per-tour markup, package discount, all-inclusive bundling).

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

  1. Vitiana строит собственные туры от своего имени (платформа = packager + seller).
  2. Партнёры с платным тарифом проектируют туры под свои каналы продаж (платформа = aggregator + tour builder service).

Связи:

  • Ось 1 (Domain) — композиционные сущности (TourDraft, TourProposal, ProposalVersion, ProposalArtifact);
  • Ось 3 (Platform as Product) — отдельный paid tier для доступа к Tour Builder;
  • Ось 4 (Data) — tracking композиционных решений; ML для compatibility и recommendation на этапе сборки;
  • Ось 5 (Operational) — отдельный SLA для Tour Builder;
  • Compliance — Package Travel Directive (обязательная insolvency protection при пакетных турах в EU).

Контуры взаимодействия (interaction contours)​

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

Контур приёма данных (data ingress contour)​

Адаптеры приёма данных от поставщиков → нормализация → проверка целостности → сохранение в supplier trace и каноничной модели.

Поверхности, на которых проявляется:

  • Внутренняя операционная (для observability и manual review);
  • (Не на внешних поверхностях.)

Контур публикации (publication contour)​

Решение о готовности offer к показу на разных поверхностях. Integrity gating, surface-aware visibility, governance hold.

Поверхности:

  • Все поверхности, на которые offer публикуется (Agency, Partner, B2C, Tour Builder);
  • Внутренняя операционная (для управления публикацией).

Контур поиска и обнаружения (search and discovery contour)​

Принятие поискового намерения, ранжирование, возврат candidate results, fasceting, geo, multi-language.

Поверхности:

  • Agency, Partner, B2C — все имеют свои варианты search-контракта;
  • Tour Builder — поиск компонентов внутри сборки тура.

Контур фиксации обещаний (quote contour)​

Создание quote с applied commercial policy, validity window, repricing, invalidation.

Поверхности:

  • Agency — полная видимость applied policy;
  • Partner — контракт-безопасное представление;
  • B2C — упрощённая видимость финальной цены;
  • Tour Builder — quote на тур-уровне (не offer-уровне).

Контур транзакционного коммита (transactional commit contour)​

Booking commit, supplier confirmation, post-booking lifecycle.

Поверхности:

  • Agency — agent-инициированный booking от имени клиента;
  • Partner — partner-инициированный booking через API;
  • B2C — самостоятельный booking конечного клиента;
  • Внутренняя операционная — exception handling, manual recovery.

Контур композиции тура (tour composition contour)​

Сборка многокомпонентного тура с проверкой совместимости и drift handling.

Поверхности:

  • Tour Builder Closed — главная поверхность;
  • Agency — agent использует Tour Builder через свою рабочую поверхность;
  • B2C — конечный клиент видит уже собранный proposal по share-ссылке.

Контур взаиморасчётов (settlement and clearing contour)​

Партнёрские балансы, кредитные лимиты, clearing entries, supplier payable, agency commission.

Поверхности:

  • Внутренняя операционная — финансовые операторы;
  • Partner — partner-facing balance dashboard, billing;
  • Agency — agency-scoped commission reports.

Контур governance и review (governance contour)​

Manual review, mapping decisions, anomaly handling, conflict resolution.

Поверхности:

  • Внутренняя операционная — governance reviewers;
  • (Не на внешних поверхностях напрямую; результаты влияют через публикацию и repricing.)

Контур наблюдаемости и инцидентов (observability contour)​

Метрики, traces, logs, dashboards, alerting, incident response.

Поверхности:

  • Внутренняя операционная — оперативные команды;
  • Partner — partner-facing usage dashboards (часть analytics product);
  • Agency — agency-scoped operational visibility.

Перекрёстные правила (cross-surface rules)​

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

Одна и та же Property, Offer, Quote, Booking, Tour существует в одном экземпляре в каноничной модели. На разных поверхностях её видимость разная, но сущность одна.

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

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

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

Внешние поверхности (Partner API, B2C) не получают доступа к маржинальной структуре, applied commercial policy trace, settlement preparation context. Только то, что зафиксировано контрактом.

Правило 4. Surface-aware visibility — first-class​

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

Правило 5. Каждая поверхность имеет своё SLA​

SLA по uptime, latency, freshness — different per surface. Партнёрский API имеет жёстче требования, чем внутренний; B2C — самые строгие к latency и uptime для conversion.

Поверхности и динамическое ценообразование​

Динамическое ценообразование платформенных услуг (см. overview/platform-as-product.md) применяется по поверхностям:

  • Partner API Surface — главная поверхность тарификации; цена зависит от объёма поисковых запросов, quote, booking, ML-инференса, supplier-call budget, сложности запросов;
  • Tour Builder Closed Surface — отдельная коммерческая модель (paid tier), цена за композиционные операции;
  • Agency Working Surface — подписка + комиссия с продаж;
  • B2C Storefront Surface — собственный канал, монетизация через маржу платформы на туристических продуктах;
  • Internal и S2S — нет внешней тарификации, внутренние операционные расходы.

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

Связь с осью 1 (каноничная доменная)​

Каждая каноничная сущность определяет видимость на каждой поверхности:

СущностьInternalAgencyPartnerB2CS2STour Builder
Propertyfull + lineagecontent + structurecontract-safe contentpresentation-safefullcontent + module
Offerfull + governance statefull operational + commercialcontract-safe with freshnessindicativefullas composable input
Quotefull + applied policy traceactor-aware breakdowncontract-safe sumnot exposed (internal to checkout)fulltour-level quote
Bookingfull lifecycle + auditfull statecontract-safe stateown onlyfullas composition output
TourDraftfullcomposer view(only for paid Tour Builder tier)not exposedfullfirst-class
TourProposalfullcomposer view + historycontract-safe versionedpublished presentationfullfirst-class
Tenantfullown contextown contextnot exposedfullown
Anomaly / ReviewCasefullnot exposednot exposednot exposedfullnot exposed

Связь с осью 3 (платформа как продукт)​

Поверхности — это продуктовые поверхности:

  • Partner API Surface = главный продукт B2B API marketplace;
  • Tour Builder Closed Surface = премиальный продукт со своим тарифом;
  • Agency Working Surface = собственный продукт для агентств;
  • B2C Storefront Surface = собственный канал продаж туристических продуктов.

Связь с осью 4 (данные и интеллект)​

Каждая поверхность — источник tracking events:

  • Partner API — usage metering, partner load profile, query complexity;
  • Agency — agent workflow analytics, conversion воронка для агентств;
  • B2C — самый интенсивный источник conversion analytics, A/B тестирования, recommendation;
  • Internal — операционная аналитика, governance metrics;
  • Tour Builder — composition analytics, ML для compatibility и recommendation;
  • S2S — operational events, reliability metrics.

Связь с осью 5 (операционная)​

Каждая поверхность определяет:

  • свой целевой уровень обслуживания (SLO — Service Level Objective);
  • свой контракт обслуживания (SLA — Service Level Agreement);
  • свои метрики деградации;
  • свои runbooks для инцидентов;
  • свои capacity envelopes (особенно per tenant tier на Partner API).

Связь с осью 6 (реализация)​

Текущая реализация home-to-go-api имеет частичную поддержку поверхностей:

  • https://api.vitrip.store/stuba — это adapter ingestion, не Partner API Surface;
  • vitrip.store сайт (Preact + HTM, PHP backend) — это зачаточная B2C Storefront Surface;
  • агентская поверхность — в концепции, не реализована;
  • Partner API Surface — в концепции, не реализована;
  • Internal Operational Surface — частично через admin-панель vitrip.store;
  • Tour Builder Closed Surface — в концепции, не реализована.

Полная карта соответствия — в overview/relation-to-implementation-baseline.md.

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

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

  • конкретный API gateway (Traefik, Kong, иной);
  • REST vs gRPC vs GraphQL для каждой поверхности;
  • конкретный мiddleware chain;
  • exact Kubernetes ingress topology.

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

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

  • Partner API Surface — REST (OpenAPI) + Webhooks (AsyncAPI) как baseline;
  • Service-to-Service Surface — gRPC + Kafka events;
  • Internal Operational Surface — REST + WebSocket для интерактивности;
  • B2C Storefront Surface — HTTP/HTML + REST для динамики;
  • Agency Working Surface — REST + WebSocket для интерактивности;
  • Tour Builder Closed Surface — REST + Webhooks; возможно gRPC для S2S-вариантов.

Это направление, не догма. Финальные решения — в фазе 4 при создании reference/api-as-product.md и связанных документов.

Этап зрелости поверхностей​

Что уже зафиксировано​

  • Концептуальные границы шести поверхностей;
  • Контракты второго круга для Partner API в reference/api-contracts.md;
  • Концептуальные клиентские поверхности в reference/clients.md;
  • Дисциплина асинхронной шины в reference/eventing-and-queue-baseline.md;
  • Skeletons и схемы событий в нескольких документах фазы 3.

Что предстоит развернуть в следующих фазах​

В фазе 4 (новые домены):

  • reference/api-as-product.md — Partner API как продукт со всеми атрибутами;
  • reference/payment-domain.md — платёжный контур, влияющий на B2C и Agency;
  • reference/notification-and-communication.md — webhook-доставка как first-class.

В фазе 5 (углубление):

  • reference/multi-tenant-isolation-strength.md — surface-aware tenant isolation;
  • reference/tour-builder-operational-model.md — операционная модель Tour Builder Closed Surface.

В фазе 7 (переработка):

  • reference/clients.md — пересвязать с tenancy и API as product.

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

  • Делать вид, что поверхности — это просто разные view одного API;
  • Подражать структуре Stuba/HomeToGo при дизайне Partner API Surface;
  • Объединять Tour Builder Closed Surface с Partner API Surface в одну поверхность (разные коммерческие модели);
  • Допускать утечку маржинальной структуры на внешние поверхности;
  • Вводить временные поверхности «пока запустим B2C, потом разделим» — каждая поверхность first-class сразу.

Уточнение под Фазу 7 (28.04.2026) — соотношение surface contracts и client surfaces​

После переработки reference/clients.md в Фазе 7 (27.04.2026) в проекте появилось две взаимодополняющие таксономии поверхностей: surface contracts (этот документ) и client surfaces (clients.md). Эта секция фиксирует их различие, чтобы будущий читатель не воспринимал их как конкурирующие.

Две ортогональные таксономии​

Таксономия 1 — Surface Contracts (этот документ, layers.md): разделение по типу контракта, который платформа предоставляет миру. Фокус — на формальном API/протокольном уровне: что именно отдаётся как стабильный контракт, по каким правилам версионируется, какие коммерческие отношения у каждого контракта.

#Surface ContractТип контракта
1Internal Operationalвнутренний — нет внешнего контракта
2Agency Workingfirst-party — managed application contract
3Partner APIвнешний — stable contract с версионированием
4B2C Storefrontfirst-party — managed presentation contract
5Service-to-Service (S2S)внутренний — между сервисами платформы
6Tour Builder Closedспециальный paid contract (отдельная коммерческая модель)

Таксономия 2 — Client Surfaces (clients.md): разделение по product surface, который user/SDK видит. Фокус — на потребителе: какие frontend-приложения, машинные интеграции, embeddable виджеты существуют как продуктовые единицы.

#Client SurfaceProduct тип
1Internal Operationalвнутренний UI
2Agency Workingfirst-party UI
3Partner Machinemachine-to-machine integration
4Partner UI/SDKpartner-facing dashboards + SDK npm package
5B2C Client-Facingend-user UI (vitrip.store)
6White-Label and Embeddedembeddable виджеты, partner-hosted flows

Соответствие между таксономиями​

Таксономии не противоречат — они проецируются друг на друга:

Surface Contract (layers.md)Соответствующие Client Surfaces (clients.md)
Internal OperationalSurface 1 (Internal Operational) — 1:1
Agency WorkingSurface 2 (Agency Working) — 1:1
Partner APISurface 3 (Partner Machine) + Surface 4 (Partner UI/SDK) — Partner API Surface обслуживает оба клиентских surfaces
B2C StorefrontSurface 5 (B2C Client-Facing) — 1:1 + Surface 6 (White-Label) для partner-hosted B2C flows
Service-to-Service(нет client surface — S2S не имеет user-facing UI)
Tour Builder Closed(специальный paid контракт; клиентские surfaces 2, 4, 5 потребляют через свои UI)

Иными словами:

  • Partner API Surface в layers.md — это контрактный слой, который обслуживает два разных типа клиентов: machine-to-machine integrations (Surface 3 в clients.md) и UI/SDK для партнёров-операторов (Surface 4). Это один surface contract, но два product surfaces.
  • Service-to-Service Surface — внутренний контракт, не имеет client surface (нет user/partner UI поверх него).
  • Tour Builder Closed Surface — это специальный коммерческий paid контракт, доступный из нескольких client surfaces (Agency, Partner UI/SDK, B2C через published proposal view).
  • White-Label and Embedded — это deployment option Partner API + B2C Storefront контрактов под партнёрским брендом, не отдельный новый contract. Согласно reference/api-as-product.md, white-label — feature Enterprise tier.

Какая таксономия для каких задач​

  • Дизайн контрактов API/AsyncAPI, версионирование, rate limits — использовать Surface Contracts (этот документ);
  • Дизайн UI/SDK, продуктовая декомпозиция, capability matrix — использовать Client Surfaces (clients.md);
  • При проектировании integration partner — обе одновременно: какой контракт он потребляет (Partner API) и какие client surfaces он использует (Machine + UI/SDK).

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

Layers.md остаётся главным документом по surface contracts (формально-контрактная сторона Оси 2). Clients.md — каноничный документ по client surfaces (продуктовая декомпозиция). Они дополняют друг друга, не конкурируют.

При конфликте — каждый документ авторитетен в своей таксономии:

  • layers.md — для contractual обязательств, versioning, SLA, rate limits, security boundaries;
  • clients.md — для UI/SDK packaging, capability matrix, truth visibility per product surface.

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

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