Каноничная доменная ось платформы (ось 1)

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

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

Этот документ — раскрытие первой оси верхнеуровневой архитектуры: каноничная доменная ось (canonical domain spine). Он отвечает на вопросы: какие сущности являются каноничными, какие — производными от поставщиков, какие — операционными, транзакционными, композиционными, governance-сущностями, как они связаны между собой, какие у них жизненные циклы, и как доменная ось проявляется на других пяти осях архитектуры.

Это верхнеуровневое описание. Детальная семантика каждой сущности — в документах второго круга (reference/domain-model.md, reference/offer-pricing-booking-semantics.md, reference/tenancy-and-identity.md, reference/tour-builder-domain.md и других).

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

Главный принцип каноничной модели

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

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

• поле в каноничной модели появляется потому, что домен Vitiana требует его существования, а не потому, что «у Stuba так возвращается»;
• если поставщик не предоставляет нужного поля — это технический долг ingestion adapter, не недостаток модели;
• любой поставщик отключаем без переделки каноничной модели;
• любой новый поставщик подключается через новый ingestion adapter, без расширения каноничных полей.

Семь групп каноничных сущностей

Каноничные сущности делятся на семь групп по их роли в платформе. Каждая группа имеет свою политику истины (truth policy), свой жизненный цикл, свои правила видимости на поверхностях.

Группа 1. Каноничные мастер-сущности (canonical master entities)

Что включает:

• Property — каноничная сущность объекта размещения как стабильной мастер-записи платформы;
• CanonicalProduct — каноничная продуктовая единица внутри property context;
• Organization — родовая сущность организации;
• User — пользователь;
• Partner — партнёр (специализация Organization);
• Agency — туристическое агентство (специализация Organization);
• PolicySet — набор политик (commercial, governance, operational);
• GovernanceDecision — формализованное решение управления данными.

Политика истины: master truth — долгоживущая, audit-critical, изменяется только через governance.

Жизненный цикл: candidate → mapped → canonicalized → enriched → revised → governed.

Где живёт: постоянная модель платформы (managed PostgreSQL Public Cloud в фазе Bootstrap; Bare Metal Scale в фазе 3+).

Видимость на поверхностях: различная per-surface; полная видимость на Internal Operational Surface, контракт-безопасное представление на Partner API Surface, презентационное на B2C.

Группа 2. Сущности, производные от поставщиков (supplier-derived entities)

Что включает:

• Supplier — поставщик информации;
• SupplierProperty — supplier-specific представление того, что потенциально соответствует Property;
• SupplierProduct — supplier-specific продаваемая единица;
• SupplierPayload — сырая полезная нагрузка от поставщика;
• SupplierSyncRun — запуск синхронизации;
• SupplierCapabilityProfile — профиль возможностей поставщика (что он умеет давать);
• SupplierBookingReference — ссылка на бронирование на стороне поставщика.

Политика истины: supplier truth — append-heavy, replay-friendly, отдельная от master truth.

Жизненный цикл: received → parsed → normalized → mapped → consumed_in_canonical_update or rejected_to_governance.

Где живёт: persistent supplier trace layer (отдельный от canonical layer).

Видимость на поверхностях: только Internal Operational и Service-to-Service. Внешние поверхности не видят supplier-derived entities в их сыром виде.

Главный принцип: supplier-derived entities никогда не подменяют canonical entities. Они существуют параллельно как trace того, что пришло от поставщика.

Группа 3. Операционные сущности предложения (operational offer entities)

Что включает:

• Offer — конкретное предложение, пригодное для показа, quotation, revalidation, потенциального бронирования;
• AvailabilitySnapshot — краткоживущая фиксация состояния доступности;
• PriceSnapshot — краткоживущая фиксация технической или коммерчески нормализованной цены;
• Quote — actor-aware коммерческая фиксация (commercial promise);
• RevalidationResult — результат повторной проверки;
• SearchSession — сессия поиска.

Политика истины: operational truth — краткоживущая, но не одноразовая; reproducible, audit-friendly для retention-grade требований.

Жизненный цикл Offer: computed → surfaced → compared → quoted → expired / revalidated / superseded.

Жизненный цикл Quote: created → active → revalidated / stale → expired / consumed.

Где живёт: persistent operational layer + rebuildable cache. Quote с audit-significant ролью — в persistent layer.

Видимость на поверхностях:

• Offer — все основные поверхности с разной детализацией;
• Quote — actor-aware видимость; на Agency полная структура, на Partner контракт-безопасная, на B2C финальная цена;
• AvailabilitySnapshot, PriceSnapshot — внутренние, видимы только Internal и S2S.

Группа 4. Транзакционные сущности (transactional entities)

Что включает:

• Booking — транзакционная фиксация подтверждённой или partially-resolved коммерческой операции;
• BookingItem — элемент бронирования;
• BookingEvent — событие в lifecycle бронирования;
• PaymentIntent — намерение платежа;
• Refund — возврат;
• AmendmentRequest — запрос на изменение бронирования.

Политика истины: transactional truth — audit-critical, retention-grade, никогда не теряется.

Жизненный цикл 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.

Полное описание state machine — reference/booking-state-machine.md фазы 5.

Где живёт: persistent transactional layer; должна переживать инциденты, расследования, reconciliation, споры, финансовую отчётность.

Видимость на поверхностях:

• Internal — полный lifecycle + audit;
• Agency — полное состояние своих бронирований;
• Partner — контракт-безопасное состояние своих бронирований через webhooks + read API;
• B2C — собственные бронирования с упрощённой видимостью;
• S2S — полное состояние.

Группа 5. Композиционные сущности (composition entities)

Что включает:

• TourDraft — рабочая, изменяемая композиционная сущность;
• TourDraftItem — отдельный элемент композиции внутри draft;
• DraftVariant — альтернативный вариант элемента;
• TourProposal — коммерчески представляемая форма результата Tour Builder;
• ProposalVersion — версия proposal;
• ProposalArtifact — материализованный output (PDF, share-link, branded export).

Политика истины:

• TourDraft — мутабельная working composition truth;
• TourProposal — published commercial presentation truth, привязанная к версии;
• ProposalArtifact — materialized output of proposal version.

Жизненный цикл TourDraft: created → editing → structured → awaiting_repricing → awaiting_revalidation → ready_for_proposal → archived.

Жизненный цикл TourProposal: prepared → published → shared → viewed → superseded → expired → accepted_for_conversion → archived.

Где живёт: persistent layer для draft / proposal / version metadata; object storage для artifact blobs.

Видимость на поверхностях:

• Tour Builder Closed Surface — first-class;
• Agency Working Surface — composer view + history;
• Partner API Surface — только при наличии paid Tour Builder tier;
• B2C — published proposal view по share-ссылке.

Главный принцип: composition entities — это модульный продукт, состоящий из:

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

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

Группа 6. Сущности управления и проверки (governance and review entities)

Что включает:

• ReviewCase — кейс проверки данных;
• MappingDecision — решение о маппинге supplier entity к canonical;
• MergeDecision — решение о слиянии данных от нескольких поставщиков;
• Anomaly — обнаруженная аномалия данных или операционная;
• FieldLineage — происхождение значения каждого поля canonical entity;
• SourcePrecedenceRule — правило приоритета источника при конфликте.

Политика истины: governance truth — долгоживущая, audit-critical; обеспечивает explainability платформы.

Жизненный цикл ReviewCase: detected → queued → reviewed → decided → applied / rejected → audited.

Где живёт: persistent governance layer. Никогда не уходит в чистый cache или unreliable очереди.

Видимость на поверхностях:

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

Группа 7. Сущности субъектов, тенантов и доступа (identity, tenancy, access entities)

Что включает:

• Tenant — boundary of isolation and policy application;
• Workspace — рабочее пространство внутри tenant;
• RoleAssignment — назначение роли пользователю;
• CapabilityGrant — выданное право (атомарное или полуатомарное);
• ApiClient — machine subject для machine access;
• ApiCredential — учётные данные API-клиента;
• ActorContext — текущий рабочий контекст identity (тот же User может быть в разных actor-контекстах).

Политика истины: master truth для основных сущностей; runtime state для access markers (rate windows, idempotency keys) — отдельный класс.

Где живёт: persistent layer для identity и tenancy truth; runtime cache для коротких access markers.

Видимость на поверхностях: subject-aware, tenant-aware, capability-aware на всех поверхностях.

Главный принцип: identity, tenancy, capability, contract — четыре разные сущности, не одна. Identity отвечает «кто», tenant — «где», capability — «что», contract — «как». Не сливать в один «role» или один «user type».

Группы сущностей и поверхности — матрица видимости

Группа сущностей	Internal	Agency	Partner	B2C	S2S	Tour Builder
Canonical Master	Full + lineage	Content + structure	Contract-safe content	Presentation-safe	Full	Content + module
Supplier-derived	Full	Limited (governance UI)	Hidden	Hidden	Full	Hidden
Operational Offer	Full + governance state	Full operational + commercial	Contract-safe with freshness	Indicative	Full	As composable input
Transactional	Full lifecycle + audit	Own state	Own contract-safe state	Own only	Full	As composition output
Composition	Full	Composer view	Tour Builder tier only	Published view	Full	First-class
Governance/Review	Full	Hidden	Hidden	Hidden	Full	Hidden
Identity/Tenancy/Access	Full	Own context	Own context	Hidden	Full	Own

Доменные контуры

Сущности группируются в доменные контуры — операционные процессы, в которых участвуют разные группы сущностей.

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

Сущности: Supplier, SupplierPayload, SupplierProperty, SupplierProduct, SupplierSyncRun + Property, CanonicalProduct.

Процесс: supplier reality → ingestion adapter → normalization → mapping → governance review or auto-update of canonical.

Главное правило: ingestion adapter переводит произвольные представления в каноничную модель Vitiana, не наоборот.

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

Сущности: SearchSession + Property, Offer (в виде поисковой проекции).

Процесс: intent capture → ranking → fasceting → result delivery.

Главное правило: результат поиска — не offer-объект напрямую, а проекция (search projection), оптимизированная для read-heavy traffic.

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

Сущности: Offer, AvailabilitySnapshot, PriceSnapshot, Quote, RevalidationResult.

Процесс: discovery → offer materialization → commercial interpretation → quote fixation → revalidation/repricing.

Главное правило: Quote — actor-aware фиксация, не «ещё одна цена на карточке». Quote удерживает quoted promise, validity window, applied commercial policy.

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

Сущности: Quote → Booking, BookingItem, BookingEvent, PaymentIntent.

Процесс: booking intent → quote revalidation → supplier reservation → platform confirmation → settlement event generation.

Главное правило: booking lifecycle сложнее, чем pending / confirmed / cancelled. Полная state machine — в reference/booking-state-machine.md фазы 5.

Контур пост-продажи (post-booking contour)

Сущности: Booking, AmendmentRequest, Refund, BookingChangeRequest, CancellationCase, SupplierDisruptionCase, SupportCase, PostBookingDecision, RefundDecision, CompensationDecision, CommunicationRecord.

Процесс: booking confirmed → потенциально cancellation/amendment/disruption → financial correction → resolution.

Главное правило: post-booking — отдельный домен, не «хвост booking». Polно описан в reference/post-booking-lifecycle.md.

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

Сущности: TourDraft, TourDraftItem, DraftVariant, TourProposal, ProposalVersion, ProposalArtifact + ссылки на Offer, Quote, Booking.

Процесс: draft creation → component assembly → variant exploration → proposal creation → version → artifact generation → optional conversion to bookings.

Главное правило: Tour Builder работает как закрытая система с raw API constructor по модулям. Это ядро платформы, не вторичная UI-фича.

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

Сущности: Booking → SettlementEvent, ReconciliationCase + Partner Financial Account, Clearing Balance, Deposit, Credit Limit, Hold, Clearing Entry, Netting Rule.

Процесс: booking confirmed → settlement event → supplier payable → agency commission → partner share → reconciliation → clearing.

Главное правило: clearing — отдельный домен от settlement. Описан в reference/partner-finance-and-clearing.md.

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

Сущности: ReviewCase, MappingDecision, MergeDecision, Anomaly, FieldLineage, SourcePrecedenceRule + влияет на все остальные сущности.

Процесс: detection → queue → review → decision → application or rejection → audit.

Главное правило: governance — не побочный admin-функционал, а самостоятельный контур платформы. Описан в reference/data-governance-and-matching.md.

Контур учёта потребления и тарификации (metering and billing contour)

Сущности: UsageEvent, MeteringWindow, QuotaState, BillingEntry + связь с Tenant, ApiClient, ApiCredential.

Процесс: взаимодействие на любой поверхности → tracking event → aggregation → quota check → billing entry generation.

Главное правило: metering — продуктовый контур, не операционный. Прямо влияет на динамическое ценообразование. Описан в reference/api-metering-and-usage-governance.md.

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

Сущности: Trace, Metric, Log, Alert + связь со всеми другими сущностями через correlation IDs.

Процесс: action на любой поверхности → trace creation → metrics emission → log capture → optional alert → dashboard visibility.

Главное правило: observability — сквозной контур, проходит через все остальные. Технологический baseline — operations/observability-tooling-baseline.md.

Сущности и контуры — матрица

Контур	Главные сущности
Data ingress	Supplier, SupplierPayload, SupplierProperty, SupplierProduct, SupplierSyncRun, Property, CanonicalProduct
Search & discovery	SearchSession, Property, Offer (projection)
Offer-Quote	Offer, AvailabilitySnapshot, PriceSnapshot, Quote, RevalidationResult
Transactional commit	Quote, Booking, BookingItem, BookingEvent, PaymentIntent
Post-booking	Booking, AmendmentRequest, Refund, BookingChangeRequest, CancellationCase, SupplierDisruptionCase, SupportCase
Tour composition	TourDraft, TourDraftItem, DraftVariant, TourProposal, ProposalVersion, ProposalArtifact
Settlement & clearing	Booking, SettlementEvent, Partner Financial Account, Clearing Balance, Hold
Governance & review	ReviewCase, MappingDecision, MergeDecision, Anomaly, FieldLineage, SourcePrecedenceRule
Metering & billing	UsageEvent, MeteringWindow, QuotaState, BillingEntry
Observability	Trace, Metric, Log, Alert

Источники истины и политики свежести

Каждая группа сущностей имеет свою политику истины и политику свежести. Эти политики определяют:

• какой срок допустимой устарелости (acceptable staleness);
• когда требуется повторная проверка (revalidation);
• какие данные сохраняются для audit, даже если устарели операционно;
• как обрабатываются конфликты между источниками.

Полное описание — в reference/storage.md. Ключевые моменты:

Группа	Acceptable staleness	Revalidation trigger
Canonical Master	Дни (для content), часы (для классификации)	Governance review + supplier sync
Supplier-derived	Минуты-часы	Каждый sync run
Operational Offer	Минуты	Каждый search; обязательно перед quote
Quote	Validity window (минуты-часы по типу)	Перед transition в booking; явно через repricing
Transactional	Без устаревания (audit-grade)	Только supplier-driven changes
Composition	Часы для drafts; days для published proposals	При изменении underlying offers
Governance	Без устаревания	Manual review only
Identity/Tenancy	Дни-недели	По administrative actions

Что нельзя путать в каноничной модели

После фиксации этой оси следующие смешения запрещены во всех документах:

• Property ↔ Offer — Property стабилен, Offer операционный.
• SupplierProperty ↔ Property — SupplierProperty не подменяет Property.
• CanonicalProduct ↔ SupplierProduct — каноничный vs supplier-specific.
• Offer ↔ Quote — Offer операционная возможность, Quote actor-specific фиксация.
• Quote ↔ Booking — Quote коммерческое обещание, Booking транзакционная фиксация.
• TourDraft ↔ TourProposal — Draft мутабельная working composition, Proposal published versioned presentation.
• TourProposal ↔ ProposalArtifact — Proposal сущность, Artifact materialized output.
• User identity ↔ Actor context — identity отвечает «кто», ActorContext отвечает «в какой роли сейчас».
• Partner ↔ Agency — разные коммерческие категории Tenant.
• supplier truth ↔ platform canonical truth — две разные истины, никогда не смешивать.
• cached preview ↔ commit-ready state — UI кеш не commit-ready.
• quote validity window ↔ availability TTL — commercial обещание vs operational актуальность.
• supplier confirmation ↔ platform confirmation — успех у поставщика vs успех в caнonic transactional layer.
• booking failure ↔ unknown external state — известный отказ vs неопределённость.
• display price ↔ quoted price — UI-проекция vs commercial promise.
• quoted price ↔ settlement price — commercial promise vs financial reality.
• commercial fixation ↔ transactional commit — quote vs booking.

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

Связь с осью 2 (поверхности взаимодействия)

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

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

• Tenant, Partner, Agency, ApiClient, ApiCredential — сущности тарификации.
• TourDraft, TourProposal — сущности отдельного paid Tour Builder tier.
• UsageEvent, BillingEntry — сущности динамической тарификации.

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

• Все сущности генерируют domain events.
• FieldLineage — основа для data quality monitoring.
• ML использует features, derived from canonical entities.
• Tracking events — параллельный класс к domain events для аналитики.

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

• Booking — самый критический операционный домен (audit, recovery, SLA).
• Governance — операционный процесс с человеком в цикле.
• Replay capability — для всех групп сущностей с persistent layer.

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

Карта соответствия каноничной модели и реальных таблиц home-to-go-api:

Каноничная группа	Текущая реализация в home-to-go-api	Статус
Canonical Master (Property, CanonicalProduct)	hotels schema	Первая итерация, требует унификации для multi-supplier
Supplier-derived	поля supplier_* в hotels	Требует выноса в отдельный supplier trace layer
Operational Offer	пока не реализовано как отдельный layer	Требует разработки в фазе 2
Transactional	пока не реализовано	Требует разработки в фазе 2
Composition (Tour)	не реализовано	Требует разработки в фазе 2-3
Governance	не реализовано как layer	Требует разработки в фазе 2
Identity/Tenancy/Access	таблицы usr_* (18 таблиц)	Первая итерация, требует ревью на multi-tenant модель
Metering & billing	не реализовано	Требует разработки в фазе 2-3
Observability	базовая через managed tools	Требует углубления в фазе 2

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

Углубление каноничной оси в документах второго круга

Эта ось верхнего уровня раскрывается детально в документах второго круга:

Тема	Документ второго круга
Каноничные сущности и их атрибуты	reference/domain-model.md
Семантика Offer/Quote/Booking	reference/offer-pricing-booking-semantics.md
Семантика Tenant/Identity/Access	reference/tenancy-and-identity.md
Семантика Tour	reference/tour-builder-domain.md
Семантика governance	reference/data-governance-and-matching.md
Семантика commercial	reference/commercial-model.md
Семантика partner finance	reference/partner-finance-and-clearing.md
Семантика post-booking	reference/post-booking-lifecycle.md
Семантика supplier intake	reference/ingestion.md
Семантика storage	reference/storage.md
Семантика persistent schema	reference/database-schema.md

В фазе 5 будут созданы дополнительные углубляющие документы:

• reference/booking-state-machine.md — полная state machine bookings;
• reference/tour-builder-operational-model.md — операционная модель Tour Builder;
• reference/multi-tenant-isolation-strength.md — выбор уровня изоляции тенантов.

Что нельзя делать с этой каноничной моделью

• Подстраивать каноничные поля под структуру конкретного поставщика;
• Делать hotelId или roomTypeId достаточным transactional identifier (transactional identity — это Offer.id или Quote.id);
• Сливать Quote и Booking в одну сущность;
• Сливать TourDraft и TourProposal в одну сущность;
• Сливать User и ActorContext (один пользователь может быть в разных ролях);
• Сливать Partner и Agency (разные коммерческие модели);
• Хранить supplier-derived entities в той же таблице, что canonical entities;
• Терять FieldLineage при canonical update — оно должно отражать, кто и когда внёс каждое значение;
• Допускать видимость supplier-derived entities на внешних поверхностях.

Уточнение naming состояний Booking (28.04.2026)

Запись жизненного цикла Booking в этом документе (Group 4, операционные сущности предложения) использовала рабочие именования, которые в Фазе 5 канонически зафиксированы в reference/booking-state-machine.md с точными именами 14 состояний. Эта секция фиксирует каноничные имена для использования во всех контрактах, событиях и кодовых артефактах.

Каноничные 14 состояний (источник истины — booking-state-machine.md)

№	Каноничное имя	Назначение
1	draft	черновик, не отправлен на обработку
2	submitted	отправлен в обработку, идут pre-checks
3	pending_revalidation	ожидание revalidation у поставщика (drift detection)
4	pending_supplier_confirmation	ожидание ответа поставщика по бронированию
5	supplier_confirmed	поставщик подтвердил (но платформа ещё не финализировала)
6	platform_confirmed	платформа финализировала (≡ confirmed для внешних потребителей)
7	partially_confirmed	поставщик подтвердил часть позиций
8	unknown_external_state	поставщик не отвечает или отвечает некорректно (target SLI: менее 1%)
9	failed	известный отказ
10	cancel_requested	запрошена отмена
11	cancel_in_progress_supplier	отмена выполняется у поставщика
12	cancelled	отменено
13	amendment_in_progress	выполняется изменение
14	completed	исполнено

Соответствие с упрощённой записью выше в этом документе

Запись жизненного цикла Booking в Group 4 (draft_intent → submitted → ... → completed → unknown_external_state) — рабочая высокоуровневая запись, не каноничные имена. При имплементации, контрактах API/AsyncAPI, событиях event stream — использовать только имена из таблицы выше.

Соответствие именований:

Запись в Group 4	Каноничное имя
draft_intent	draft
partially_failed	partially_confirmed
cancel_pending	cancel_in_progress_supplier
amendment_requested (отдельный)	(отсутствует — сразу amendment_in_progress)

Кроме того, верхнеуровневая запись содержит 15 элементов из-за разделения amendment_requested и amendment_in_progress. Каноничная state machine — 14 состояний.

Эта секция является уточнением no-destruction — текст Group 4 выше остаётся для смыслового каркаса, истина по именованию состояний — в booking-state-machine.md.

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

• Главная архитектурная ось (overview/index.md)
• Манифест переосмысления (overview/platform-vision-and-manifest.md)
• Поверхности взаимодействия (overview/layers.md)
• Архитектурный якорь и бизнес-модель (overview/architectural-anchor-and-business-model.md)
• Платформа как продукт (overview/platform-as-product.md)
• Ось данных и интеллекта (overview/data-and-intelligence-spine.md)
• Операционная ось (overview/operational-spine.md)
• Связь с реализацией (overview/relation-to-implementation-baseline.md)
• Граф пересечений архитектурных осей (overview/architectural-axes-and-cross-links.md)
• Каноничная доменная модель второго круга (reference/domain-model.md)
• Семантика Offer/Quote/Booking (reference/offer-pricing-booking-semantics.md)
• Семантика Tenant/Identity (reference/tenancy-and-identity.md)
• Семантика Tour (reference/tour-builder-domain.md)
• Семантика governance (reference/data-governance-and-matching.md)
• Семантика storage (reference/storage.md)
• Семантика persistent schema (reference/database-schema.md)