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

Offer Pricing Booking Semantics — Семантика предложения, цены и бронирования

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

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

Этот документ фиксирует единый смысловой контур для Offer, Quote, price views, revalidation и Booking.

Его задача — снять главный архитектурный разрыв между:

  • доменной моделью;
  • сервисной декомпозицией;
  • API-контрактами;
  • клиентскими поверхностями;
  • коммерческим и transactional поведением платформы.

Именно здесь должно быть окончательно зафиксировано:

  • что такое Offer в платформе;
  • чем Offer отличается от Property, CanonicalProduct, SupplierProduct и Quote;
  • какие уровни цены существуют;
  • что считается revalidation;
  • когда можно переходить к booking;
  • что именно означает Booking как транзакционная сущность;
  • какие состояния, truth boundaries и failure semantics обязательны.

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

Почему Это Следующий Критический Документ​

В Главные выводы и проблемные зоны платформы уже зафиксировано, что offer-level модель пока недоопределена, а без неё нельзя строить pricing и booking.

Это критично, потому что пока платформа не различает жёстко:

  • стабильный продуктовый контекст;
  • краткоживущий actionable offer;
  • actor-specific quote;
  • booking commitment;

она неизбежно будет:

  • возвращаться к hotel-centric thinking;
  • путать “цена на карточке” и commit-ready price;
  • смешивать UI view и transactional truth;
  • терять связь между supplier reality и booking state.

Главный Принцип Offer / Pricing / Booking Semantics​

Платформа должна различать четыре принципиально разных уровня:

  1. Product basis
  2. Offerable operational state
  3. Quoted commercial fixation
  4. Transactional booking commitment

Эти уровни связаны между собой, но не являются взаимозаменяемыми.

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

  • truth discipline;
  • explainability;
  • revalidation logic;
  • contract honesty;
  • failure isolation.

Базовые Сущности Семантического Контура​

1. Product Basis​

Это основа, на которой вообще возможно предложение.

Сюда входят:

  • Property
  • CanonicalProduct
  • SupplierProperty
  • SupplierProduct

Этот слой описывает, что вообще существует как объект и продуктовая единица.

Он не отвечает на вопрос:

  • можно ли это продать сейчас;
  • по какой цене;
  • под какого актора;
  • можно ли это уже бронировать.

2. Offer​

Offer отвечает на вопрос:

какая конкретная action-ready возможность существует сейчас для данного product basis при данных датах, occupancy, условиях и видимом ценовом контексте.

Offer — это не просто найденный отель и не просто “номер с ценой”.

Offer должен быть:

  • time-scoped;
  • occupancy-scoped;
  • policy-aware;
  • supplier-aware;
  • freshness-aware;
  • commercially interpretable;
  • ready for comparison and quote transition.

3. Quote​

Quote отвечает на вопрос:

что именно платформа зафиксировала как коммерчески и операционно значимое предложение для конкретного actor/tenant/channel в конкретный момент времени.

Quote — это уже не просто operational opportunity. Это коммерчески значимая фиксация.

4. Booking​

Booking отвечает на вопрос:

какой transactional commitment был инициирован, к какому результату он привёл и в каком состоянии находится сейчас.

Booking — это не расширенный quote и не просто supplier response wrapper.

Что Такое Offer На Самом Деле​

Платформа должна жёстко закрепить смысл Offer, потому что это главный операционный центр всей модели.

Offer Должен Отвечать На Следующие Вопросы​

  • какой Property и CanonicalProduct он представляет;
  • какой SupplierProduct лежит в его основании;
  • на какие даты и для какой occupancy он релевантен;
  • какая price view сейчас видна;
  • какие ограничения и policy terms действуют;
  • какова freshness этого состояния;
  • нужна ли обязательная revalidation;
  • допускается ли переход к quote или booking.

Offer Не Должен Подменять Собой​

  • property content;
  • supplier raw payload;
  • final quote;
  • booking state;
  • finance settlement figure.

Offer Как Operational Promise​

Offer — это не обещание финального исхода. Это controlled operational representation, достаточно честная, чтобы:

  • показываться пользователю или системе;
  • участвовать в сравнении;
  • использоваться как вход в quote path;
  • при определённых условиях переходить к booking.

Но он обязан содержать собственные ограничения.

Offer Identity​

У Offer должна быть своя идентичность, независимая от hotelId или roomTypeId.

Offer Identity Должна Включать По Смыслу​

  • product basis reference;
  • supplier basis reference;
  • stay/date scope;
  • occupancy;
  • meal/cancellation/restriction basis;
  • currency/pricing context;
  • freshness basis;
  • optional actor-sensitive visibility basis.

Почему Это Важно​

Потому что один и тот же Property может одновременно иметь:

  • несколько supplier-backed offers;
  • несколько occupancy variants;
  • несколько cancellation profiles;
  • несколько meal plan variants;
  • разные visible prices для разных actors.

Значит, hotelId никогда не может быть достаточным transactional identifier.

Price Semantics​

Одна из самых опасных зон платформы — это смешение уровней цены.

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

1. Supplier Raw Price​

Это цена, пришедшая от поставщика, как он её возвращает в своей модели.

Она может:

  • быть неполной;
  • иметь supplier-specific tax logic;
  • не учитывать tenant-specific commercial rules;
  • не быть пригодной для прямого показа клиенту.

2. Normalized Base Price​

Это цена после приведения supplier reality к внутренней нормализованной форме.

Она нужна для:

  • сопоставимости;
  • downstream calculations;
  • explainability;
  • offer assembly.

3. Commercial Rule Output​

Это цена после применения platform/tenant/channel-specific коммерческой логики:

  • markup;
  • commission;
  • fee;
  • discount;
  • partner override;
  • agency rule;
  • currency conversion policy.

4. Quoted Price​

Это финальная цена, зафиксированная в рамках Quote для конкретного actor context.

Именно quoted price является тем уровнем, который ближе всего к честному коммерческому обещанию платформы в пределах quote validity.

5. Settlement-Relevant Price​

Это цена или набор денежных величин, которые нужны уже для:

  • расчётов;
  • финансовой отчётности;
  • partner settlement;
  • agency commission accounting;
  • refund handling.

Что Нельзя Больше Смешивать​

  • supplier raw price и quoted price;
  • UI price preview и booking-time confirmed price;
  • partner contract price и client-facing display price;
  • quoted price и settlement-relevant figures.

Price View Как Actor-Sensitive Сущность​

Цена в платформе не существует в отрыве от контекста.

Price View Должен Учитывать​

  • tenant;
  • organization type;
  • actor context;
  • partner contract;
  • agency rules;
  • currency context;
  • channel policy;
  • visibility policy.

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

Один и тот же Offer может иметь:

  • разный visible price view;
  • разный markup structure;
  • разную коммерческую пригодность;
  • разные eligibility rules

для разных actor-ов.

При этом product basis и часть operational basis могут оставаться теми же.

Quote Semantics​

Quote — это обязательный доменный слой между offer и booking.

Quote Нужен Для Того, Чтобы​

  • зафиксировать конкретную интерпретацию offer;
  • зафиксировать конкретную price view;
  • зафиксировать actor/tenant/channel context;
  • определить окно валидности;
  • подготовить безопасный переход к booking;
  • удержать trace для объяснения, что именно было предложено.

Quote Должен Включать По Смыслу​

  • source offer reference;
  • quoted price breakdown;
  • tenant and ownership context;
  • actor / workspace / channel context;
  • applied commercial policy reference;
  • traveler assumptions, если применимо;
  • validity window;
  • revalidation requirement;
  • repricing basis;
  • publication readiness;
  • transition contract toward booking;
  • links to governing policies and restrictions.

Quote Не Должен Быть​

  • просто кешом offer response;
  • только UI session object;
  • финальным booking record.

Quote Как Commercial Fixation​

Quote должен пониматься не только как operational bridge, но и как коммерческая фиксация.

Это означает, что он должен удерживать:

  • применённую commercial policy;
  • итоговую actor-sensitive price view;
  • допустимый scope публикации;
  • условия, при которых quoted promise ещё можно считать честным;
  • различие между quoted commercial promise и будущими settlement-relevant figures.

Именно поэтому Quote не должен вычисляться заново “по месту” клиентским слоем или booking flow без явной revalidation / repricing semantics.

Freshness And Revalidation​

Платформа должна считать freshness и revalidation центральными понятиями этого контура.

Freshness Отвечает На Вопрос​

насколько оперативное состояние ещё пригодно для действия.

Revalidation Отвечает На Вопрос​

нужно ли перед следующим критическим шагом заново проверить:

  • availability;
  • price;
  • restrictions;
  • cancellation implications;
  • supplier-side feasibility.

Revalidation Нельзя Считать Только Техническим Retry​

Это доменная операция, потому что она может привести к:

  • подтверждению offer/quote assumptions;
  • изменению цены;
  • изменению availability;
  • изменению policy terms;
  • отказу в продолжении flow.

Revalidation И Repricing Нужно Различать​

Платформа должна различать:

  • revalidation без изменения quoted price;
  • repricing с сохранением business viability;
  • repricing, которое делает прежний quote недействительным;
  • supplier drift, который не меняет видимую цену, но меняет settlement or policy basis.

Без этого система будет либо слишком часто ломать quote path, либо слишком часто лгать о сохранности исходного коммерческого обещания.

Базовые Типы Revalidation​

  • soft revalidation
  • hard revalidation
  • booking-time mandatory revalidation
  • manual or operator-triggered revalidation

Eligibility For Next Step​

Каждый Offer и Quote должен иметь смысловую eligibility-оценку.

Offer Eligibility Должна Отвечать На Вопросы​

  • можно ли из offer перейти к quote;
  • можно ли сразу инициировать booking path;
  • есть ли missing data;
  • есть ли freshness limits;
  • есть ли supplier-side restrictions.

Quote Eligibility Должна Отвечать На Вопросы​

  • можно ли создать booking intent;
  • требуется ли повторная проверка;
  • истёк ли quote;
  • хватает ли traveler/commercial data;
  • не нарушены ли tenant or partner rules.

Booking Semantics​

Booking должен мыслиться как stateful transactional commitment process.

Booking Начинается Не С Supplier Confirmation​

Он начинается с booking intent, который строится на базе:

  • source quote;
  • или equivalent validated basis, если домен допускает такой путь.

Booking Включает Несколько Уровней Реальности​

  • platform intent;
  • internal booking state;
  • supplier attempt/result;
  • commercial ownership;
  • payment implications;
  • settlement implications;
  • amendment/cancellation potential.

Booking Не Должен Подменяться Одним Статусом​

Платформе нужен полноценный lifecycle, а не pending / confirmed / cancelled.

Базовая State Model Для Booking​

На текущем уровне зрелости нужно как минимум различать:

  • draft_intent
  • submitted
  • pending_revalidation
  • pending_supplier_confirmation
  • supplier_confirmed
  • platform_confirmed
  • partially_failed
  • failed
  • cancel_requested
  • cancel_pending
  • cancelled
  • amendment_requested
  • amendment_in_progress
  • completed
  • unknown_external_state

Почему Здесь Есть И supplier_confirmed, И platform_confirmed​

Потому что supplier positive response и platform-level commit finalization не всегда являются одним атомарным моментом.

Платформа может:

  • ещё фиксировать внутренние инварианты;
  • запускать post-processing;
  • ждать payment finalization;
  • проверять reconciliation conditions.

Booking Failure Semantics​

Платформа должна рассматривать failure как first-class часть модели.

Возможные Классы Failure​

  • validation failure before commit;
  • quote expired;
  • revalidation mismatch;
  • supplier rejection;
  • supplier timeout;
  • uncertain external state;
  • payment-related failure;
  • partial downstream failure;
  • cancellation failure;
  • amendment failure.

Почему Это Нужно Фиксировать Отдельно​

Потому что без этого клиентские поверхности, partner contracts и support workflows начинают лгать о реальном состоянии системы.

Booking Ownership And Commercial Responsibility​

Booking всегда должен иметь ownership context.

Минимально Нужно Фиксировать​

  • under which tenant booking was created;
  • by which actor context;
  • for which organization;
  • under which commercial profile;
  • through which client or contract surface;
  • with which partner or agency ownership.

Это критично для:

  • visibility;
  • audit trail;
  • support routing;
  • reporting;
  • settlement.

Booking Не Должен Терять Связь С Quote Context​

Даже если booking lifecycle живёт отдельно, система должна сохранять:

  • на базе какого quote был создан booking intent;
  • какая commercial policy действовала в момент commit;
  • был ли commit выполнен по исходному quote или после repricing;
  • какие расхождения между quoted promise и downstream financial reality возникли позже.

Это критично для dispute handling, support, audit и settlement explainability.

Supplier Correlation In Booking​

Booking обязан хранить supplier-side correlation, но не растворяться в нём.

Нужно Различать​

  • platform booking ID;
  • supplier reservation/booking reference;
  • supplier confirmation state;
  • supplier-side cancellation reference;
  • supplier-side amendment reference.

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

Supplier identifier никогда не должен подменять собой platform booking identity.

Idempotency And Safe Retries​

В этом контуре идемпотентность — обязательное свойство.

Особенно Для​

  • booking submission;
  • confirm-like actions;
  • cancel request;
  • amendment request;
  • quote consumption;
  • webhook/event processing.

Платформа Должна Уметь​

  • принимать client-supplied idempotency key;
  • различать duplicate and distinct intent;
  • возвращать retry-safe stateful response;
  • объяснять pending/unknown situations без ложного confirmation.

Truth Boundaries В Этом Контуре​

Offer Truth​

Это operational truth, пригодная для чтения и действий, но ограниченная freshness and revalidation conditions.

Quote Truth​

Это actor-specific commercial truth within a validity window.

Booking Truth​

Это transactional truth о commit process and state.

Settlement Truth​

Это финансовая truth, которая может зависеть от booking events, но не обязана совпадать с UI-visible quote price в один момент времени.

Governance Truth​

Это truth о том, почему система приняла или не приняла определённое решение в спорных случаях.

Что Нельзя Больше Путать​

После фиксации этого документа в других материалах ошибкой должно считаться смешение:

  • Property и Offer;
  • Offer и Quote;
  • Quote и Booking;
  • display price и quoted price;
  • quoted price и settlement price;
  • commercial fixation и transactional commit;
  • revalidation и просто технический retry;
  • supplier confirmation и platform confirmation;
  • booking failure и unknown external state.

Что Commercial Model Требует От Этого Документа​

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

Quote Должен Быть Commercial Promise, А Не Только Technical Bridge​

Quote должен фиксировать не просто “подходящую цену на текущий момент”, а управляемое коммерческое обещание в пределах своей validity window.

Это требует:

  • actor-aware price semantics;
  • channel-aware visibility semantics;
  • applied commercial policy trace;
  • publication readiness;
  • понятной границы между quoted price и settlement-relevant figures.

Канальные Различия Должны Быть Видны Уже На Уровне Semantics​

Один и тот же Offer может перейти в разные Quote-состояния для:

  • agency surface;
  • partner surface;
  • B2C surface;
  • internal operational surface.

Поэтому этот документ должен трактовать Quote как channel-sensitive объект, а не как универсальную денежную проекцию.

Repricing Должен Быть Первоклассной Семантикой​

Между Quote и Booking должна существовать честная логика:

  • когда достаточно revalidation;
  • когда нужен repricing;
  • когда repricing сохраняет коммерческую приемлемость;
  • когда repricing разрушает исходное коммерческое обещание.

Booking И Settlement Должны Быть Связаны, Но Не Слиты​

Booking остаётся transactional commitment process.

Но этот документ должен явно признавать, что downstream financial reality:

  • использует booking events;
  • зависит от quote context;
  • не обязана быть тождественной quoted price;
  • требует отдельного settlement truth layer.

Связь С Уже Переписанными Документами​

Domain Model​

Domain Model — Центральная доменная модель платформы задаёт сущности Offer, Quote, Booking. Этот документ раскрывает их поведение и смысловые границы.

Tenancy And Identity​

Tenancy And Identity — Субъекты платформы, изоляция и модель доступа объясняет, почему Quote и Booking всегда actor/tenant-sensitive.

Business Services​

Business Services — Сервисная декомпозиция платформы уже различает Offer Service, Pricing, Quote And Commercial Service и Booking Service. Этот документ даёт этим сервисам согласованную семантическую основу.

Commercial Model​

Commercial Model — Коммерческая модель, цена, settlement и канальные условия объясняет, почему Quote должен считаться коммерческой фиксацией и почему quoted price не равен settlement-relevant figures. Этот документ связывает эти денежные слои с operational path Offer → Quote → Booking.

API Contracts​

API Contracts — Surface Contracts и правила внешнего взаимодействия строит resource families around Offer, Quote and Booking. Этот документ делает их meaning explicit.

Storage​

Storage Layer — Модель хранения и жизненный цикл данных объясняет, где живут offer snapshots, quote sessions and booking state. Этот документ объясняет, зачем они доменно различаются.

Clients​

Clients Layer — Клиентские поверхности и рабочие модели должен строить рабочие сценарии вокруг этих semantics, а не вокруг hotel-card thinking.

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

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

  • database-schema.md в части offer/quote/booking projections;
  • api-contracts.md в части resource semantics and state responses;
  • clients.md в части compare/quote/booking workflows;
  • commercial-model.md в части quote promise, repricing and settlement links;
  • tour-builder-domain.md, потому что он зависит от offer and quote semantics.

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

Платформа должна мыслить этот контур так:

  • Offer — operational actionable representation;
  • Quote — actor-specific commercial fixation with validity;
  • Booking — stateful transactional commitment process;
  • price — это не одна величина, а набор разных truth levels;
  • revalidation — это доменная операция, а не просто техническая проверка;
  • supplier response — это важная часть booking reality, но не вся её истина.

Именно эта модель должна дальше удерживать search-to-quote-to-booking path как зрелый промышленный контур, а не как цепочку loosely coupled экранов и endpoint-ов.

Уточнение под Фазы 4–6 (28.04.2026) — каноничные именования и связи​

После Фаз 4–6 каноничной архитектуры (25–27.04.2026) часть смыслов этого документа углублена в специализированных документах. Этот документ остаётся как семантический контур Offer/Quote/Booking, но именования состояний и интеграция с Payment, Tour Builder, Multi-Tenant Isolation теперь определяются в специализированных источниках.

Каноничные имена 14 состояний Booking — booking-state-machine.md​

В разделе «Базовая State Model Для Booking» этого документа перечислены 15 элементов с рабочими именованиями. Каноничная истина — 14 состояний в reference/booking-state-machine.md:

draft → submitted → pending_revalidation → pending_supplier_confirmation → supplier_confirmed → platform_confirmed → partially_confirmed → unknown_external_state → failed → cancel_requested → cancel_in_progress_supplier → cancelled → amendment_in_progress → completed = 14 состояний.

Различия в именовании:

Имя в этом документеКаноничное имя
draft_intentdraft
partially_failedpartially_confirmed
cancel_pendingcancel_in_progress_supplier
amendment_requested (отдельный)(отсутствует — состояние сразу amendment_in_progress)

При создании контрактов API, AsyncAPI событий, кодовых артефактов и аналитических проекций — использовать только каноничные имена из booking-state-machine.md.

Платёжный домен — каноничная истина в payment-domain.md​

Этот документ упоминает PaymentIntent как часть booking lifecycle (booking includes commercial ownership, payment implications, settlement implications). Каноничная модель платёжного домена — в reference/payment-domain.md (Фаза 4):

  • PaymentIntent lifecycle (created → awaiting_method → method_attached → authorized → captured → succeeded или canceled / failed);
  • PaymentTransaction — фактическая транзакция через PSP;
  • Refund lifecycle;
  • Chargeback workflow;
  • Settlement каноничные сущности;
  • PSP abstraction (Stripe / Adyen / Mollie через единый адаптер);
  • PCI DSS compliance через PSP-only handling (zero-touch к card data).

Связь с booking state machine: pending_supplier_confirmation требует PaymentIntent.authorized; transition к platform_confirmed требует PaymentIntent.captured.

Tour Builder operational model — каноничная истина в tour-builder-operational-model.md​

Этот документ говорит «tour-builder-domain.md... зависит от offer and quote semantics». Каноничная операционная истина для Tour Builder, включая saga, drift detection, compensation — в reference/tour-builder-operational-model.md (Фаза 5):

  • CompositionRule engine;
  • TourBookingTransaction saga state с компенсациями при сбое одной из позиций;
  • DriftEvent — когда underlying offers устаревают;
  • CompensationEvent — saga rollback actions;
  • связь с booking state machine — каждый компонент тура — отдельный booking, координируется sagа.

Multi-tenant isolation — каноничная истина в multi-tenant-isolation-strength.md​

Quote и Booking явно tenant-aware (этот документ это говорит). Уровни изоляции и IsolationBoundaryCheck — в reference/multi-tenant-isolation-strength.md (Фаза 5):

  • три уровня: logical / dedicated_compute / dedicated_infrastructure;
  • автоматизированный IsolationBoundaryCheck;
  • per-tier deployment shape (см. также operations/deployment.md).

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

Этот документ остаётся семантическим контуром Offer/Quote/Booking — он определяет что значат эти сущности, какие у них truth boundaries, какие правила revalidation/repricing. Имена состояний и детальные процессы (Payment lifecycle, Tour saga, Tenant isolation level) — в специализированных документах:

При конфликте между этим документом и каноничным специализированным — истина в специализированном (правило single source of truth per domain, см. development/documentation-governance.md).

Уточнение выполнено через no-destruction: текст этого документа выше не правится.

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