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

Tour Builder Domain — Домен композиции, draft/proposal lifecycle и пакетного продукта

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

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

Этот документ фиксирует Tour Builder как самостоятельный домен платформы, а не как вторичную UI-фичу, не как "генератор PDF" и не как thin layer над поиском, ценой и бронированием.

Его задача — определить:

  • что такое тур в контексте платформы;
  • чем TourDraft отличается от TourProposal;
  • как устроен lifecycle композиционного продукта;
  • как работает ownership model;
  • как версии и альтернативы должны жить внутри платформы;
  • как Tour Builder связан с Offer, Quote, Booking, клиентскими поверхностями и коммерческой логикой;
  • какие границы нужно провести между composition domain и transactional booking domain.

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

Почему Tour Builder Нельзя Оставлять На Уровне Feature​

В Главные выводы и проблемные зоны платформы уже зафиксировано, что Tour Builder признан важным, но пока не описан как самостоятельный домен.

Это критично, потому что если Tour Builder действительно является продуктовым differentiator платформы, он влияет сразу на:

  • агентский workflow;
  • quote lifecycle;
  • proposal semantics;
  • ownership model;
  • versioning model;
  • booking conversion path;
  • клиентские presentation surfaces;
  • PDF/export and artifact logic.

Если оставить его на уровне "у нас есть маршрут и PDF", платформа потеряет одно из своих ключевых отличий.

Главный Принцип Tour Builder Domain​

Tour Builder — это домен композиции и управляемой фиксации составного туристического предложения.

Он не строится вокруг одной брони, одного отеля или одного supplier response. Он строится вокруг controlled assembly of multiple components, связанных:

  • общей идеей поездки;
  • временной структурой;
  • ownership context;
  • коммерческим контекстом;
  • историей изменений;
  • дальнейшим переходом к клиентскому предложению и/или booking artifacts.

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

На текущем этапе слово "тур" нельзя использовать слишком расплывчато.

В контексте платформы тур может означать:

  • рабочий composition draft;
  • коммерчески оформленное предложение;
  • пакетный или полупакетный продукт;
  • программу маршрута;
  • набор связанных позиций, часть из которых bookable, часть informational or auxiliary.

Поэтому платформе нужно различать как минимум две главные сущности:

  • TourDraft
  • TourProposal

Главные Сущности Доменa​

1. TourDraft​

TourDraft — это рабочая, изменяемая композиционная сущность.

Она нужна для того, чтобы:

  • собирать маршрут;
  • держать варианты и альтернативы;
  • пробовать разные комбинации компонентов;
  • менять состав без потери истории;
  • работать с неполной определённостью;
  • готовить предложение для клиента.

TourDraft должен считаться mutable working object.

2. TourDraftItem​

TourDraftItem — отдельный элемент композиции внутри draft.

Он может представлять:

  • размещение;
  • segment of itinerary;
  • сервисный блок;
  • activity / excursion;
  • transfer;
  • manual informational block;
  • auxiliary non-bookable element;
  • future extensible package component.

Это важно: Tour Builder не должен ограничиваться только hotel stays.

3. DraftVariant / Alternative​

Платформа должна быть готова к тому, что по одному и тому же месту в маршруте существуют:

  • альтернативные offers;
  • альтернативные properties;
  • альтернативные даты;
  • альтернативные ценовые конфигурации;
  • альтернативные service bundles.

Даже если отдельная сущность DraftVariant позже будет реализована иначе, доменно это нужно считать first-class reality.

4. TourProposal​

TourProposal — это коммерчески представляемая форма результата Tour Builder.

Она должна:

  • быть связана с конкретным draft state;
  • иметь versioning;
  • иметь ownership and audience context;
  • быть пригодной для показа клиенту;
  • служить основой для export / PDF / share links / partner presentation;
  • сохранять trace to underlying offers and quotes.

5. ProposalVersion​

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

Это нужно, чтобы:

  • не терять историю;
  • объяснять, что именно было отправлено клиенту;
  • сравнивать изменения;
  • понимать, на каком основании позже был создан booking или получен отказ.

6. ProposalArtifact​

Это materialized presentation output:

  • PDF;
  • HTML share view;
  • branded export;
  • downstream presentation package.

Artifact — это производная сущность, а не доменное ядро.

Tour Builder Не Равен Booking Bundle​

Это одна из важнейших границ.

Tour Builder может подготавливать основу для будущих бронирований, но сам по себе он:

  • не равен booking;
  • не равен нескольким bookings, склеенным в UI;
  • не обязан всегда приводить к booking;
  • может содержать элементы, которые вообще не переходят в bookable flow.

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

Переход от TourProposal к booking artifacts должен быть управляемым, а не автоматически предполагаться как тождественный.

Composition Semantics​

Tour Builder должен иметь собственную логику композиции.

Она Должна Учитывать​

  • временную последовательность;
  • location continuity;
  • component compatibility;
  • occupancy compatibility;
  • policy compatibility;
  • commercial coherence;
  • ownership consistency;
  • partial uncertainty.

Что Это Меняет​

Tour Builder не может жить только как "список карточек отелей по дням". Ему нужна логика составления продукта.

Draft Lifecycle​

TourDraft должен иметь собственный lifecycle.

Минимальные Состояния Draft​

  • created
  • editing
  • structured
  • awaiting_repricing
  • awaiting_revalidation
  • ready_for_proposal
  • archived

Смысл Этого Lifecycle​

  • draft начинается как рабочий черновик;
  • постепенно получает структуру;
  • может терять актуальность при drift offers or pricing;
  • может требовать повторной проверки;
  • может становиться готовым к выпуску proposal;
  • может быть архивирован без перехода в booking.

Proposal Lifecycle​

TourProposal — отдельный жизненный цикл, не равный lifecycle draft.

Минимальные Состояния Proposal​

  • prepared
  • published
  • shared
  • viewed
  • superseded
  • expired
  • accepted_for_conversion
  • archived

Почему Это Нужно​

Потому что одно и то же draft-состояние может породить несколько proposal versions, и не каждая версия должна считаться актуальной после следующих изменений.

Ownership Model​

Tour Builder обязан быть жёстко привязан к ownership and actor context.

Для Каждого Draft / Proposal Нужно Фиксировать​

  • creating actor;
  • current owning organization;
  • tenant boundary;
  • optional customer context;
  • delegated collaborators, если нужны;
  • channel / surface context;
  • commercial profile used for visible pricing.

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

Иначе невозможно будет последовательно решить:

  • кто видит draft;
  • кто имеет право публиковать proposal;
  • кто может изменять уже показанное предложение;
  • кому принадлежат последующие booking artifacts.

Tour Builder И Offer / Quote​

Tour Builder не должен работать с “голыми hotel cards”. Его смысловой вход — это Offer и, в критических местах, Quote.

Offer Нужен Для​

  • выбора базового варианта;
  • сравнения альтернатив;
  • формирования структуры draft;
  • ранней композиции.

Quote Нужен Для​

  • коммерческой фиксации конкретного варианта;
  • подготовки клиентского предложения;
  • удержания price validity;
  • перехода к booking-aware scenario.

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

Tour Builder должен уметь жить как с offer-level неопределённостью, так и с quote-level фиксацией. Если он знает только offer или только quote, модель будет слишком слабой.

Drift Handling​

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

Drift Возникает Когда​

  • offer устарел;
  • price изменилась;
  • availability ушла;
  • policy terms изменились;
  • supplier basis перестал быть валиден;
  • часть составного маршрута стала несовместимой.

Tour Builder Должен Уметь​

  • помечать affected draft items;
  • пересчитывать proposal readiness;
  • отделять stale и still-usable элементы;
  • предлагать recomposition path;
  • не терять связь со старой версией для объяснения.

Versioning Strategy​

Versioning должен существовать не как техническая прихоть, а как доменная необходимость.

Версионировать Нужно​

  • draft snapshots at major transitions;
  • published proposals;
  • artifact generations tied to proposal version;
  • acceptance/conversion events.

Что Это Даёт​

  • auditability;
  • explainability;
  • rollback to known business state;
  • comparison between versions;
  • support for client and operator communication.

Manual And Automatic Components​

Tour Builder должен уметь работать с компонентами двух типов.

Automatic Components​

Это элементы, происходящие из:

  • offers;
  • quotes;
  • availability/pricing-derived suggestions;
  • platform-generated structures.

Manual Components​

Это элементы, добавленные человеком:

  • заметки;
  • itinerary steps;
  • custom service blocks;
  • manual pricing annotations;
  • informational content.

Почему Это Нужно Разделять​

Потому что automatic components подвержены freshness and drift, а manual components подвержены ownership and editorial control.

Bookable И Non-Bookable Elements​

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

Возможные Классы Элементов​

  • directly bookable;
  • quote-only for now;
  • informational only;
  • externally fulfilled;
  • manually arranged;
  • future component type.

Это делает Tour Builder ближе к реальному туристическому продукту, а не только к hotel bundle.

Tour Builder И Клиентские Поверхности​

Tour Builder тесно связан с Agency Working Surface, но не ограничивается ей.

Agency Surface​

Здесь происходит:

  • создание draft;
  • работа с альтернативами;
  • подготовка предложения;
  • управление версией;
  • переход к клиентскому показу.

Client-Facing Surface​

Здесь живёт уже не draft, а controlled proposal representation:

  • share view;
  • branded presentation;
  • proposal reading;
  • optional acceptance path.

Internal Operational Surface​

Может быть нужен для:

  • troubleshooting;
  • support;
  • audit;
  • governance of problematic proposals or conversions.

Tour Builder И Booking Conversion​

Tour Builder должен уметь переходить к booking artifacts, но не терять свою доменную независимость.

Возможные Модели Перехода​

  • whole-proposal conversion;
  • partial item conversion;
  • staged conversion;
  • assisted/manual operator conversion.

При Переходе Нужно Сохранять​

  • связь с proposal version;
  • связь с source quotes;
  • ownership context;
  • conversion decisions;
  • failure mapping for each affected item.

Export And Artifact Logic​

PDF и иные export outputs важны, но это не центр домена.

Artifact Layer Нужен Для​

  • customer communication;
  • partner presentation;
  • branded export;
  • attachment to external processes.

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

  • считать PDF единственным выражением tour domain;
  • терять связь между artifact и proposal version;
  • строить домен вокруг output template instead of composition truth.

Truth Boundaries В Tour Builder​

Draft Truth​

Это working composition truth, которая может быть mutable и ещё не обязана быть стабильной снаружи.

Proposal Truth​

Это published commercial presentation truth, привязанная к конкретной версии.

Artifact Truth​

Это materialized output of proposal version.

Booking Truth​

Это уже отдельный transactional слой, который может возникнуть из proposal, но не совпадает с ним.

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

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

  • TourDraft и TourProposal;
  • proposal и PDF;
  • draft item и booking item;
  • offer-based composition и booking commitment;
  • manual component и supplier-backed component;
  • published proposal и current working draft;
  • tour domain и UI page for tours.

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

Domain Model​

Domain Model — Центральная доменная модель платформы уже ввёл TourDraft, TourProposal, ProposalVersion, ProposalArtifact. Этот документ раскрывает их поведение.

Offer / Pricing / Booking Semantics​

Offer Pricing Booking Semantics — Семантика предложения, цены и бронирования нужен Tour Builder как basis for actionable and price-aware composition.

Tenancy And Identity​

Tenancy And Identity — Субъекты платформы, изоляция и модель доступа определяет ownership, visibility and publishing rights for draft/proposal flows.

Business Services​

Business Services — Сервисная декомпозиция платформы уже выделяет Tour Builder как самостоятельный сервисный контур. Здесь зафиксирован домен, который этот контур должен обслуживать.

API Contracts​

API Contracts — Surface Contracts и правила внешнего взаимодействия описывает Tour Builder как stateful composition surface. Этот документ задаёт его внутренний смысл.

Clients​

Clients Layer — Клиентские поверхности и рабочие модели должен строить agency and client-facing workflows вокруг этой модели, а не вокруг случайного CRUD по tours.

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

После фиксации Tour Builder domain следующим обязательным документом должен быть:

  • data governance and matching

Потому что после domain-model, identity и offer/booking semantics именно governance остаётся последним большим незакрытым контуром второго слоя.

Затем нужно будет вернуться и синхронизировать:

  • api-contracts.md в части draft/proposal operations;
  • clients.md в части Tour Builder workflows;
  • storage.md в части version and artifact persistence;
  • будущий документ про commercial model and proposal pricing.

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

Tour Builder в vitiana-api-platform нужно мыслить как отдельный домен композиции и коммерческой фиксации составного продукта.

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

  • TourDraft — mutable working composition;
  • TourProposal — versioned commercial presentation;
  • ProposalArtifact — производный output;
  • Tour Builder работает на базе Offer и Quote, но не сводится к ним;
  • Tour Builder может приводить к booking artifacts, но не равен им;
  • versioning, ownership, drift handling и conversion semantics являются обязательной частью домена, а не дополнительными деталями.

Уточнение под Фазы 4–6 (28.04.2026) — operational model, partner-grade SDK, правило 00000​

После Фаз 4–6 каноничной архитектуры (25–27.04.2026) Tour Builder получил несколько критичных расширений, которые должны быть явно зафиксированы для всех потребителей этого документа. Этот документ остаётся как семантический контур композиционного домена, но операционная истина теперь живёт в специализированном документе фазы 5.

Операционная модель Tour Builder — каноничная истина в tour-builder-operational-model.md​

В этом документе зафиксировано что есть TourDraft, TourProposal, DraftVariant. Каноничная операционная реализация — в reference/tour-builder-operational-model.md (Фаза 5):

  • CompositionRule engine — правила совместимости модулей тура (accommodation + transfer + activity + service + transport rental + insurance + custom + informational);
  • TourBookingTransaction saga — координация бронирования multi-component тура с компенсациями при сбое одного из шагов;
  • DriftEvent — каноничное событие, когда underlying offer/quote устарел во время работы с draft (это уточняет «drift handling» из этого документа);
  • CompensationEvent — saga rollback actions при partial booking failure;
  • State machine TourDraft — created → editing → structured → awaiting_repricing → awaiting_revalidation → ready_for_proposal → archived (см. overview/canonical-domain-spine.md);
  • State machine TourProposal — prepared → published → shared → viewed → superseded → expired → accepted_for_conversion → archived.

Связь с booking state machine: каждый компонент тура — отдельный Booking со своим lifecycle (см. reference/booking-state-machine.md, 14 состояний); saga координирует их состояния как единое транзакционное целое.

Tour Builder как core platform с правилом 00000​

Согласно архитектурному якорю (overview/architectural-anchor-and-business-model.md) и правилу 00000 (платформа главенствует над поставщиками):

  • Tour Builder — core платформы, не вспомогательная UI-фича (это уже зафиксировано в этом документе);
  • Tour Builder — partner-grade peer surface (см. reference/clients.md, Surface 4 Partner UI/SDK): партнёры с платным доступом к API получают полноценный Tour Builder UI/SDK, не упрощённую копию agency Tour Builder;
  • partners получают raw API constructor (composition primitives) и UI components (npm package), которые могут embedd в свой канал.

Каноничная attribute: Tour Builder доступен на следующих контурах:

КонтурУровень доступаTier
Internal Operationalfull lineage + governance—
Agency Working Surfacecomposer view + history—
Partner Tour Builder UI/SDKfull peer Tour BuilderProfessional+, Enterprise
B2C (vitrip.store)published proposal view (только share link)—
White-label embeddedpartner-defined visibilityпо контракту

Partner-grade SDK — каноничная реализация​

Согласно reference/api-as-product.md и development/proposal-stack-roadmap-by-product-tier.md:

  • partner Tour Builder SDK — отдельный npm package @vitiana/tour-builder (Vite library mode);
  • переиспользуется в agency app (Vite SPA) и partner app (Vite SPA);
  • partners могут embedd composition primitives в свой канал (Surface 6 White-Label);
  • partner-side composition rules опираются на каноничные CompositionRule объекты (через partner-grade API);
  • saga для partner-initiated booking transactions работает идентично agency flow (правило 00000 — partners не получают «упрощённой» версии).

Связь с Multi-Tenant Isolation​

Tour Builder композиции живут в Workspace context (под-boundary внутри Tenant — см. reference/tenancy-and-identity.md, уточнение под Фазы 4–6):

  • TourDraft принадлежит конкретному Workspace внутри Tenant;
  • TourProposal версионирован в Workspace context;
  • visibility ограничена IsolationBoundaryCheck (см. reference/multi-tenant-isolation-strength.md);
  • для tenant Enterprise с dedicated_compute — Tour Builder workloads в выделенном namespace.

Связь с платёжным доменом​

Booking conversion из Tour Builder включает payment intent для каждого компонента (см. reference/payment-domain.md):

  • single PaymentIntent для всего тура (предпочтительно) или multi-PaymentIntent (один на компонент) — зависит от композиции;
  • saga координирует payment lifecycle с booking lifecycle;
  • refund handling для частичной отмены тура (один компонент отменён, остальные сохраняются) — отдельный канал reference/post-booking-lifecycle.md.

Связь с экономической моделью​

Tour Builder как paid feature (Professional+ tier) генерирует:

Связь с компонентами через 8 каноничных модулей​

Каноничный список модулей тура (см. overview/canonical-domain-spine.md):

  1. модуль размещения (accommodation segment);
  2. модуль переезда (transfer segment);
  3. модуль активности (activity);
  4. модуль услуги (service);
  5. модуль аренды транспорта (transport rental);
  6. модуль страхования (insurance);
  7. пользовательский модуль (custom block);
  8. информационный модуль (informational block).

Каждый модуль имеет свой контракт совместимости (compatibility check через CompositionRule) и свои операционные правила.

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

Этот документ остаётся семантическим контуром композиционного домена (что есть TourDraft, TourProposal, как они связаны с Offer/Quote, ownership, versioning). Расширения и реализация:

При конфликте с этим документом — истина в каноничном специализированном (правило single source of truth per domain).

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

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