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

Clients Layer — Клиентские поверхности и рабочие модели

Версия: 2.0 (архивная)
Дата архивации: 27.04.2026
Статус: Черновик (архивный, не source of truth)

Архивный документ. Эта версия концептуально верно различала 5 client surfaces, но была недо-связана: создана до публикации api-as-product, notification-and-communication, media-and-content, internationalization-and-localization, analytics-and-bi, multi-tenant-isolation-strength, booking-state-machine, tour-builder-operational-model, runbooks, sla. Также не учитывала Tour Builder с partner-grade API как core (правило 00000) — partner surface перестал быть «производным от first-party UI».

Актуальный документ: clients.md — переписан на каноничной архитектуре после Фаз 4–6.

Текст ниже сохраняется без изменений для исторической справки.

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

Этот документ фиксирует, какие клиентские поверхности вообще должны существовать у платформы, какие сценарии они обслуживают, как соотносятся с surface model из API Contracts и почему клиентский слой нельзя больше описывать как "сайт + партнёрский API + единый frontend stack".

Задача этого документа — не выбрать модный UI-фреймворк и не перечислить компоненты в вакууме. Его задача — зафиксировать рабочую модель тех интерфейсов, через которые платформа реально будет использоваться людьми и системами:

  • внутренними командами;
  • агентствами;
  • партнёрами;
  • клиентскими витринами;
  • автоматизированными downstream channels.

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

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

После появления второго круга документов clients.md уже нельзя считать просто описанием “типов приложений”.

Теперь клиентский слой обязан явно удерживать:

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

Clients Layer обязан описывать не только кто каким приложением пользуется, но и какие истины, ограничения и уровни завершённости каждое приложение вправе показывать и менять.

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

Старый вариант документа имел несколько структурных проблем.

Во-первых, он утверждал, что "веб-сайт и внешние партнёры используют одни и те же API. Одна логика для всех". Для раннего pitch-документа это ещё допустимо, но для промышленной платформы это слишком грубое упрощение. Одинаковое доменное ядро ещё не означает одинаковую клиентскую поверхность.

Во-вторых, старый документ описывал website for agents, partner SDK, hotel search, hotel details, booking form, tour PDF как будто этого уже достаточно, чтобы определить клиентский слой платформы. На деле это только маленькая часть клиентского ландшафта.

В-третьих, старый текст слишком рано цементировал конкретную фронтенд-форму: React/Next.js, один тип app shell, один набор screens и один API client как будто все consumer-ы живут одинаково.

Новый подход исправляет это:

  1. Сначала различаются типы клиентов и типы рабочих поверхностей.
  2. Затем фиксируются use cases и operational needs.
  3. Только потом можно обсуждать application form, UI composition и техническую реализацию.

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

Clients Layer — это совокупность всех пользовательских и channel-facing surfaces, через которые платформа:

  • получает поисковые и продуктовые намерения;
  • показывает канонический и presentation-готовый контент;
  • даёт работать с offers и quotes;
  • позволяет создавать, сопровождать и анализировать bookings;
  • поддерживает tour composition;
  • даёт инструменты governance и operational control;
  • даёт партнёрам и downstream systems предсказуемый способ интеграции.

Клиентский слой здесь не равен "frontend". Он включает:

  • human-facing applications;
  • partner-facing integration forms;
  • customer-facing storefronts;
  • internal operational tools;
  • embeddable and white-label channels;
  • automation-friendly consumption surfaces.

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

Клиентские поверхности должны проектироваться от роли и рабочего сценария, а не от мысли "дадим всем один и тот же интерфейс или один и тот же payload".

Из этого следуют жёсткие выводы:

  • нельзя считать агентский рабочий кабинет копией публичной витрины;
  • нельзя считать partner integration частным случаем first-party UI;
  • нельзя считать внутренние operational tools обычным admin frontend поверх тех же моделей;
  • нельзя строить screens напрямую из случайной структуры старого hotel-centric API;
  • нельзя выбирать технологическую форму раньше, чем зафиксированы клиентские use cases и surface boundaries.

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

  • нельзя скрывать разницу между preview state и commit-ready state;
  • нельзя показывать quoted price как будто это просто ещё одна “цена на карточке”;
  • нельзя скрывать, что price могла быть пересчитана через repricing, если это влияет на решение пользователя;
  • нельзя смешивать working draft и published proposal в один и тот же экранный объект;
  • нельзя раздавать одинаковую visibility model agency, partner и B2C surface-ам.

Карта Клиентских Поверхностей​

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

1. Internal Operational Applications​

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

Сюда входят:

  • governance and review workspaces;
  • supplier monitoring consoles;
  • anomaly handling screens;
  • booking exception handling;
  • reconciliation and finance support tools;
  • partner management consoles;
  • observability and operational diagnostics.

Эта поверхность не должна жить по тем же сценариям, что агентский кабинет. Ей нужны richer internal models, review actions, lineage, conflict explanation и manual override flows.

2. Agency Working Applications​

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

Сюда входят:

  • поиск;
  • отбор вариантов;
  • offer comparison;
  • quote workflow;
  • booking workflow;
  • tour draft and proposal workflow;
  • client work context;
  • история решений и изменений.

Это не "сайт поиска отелей". Это полноценная рабочая система продаж и сопровождения travel product-а.

2B. Agency Quote Promise Awareness​

Agency surface должен уметь явно показывать:

  • когда цена является только preview;
  • когда создан полноценный Quote;
  • когда quote был пересчитан;
  • какие monetary components видимы агенту;
  • какой следующий шаг допустим без повторной проверки, а какой требует revalidation / repricing.

2A. Workspace-As-A-Unit​

Для agency surface-а важно закрепить, что рабочей единицей является не только пользователь, но и workspace / tenant context.

Это означает:

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

3. Partner Integration Clients​

Это системы партнёров, интегрирующиеся с платформой как machine-to-machine consumers.

Сюда входят:

  • CRM and ERP integrations;
  • B2B reseller systems;
  • white-label booking channels;
  • external agency systems;
  • downstream aggregators;
  • webhook consumers.

Эти клиенты не требуют визуального интерфейса платформы, но всё равно являются частью Clients Layer, потому что через них платформа реально используется.

4. B2C / Client-Facing Applications​

Это публичные или полупубличные каналы для конечного клиента.

Сюда могут входить:

  • storefront web applications;
  • mobile apps;
  • embedded booking widgets;
  • branded landing flows;
  • proposal viewing surfaces;
  • customer self-service pages.

Этот контур может оказаться очень важным, но его нельзя автоматически считать тождественным agency surface.

4A. Presentation Honesty​

B2C surface особенно чувствителен к тому, чтобы presentation не подменяла доменную правду.

Здесь нужно жёстко удерживать:

  • indicative offer не равен quote;
  • published proposal view не равен internal working draft;
  • price visibility зависит от channel and commercial policy;
  • pending supplier state нельзя прятать за ложной финальностью.
  • repriced quote нельзя выдавать как будто цена никогда не менялась.

5. White-Label And Embedded Surfaces​

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

Сюда могут входить:

  • embedded search widgets;
  • branded agency portals;
  • partner-hosted flows;
  • co-branded itinerary/proposal screens;
  • SDK-driven surfaces.

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

  • surface boundary discipline;
  • scoped branding;
  • capability restrictions;
  • contract stability requirements.
  • publication boundary discipline.

Клиенты Не Равны Surface-ам Один К Одному​

Один тип клиента может использовать несколько surface-ов.

Например:

  • агент работает через Agency Working Application, но может также получать customer-facing proposal links;
  • внутренний оператор использует Internal Operational Application, но может заходить в scoped agency-like views для troubleshooting;
  • партнёр может использовать Partner API для интеграции и одновременно white-label UI components;
  • конечный клиент может видеть proposal page, а не полноценный storefront.

Поэтому этот документ должен связываться с API Contracts, а не пытаться подменить его.

Основные Рабочие Модели Клиентского Слоя​

1. Discover And Narrow​

Пользователь или система:

  • формирует travel intent;
  • задаёт destination/date/occupancy constraints;
  • получает candidate results;
  • уточняет выбор;
  • переходит к offer-level сравнению.

Это не только UX-паттерн, но и базовая рабочая модель для клиента.

2. Compare And Compose​

Пользователь:

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

Это особенно важно для agency surface и tour builder scenarios.

3. Commit And Support​

Пользователь или интеграция:

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

Это уже transactional working model и она не должна маскироваться под обычный CRUD.

4. Review And Govern​

Внутренние пользователи:

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

Это полноценная рабочая модель platform operations, а не side-admin feature.

Agency Working Applications Как Центральный Human Surface​

На текущем этапе именно agency working applications нужно считать главным human-facing surface-ом платформы.

Что Должно Жить Внутри Него​

  • search workspace;
  • property and offer evaluation;
  • quote creation and revision;
  • booking submission and follow-up;
  • customer context;
  • tour builder;
  • proposal management;
  • history, notes, collaboration and audit-friendly traces.

Что Это Меняет По Сравнению Со Старым Подходом​

Старый документ рисовал агентский интерфейс как обычный frontend для поиска и бронирования отелей. Но в реальности агентский кабинет должен быть closer to operating workspace than storefront.

Ему нужны:

  • explainable offers;
  • видимость quote validity;
  • понимание коммерческого контекста;
  • работа с draft и альтернативами;
  • доступ к booking lifecycle, а не только к моменту создания booking;
  • стабильная связь с customer and tenant context.

B2C / Client-Facing Applications Как Отдельный Контур​

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

У Этого Контура Свои Приоритеты​

  • high-volume read scenarios;
  • fast discovery;
  • simplified offer presentation;
  • reduced operational complexity;
  • legal/compliance presentation constraints;
  • different pricing visibility policy;
  • conversion-oriented UX.

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

  • нельзя просто отдать клиенту агентский кабинет в другой обёртке;
  • нельзя автоматически раскрывать все commercial and operational fields;
  • нельзя считать публичную витрину primary model for the whole platform;
  • нельзя подстраивать весь домен под ограничения storefront UX.

Partner Integration Clients Как Product Surface​

Партнёрские интеграции нужно воспринимать как отдельный продуктовый контур, а не как "ещё один пользователь API".

Для Них Важно​

  • predictable machine contracts;
  • strong environment separation;
  • scope-aware auth;
  • retry-safe semantics;
  • webhooks or async notifications;
  • partner-specific visibility rules;
  • explainable integration failures;
  • onboarding and certification paths.

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

Партнёрский SDK, примеры кода и integration helpers могут существовать, но они не должны определять платформу целиком. Сначала контракт, потом SDK, а не наоборот.

Internal Operational Applications Как Необходимая Часть Платформы​

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

Для vitiana-api-platform это недопустимо.

Внутренние Операционные Приложения Должны Поддерживать​

  • review queue handling;
  • supplier anomaly inspection;
  • mapping and merge decisions;
  • booking exception handling;
  • manual revalidation workflows;
  • support diagnostics;
  • partner key and tenant administration;
  • audit and reconciliation access.

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

Клиентские Поверхности И Доменные Контуры​

Клиентские приложения не должны проектироваться напрямую от БД или случайных endpoint-ов. Они должны опираться на доменные контуры из Архитектурная основа платформы vitrip.store.

Supplier Ingestion And Normalization​

Обычно не имеет прямого user-facing surface, но даёт operational tooling для внутренних команд.

Canonical Inventory And Content​

Питает property pages, content cards, destination views, search results, proposal content.

Offers / Pricing / Quote Pipeline​

Питает compare flows, commercial views, quote generation, partner pricing surfaces.

Booking Domain​

Питает create/manage/support/amend/cancel scenarios.

Tour Builder Domain​

Питает draft/proposal/composition interfaces.

Identity / Tenancy / Access​

Питает login, workspace scoping, role-based UI capability model, partner/tenant isolation.

Governance / Quality / Moderation​

Питает internal review and exception handling tools.

Client Composition Принципы​

Этот документ специально не фиксирует окончательно, будет ли каждая поверхность реализована отдельным приложением, набором модулей внутри одного продукта или гибридной схемой. Это решение должно вытекать из зрелости платформы и operational constraints.

Но уже сейчас нужно зафиксировать принципы композиции.

1. Surface Boundary First​

Нельзя проектировать единый гигантский UI, если разные actor-ы имеют разные задачи и разные data visibility rules.

2. Shared Domain Core, Different Presentation Models​

Разные client surfaces могут опираться на одно доменное ядро, но использовать разные presentation models, workflows и affordances.

3. Human Workflow Over Raw CRUD​

Agency, internal и support applications должны строиться вокруг рабочих сценариев, а не набора CRUD-страниц.

4. Draft And Session Awareness​

Tour builder, quote flow и часть booking scenarios stateful по природе. Клиентский слой обязан это уважать.

5. Capability-Aware UI​

Показываемые функции должны зависеть не только от auth fact, но и от role, tenant scope, partner scope, operational context.

6. Truth-And-Freshness-Aware UI​

Клиентские поверхности обязаны различать:

  • stable content;
  • operational offer state;
  • actor-specific quote fixation;
  • transactional booking state;
  • published proposal artifact;
  • governance-reviewed internal state.

7. Commercial-Truth-Aware UI​

Клиентские поверхности обязаны различать:

  • indicative price preview;
  • quoted promise;
  • repriced quote;
  • booking-time commit state;
  • settlement-aware internal follow-up.

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

Технологическая Форма И Её Статус​

Старый документ слишком рано зафиксировал React/Next.js как будто технологическая форма клиентского слоя уже окончательно выбрана.

На текущем этапе правильнее говорить так:

  • platform requires rich web applications for agency and internal surfaces;
  • platform may require storefront and mobile-adjacent surfaces for customer-facing channels;
  • partner integrations require SDK/examples/tooling, but they are derivative from contracts;
  • technical implementation may include one or several web frontends, embeddable modules, white-label shells and integration packages.

Что Уже Можно Считать Разумным Вектором​

  • web-first applications для agency и internal surfaces;
  • strongly typed integration boundaries;
  • reusable design and interaction primitives;
  • clear separation between contract models and UI-specific view models;
  • observability-aware client operations for critical workflows.

Что Пока Нельзя Считать Окончательно Зафиксированным​

  • конкретный frontend framework как единственно возможный стандарт;
  • exact application split by repositories;
  • final mobile strategy;
  • final white-label packaging strategy;
  • final SDK form factor.

Клиентские Данные И Truth Policy​

Клиентский слой обязан уважать truth policy из Архитектурная основа платформы vitrip.store и API Contracts.

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

  • property content может кэшироваться и безопасно читаться как stable read model;
  • offer и price view должны показывать freshness и ограничения;
  • quote должен иметь validity semantics;
  • booking UI должен явно различать pending, confirmed, failed и exception states;
  • клиентское приложение не должно скрывать revalidation-critical моменты там, где они важны для решения пользователя.

Publication And Visibility Policy Для Клиентов​

Разные клиентские поверхности должны получать разные формы объекта:

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

Monetary Breakdown Visibility Policy​

Разные клиентские поверхности также должны получать разный объём денежной структуры:

  • agency workspace может видеть richer commercial breakdown;
  • partner integration UI или partner-hosted surface может видеть только contract-approved monetary model;
  • B2C surface может видеть presentation-safe visible price и ограниченный disclosure set;
  • internal operational tools могут видеть policy trace, override source и settlement preparation context.

Это различие не должно рождаться случайно в UI. Оно должно следовать из commercial-model.md, api-contracts.md и actor/surface policy.

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

После фиксации Commercial Model — Коммерческая модель, цена, settlement и канальные условия клиентский слой обязан явно удерживать:

  • различие между preview price и quoted promise;
  • видимость repricing и утраты актуальности quote;
  • разные уровни monetary breakdown visibility для agency, partner, B2C и internal surfaces;
  • честную подачу booking follow-up, если downstream financial reality уже не тождественна исходному quote;
  • explainable связь между policy-driven price view и actor/surface context.

Клиентские Приложения И Ошибки​

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

Особенно Важны​

  • validation feedback;
  • retry-safe action handling;
  • distinction between temporary and terminal failures;
  • visibility of pending processing;
  • clear user messaging without lying about finality;
  • operator-facing diagnostics for internal tools.

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

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

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

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

  • возможный web application stack;
  • idea of partner SDK;
  • первые примеры экранов и пользовательских сценариев;
  • code-level sketches интеграционного клиента.

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

  • смешивал разные клиентские surface-ы в один слой;
  • переоценивал принцип "один API для всех";
  • делал client layer слишком hotel-centric;
  • слишком рано объявлял технологическую форму окончательной.

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

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

Клиентский слой vitiana-api-platform нужно мыслить не как один сайт и не как thin оболочку над набором endpoint-ов. Это набор разных рабочих поверхностей, связанных общим доменным ядром, но различающихся по задачам, видимости, жизненным циклам и правилам взаимодействия.

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

  • agency applications становятся главным human workflow surface;
  • internal operational tools считаются обязательной частью платформы;
  • partner integrations живут как отдельный продуктовый контур;
  • customer-facing channels проектируются отдельно, а не как копия агентского кабинета;
  • выбор конкретных UI-технологий остаётся следствием архитектуры, а не её заменой.

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