Связь с реализацией (ось 6) — мост между архитектурой и home-to-go-api

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

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

Этот документ — раскрытие шестой оси верхнеуровневой архитектуры: связь с реализацией. Он отвечает на вопросы: какое существует уже работающее ядро (home-to-go-api), какое отношение оно имеет к каноничной модели Vitiana, где совпадают и где расходятся, какой технический долг есть в первой реализации, какой путь конвергенции от первой реализации к зрелой каноничной архитектуре.

Документ читается после главной архитектурной оси (overview/index.md). Он критически важен для понимания, что архитектура vitiana-api-platform строится поверх уже работающего ядра, не green-field, и архитектурные решения должны учитывать реальное состояние реализации.

Главный принцип

Каноничная модель Vitiana — архитектурный приоритет (правило 00000). Существующая реализация home-to-go-api — это первая итерация ingestion и базового storage слоя.

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

• если каноничная модель требует структуры, отличной от текущих таблиц home-to-go-api, — каноничная модель выигрывает;
• расхождения между каноничной моделью и реализацией фиксируются как технический долг ingestion слоя, не как ограничение архитектуры;
• путь конвергенции — рефакторинг ingestion adapter с возможной миграцией первичного storage, не пересмотр каноничной модели под существующие таблицы;
• редактирование home-to-go-api запрещено архитектору без явного указания пользователя.

Что такое home-to-go-api

home-to-go-api — это код-проект реализации первой итерации платформы Vitiana.

Базовые факты:

• Корень кода: /mnt/d/SITES/home.to.go.api;
• Slug в DocMap: home-to-go-api (default project в registry);
• БД: apivitianadb PostgreSQL 18.1, хост vitianaapipg.psql.tools:10167;
• Production endpoint: https://api.vitrip.store/stuba (это adapter Stuba module, не Partner API Surface платформы Vitiana);
• Главный сайт: vitrip.store (frontend Preact + HTM, backend PHP) — первая клиентская поверхность.

Что задеплоено и работает (на 25.04.2026):

Компонент	Статус	Документ
Stuba module	production-ready 2026-04-15 (XML API v1.28)	home-to-go-api/api-module-stuba/docs/CONTRACT.md
Hotel Loader	первый прогон завершён, 127 304 отелей, 4.6M фото	home-to-go-api/HOTEL_LOADER.md
Geo Chain	182 страны синхронизированы, locations + translations + supplier_map	home-to-go-api/GEO_CHAIN.md
Hotel Database	DDL выполнен 2026-04-16, schema hotels	home-to-go-api/HOTEL_DATABASE.md
USR Architecture	DDL, 18 таблиц с префиксом usr	home-to-go-api/USR_ARCHITECTURE.md
Events & Themes DB	DDL выполнен 2026-04-24	home-to-go-api/EVENTS_THEMES_DB.md
Amenity Plan	справочник 145 концептов, 224 маппинга для Stuba	home-to-go-api/AMENITY_PLAN.md
HomeToGo HTG API	исследование интеграции (второй поставщик)	home-to-go-api/api-module-htg-research/ (если применимо)

Что пока НЕ реализовано:

• Partner API Surface (нет sandbox, нет developer portal, нет certification flow);
• Tour Builder Closed Surface;
• Agency Working Surface (полноценный);
• Internal Operational Surface (только частично через admin-панель vitrip.store);
• B2C Storefront Surface (только частично через vitrip.store);
• Service-to-Service Surface (без формальных контрактов между сервисами);
• managed Kafka, OpenSearch, ClickHouse;
• ML platform;
• A/B testing framework;
• multi-region deployment;
• formal disaster recovery plan;
• production-grade observability.

Текущая реализация в терминах архитектурных осей

Ось 1 (каноничная доменная)

Что покрыто:

Каноничная группа	Текущая реализация	Состояние
Canonical Master Entities	hotels schema (Property + CanonicalProduct в одной таблице)	Первая итерация; есть Stuba-specific следы
Supplier-derived Entities	поля supplier_* в hotels + отдельные tables для supplier metadata	Smешение с canonical; требует выноса в отдельный supplier trace layer
Operational Offer Entities	пока не реализовано как отдельный layer; offers рассчитываются on-demand при поисковых запросах	Требует разработки в фазе 2
Transactional Entities	пока не реализовано в production (тестовые bookings через Stuba)	Требует разработки в фазе 2
Composition Entities (Tour)	не реализовано	Требует разработки в фазе 2-3
Governance/Review Entities	не реализовано как layer; ad-hoc через admin UI	Требует разработки в фазе 2
Identity/Tenancy/Access	таблицы usr_* (18 таблиц) для users + organizations	Первая итерация; требует ревью на multi-tenant модель Vitiana
Geo	locations + translations (ru/uk) + location_supplier_map	Хорошее покрытие; направление верное
Amenity	глобальный справочник 145 концептов + 224 supplier_map	Соответствует канону

Главный технический долг:

• hotels schema смешивает canonical Property и SupplierProperty — нужно разделение;
• нет отдельного supplier trace layer (supplier payloads, sync runs, parse failures);
• нет Offer/Quote/Booking сущностей в каноничной форме;
• нет governance layer.

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

Текущее покрытие поверхностей:

Поверхность	Текущая реализация	Состояние
Internal Operational Surface	admin-панель vitrip.store (Preact + HTM, PHP backend)	Частичная реализация; не покрывает governance, dispute resolution, manual overrides
Agency Working Surface	не реализовано	Концепция, разработка в фазе 2-3
Partner API Surface	https://api.vitrip.store/stuba — это adapter Stuba module, не Partner API Surface	Принципиально другая природа; Partner API Surface требует полной разработки
B2C Storefront Surface	vitrip.store сайт (Preact + HTM, PHP backend)	Зачаточная реализация; нет conversion-оптимизации, ML-ranking, advanced features
Service-to-Service Surface	базовые внутренние API между PHP backend и Stuba module	Без формальных контрактов; требует переработки
Tour Builder Closed Surface	не реализовано	Концепция, разработка в фазе 2-3

Главное расхождение: существующий https://api.vitrip.store/stuba — это первая итерация adapter ingestion, не Partner API Surface платформы. Эти две поверхности имеют разную природу: adapter переводит supplier API в внутренние формы; Partner API Surface раскрывает каноничную модель Vitiana партнёрам.

Ось 3 (платформа как продукт)

Текущее покрытие:

• Tenant tiers — нет.
• Динамическая тарификация — нет.
• Developer experience (sandbox, DX) — нет.
• Certification flow — нет.
• SLA-контракт — нет формального.
• Self-service инструменты — нет.
• Tour Builder paid tier — нет.
• Partner-facing analytics — нет.

Главное: платформа как продукт ещё не существует. Текущая реализация — это первая B2C-витрина (vitrip.store) и прототип ingestion (Stuba module). Полная разработка как продукта — фазы 2-4.

Ось 4 (данные и интеллект)

Текущее покрытие:

Компонент	Текущая реализация	Состояние
Domain events	частично через events_themes (DDL выполнен 2026-04-24)	Первая итерация event capture; требует разделения на domain vs analytical
Analytical events	не реализовано	Требует разработки в фазе 2
Data Warehouse	базовая аналитика возможна через PostgreSQL apivitianadb, не оптимально для analytical queries в production-объёме	Требует выделения в отдельный storage class; managed ClickHouse в фазе 3
ETL/streaming pipelines	не реализовано	Требует разработки в фазе 2-3
ML Platform	не реализовано	Требует разработки в фазе 3
A/B testing framework	не реализовано	Требует разработки в фазе 2

Главный технический долг: events_themes smешивает domain events и analytical events — требуется разделение.

Ось 5 (операционная)

Текущее покрытие:

Принцип	Текущая реализация	Состояние
Эластичность	managed PostgreSQL apivitianadb имеет базовое масштабирование; Stuba module — на одном PHP backend	Базовое; не auto-scaling, не horizontal scaling по контурам
Изоляция контуров исполнения	нет; всё на одной инфраструктуре	Требует разработки в фазе 2
Managed services	managed PostgreSQL у vitianaapipg.psql.tools (внешний провайдер, не OVHcloud)	Текущий managed-сервис — на старом провайдере; миграция на OVHcloud Public Cloud в фазе 1
Disaster Recovery	базовое managed backup; нет formal DR plan, RTO/RPO targets	Требует разработки в фазе 2-3
Observability	базовая через PHP logs + managed PostgreSQL metrics	Требует разработки в фазе 1-2
Incident management	ad-hoc; нет formal runbooks, on-call rotation	Требует разработки в фазе 2
Release engineering	базовое; нет formal feature flags, canary deployments, contract testing	Требует разработки в фазе 2

Главное: операционная зрелость — на уровне фазы Bootstrap. Требует развития во всех направлениях.

Карта соответствия каноничной модели и реальной схемы

Полная матрица

Каноничная сущность	Текущая реализация	Тип расхождения	План конвергенции
Property	таблица hotels (поля: id, name, address, geo coordinates, classification, content)	Содержит supplier-specific следы (источник Stuba); смешан с SupplierProperty	Фаза 2: разделить hotels на canonical properties + supplier_properties
SupplierProperty	поля supplier_* в hotels (supplier_id, supplier_native_id, supplier_metadata)	Не отдельная сущность	Фаза 2: вынести в отдельный supplier trace layer
CanonicalProduct	таблица rooms или поля в hotels для room types	Не отдельный canonical layer	Фаза 2: ввести canonical product layer
SupplierProduct	реализовано через Stuba content API + сохранение в rooms	Тесно связан с Stuba	Фаза 2: вынести в supplier product layer
Supplier	возможно через справочник в schema + supplier-specific tables	Ограниченное покрытие	Фаза 2: ввести canonical Supplier registry
SupplierPayload	возможно через cache или ad-hoc	Не отдельная persistent сущность	Фаза 2: ввести supplier trace layer (raw payloads, parse failures)
SupplierSyncRun	логи sync через Hotel Loader	Не persistent сущность	Фаза 2: ввести SyncRun сущность с metadata
Offer	НЕ реализовано как persistent сущность; offers рассчитываются on-demand	Не существует	Фаза 2: ввести Offer canonical entity и Offer Service
AvailabilitySnapshot, PriceSnapshot	НЕ реализовано	Не существует	Фаза 2: ввести operational layer
Quote	НЕ реализовано	Не существует	Фаза 2: ввести Quote как canonical entity
Booking	НЕ реализовано в production (только тестовые через Stuba)	Не существует	Фаза 2: ввести Booking lifecycle
BookingItem, BookingEvent	НЕ реализовано	Не существует	Фаза 2
PaymentIntent, Refund	НЕ реализовано	Не существует	Фаза 2 (после payment domain)
AmendmentRequest	НЕ реализовано	Не существует	Фаза 2-3
TourDraft, TourDraftItem, DraftVariant	НЕ реализовано	Не существует	Фаза 2-3 (Tour Builder)
TourProposal, ProposalVersion, ProposalArtifact	НЕ реализовано	Не существует	Фаза 2-3
Organization, Tenant, Workspace	таблицы usr_organizations, usr_users (или эквивалент)	Базовая реализация без full multi-tenant модели	Фаза 2: ревью и расширение для multi-tenant
User	таблица usr_users	Реализовано	Конвергенция через ревью schemes
Partner, Agency	возможно через usr_organizations с типизацией	Не отдельные сущности	Фаза 2: ввести Partner и Agency как specializations
ApiClient, ApiCredential	не реализовано (Stuba use API keys через config)	Не отдельные сущности	Фаза 2: ввести API credentials management
RoleAssignment, CapabilityGrant	возможно через usr_roles или эквивалент	Базовая реализация	Фаза 2: ревью на capability model
ActorContext	возможно через session state в PHP	Не persistent сущность	Фаза 2: ввести как явный концепт
ReviewCase, MappingDecision, MergeDecision, Anomaly, FieldLineage, SourcePrecedenceRule	НЕ реализовано	Не существует	Фаза 2: ввести governance layer
Geo (locations, translations, supplier_map)	реализовано полностью	Соответствует канону	Возможно мелкие refinements
Amenity	реализовано через справочник + supplier_map	Соответствует канону	Возможно мелкие refinements

Технический долг ingestion слоя

Зафиксирован как первоочередная зона рефакторинга при переходе к каноничной архитектуре.

Долг 1. Разделение canonical и supplier-derived entities

Текущее состояние: hotels schema содержит и canonical свойства property, и supplier-specific следы.

Целевое состояние:

• properties — canonical Property entity с canonical полями;
• supplier_properties — supplier-derived entity с supplier-specific полями + ссылка на canonical property;
• canonical_products — canonical CanonicalProduct entity;
• supplier_products — supplier-derived;
• маппинг между canonical и supplier через mapping decisions (не прямую связь one-to-one).

Путь конвергенции:

• Шаг 1: создать новые tables properties, canonical_products с минимальной схемой.
• Шаг 2: создать новые tables supplier_properties, supplier_products для supplier-specific данных.
• Шаг 3: написать migration script, который читает текущий hotels и распределяет данные в canonical и supplier tables.
• Шаг 4: обновить ingestion adapter для записи в обе схемы.
• Шаг 5: переключить read paths на canonical schema.
• Шаг 6: deprecate старую hotels после полной миграции.

Эскалация: требует решения пользователя для запуска миграции production данных. Эскалируется при создании reference/database-schema.md фазы 5 или раньше при практической необходимости.

Долг 2. Отсутствие persistent supplier trace layer

Текущее состояние: raw supplier payloads не сохраняются persistently. Sync runs логируются, но без полного trace.

Целевое состояние:

• supplier_payloads — append-only хранение raw payloads (по retention policy);
• supplier_sync_runs — metadata о каждом sync (когда, какой supplier, что обновилось, сколько records);
• supplier_parse_failures — failures для recovery и debugging;
• replay capability — возможность переиграть sync с любой точки.

Путь конвергенции: разработка в фазе 2 при усилении ingestion слоя.

Долг 3. Отсутствие operational offer/quote layer

Текущее состояние: offers рассчитываются on-demand при поисковых запросах (через прямой вызов Stuba API). Нет persistent layer для operational state.

Целевое состояние:

• Offer Service с persistent offers table для значимых operational state;
• AvailabilitySnapshot и PriceSnapshot для freshness и audit;
• Quote Service для actor-specific commercial fixation;
• RevalidationResult для tracked revalidation outcomes.

Путь конвергенции: разработка в фазе 2 — это центральный архитектурный шаг.

Долг 4. Отсутствие booking lifecycle

Текущее состояние: booking commit прямой через Stuba (без platform-side persistent state). Нет state machine, нет audit trail, нет recovery procedures.

Целевое состояние:

• Booking canonical entity с полным state machine (см. reference/booking-state-machine.md фазы 5);
• BookingEvent journal;
• Idempotency для booking commit;
• Recovery procedures для unknown_external_state.

Путь конвергенции: разработка в фазе 2 — критически важный шаг для платформы.

Долг 5. Отсутствие governance layer

Текущее состояние: governance ad-hoc через admin UI. Нет formal review queues, mapping decisions, anomaly tracking, field lineage.

Целевое состояние: полный governance layer (см. reference/data-governance-and-matching.md).

Путь конвергенции: разработка в фазе 2.

Долг 6. Multi-tenant модель не реализована полностью

Текущее состояние: usr_* tables покрывают базовых users + organizations. Multi-tenant boundary (Tenant entity, Workspace, capability scope) — не явно реализован.

Целевое состояние: полная multi-tenant модель (см. reference/tenancy-and-identity.md, углубление — reference/multi-tenant-isolation-strength.md фазы 5).

Путь конвергенции: ревью существующих usr_* tables, возможный refactoring для phase 2.

Долг 7. Missing payment domain

Текущее состояние: payments handled outside of home-to-go-api (через external PSP integration в admin UI vitrip.store, или напрямую через Stuba booking).

Целевое состояние: полный payment domain (см. reference/payment-domain.md фазы 4).

Путь конвергенции: разработка в фазе 2-3 после выбора PSP и определения merchant-of-record модели per tenant.

Долг 8. Mixed domain и analytical events в events_themes

Текущее состояние: events_themes schema (DDL 2026-04-24) — единое хранилище для разных типов событий.

Целевое состояние:

• domain_events — domain events через event bus (Kafka в фазе 2);
• analytical_events — tracking events через отдельный pipeline в DWH (managed ClickHouse в фазе 3).

Путь конвергенции: разработка в фазе 2.

Путь конвергенции (полная схема)

Фаза 1 (Bootstrap, 0-12 мес) — параллельная разработка canonical model

Что делается:

• сохраняется текущая реализация home-to-go-api в production;
• vitrip.store продолжает работать на текущей apivitianadb;
• создаётся новая dev-инфраструктура на OVHcloud (см. operations/scaling-and-packaging-roadmap.md);
• создаётся новая dev-БД managed PostgreSQL Essential на OVHcloud (НЕ совмещается с текущей vitianaapipg.psql.tools);
• разрабатываются прототипы canonical model (Offer, Quote, Booking) в новой dev-БД;
• разрабатывается прототип ingestion adapter, переводящий Stuba data в canonical model;
• НЕ трогается текущая production-инфраструктура.

Цель: доказать viability канонической модели на новой dev-инфраструктуре + начать разработку прототипа второго supplier (HomeToGo) для проверки независимости canonical model от Stuba.

Фаза 2 (Service isolation, 12-24 мес) — постепенная миграция

Что делается:

• разрабатывается полная canonical schema в новой production БД;
• ingestion adapter Stuba переписан для записи и в текущую apivitianadb, и в новую canonical БД (dual-write);
• vitrip.store сайт переключается на чтение из новой canonical БД (read paths first);
• разрабатывается Partner API Surface на основе canonical model;
• разрабатывается формальная Tenant + Multi-tenant model;
• запускается formal SLA, on-call, runbooks;
• HomeToGo подключается через новый ingestion adapter.

Цель: parallel running старой и новой реализаций; постепенный switchover.

Фаза 3 (Workload-specific, 24-36 мес) — deprecation старой реализации

Что делается:

• write paths полностью переключаются на canonical БД;
• старая apivitianadb deprecated и переходит в read-only архив;
• vitrip.store сайт полностью на canonical model;
• Partner API Surface launched;
• Tour Builder Closed Surface launched;
• Agency Working Surface launched.

Цель: платформа Vitiana работает на canonical архитектуре; первая реализация сохраняется как archive.

Фаза 4 (Multi-region, 36+ мес) — масштабирование

Текущая реализация полностью deprecated; платформа работает на зрелой canonical архитектуре с multi-region deployment.

Принципы работы архитектора с home-to-go-api

Что архитектор делает

• Читает документы home-to-go-api для понимания текущего состояния (через DocMap или напрямую Read);
• Проверяет, не делает ли каноничная архитектура vitiana-api-platform явных невыполнимых требований к существующей реализации;
• Идентифицирует места, где текущая реализация содержит supplier-specific следы — фиксирует как технический долг ingestion слоя, не как ограничение архитектуры;
• Документирует карту соответствия canonical model и реальных таблиц.

Что архитектор НЕ делает

• Не выводит canonical model vitiana-api-platform из существующей schemy hotels. Если canonical model требует другой структуры, ingestion adapter переводит существующую schemu в нужный canonical вид.
• Не считает Stuba archetype для всех поставщиков. Stuba — частный случай.
• Не описывает архитектуру так, что отключение Stuba требует переделки ядра. Любой поставщик отключаем без последствий для canonical model.
• Не редактирует home-to-go-api без явного указания пользователя (правила 22-25 Свода законов ИИ).

При обнаружении расхождений

Если каноничная модель vitiana-api-platform несовместима с задеплоенной schemoy home-to-go-api:

1. Каноничная модель — приоритет (правило 00000).
2. Расхождение фиксируется в архитектурном документе как технический долг ingestion слоя или миграция первичного storage.
3. Не делается декомпозиция задним числом под текущую schemu.
4. Эскалируется пользователю только при необходимости существенных операционных изменений (downtime, миграция данных, contract impact).

Документы home-to-go-api для контекстного чтения

При работе над архитектурой соответствующего домена обязательно читать соответствующие документы home-to-go-api:

Каноничный домен	Документы home-to-go-api для контекста
Domain Model (Property, CanonicalProduct, SupplierProperty, SupplierProduct)	PLATFORM.md, HOTEL_DATABASE.md, HOTEL_LOADER.md, HOTEL_SYNC.md
Geo	GEO_DATABASE.md, GEO_CHAIN.md, GEO_POI.md
Amenity	AMENITY_PLAN.md
Tenancy/Identity	USR_ARCHITECTURE.md
Domain Events	EVENTS_THEMES_DB.md
Suppliers	api-module-stuba/docs/STUBA_* (полный набор: ARCHITECTURE, CONTRACT, REFERENCE, REVIEW_*, CONTENT_API, COUNTRIES)
Ingestion	HOTEL_LOADER.md, HOTEL_SYNC.md, CONTENT_PIPELINE.md
Platform overview	PLATFORM.md, CLAUDE.md

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

Связь с осью 1 (каноничная доменная)

См. полную матрицу выше. Главное: текущие таблицы hotels, usr, events_themes — первая итерация подмножества каноничной модели, требует поэтапного рефакторинга.

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

Текущая реализация имеет частичное покрытие: vitrip.store сайт = зачаточная B2C Storefront Surface; admin UI = частичная Internal Operational Surface; Stuba endpoint = adapter ingestion (НЕ Partner API Surface).

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

Платформа как продукт — не реализована в текущем home-to-go-api. Полная разработка в фазах 2-4.

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

events_themes — первая итерация event capture; требует разделения на domain events vs analytical events. ML platform, A/B testing — не реализованы.

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

Текущая инфраструктура managed PostgreSQL vitianaapipg.psql.tools — это первая реализация фазы Bootstrap, но на стороннем провайдере. Миграция на OVHcloud Public Cloud — фаза 1.

Открытые развилки

Развилка 1. Параллельная разработка canonical model или сначала рефакторинг текущей

Открытый вопрос: делать рефакторинг ingestion параллельно с разработкой новой canonical model в фазе 1, или сначала закрыть документную базу и начать рефакторинг кода в фазе 2?

Рекомендация архитектора: документную базу закрыть в фазах 1-9 архитектурного плана; разработка прототипа canonical model в новой dev-БД в фазе 1; полный рефакторинг кода — в фазе 2 после стабилизации canonical-документов.

Эскалируется при обсуждении development plan с пользователем.

Развилка 2. Сохранение текущей vitianaapipg.psql.tools или миграция в OVHcloud

Открытый вопрос: сохранить текущую managed PostgreSQL у внешнего провайдера для production, или мигрировать в OVHcloud Public Cloud вместе с остальной инфраструктурой?

Рекомендация архитектора: в фазе 1 — оставить как production read-only архив старой системы; новая разработка ведётся в новой managed PostgreSQL на OVHcloud в Strasbourg. Полная миграция — в фазе 2.

Эскалируется при принятии решения о развёртывании фазы Bootstrap.

Развилка 3. Migration script сложности

Открытый вопрос: при миграции данных из hotels в canonical schemy — насколько сложным может быть migration script? Если мapping простой (split полей по двум tables) — straight script; если требуются manual decisions — необходим governance review для каждой spornoy записи.

Эскалируется в фазе 2 при детальной разработке migration.

Развилка 4. Что делать с уже существующими bookings (если будут)

Открытый вопрос: если к моменту фазы 2 в home-to-go-api появятся реальные production bookings, как мигрировать их в canonical Booking model?

Рекомендация архитектора: не запускать production bookings в текущем home-to-go-api до разработки canonical Booking model в фазе 2. Если уже запущены — миграция через snapshot + rebuild.

Эскалируется при появлении первых production bookings.

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

• Главная архитектурная ось (overview/index.md)
• Манифест переосмысления (overview/platform-vision-and-manifest.md)
• Архитектурный якорь (overview/architectural-anchor-and-business-model.md)
• Поверхности взаимодействия (overview/layers.md)
• Каноничная доменная ось (overview/canonical-domain-spine.md)
• Платформа как продукт (overview/platform-as-product.md)
• Ось данных и интеллекта (overview/data-and-intelligence-spine.md)
• Операционная ось (overview/operational-spine.md)
• Граф пересечений архитектурных осей (overview/architectural-axes-and-cross-links.md)
• Дорожная карта инфраструктурного масштабирования (operations/scaling-and-packaging-roadmap.md)
• Каноничная доменная модель (reference/domain-model.md)
• Database Schema (reference/database-schema.md)
• Storage (reference/storage.md)
• Ingestion (reference/ingestion.md)
• Suppliers (reference/suppliers.md)
• Tenancy And Identity (reference/tenancy-and-identity.md)

Расширение моста под Фазы 4–6 (27.04.2026) — связь home-to-go-api с новыми каноничными доменами

После Фаз 4–6 опубликованы 16 новых каноничных доменных и операционных документов, существенно расширяющих архитектурную модель Vitiana. Эта секция фиксирует новые точки расхождения и точки конвергенции между текущей реализацией home-to-go-api и расширенной каноничной моделью, и определяет каноничный путь имплементации.

Связь home-to-go-api с новыми доменами Фазы 4

Новый каноничный домен	Текущее состояние в home-to-go-api	Gap	Путь конвергенции
Платёжный домен (payment-domain.md)	отсутствует в home-to-go-api	критический	стадия 1 — выбор PSP, реализация PaymentIntent flow с zero-touch к card data
API as Product (api-as-product.md)	partial — есть production endpoint https://api.vitrip.store/stuba, но без partner lifecycle / sandbox / certification / tier system	средний	стадия 2 — partner sandbox + certification flow; API key management
Search & Discovery (search-and-discovery.md)	partial — search возможен через прямые SQL queries по apivitianadb.hotels, но без caноничного SearchProjection / RankingPolicy	средний	стадия 1–2 — выделение каноничного search service; начало с PostgreSQL FTS
Data Platform & Events (data-platform-and-events-tracking.md)	отсутствует	критический	стадия 2 — event store baseline (Redis Streams минимум); DWH — стадия 3
ML Platform (ml-platform.md)	отсутствует	низкий приоритет (фаза 4)	стадия 4 — формирование ML team
A/B Testing (ab-testing-platform.md)	отсутствует	средний	стадия 3 — feature flags + experiment infrastructure
Notifications (notification-and-communication.md)	partial — какие-то transactional emails возможны через PHP backend	средний	стадия 2 — каноничный notification service
Media & Content (media-and-content.md)	partial — 4.6M фото загружены, но без каноничного MediaAsset model и transforms	средний	стадия 2 — abstraction layer над media; image transform service
i18n (internationalization-and-localization.md)	partial — geo translations ru/uk загружены, но без каноничной i18n infrastructure	низкий	стадия 1 — i18n baseline
Analytics & BI (analytics-and-bi.md)	отсутствует	низкий приоритет	стадия 3 — minimal viable BI
Economic Model (economic-model.md)	отсутствует	средний	стадия 2 — basic revenue/cost tracking

Связь home-to-go-api с новыми доменами Фазы 5

Новый каноничный домен	Текущее состояние в home-to-go-api	Gap	Путь конвергенции
Tour Builder Operational Model (tour-builder-operational-model.md)	отсутствует	критический (для Tour Builder = core anchor)	стадия 2 — composition rules engine; saga для multi-component bookings
Booking State Machine (booking-state-machine.md)	partial — booking states возможно есть в apivitianadb, но без 14 каноничных states и unknown_external_state recovery	критический	стадия 1 — миграция booking schema на каноничные 14 состояний
Multi-Tenant Isolation (multi-tenant-isolation-strength.md)	отсутствует как каноничная модель — текущий single-tenant deployment	критический (платформа должна быть multi-tenant с фазы 1)	стадия 1 — tenant_id во все таблицы; RLS policies; IsolationBoundaryCheck

Связь home-to-go-api с операционными документами Фазы 6

Новый каноничный домен	Текущее состояние в home-to-go-api	Gap	Путь конвергенции
Runbooks (runbooks-incident-playbooks.md)	отсутствует	средний	стадия 2 — runbooks для критических incident classes
SLA & On-call (sla-and-on-call-model.md)	informal	средний	стадия 2 — формальная on-call rotation; SLI metrics; SLA для Free tier
Disaster Recovery (disaster-recovery-and-capacity.md)	partial — managed PostgreSQL backups OVH	средний	стадия 1 — Tier 1 backup verification; стадия 2 — restore drills

Связь home-to-go-api с safety / compliance / security документами

Новый каноничный домен	Текущее состояние в home-to-go-api	Gap	Путь конвергенции
Compliance & Legal (compliance-and-legal.md)	partial — implicit GDPR через cloud provider; no formal DPA management	критический (любой EU citizen data flow без compliance baseline нарушает GDPR)	стадия 1 — privacy notice; consent management; DSR API minimal
Security Architecture (security-architecture.md)	basic — TLS, авторизация на endpoints; no formal threat model, no MFA, no canonical IAM	критический	стадия 1 — MFA mandatory для admin; secrets manager; audit logging baseline

Каноничные приоритеты конвергенции для стадии 1

После сводки gaps выше, каноничный приоритет работы стадии 1 implementation baseline:

Приоритет 1 — критические gaps, блокирующие production

1. Multi-tenancy migration — добавить tenant_id во все таблицы существующего apivitianadb; RLS policies; IsolationBoundaryCheck автомат;
2. Booking state machine miграция — 14 каноничных состояний с обработкой unknown_external_state;
3. Payment domain implementation — выбор PSP (Stripe рекомендуется), PaymentIntent flow, no card data on platform;
4. Compliance baseline — privacy notice, consent management, DSR API minimal viable, retention policies enforcement;
5. Security baseline — MFA для admin, secrets manager (SOPS bootstrap), audit logging для security events;
6. DR baseline для Tier 1 — verified backup и restore процедура для критических данных (booking, payment когда появится, audit log).

Приоритет 2 — важные расширения для controlled internal platform

7. Notification service — каноничный multichannel service вместо ad-hoc emails;
8. Search service — выделение от прямых SQL queries; PostgreSQL FTS minimum;
9. Event store baseline — Redis Streams для domain events;
10. API as Product partner lifecycle — sandbox + certification minimum для второго supplier (демонстрация правила 00000);
11. Media abstraction — каноничный MediaAsset model;
12. i18n baseline — каноничная supported_language / supported_currency / FX rates.

Приоритет 3 — для controlled external beta (стадия 3)

13. Tour Builder operational model — composition rules engine, saga, drift detection;
14. A/B testing infrastructure — feature flags + experiment platform;
15. Analytics baseline — partner-facing analytics dashboard minimum;
16. Runbooks — для всех каноничных incident classes;
17. SLA monitoring — SLI metrics, SLO calculation, dashboards;
18. Capacity planning automation.

Каноничный технический долг (формальный список)

Технический долг, fixed на текущей стадии 0, который должен быть разрешён в стадии 1:

Долг 1. Single-tenant database

apivitianadb спроектирована как single-tenant без tenant_id. Все существующие данные (127K hotels, geo, photos) попадают в logical default tenant при миграции. Это требует:

• DDL миграции с добавлением tenant_id колонок;
• backfill tenant_id = default_tenant для existing data;
• updates всех queries для tenant_id filtering;
• RLS policies enforcement.

Долг 2. Stuba-shaped data model

Текущая apivitianadb.hotels schema спроектирована преимущественно от Stuba XML structure. Это нарушение правила 00000 — каноничная модель должна быть platform-first, а supplier — точкой входа.

Конвергенция:

• canonical Property schema (independent от Stuba/HomeToGo) — на стадии 1;
• existing apivitianadb.hotels остаётся как legacy supplier_data (raw trace storage);
• mapping layer (ingestion) — supplier-agnostic.

Долг 3. No event-driven architecture

Текущая home-to-go-api — синхронная REST architecture. Нет event store, нет async processing для долгих операций.

Конвергенция:

• event store baseline на стадии 1–2;
• key flows (booking confirmations, supplier sync, notifications) переводятся в event-driven на стадии 2–3.

Долг 4. PHP backend для основных flows

Текущий backend — PHP. Это допустимо для bootstrap, но не для:

• payment domain (нужны strong typing, security-critical code в memory-safe languages — TypeScript/Go/Rust);
• Tour Builder operational model (нужна saga state machine);
• search service (performance-critical).

Конвергенция:

• new services пишутся в TypeScript / Go (см. implementation-technology-baseline.md);
• existing PHP code остаётся для legacy paths, постепенная миграция;
• gateway abstraction для unified API surface.

Долг 5. Frontend Preact + HTM

Frontend vitrip.store — Preact + HTM. Это отлично для simple cases, но:

• agency surface требует richer UI framework (rich data tables, complex forms, real-time updates);
• partner self-service UI — то же.

Конвергенция:

• Next.js / React для новых rich surfaces (agency, partner UI);
• existing Preact frontend остаётся для B2C на текущем этапе;
• design system shared между frameworks.

Долг 6. No formal observability stack

Нет Prometheus / Grafana / structured logs / tracing. Operations работают на ad-hoc basis.

Конвергенция:

• observability stack на стадии 1 (Prometheus + Grafana + Loki);
• structured logging mandatory для new services;
• distributed tracing (OpenTelemetry) — стадия 2.

Долг 7. No formal CI/CD discipline

Deployment — manual / partially automated.

Конвергенция:

• formal CI/CD на стадии 1 (GitHub Actions / GitLab CI);
• staged rollout discipline;
• rollback procedures.

Каноничные принципы миграции

При implementation стадии 1:

Принцип 1. Strangler Fig pattern

Не "rewrite all". Новые services пишутся вокруг existing system, постепенно заменяя legacy paths. Existing home-to-go-api остаётся functional во время migration.

Принцип 2. Canonical model first, then implementation

Перед coding нового domain — фиксируется каноничная schema (см. database-schema.md). Существующий код адаптируется к canonical, не наоборот.

Принцип 3. Tenant isolation от первого commit

Любой новый код пишется multi-tenant aware с первого дня. Existing single-tenant code мигрируется явно через DDL migration в стадии 1.

Принцип 4. No hardcoded supplier logic

Любой новый код, касающийся ingestion, написан supplier-agnostic с adapter pattern. Captive Stuba-specific логика в общем коде запрещена (правило 00000).

Принцип 5. Security by design

Любой новый code path проходит security review до production deployment. Existing endpoints без security review — на удалении или explicit security audit на стадии 1.

Принцип 6. Compliance by design

Любая обработка персональных данных проходит privacy review (см. compliance-and-legal.md). Existing flows без privacy review — audit на стадии 1.

Что home-to-go-api даёт стадии 1 как стартовый капитал

Несмотря на gaps выше, home-to-go-api предоставляет существенный стартовый капитал для стадии 1:

1. 127K hotels загружены — каноничный Property model имеет real data для testing;
2. 4.6M фото — media baseline существует, нужна только abstraction layer;
3. Geo chain (182 страны) — i18n / geo data ready;
4. Stuba integration работает в production — canonical Supplier model имеет реальный test case;
5. Production endpoint api.vitrip.store/stuba с реальным traffic — operational baseline;
6. PostgreSQL 18.1 baseline — current стек для каноничной БД.

Это значительно снижает риск стадии 1 — мы строим на работающем foundation, а не green-field.

Каноничный итог моста

home-to-go-api — первая реализация ingestion слоя платформы Vitiana, не полная реализация платформы. После Фаз 4–6 каноничной архитектуры разрыв между current state (home-to-go-api) и target state (Vitiana platform) явно картирован:

• 11 новых каноничных доменов (Фаза 4) — большинство отсутствуют в home-to-go-api;
• 3 углубления (Фаза 5) — критические gaps по multi-tenancy, booking-state-machine, tour-builder-operational;
• 3 операционных документа (Фаза 6) — требуют построения с нуля;
• 2 safety документа (compliance, security) — критические gaps;
• 7 каноничных видов технического долга — explicit, с конвергенционным путём.

Каноничный путь конвергенции — стадии 1–4 development roadmap, начиная с критических gaps (multi-tenancy migration, booking state machine, payment domain, compliance + security baseline). Strangler Fig pattern сохраняет работающий home-to-go-api во время миграции.

Это не означает что home-to-go-api будет deprecated — это означает что home-to-go-api трансформируется в первый ingestion adapter (Stuba) внутри multi-supplier canonical platform, согласно правилу 00000.