Клиентские поверхности (clients layer) — рабочие модели, surface boundaries и связь с программой как продуктом

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

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

Этот документ задаёт каноничную модель клиентского слоя платформы Vitiana — совокупности всех пользовательских и канальных поверхностей (user- and channel-facing surfaces), через которые платформа реально используется.

Документ переработан с учётом каноничной архитектуры, опубликованной в Фазах 4–6: программный интерфейс как продукт (API as product), уведомления и коммуникации, медиа и контент, интернационализация, аналитика, тенантная изоляция, статусная машина бронирования, операционная модель Tour Builder. После этих документов клиентский слой не может быть описан как «сайт + партнёрский API + единый frontend stack» — он становится сложной композицией поверхностей, каждая со своим контрактом, видимостью, capability set и tenant scope.

Главная задача документа — зафиксировать surface boundaries (границы поверхностей), truth visibility policy (политику видимости истины), capability matrix (матрицу возможностей) и связь с программным интерфейсом как продуктом. Документ намеренно не выбирает конкретный UI-фреймворк — это решение принимается на стадии 1 development roadmap.

Тезисное обоснование

Тезис 1. Клиентский слой — продуктовая декомпозиция, а не frontend-стек.

Альтернативы: (а) единый frontend для всех ролей с скрытием/показом фич; (б) отдельный frontend на каждую роль; (в) SDK + composition primitives.

Trade-off: единый frontend дешевле в разработке, но смешивает agency workflow с partner integration с B2C storefront, что приводит к утечке внутренних истин в B2C surface (например, supplier names, internal pricing breakdown). Отдельные frontends дают чистые boundaries, но дороже. Декомпозиция по surface boundaries (внутренний, agency, partner machine, partner UI/SDK, B2C, white-label) с shared domain core — pattern Stripe Dashboard / Stripe.js / Stripe Connect, Twilio Console / Helper Libraries / Verify SDK. Это оправданно для платформы верхнего уровня.

Тезис 2. Partner surface — peer (равноправная), не производная от first-party UI.

Альтернативы: (а) partner surface = first-party UI с другим брендингом; (б) partner surface = только machine-to-machine API без UI; (в) partner surface = full peer (machine API + Tour Builder API + dashboards + SDK + sandbox + certification).

Trade-off: вариант (а) экономит разработку, но нарушает правило 00000 — поставщики не должны навязывать структуру каноничной модели, и партнёры не должны зависеть от первичного UI первого ассортимента. Вариант (б) недоступен для Tour Builder partner-grade API (см. tour-builder-domain.md) — партнёрам нужны UI/SDK для самостоятельной композиции туров. Вариант (в) — реальный peer-уровень, как у Stripe Connect или Algolia Custom Search. Это oбязательно для top-tier platform.

Тезис 3. Truth visibility policy — first-class требование клиентского слоя.

Альтернативы: (а) делегировать видимость на бэкенд через role-based filtering; (б) каждый клиент сам фильтрует через capability-check; (в) каноничная visibility policy с явной моделью.

Trade-off: вариант (а) скрывает дисциплину видимости, что приводит к случайным leak'ам (например, B2C клиент получает internal supplier name через ranking endpoint). Вариант (б) рассыпает логику между клиентами и неминуемо приводит к расхождению. Вариант (в) — каноничная VisibilityPolicy с explicit правилами per surface (agency / partner / B2C / internal / white-label) — single source of truth для всех клиентов. Это критично для платформы с хорошей дисциплиной truth boundaries.

Тезис 4. Capability-aware UI обязателен на всех human surfaces.

Альтернативы: (а) RBAC только на API уровне, UI показывает всё; (б) UI скрывает кнопки, бэкенд проверяет permissions; (в) UI и API явно потребляют capability descriptor.

Trade-off: вариант (а) даёт plausible UI, но ломается при изменении roles (UI не реагирует на изменение). Вариант (б) — стандартная практика, но приводит к рассогласованию UI/API при добавлении новых capabilities. Вариант (в) — UI и API получают capability_set для текущего actor / tenant / workspace и используют его явно — единственная масштабируемая модель для платформы с десятками ролей и партнёрских tier'ов. Это согласуется с api-as-product.md — capability set часть partner contract.

Тезис 5. Notifications, media, i18n, analytics — общая инфраструктура клиентского слоя.

Альтернативы: (а) каждый client builds свой notification UI / media handling / i18n / analytics; (б) централизованные сервисы платформы, потребляемые клиентами; (в) клиент сам выбирает стратегию.

Trade-off: вариант (а) приводит к дублированию и расхождению (B2C показывает booking confirmation в одном формате, agency — в другом, partner получает webhook в третьем). Вариант (в) — то же без принципа. Вариант (б) — каноничные платформенные домены: notification-and-communication.md, media-and-content.md, internationalization-and-localization.md, analytics-and-bi.md. Клиенты потребляют их как infrastructure, не реализуют заново. Это масштабируемое решение, согласованное с decomposition of concerns.

Главная архитектурная ось — что клиентский слой обязан удерживать

После Фаз 4–6 клиентский слой обязан явно удерживать:

• Каноничная доменная модель (см. domain-model.md): клиентские поверхности не могут смешивать canonical content, operational offers, quotes, bookings, tour composition, governance objects как один UI-материал.
• Тенантность и идентичность (см. tenancy-and-identity.md): human-facing applications обязаны быть tenant-aware, workspace-aware, actor-aware, capability-aware.
• Семантика предложения и цены (см. offer-pricing-booking-semantics.md): интерфейсы обязаны различать Offer, Quote, Booking, не пряча различия под одной карточкой.
• Коммерческая модель (см. commercial-model.md): preview price, quoted promise, repricing, monetary breakdown visibility, settlement-aware follow-up.
• Tour Builder как core (см. tour-builder-domain.md, tour-builder-operational-model.md): draft workspace, proposal presentation, proposal versioning, artifact publication, partner-grade API.
• Статусная машина бронирования (см. booking-state-machine.md): 14 каноничных состояний, обработка unknown_external_state.
• Платёжный домен (см. payment-domain.md): PaymentIntent flow, refund visibility, chargeback handling в support UI.
• Программный интерфейс как продукт (см. api-as-product.md): partner lifecycle, sandbox, certification, SLA tiers — UI и SDK обязаны это поддерживать.
• Тенантная изоляция (см. multi-tenant-isolation-strength.md): UI обязан показывать dedicated_compute / dedicated_infrastructure индикаторы для соответствующих тенантов.
• Уведомления (см. notification-and-communication.md): UI потребляет multichannel notification API, не строит свой.
• Медиа и контент (см. media-and-content.md): media bundles, content translations, image transforms через каноничный медиа-сервис.
• Интернационализация (см. internationalization-and-localization.md): supported languages, currencies, FX rates через каноничный i18n.
• Аналитика (см. analytics-and-bi.md): partner-facing analytics dashboards с правильной k-anonymization.
• A/B-тестирование (см. ab-testing-platform.md): UI потребляет experiment assignments через единый клиент.
• Governance (см. data-governance-and-matching.md): internal operational clients обязаны иметь explainable governance/review surfaces.

Главный принцип клиентского слоя

Клиентские поверхности проектируются от роли и рабочего сценария, не от мысли «дадим всем один интерфейс или один payload».

Жёсткие следствия:

• агентский рабочий кабинет не равен публичной витрине;
• partner integration не частный случай first-party UI — peer-уровень с собственным жизненным циклом (sandbox → certification → production);
• внутренние operational tools не «обычный admin» поверх тех же моделей — отдельный продуктовый контур;
• screens не строятся напрямую из supplier-shaped API (нарушение правила 00000);
• технологическая форма не выбирается раньше surface boundaries и use cases;
• preview state ≠ commit-ready state;
• quoted price ≠ «ещё одна цена на карточке»;
• repriced quote не выдаётся как будто цена не менялась;
• working draft и published proposal — разные UI-объекты;
• agency, partner, B2C, internal, white-label — разные visibility models.

Каноничная карта клиентских поверхностей — шесть surfaces

Платформа Vitiana различает шесть каноничных surfaces (в предыдущей версии было пять — добавлен Partner Machine как отдельный surface, чтобы явно отделить машинную интеграцию от партнёрского UI/SDK).

Surface 1. Internal Operational Surface

Приложения для внутренних сотрудников платформы.

Включает:

• governance and review workspaces;
• supplier monitoring consoles (мониторинг здоровья поставщиков, не captive логика);
• anomaly handling screens;
• booking exception handling (включая unknown_external_state recovery);
• reconciliation and finance support tools;
• partner management consoles (lifecycle, certification, billing);
• on-call dashboards (см. sla-and-on-call-model.md);
• runbook execution interfaces (см. runbooks-incident-playbooks.md);
• DR drill orchestration (см. disaster-recovery-and-capacity.md);
• A/B experiment management (см. ab-testing-platform.md).

Особенности: richer internal models, lineage visibility, conflict explanation, manual override flows. Не должна жить по тем же сценариям, что agency surface.

Surface 2. Agency Working Surface

Основная рабочая поверхность для агентств и агентских пользователей.

Включает:

• search workspace (см. search-and-discovery.md);
• offer comparison и shortlist;
• quote workflow с repricing visibility;
• booking workflow с обработкой 14 каноничных состояний (см. booking-state-machine.md);
• tour draft и proposal workflow (см. tour-builder-operational-model.md);
• client work context;
• история решений и изменений;
• agency analytics dashboards (см. analytics-and-bi.md);
• agency-level notifications inbox (см. notification-and-communication.md);
• multi-language UI с supported languages (см. internationalization-and-localization.md).

Особенности: workspace-as-a-unit (рабочая единица — не пользователь, а workspace/tenant context):

• quotes живут в рабочем контексте;
• drafts и proposals имеют owner / workspace semantics;
• booking follow-up зависит от tenant-specific commercial и access policy;
• один человек видит разный набор действий в разных рабочих контурах.

Quote promise awareness: Agency surface обязан явно показывать:

• preview price (indicative);
• зафиксированный Quote с validity window;
• repriced quote (с visibility разницы);
• monetary components доступные agent (через MonetaryBreakdownVisibilityPolicy);
• следующий допустимый шаг (с/без revalidation/repricing).

Surface 3. Partner Machine Surface

Чисто machine-to-machine интеграции через программный интерфейс (см. api-as-product.md).

Включает:

• B2B reseller backends;
• white-label booking channels (machine side);
• external agency systems;
• downstream aggregators;
• webhook consumers (см. notification-and-communication.md);
• CRM/ERP integrations.

Особенности:

• predictable machine contracts (OpenAPI + AsyncAPI);
• strong environment separation (sandbox vs production);
• scope-aware auth с partner certification (см. api-as-product.md);
• retry-safe semantics (idempotency keys);
• webhooks с разными topic'ами (booking.confirmed, booking.unknown_external_state, payment.refunded, и т.д.);
• partner-specific visibility rules (через VisibilityPolicy);
• explainable integration failures (с error_code + recovery_hint);
• onboarding и certification paths.

Surface 4. Partner UI/SDK Surface

Партнёрские UI, white-label dashboards, SDK для построения собственных интеграций.

Это новый peer surface, выделенный из старого «Partner Integration Clients» — потому что для top-tier platform partner-facing UI/SDK становится самостоятельным продуктом (Stripe Connect Dashboard, Twilio Console для sub-accounts, Algolia Dashboard для tenant'ов).

Включает:

• partner self-service portal (provisioning, billing, analytics);
• partner Tour Builder UI (для самостоятельной композиции туров — core requirement Tour Builder partner-grade API);
• partner sandbox testing UI;
• partner certification UI;
• partner analytics dashboards (см. analytics-and-bi.md);
• partner support / ticketing UI;
• SDK для популярных языков (минимум JavaScript/TypeScript, Python, PHP, Go);
• composition primitives (UI components partners can embed);
• documentation portal (auto-generated from OpenAPI).

Особенности:

• partner brand awareness (white-label поддержка);
• capability set ограничен tier'ом (см. api-as-product.md: Free/Starter/Professional/Enterprise);
• visibility ограничена VisibilityPolicy.partner_ui;
• monetary breakdown ограничен MonetaryBreakdownVisibilityPolicy.partner_ui;
• multi-tenant внутри одного партнёра (партнёр-агентство со своими sub-tenants).

Surface 5. B2C Client-Facing Surface

Публичные или полупубличные каналы для конечного клиента (vitrip.store как первый референсный B2C surface).

Включает:

• storefront web application;
• mobile app (фаза позже);
• embedded booking widgets;
• branded landing flows;
• proposal viewing surfaces (по уникальной ссылке);
• customer self-service pages (booking management, refund requests).

Особенности:

• high-volume read scenarios;
• fast discovery с aggressive caching;
• simplified offer presentation;
• legal/compliance presentation (price disclosure rules, T&Cs, GDPR);
• presentation-safe pricing visibility (нет supplier names, нет internal breakdown);
• conversion-oriented UX;
• A/B-эксперименты как first-class через ab-testing-platform.md;
• payment UI через payment-domain.md с PSP-абстракцией.

Presentation honesty (критично):

• indicative_offer ≠ Quote — UI явно различает;
• published_proposal_view ≠ internal_working_draft;
• price_visibility зависит от channel и commercial policy;
• pending_supplier_state не прячется за ложной финальностью;
• repriced_quote не выдаётся как будто цена не менялась.

Surface 6. White-Label and Embedded Surface

Платформа живёт внутри чужого бренда, процесса или продукта.

Включает:

• embedded search widgets (для партнёрских сайтов);
• branded agency portals (полностью под брендом партнёра);
• partner-hosted booking flows;
• co-branded itinerary/proposal screens;
• SDK-driven embedded surfaces.

Особенности:

• surface boundary discipline (что можно — что нельзя в чужом брендинге);
• scoped branding (Vitiana mention required vs invisible);
• capability restrictions (зависит от tier);
• contract stability requirements (deprecation policy ≥ 6 месяцев);
• publication boundary discipline.

Surface boundaries — каноничная матрица

Один тип actor может использовать несколько surfaces. Каноничные комбинации:

Actor	Surfaces, к которым имеет доступ
Internal operator	Surface 1 (Internal Operational), сценарно — Surface 2 (Agency, scoped views для troubleshooting)
Agent (employee партнёра-агентства)	Surface 2 (Agency Working)
Partner integrator (developer)	Surface 3 (Partner Machine), Surface 4 (Partner UI/SDK для онбординга)
Partner manager (business user партнёра)	Surface 4 (Partner UI/SDK), сценарно — Surface 6 (White-Label для конечных клиентов)
End customer (B2C)	Surface 5 (B2C), Surface 6 (White-Label через партнёрский канал)
Customer success (Vitiana support)	Surface 1 (Internal Operational), сценарно — scoped Surface 2 read-only для troubleshooting

Это не fixed model — actor может иметь несколько ролей. Capability set определяется через tenancy-and-identity.md.

Каноничные рабочие модели — четыре workflow patterns

Workflow 1. Discover and Narrow

Пользователь или система формирует travel intent, задаёт constraints, получает candidates, уточняет выбор, переходит к offer-level сравнению.

Используемые domains: search-and-discovery.md, offer-pricing-booking-semantics.md.

Применимо к: Surface 2 (Agency), Surface 5 (B2C), Surface 6 (White-Label).

Workflow 2. Compare and Compose

Пользователь сравнивает варианты, удерживает shortlist, формирует quote, собирает предложение для клиента, комбинирует элементы в маршрут или программу.

Используемые domains: tour-builder-domain.md, tour-builder-operational-model.md, commercial-model.md, media-and-content.md.

Применимо к: Surface 2 (Agency, через polished UI), Surface 4 (Partner UI/SDK, через partner-grade Tour Builder API).

Workflow 3. Commit and Support

Пользователь или интеграция отправляет booking intent, отслеживает booking state, получает подтверждение или исключение, проводит отмену/изменение, видит историю и operational next steps.

Используемые domains: booking-state-machine.md, payment-domain.md, post-booking-lifecycle.md, notification-and-communication.md.

Применимо к: все surfaces в разной мере.

Workflow 4. Review and Govern

Внутренние пользователи смотрят anomalies, проверяют matching/mapping, обрабатывают booking exceptions, делают manual decisions, проводят reconciliation, управляют доступами и партнёрскими настройками.

Используемые domains: data-governance-and-matching.md, partner-finance-and-clearing.md, runbooks (см. runbooks-incident-playbooks.md).

Применимо к: Surface 1 (Internal Operational).

Truth visibility policy — каноничная модель

Каждый surface получает разную форму одного и того же доменного объекта. Это управляется через VisibilityPolicy, привязанную к surface и actor capability.

Каноничная матрица visibility

Объект	Surface 1 (Internal)	Surface 2 (Agency)	Surface 3 (Partner Machine)	Surface 4 (Partner UI)	Surface 5 (B2C)	Surface 6 (White-Label)
Property	full lineage, supplier metadata, governance flags	sanitized + supplier name (при agency contract)	contract-approved fields	partner-tier dependent	presentation-safe (без supplier name)	partner-defined (per agreement)
Offer	full breakdown, integrity flags	commercial breakdown	contract-approved	partner-tier	presentation-safe	partner-defined
Quote	full validity, repricing trace	validity + repricing visible	contract-approved	partner-tier	presentation-safe (final price)	partner-defined
Booking	full state including unknown_external_state	full state	contract-approved states	partner-tier states	simplified (pending/confirmed/failed)	partner-defined
TourComposition	full draft + history	full draft + workspace	partner-grade API	partner Tour Builder UI	published proposal only	published proposal only
MonetaryBreakdown	full (supplier cost + margin + commission + tax)	agency-visible (без supplier cost)	contract-approved fields	partner-tier	presentation-safe (final price + tax)	partner-defined
GovernanceFlag	visible	hidden	hidden	hidden	hidden	hidden
SupplierName	visible	visible (agency contract)	optional (per contract)	optional (per tier)	hidden (always)	partner-defined

Эта матрица — single source of truth для всех surfaces. Реализация — через VisibilityPolicy resolver на API уровне, который применяется к response-документам перед сериализацией.

Capability matrix — каноничная модель

Capability — конкретное действие, которое actor может выполнить в данном tenant context.

Каноничные capabilities (выборка)

• search.execute — выполнить search query;
• offer.view — просмотреть offer;
• quote.create, quote.revise, quote.expire — действия с Quote;
• booking.create, booking.cancel, booking.modify — действия с Booking;
• tour.compose, tour.publish, tour.archive — действия с Tour;
• payment.refund.initiate, payment.chargeback.respond — действия с Payment;
• partner.onboard, partner.certify — управление партнёром (Surface 1);
• governance.review, governance.lock, governance.publish_hold — действия governance (Surface 1);
• analytics.view.tenant, analytics.view.platform — доступ к аналитике;
• experiment.assign, experiment.exposure — A/B-тестирование;
• notification.send.outbound, notification.template.author — уведомления.

Capability resolution

UI и API получают capability_set для текущего (actor, tenant, workspace) через каноничный endpoint GET /capability/me. UI потребляет это для:

• скрытия/показа кнопок и меню;
• pre-validation действий перед отправкой на сервер;
• адаптации workflow под доступные действия.

API использует то же capability set для authorization checks. Это исключает рассогласование UI ↔ API.

Платформенные сервисы для всех клиентов

Клиенты не реализуют заново — потребляют каноничные платформенные сервисы.

Notifications

Все клиенты получают каноничный notification client (см. notification-and-communication.md):

• email, SMS, push, in-app, webhook;
• multilingual templates;
• consent log;
• delivery tracking.

Никакой клиент не строит свой email-pipeline.

Media and content

Все клиенты потребляют media через каноничный медиа-сервис (см. media-and-content.md):

• MediaAsset reference + on-the-fly transforms;
• ContentBundle для property/offer/tour;
• ContentTranslation для multilingual content;
• responsive images через transform query params.

Никакой клиент не хранит свои изображения.

Internationalization

Все клиенты используют каноничный i18n (см. internationalization-and-localization.md):

• SupportedLanguage set;
• SupportedCurrency с FX rates;
• timezone handling;
• pluralization rules;
• date/number formatting.

Никакой клиент не реализует свой FX converter.

Analytics

Партнёрские клиенты (Surface 4) и agency client (Surface 2) потребляют каноничные analytics dashboards (см. analytics-and-bi.md):

• pre-aggregated tenant metrics;
• proper k-anonymization;
• export в стандартных форматах (CSV, Excel, API).

Никакой клиент не делает свои queries в DWH.

A/B testing

Все surfaces, где идут эксперименты, потребляют единый A/B клиент (см. ab-testing-platform.md):

• experiment.assign(experiment_id, user_id) → variant;
• experiment.exposure(...) → exposure event;
• feature flags через тот же клиент.

Никакой клиент не реализует свой A/B framework.

Search

Все surfaces, где есть поиск, используют каноничный Search API (см. search-and-discovery.md):

• SearchProjection за surface;
• RankingPolicy (без captive boost — правило 00000);
• faceting и filtering.

Payments

Все surfaces с платежами используют PaymentIntent API (см. payment-domain.md):

• единый PSP abstraction;
• 3DS / SCA flow handled by platform;
• refund / chargeback workflow в support UI (Surface 1).

Связь с tenancy-and-identity

Каждый клиент обязан явно использовать модель tenancy (см. tenancy-and-identity.md):

• Tenant context определяет данные, к которым клиент имеет доступ;
• Workspace — рабочая единица внутри tenant (для agency surface);
• Actor — конкретный пользователь или service account;
• Role + Capability set — что actor может делать в данном tenant/workspace;
• Isolation level (logical / dedicated_compute / dedicated_infrastructure — см. multi-tenant-isolation-strength.md) — UI обязан показывать индикатор для tenant с dedicated tier (например, badge «Dedicated Infrastructure» в Settings).

Связь с программным интерфейсом как продуктом

Surface 3 (Partner Machine) и Surface 4 (Partner UI/SDK) обязаны явно поддерживать концепцию API as Product (см. api-as-product.md):

• Partner lifecycle: sandbox → certification → production → deprecation;
• API tiers: Free / Starter (95% SLA) / Professional (99% SLA) / Enterprise (99.9% SLA);
• Quotas и rate limits: per-tier (см. api-metering-and-usage-governance.md);
• Versioning: explicit version в URL или header;
• Deprecation: ≥ 6 месяцев notice через notifications + dashboard banner;
• Documentation portal: auto-generated from OpenAPI/AsyncAPI;
• Status page: реальное время SLA (см. sla-and-on-call-model.md);
• Support: tier-зависимые SLA на ответ.

Tour Builder partner-grade UI/SDK — особое требование

Согласно tour-builder-domain.md и правилу 00000, Tour Builder доступен партнёрам с платным доступом как первичный продукт платформы, не как «дополнение». Это означает:

• partners получают raw API constructor (composition primitives);
• partners получают partner-grade Tour Builder UI components (в Surface 4);
• partners могут embed композицию в свой канал (Surface 6 White-Label);
• partner-side composition rules опираются на каноничные CompositionRule объекты (см. tour-builder-operational-model.md);
• saga для partner-initiated booking transactions работает идентично agency flow.

UI/SDK не упрощённая копия agency Tour Builder — это full peer-функциональность с контрактной стабильностью.

Технологическая форма — что зафиксировано и что нет

Что разумно зафиксировано

• Web-first applications для Surface 1 (Internal) и Surface 2 (Agency);
• Strongly-typed integration boundaries — каждый surface потребляет API через сгенерированные клиенты из OpenAPI/AsyncAPI;
• Reusable design and interaction primitives (design system платформы, переиспользуемый Surface 1 / Surface 2 / Surface 4);
• Clear separation между contract models (DTO) и UI-specific view models;
• Observability-aware client operations (frontend трассирует critical workflows и публикует client-side events в data-platform-and-events-tracking.md);
• A/B-aware клиенты (потребляют experiment assignments через единый клиент);
• Capability-aware клиенты (потребляют capability_set через GET /capability/me).

Что не зафиксировано (откладывается до стадии 1)

• конкретный frontend framework для каждого surface (React, Svelte, Solid — решение per surface);
• exact application split (один монорепозиторий vs несколько);
• final mobile strategy (native iOS/Android, React Native, PWA — решение по результатам стадии 3);
• final white-label packaging strategy (npm package, CDN-hosted bundle, iframe);
• final SDK form factor (single SDK vs multiple per language).

Клиентские данные и truth policy

Клиентский слой обязан уважать truth policy:

• property_content может кэшироваться (stable read model);
• offer и price показывают freshness и ограничения;
• quote имеет validity semantics с visible expiration;
• booking UI явно различает 14 каноничных состояний (см. booking-state-machine.md);
• unknown_external_state особо обрабатывается с recovery UI;
• клиент не скрывает revalidation-critical моменты;
• repriced quote визуально маркирован.

Visibility policy для разных surfaces

• agency workspace — internal working draft;
• клиент по ссылке — published proposal view;
• partner integration — contract-approved fields;
• internal governance — lineage, conflict explanation, review state;
• B2C — presentation-safe offer/read models.

Monetary breakdown visibility per surface

Это — расширение каноничной матрицы visibility:

• agency workspace — richer commercial breakdown (без supplier cost);
• partner integration — contract-approved monetary model;
• B2C — presentation-safe visible price + tax breakdown;
• internal — policy trace, override source, settlement preparation context;
• white-label — partner-defined disclosure set.

Это не рождается случайно в UI — следует из commercial-model.md, api-contracts.md, VisibilityPolicy.

Клиентские приложения и ошибки

UI и интеграционные клиенты проектируются так, чтобы ошибки были recoverable, explainable и operationally useful.

Особенно важны:

• validation feedback (с конкретным указанием, что не так);
• retry-safe action handling (idempotency keys для всех mutating actions);
• distinction между temporary и terminal failures;
• visibility of pending processing (с примерным временем);
• clear user messaging без лжи о финальности;
• operator-facing diagnostics для Surface 1 (correlation id, lineage, error trace).

Каноничный error envelope (для всех surfaces):

• error_code — машинный код;
• message — человекочитаемое сообщение (с учётом supported language actor);
• recovery_hint — что пользователь может сделать;
• correlation_id — для support escalation;
• is_retryable — boolean (для machine surfaces);
• retry_after_seconds — рекомендация для machine surfaces.

Каноничные события клиентов

Клиенты публикуют события в data-platform-and-events-tracking.md:

UI-side events:

• client.session.started / client.session.ended;
• client.page.viewed (с surface tag);
• client.action.executed (с capability check trace);
• client.error.shown (с error_code);
• client.experiment.exposure (см. ab-testing-platform.md);
• client.feature_flag.evaluated.

Domain workflow events (через API, не client-side):

• quote.created, quote.revised, quote.expired;
• booking.intent.submitted, booking.confirmed, booking.unknown_external_state;
• tour.draft.created, tour.proposal.published;
• payment.intent.created, payment.captured, payment.refunded.

Открытые вопросы и развилки

1. Mobile-first vs web-first для Surface 5. vitrip.store как первый B2C surface — в первую очередь web или mobile? Решение — на стадии 3 после анализа аудитории первой волны (UA/CZ/PL/KZ).
2. Single SDK vs per-language SDKs. Один SDK на TypeScript с обёртками на других языках vs полноценные SDK на каждом языке. Решение — на стадии 1 после первых партнёрских интервью.
3. White-label deep customization vs surface contract stability. Партнёры хотят deep customization (свой look-and-feel), но это конфликтует с contract stability и feature ramping. Trade-off резервируется на стадию 4.
4. Internal Operational vs Agency UI shared components. Где граница shared design system vs surface-specific UI? Решение — после первых implementation slice'ов (стадия 1).
5. Mobile native vs PWA для Surface 5. Native (iOS/Android) дороже, PWA дешевле. Решение — после стадии 3 на основании B2C engagement metrics.

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

Архитектурная основа

• Архитектурная основа платформы (overview/index.md);
• Архитектурный якорь и бизнес-модель (overview/architectural-anchor-and-business-model.md);
• Архитектура поверхностей (overview/layers.md).

Каноничная доменная модель

• Доменная модель (domain-model.md);
• Тенантность и идентичность (tenancy-and-identity.md);
• Сила тенантной изоляции (multi-tenant-isolation-strength.md);
• Семантика предложения, цены и бронирования (offer-pricing-booking-semantics.md);
• Коммерческая модель (commercial-model.md);
• Tour Builder домен (tour-builder-domain.md);
• Операционная модель Tour Builder (tour-builder-operational-model.md);
• Статусная машина бронирования (booking-state-machine.md);
• Платёжный домен (payment-domain.md);
• Жизненный цикл после бронирования (post-booking-lifecycle.md);
• Целостность и публикация (offer-integrity-and-publication-control.md);
• Партнёрские взаиморасчёты (partner-finance-and-clearing.md);
• Data governance and matching (data-governance-and-matching.md).

Платформенные домены

• Программный интерфейс как продукт (api-as-product.md);
• API metering и usage governance (api-metering-and-usage-governance.md);
• Поиск и обнаружение (search-and-discovery.md);
• Уведомления и коммуникации (notification-and-communication.md);
• Медиа и контент (media-and-content.md);
• Интернационализация и локализация (internationalization-and-localization.md);
• Аналитика и BI (analytics-and-bi.md);
• Платформа A/B-тестирования (ab-testing-platform.md);
• Платформа данных и трекинг событий (data-platform-and-events-tracking.md);
• API контракты (api-contracts.md);
• Бизнес-сервисы (business-services.md).

Операционные документы

• Модель SLA и дежурств (sla-and-on-call-model.md);
• Runbook'и инцидент-плейбуки (runbooks-incident-playbooks.md);
• Восстановление после аварий и планирование ёмкости (disaster-recovery-and-capacity.md);
• Развёртывание и эксплуатационная модель (deployment.md);
• Наблюдаемость и реагирование на инциденты (observability-and-incident-response.md).

Архитектурные правила

• Закон 00000 — платформа главенствует над поставщиками — Tour Builder partner-grade UI как обязательный peer surface;
• Современные лучшие практики верхнеуровневых платформ — Stripe Dashboard / Twilio Console / Algolia Dashboard как ориентир;
• Развитие без деградации — surface boundaries без shortcut'ов;
• Тезисное обоснование архитектурных решений — формат принятия решений.

Документы развития

• Дорожная карта развития платформы (roadmap.md);
• Архивная версия (clients-old-2026-04-27.md);
• Архивная версия (clients-old-2026-04-23.md).