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

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

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

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

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

Документ выполняет три задачи одновременно:

  1. Переосмысление роли платформы — формальная фиксация новой парадигмы: Vitiana как гибкая модульная глобальная платформа верхнего уровня, не как ещё один туристический агрегатор.
  2. Лучшие гибкие практики масштабирования — фиксация принципов эластичности (elastic scaling) и фазовой упаковки вычислений (phased compute packaging), на которых строится вся последующая архитектура.
  3. Известные дыры первичного слоя документов — честное признание пробелов в существующем пакете из 50 документов первого-третьего круга, с явным планом их закрытия.

Документ написан под правилом 00000 и всеми связанными правилами разработки документации (см. раздел «Правила, на которых основан документ»).

Этот документ обязателен к чтению первым при любом входе в архитектурную документацию платформы. Существующий overview/index.md (Архитектурная основа платформы vitrip.store) сохраняется как «архитектурная основа второго круга» — она остаётся валидной для тех решений, которые в ней зафиксированы, но трактуется через призму этого манифеста.

Правила, на которых основан документ​

Этот манифест построен поверх следующих правил, зафиксированных в рабочей памяти архитектора:

  • Правило 00000 — платформа главенствует над поставщиками (высший приоритет). Платформа задаёт каноничную модель и условия; поставщики — точка входа информации, не ориентир.
  • Современные лучшие практики (modern best practices) — паттерны облачных платформ верхнего уровня (Stripe, Twilio, Algolia, Cloudflare, Snowflake), не legacy-подходы туристической индустрии.
  • Эластичное масштабирование и упаковка по фазам (elastic scaling and packaging) — авто-масштабирование (auto-scaling) как baseline; упаковка вычислений разворачивается по 4 фазам с явными метрическими и доменными триггерами.
  • Развитие, не деградация (growth not degradation) — никаких заглушек (stubs), временных решений без плана миграции, captive-интеграций под одного поставщика.
  • Тезисное обоснование (thesis-based justification) — каждое нетривиальное решение содержит цели, тезисы поддержки, отклонённые альтернативы, принимаемые компромиссы, связи с другими решениями.
  • Удержание контекста связанных логик и документов — все ссылки между документами поддерживаются явно через DocMap.
  • Развитие без деградации в языке — только русский язык, англоязычные термины с расшифровкой в скобках, никакого смешения языков в одном предложении.

Часть 1. Переосмысление роли платформы​

1.1. Что Vitiana есть на самом деле​

Vitiana — это глобальная гибкая модульная платформа верхнего уровня (top-tier global flexible modular platform) для туристической индустрии.

Это не означает «ещё один туристический агрегатор» (online travel aggregator, OTA). Это означает следующее:

  • Глобальность. Платформа изначально проектируется на десятки и сотни поставщиков информации, на разные юрисдикции, на разные географии. Не на одного поставщика, не на одну страну.
  • Гибкость. Каноничная модель (canonical model) платформы изначально рассчитана на расширение через добавление, не через переписывание. Любое расширение домена — это новые модули, новые сущности, новые поверхности взаимодействия (surfaces) — без переделки ядра.
  • Модульность. Каждая возможность платформы — это отдельный модуль с явным контрактом. Модули собираются клиентами (партнёрами с платным доступом, нашими собственными сайтами, агентствами) в нужные комбинации.
  • Верхнеуровневость (top-tier). Платформа не подражает upstream-системам. Она задаёт собственный стандарт работы с туристическим инвентарём, ценой, обещаниями, бронированием, композицией туров.

1.2. Чем Vitiana НЕ является​

Чтобы переосмысление было честным, важно зафиксировать и отрицательные границы:

  • Не «улучшенный Booking.com». Booking.com — каталог отелей с прямой продажей конечному клиенту. Vitiana — платформа для тех, кто продаёт туристические продукты, включая собственные сайты Vitiana и партнёров с платным API-доступом.
  • Не proxy над поставщиками. Платформа не пересылает запросы напрямую к Stuba/HomeToGo, переименовывая их ответы. Платформа имеет собственную каноничную модель, в которую переводятся данные любых поставщиков.
  • Не закрытая экосистема одного бренда. Vitiana — это платформенная инфраструктура с двойным использованием: собственные сайты (vitrip.store) + закрытая система с raw API constructor для партнёров с платным доступом.
  • Не MVP. Никаких заглушек, временных решений, hardcode-привязок к одному поставщику. Архитектура с первого документа описывает зрелую систему, реализуемую по фазам с явными триггерами.

1.3. Цепочка ответственности и роль поставщиков​

Зафиксированная цепочка merchant-of-record (классическая модель агрегатора):

платформа → поставщики
       ↑
наши клиенты (агентства, партнёры с платным API) → платформа
       ↑
конечные клиенты партнёров → партнёры

Роль поставщиков (Stuba, HomeToGo и сотни возможных в будущем):

  • Поставщики — это точки входа информации (data ingress points) в каноничный слой платформы.
  • Платформа не зависит от поставщиков. Любой может быть отключён, заменён, переподключён без переделки ядра.
  • Поставщики зависят от платформы как канала дистрибуции и точки коммерциализации их инвентаря.
  • Все поставщики равноправны как источники данных. Структурного приоритета нет. Допустимы только операционные характеристики: класс риска (risk class), профиль возможностей (capability profile), операционное здоровье (operational health).

Это означает: поле в каноничной модели не появляется потому, что «у Stuba так возвращается». Поле появляется потому, что домен Vitiana требует его существования. Если поставщик не даёт нужного значения — это технический долг адаптера приёма данных (ingestion adapter), не недостаток модели.

1.4. Цепочка коммерциализации и динамическое ценообразование услуг​

Платформа имеет три источника монетизации:

  1. Собственные сайты (vitrip.store) — продажа туристических продуктов от своего имени конечным клиентам с собственной коммерческой надбавкой.
  2. Партнёры с платным доступом к API — продажа доступа к каноничной модели, поисковой проекции (search projection), композиции туров (Tour Builder API), системе бронирования (booking commit) и сопутствующим возможностям.
  3. Агентский слой (agency working surface) — рабочее место для туристических агентств с подпиской и/или комиссией с продаж.

Цена услуг платформы — динамическая, зависит от нагрузки на платформу:

  • объём поисковых запросов (search calls) от партнёра;
  • объём созданных коммерческих фиксаций (quote creation rate);
  • объём подтверждённых бронирований (booking commit rate);
  • сложность запросов (query complexity) — количество фильтров, географический охват, число поставщиков в результате;
  • профиль нагрузки на поставщиков (supplier load profile) — партнёр, активно использующий «дорогих» поставщиков, создаёт больше операционного давления;
  • использование тяжёлых функций (Tour Builder композиция, ML-инференс ранжирования и рекомендаций).

Это переводит модель монетизации с «комиссии за бронирование» (commission per booking) на динамическую модель доступа к платформе (platform access model). Платформа взимает плату не за «результаты поиска отелей», а за свой агрегационный труд: нормализацию, governance, проверку целостности предложений (integrity gating), поисковую проекцию, фиксацию обещаний (quote fixation), гарантии взаиморасчётов (settlement guarantees).

Принципы тарификации:

  • партнёр в момент превышения квоты не получает отказа в обслуживании; он получает ясный сигнал о превышении и возможность купить расширение;
  • партнёр всегда видит свою фактическую нагрузку и прогноз счёта;
  • тарифные уровни (tiers) описываются явно, без скрытых условий;
  • бесплатный начальный уровень (free tier) для интеграции и тестирования — присутствует.

1.5. Tour Builder как ядро платформы​

Tour Builder (домен сборки тура) — не дополнительная возможность, а ядро платформы. Решение зафиксировано 25.04.2026.

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

  • модули композиции (composition primitives) — это первичный API: модуль размещения (accommodation segment), модуль переезда (transfer segment), модуль активности (activity), модуль услуги (service), модуль аренды транспорта (transport rental), модуль страхования (insurance), пользовательский модуль (custom block), информационный модуль (informational block);
  • модули собираются в произвольных комбинациях с проверкой совместимости (compatibility checks);
  • доступ к модулям — через закрытый API (не публичный), доступный собственным сайтам Vitiana и платящим партнёрам с соответствующим тарифом;
  • двойное назначение: vitrip.store строит собственные туры от своего имени; партнёры с платным доступом проектируют туры под свои каналы продаж;
  • финальный продукт Tour Builder — это многосегментный туристический пакет: переезды, разное проживание по сегментам, экскурсии, услуги, аренда транспорта, страхование.

Это означает: всякая мысль о «турбилдере как помощнике агента в отдельном UI» отвергается. Tour Builder — это архитектурный домен с собственным API и собственной коммерческой моделью, на который опираются и собственные интерфейсы, и партнёрские интеграции.

1.6. Слои данных, машинного обучения и эксперимента — first-class с нулевого дня​

Решение зафиксировано 25.04.2026: события (events tracking), хранилище данных (data warehouse, DWH), пайплайны (ETL/streaming pipelines), инфраструктура машинного обучения (ML platform), фреймворк A/B тестирования закладываются в архитектуру с самого первого документа.

Тезис: ranking, recommendation, dynamic pricing, anomaly detection, conversion optimization, partner-facing analytics product — всё это требует промышленной data-платформы. Если её не закладывать с нуля, попытка добавить машинное обучение через 12 месяцев потребует переписывания event sourcing, retention policies, schema governance, privacy boundaries.

Требуемые контуры:

  • Захват событий (events tracking) — schema-aware, governed, разделённый на доменные события (domain events) и аналитические события (analytical events) с границами приватности.
  • Хранилище данных (data warehouse) — отдельный класс хранилища с retention policies, cross-tenant aggregation rules, privacy-by-design.
  • Пайплайны (ETL/streaming) — реальное время через event bus, пакетная обработка через CDC (change data capture), replay capability как first-class.
  • Платформа машинного обучения (ML platform) — feature store, model registry, model serving, model monitoring. Применяется для ранжирования поиска, рекомендаций, динамического ценообразования, обнаружения аномалий в приёме данных, оценки риска партнёров.
  • A/B тестирование — framework, feature flags, cohort assignment, exposure tracking, метрики основные/вторичные/охранные (primary/secondary/guardrail), статистическая значимость.

Эти контуры разворачиваются по фазам (см. часть 2), но зафиксированы в архитектуре с первого документа.

Часть 2. Лучшие гибкие практики масштабирования​

2.1. Эластичность как baseline​

С первого дня платформа проектируется как эластично самомасштабирующаяся система (elastically auto-scaling system). Это означает следующее:

  • Горизонтальное масштабирование (horizontal scaling) как первичный путь для всех stateless-контуров.
  • Авто-масштабирование (auto-scaling) на основе метрик нагрузки: использование процессора, использование памяти, отставание очередей (queue lag), частота запросов (request rate), задержка на 95-м и 99-м процентилях (p95/p99 latency), доменные метрики (активные quote, ожидающие бронирования, давление на поставщиков).
  • Изоляция контуров исполнения (execution contour isolation) с независимым масштабированием каждого контура.
  • Гарантированная мощность для премиум-клиентов (capacity envelope per tenant tier) — дифференцированное обслуживание по уровню партнёра.
  • Дисциплина обратного давления (backpressure discipline) на асинхронных очередях для предотвращения каскадных сбоев.
  • Грациозная деградация (graceful degradation) при перегрузке — не отказ в обслуживании, а понижение качества (например: чтение продолжает работать, новый booking — отложен с retry-after).

2.2. Фазовая упаковка вычислений с триггерами​

Стратегия упаковки вычислений (compute packaging) разворачивается через 4 фазы с явными триггерами перехода. Полная карта фаз — в документе Дорожная карта инфраструктурного масштабирования и упаковки вычислений (OVHcloud baseline).

Краткая суть:

ФазаДлительность ориентировочноОсновная упаковкаРасходы $/год
1 Bootstrap (запуск)0-12 месVPS-3 + Managed PostgreSQL Essential + Object Storage + vRack800-2900
2 Service isolation (изоляция сервисов)12-24 месBare Metal Advance × 3 + Managed Kafka + OpenSearch + Managed Kubernetes17 000-31 000
3 Workload-specific (упаковка под профиль нагрузки)24-36 месBare Metal Scale + Eco Rise + Managed Enterprise + AI Platform77 000-166 000
4 Multi-region и dedicated (многорегиональная и выделенная)36+ месBare Metal Multi-region + 3-AZ Paris + edge130 000-300 000+

Каждый переход — это расширение, не миграция. Все фазы реализуются внутри одной экосистемы (OVHcloud), все компоненты соединяются через единую частную сеть (vRack), переезд между типами упаковки не требует переделки сетевой архитектуры.

2.3. Управляемые сервисы первичны​

Базы данных, очереди, поиск, объектное хранилище — берутся как managed-сервисы у OVHcloud (или эквивалентного провайдера). Своя ценность платформы — каноничная модель и бизнес-логика, не самостоятельное администрирование PostgreSQL.

Тезисы:

  • managed-сервисы освобождают команду от операционного бремени резервного копирования, восстановления, обновления версий, мониторинга базовых метрик;
  • их стоимость на старте сопоставима с self-hosted при пересчёте на стоимость инженерного времени;
  • миграция с managed на self-hosted (если потребуется на фазе 3+) — это локальный рефакторинг, не переписывание архитектуры;
  • managed-сервисы по открытым стандартам (стандартный PostgreSQL, S3-совместимое хранилище, стандартный Kubernetes API) — без проприетарного замыкания (vendor lock-in).

2.4. Открытые стандарты, без замыкания на провайдере​

Все архитектурные решения по выбору технологий проверяются по критерию открытости:

  • PostgreSQL — стандарт, не Aurora/Spanner.
  • S3-совместимое объектное хранилище — стандартный API, не проприетарный формат.
  • Kafka — стандарт, не Kinesis.
  • Kubernetes API — стандарт, не EKS-специфичные расширения.
  • Redis-совместимый Valkey — стандарт.
  • OpenAPI / AsyncAPI — стандартные контрактные форматы.

Это позволяет в фазе 4 рассмотреть многооблачную (multi-cloud) стратегию для отдельных нагрузок без переписывания.

2.5. Динамическая тарификация платформенных услуг​

Тарификация партнёров основана на реальной нагрузке, которую они создают на платформу:

  • базовая ставка за подписку (subscription fee) — фиксированная плата за уровень доступа;
  • переменная плата за объём (usage-based component) — поисковые запросы, quote, booking, ML-инференс, supplier-call budget;
  • дифференциация по сложности — «дорогие» поставщики, тяжёлые композиции Tour Builder, сложные геозапросы стоят больше;
  • квоты и лимиты как продукт — каждый тарифный уровень имеет явные envelope, превышение — повышение тарифа или отдельная оплата;
  • прозрачность — партнёр в любой момент видит свою фактическую нагрузку и прогноз счёта.

Это переводит коммерческую модель с «комиссия с бронирования» на полноценную модель доступа к платформе, где сама платформа — продукт.

Часть 3. Известные дыры первичного слоя документов​

Этот раздел — честное признание пробелов в существующих 50 документах первого-третьего круга. Это не критика старой работы (она дала сильный фундамент по доменной модели, surface contracts, commercial axis), а карта работ, которые необходимо выполнить для перехода к зрелой архитектуре.

Полный анализ пробелов и сильных сторон зафиксирован в рабочем артефакте архитектора: /mnt/d/SITES/@@@@DocsRev/vitiana-api-platform-critical-analysis-2026-04-25.md. Здесь — выжимка с приоритизацией.

3.1. Структурные пробелы (главные)​

Восемь структурных проблем, обнаруженных в первичном слое документов:

Дыра 1. Не зафиксирован архитектурный якорь (architectural anchor)​

Проблема в первичном слое: документация одновременно описывает четыре направления (canonical inventory backbone, B2B agency platform, B2B API marketplace, B2C storefront) как параллельные приоритеты. Без явного якоря решения по доменам остаются плавающими.

Как закрыто в манифесте: часть 1.1-1.4 фиксирует B2B API marketplace как primary + vitrip.store как demonstration + agency platform как fast-follower. Все 4 направления сохраняются, но приоритет инвестиций определён.

Документ-следствие: новый overview/architectural-anchor-and-business-model.md — расширенное описание якоря и trade-off matrix.

Дыра 2. API-as-product недостроен ровно там, где должен быть монетизирован​

Проблема в первичном слое: существующие документы (api-contracts.md, api-metering-and-usage-governance.md) описывают контракты и метрики, но не описывают API как полноценный продукт: sandbox, developer experience, тарифные уровни, billing console, certification flow, status page, support tiers.

Как закрыто в манифесте: часть 1.4 фиксирует динамическую тарификацию услуг как ключевой источник монетизации.

Документ-следствие: новый reference/api-as-product.md — описание API как продукта со всеми атрибутами.

Дыра 3. Tour Builder как differentiator без операционной модели​

Проблема в первичном слое: существующий tour-builder-domain.md описывает доменные сущности (Draft, DraftItem, Variant, Proposal, Version, Artifact), но не описывает: правила композиции (composition rules taxonomy), согласованность между поставщиками (multi-supplier coherence), обработку дрифта (drift handling), классификацию bookable / informational, merchant-of-record per компонент, тур-уровневое ценообразование.

Как закрыто в манифесте: часть 1.5 фиксирует Tour Builder как ядро платформы с raw API constructor по модулям и закрытой системой доступа.

Документ-следствие: новый reference/tour-builder-operational-model.md — операционная модель композиции тура.

Дыра 4. Search и discovery как доменная зона​

Проблема в первичном слое: существующие документы трактуют поиск как «вход в offer pipeline». Не описаны: ранжирование (ranking), релевантность, наблюдаемость качества поиска, экономика запросов, защита от злоупотреблений (anti-abuse), стратегия фасетов, согласованность канонической истины и поисковой проекции, geo и destination model, локализация.

Как закрыто в манифесте: часть 1.6 фиксирует, что слой данных и машинного обучения (включая поисковое ранжирование) закладывается с нуля.

Документ-следствие: новый reference/search-and-discovery.md — доменное описание поиска как самостоятельного контура.

Дыра 5. Multi-tenancy недо-продуктована для дистрибуции​

Проблема в первичном слое: существующий tenancy-and-identity.md описывает правильные boundaries (Identity / Organization / Tenant / ActorContext / CapabilityScope / Contract). Но для бизнес-модели «партнёры разворачивают свои платформы поверх нашего API» нужны: white-label semantics, tenant isolation strength (RLS / schema-per-tenant / dedicated database), self-service developer onboarding, tenant tier и feature gates, cross-tenant analytics, billing console.

Как закрыто в манифесте: части 1.4 и 2.5 фиксируют динамическую тарификацию и явные тарифные уровни.

Документ-следствие: новый reference/multi-tenant-isolation-strength.md + расширения существующих tenancy-and-identity.md и tenant-configuration-and-enablement.md.

Проблема в первичном слое: для платформы, продающей туристические продукты в EU и предоставляющей API партнёрам, требования включают: GDPR (DSR, DPA, sub-processor lists, cross-border transfers), Package Travel Directive (EU 2015/2302), DAC7/DSA, PCI DSS, merchant-of-record, AML/KYC на партнёров, налоги/НДС (TOMS — Tour Operators' Margin Scheme), consumer rights, chargeback handling. В существующих документах это упомянуто только косвенно.

Как закрыто в манифесте: часть 1.3 фиксирует цепочку merchant-of-record как гибридную per-tenant.

Документ-следствие: новый reference/compliance-and-legal.md (или operations/compliance-and-legal.md) — соответствие и правовая позиция.

Дыра 7. Operations execution — самое тонкое место​

Проблема в первичном слое: существующие документы (deployment.md, settlement-and-reconciliation.md, observability-and-incident-response.md) описывают контуры исполнения и классы расхождений. Но не описывают: операционные руководства (runbooks) для топ-10 инцидентов, модель дежурства (on-call model), SLA как контракт с явными credits, план восстановления после аварии (disaster recovery) с RTO/RPO, планирование мощности (capacity planning), цикл закрытия сверки (reconciliation closing), SLA жизненного цикла спора (dispute lifecycle SLA).

Как закрыто в манифесте: часть 2.2 ссылается на дорожную карту масштабирования; описывает фазовый подход к operations.

Документы-следствия:

  • новый operations/runbooks-incident-playbooks.md
  • новый operations/sla-and-on-call-model.md
  • новый operations/disaster-recovery-and-capacity.md
  • расширение существующего operations/settlement-and-reconciliation.md до dispute & reconciliation operations.

Дыра 8. Размер документации против реалистичной команды​

Проблема в первичном слое: 50 документов архитектуры, 13 release units, 17+ event channel families. Без явного MVP-боундари и реалистичного team plan этот объём не реализуем командой 6 человек за 6 месяцев, как описано в существующем roadmap.md.

Как закрыто в манифесте: часть 2.2 фиксирует фазовую упаковку с триггерами; не календарную, а метрическую.

Документы-следствия:

  • переработка существующего development/roadmap.md — выкинуть Year-1 timeline в архив, переписать в чистую stages model;
  • новый development/team-and-staffing-plan.md — реалистичный team plan по фазам;
  • новый development/documentation-governance.md — управление связями между документами и кодом.

3.2. Доменные пробелы​

Восемь доменных областей, отсутствующих или фрагментарных в первичном слое:

ДыраОписаниеДокумент-следствие
3.2.1 Booking state machine14+ состояний бронирования упомянуты, но нет полной диаграммы переходов, параллельных состояний, разрешения unknown_external_state, компенсирующих транзакцийreference/booking-state-machine.md
3.2.2 Payment domainPaymentIntent упомянут как сущность, но нет описания PSP, 3DS/SCA, токенизации, refund mechanics, chargeback handling, payment methods per regionreference/payment-domain.md
3.2.3 Notification & communicationWebhooks упомянуты, но customer-facing email/SMS/in-app, partner webhooks, internal alerts, vouchers — не описаны как доменreference/notification-and-communication.md
3.2.4 Inventory completeness и coverage gap detectionAuto/probable/no-match handling описан, но обратная задача обнаружения отсутствующих данных от поставщика — не описанарасширение reference/ingestion.md
3.2.5 Search query languageНе описан синтаксис запросов: free-form, structured filter, geo radius/polygon, гибкие даты, multi-legчасть reference/search-and-discovery.md
3.2.6 Image и blob pipelineObject Storage упомянут, но нет описания: нормализация, дедупликация, attribution/copyright, CDN economicsreference/media-and-content.md
3.2.7 Internationalization deeperЛокализация упомянута на уровне contracts. Не описаны: translation workflow, currency display/conversion, timezone handling, locale formattingreference/internationalization-and-localization.md
3.2.8 Аналитика и BI как продукт для tenantsStorage class «Analytical / Reporting Layer» упомянут, но нет описания внутренней аналитики и tenant-facing reporting productreference/analytics-and-bi.md

3.3. Конкретные противоречия в существующих документах​

Десять противоречий, обнаруженных в первичном слое:

  1. Vitiana API Platform vs vitrip.store — slug проекта и домен не совпадают.
  2. Статус «Готов к обсуждению» на всех документах с разной фактической зрелостью.
  3. Roadmap старая часть vs новая часть — две несшитые эпохи (stages model + Year-1 timeline).
  4. «13 services» vs «RU-1 — RU-7» — два независимых разбиения без mapping.
  5. Sandbox / production environment separation — упомянут в contracts, но не в инфраструктуре.
  6. Формат API ключей — расходится между документами.
  7. PostGIS coordinate type — расхождение с реальным использованием.
  8. Refresh token blacklist — упомянут в логике, не в schema.
  9. Hotel matching algorithm — описан в нескольких местах с разной детализацией.
  10. Database schema property-centric, domain-model offer-centric — расхождение, ожидаемое на драфтовой стадии.

План закрытия: систематическая ревизия в фазе 7 (см. CLAUDE.md §8 «Порядок работы»). Каждое противоречие резолвится через docs_patch_section с явным обоснованием выбранного варианта.

3.4. Отсутствующая экономическая модель​

В первичном слое присутствует revenue model на уровне roadmap (€45K MRR к 12 месяцу), но нет экономической модели платформы:

  • стоимость поиска / quote / booking (cost-per-search / quote / booking);
  • экономика look-to-book ratio;
  • экономика cache hit rate;
  • per-tenant economics — где порог окупаемости.

Документ-следствие: новый reference/economic-model.md — обоснование динамической тарификации в unit economics.

3.5. Слабая увязка между «вертикалями»​

Соседние документы описывают одни сущности с разной детализацией. Примеры: domain-model.md называет Quote коммерческой фиксацией, commercial-model.md — commercial promise, offer-pricing-booking-semantics.md — actor-specific fixation. Смыслы близкие, но точные атрибуты различаются.

Как закрывается: живой граф ссылок (living link graph) через docs_links после каждого крупного изменения. Documentation governance (новый документ) формализует процедуру.

Часть 4. План закрытия дыр​

Полный план реализации — в CLAUDE.md §8 «Порядок работы». Краткая сводка по фазам:

ФазаЧто делаетсяДокументы
Фаза 0 — фиксация (закрыта 25.04.2026)Манифест, рабочая память, правилаэтот документ, CLAUDE.md, memory
Фаза 1 — глубокая ориентацияКонтекст первой реализации ingestion (home-to-go-api); карта соответствия canonical model и текущей реализациивнутренние заметки архитектора
Фаза 2 — anchor & business modelРасширенное описание архитектурного якоряoverview/architectural-anchor-and-business-model.md
Фаза 3 — bridge documentМост между архитектурой и home-to-go-apioverview/relation-to-implementation-baseline.md
Фаза 4 — критические gaps (новые домены)В порядке зависимости: Compliance & Legal → Payment → Search → API-as-Product → Data Platform / ML / A-B → Notification → Media → Internationalization → Analytics & BI → Economic Model10 новых документов в reference/
Фаза 5 — углубление существующихTour Builder operational, Booking state machine, Multi-tenant isolation strength3 новых документа в reference/
Фаза 6 — operations layerRunbooks, SLA, DR, dispute & reconciliation4 новых документа в operations/
Фаза 7 — переработка проблемныхroadmap.md, clients.md, deployment.mdпереписывание существующих
Фаза 8 — documentation governanceУправление связями между документами и кодомdevelopment/documentation-governance.md
Фаза 9 — team & staffingРеалистичный team plan по фазам зрелостиdevelopment/team-and-staffing-plan.md
Фаза 10 — финалdocs_lint по всем документам; обновление index.md; обновление main-findings.mdфинальная синхронизация

После каждой фазы — отчёт пользователю с картой пересечений: какие документы созданы/обновлены, какие получили новые backlinks, какие открытые развилки появились, какие следующие документы заблокированы или разблокированы.

Часть 5. Принципы поверх правил​

5.1. Каждое решение проходит через 4 проверки​

Перед публикацией любого архитектурного решения в документе оно проверяется по четырём вопросам:

  1. Не выводится ли решение из структуры конкретного поставщика? Если да — переформулировать от целей платформы (правило 00000).
  2. Можно ли заменить любого поставщика без переписывания этого документа? Если нет — рефакторить формулировки.
  3. Описана ли в документе платформа как самостоятельный коммерческий продукт, не как «доступ к чужим данным»?
  4. Поддерживает ли архитектура добавление нового поставщика без расширения каноничной модели?

Если хоть один ответ «нет» — документ переписывается.

5.2. Каждое нетривиальное решение содержит обоснование​

Минимальный набор для любого ключевого решения в документе:

  • цель решения;
  • 3-5 тезисов поддержки;
  • 1-2 отклонённые альтернативы с обоснованием отклонения;
  • принимаемые компромиссы (trade-off);
  • связь с другими документами и решениями;
  • ссылка на современные лучшие практики.

5.3. Развитие, не деградация​

Каждое решение работает на развитие:

  • никаких заглушек, временных решений без плана миграции, hardcode-привязок;
  • каждый переход между фазами — расширение, не миграция;
  • открытые развилки фиксируются явно (раздел «Открытые вопросы»), не превращаются в заглушки.

5.4. Современные лучшие практики, не legacy​

Архитектурные решения опираются на паттерны платформ верхнего уровня (Stripe, Twilio, Algolia, Cloudflare, Snowflake, Vercel, Plaid). Чужие практики переосмысливаются и улучшаются, не копируются. Запрещено: «Booking.com делает так, поэтому мы тоже».

5.5. Контекст связей удерживается активно​

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

Часть 6. Открытые развилки манифеста​

Несколько решений требуют дополнительного диалога с пользователем при их закрытии. Зафиксированы здесь как явные открытые точки:

Развилка 1. Migration path для уже задеплоенных таблиц​

Текущая реализация home-to-go-api содержит схемы (hotels, usr, events_themes), которые были спроектированы под Stuba. Переход к каноничной модели Vitiana потребует рефакторинга adapter ingestion.

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

Рекомендация архитектора: документную базу закрыть в фазах 1-9, рефакторинг кода начать после стабилизации canonical-документов. Эскалируется при принятии решения.

Развилка 2. Размер первой команды​

CLAUDE.md фиксирует требование «12-15 человек минимум для зрелой системы в 9-12 месяцев». Это противоречит существующему roadmap «6 человек за 6 месяцев».

Открытый вопрос: какой размер команды и какой бюджет на 12-месячный горизонт реально доступен?

Рекомендация архитектора: уточнить совместно при создании development/team-and-staffing-plan.md.

Развилка 3. Использование AWS/GCP в дополнение к OVHcloud​

OVHcloud — первичная экосистема. Открытая развилка для фазы 4: использование AWS/GCP для отдельных нагрузок (например, более развитого AI-стека).

Открытый вопрос: есть ли конкретные кейсы, где AWS/GCP даёт критическое преимущество?

Рекомендация архитектора: не пересматривать на фазах 1-3. Эскалируется в момент достижения фазы 4.

Развилка 4. Tier структура динамической тарификации​

Часть 1.4 фиксирует принципы динамической тарификации. Конкретные tier (Free / Starter / Professional / Enterprise) и их цены требуют отдельной экономической проработки.

Открытый вопрос: какие tier и какие цены входят в каждый?

Рекомендация архитектора: проработать в reference/economic-model.md и reference/api-as-product.md. Эскалируется на этапе создания этих документов.

Часть 7. Связь с другими документами​

7.1. Документы, на которые опирается манифест​

7.2. Документы инфраструктуры и фаз​

7.3. Документы первичного анализа​

7.4. Документы-следствия (создаются после манифеста)​

В порядке зависимости (см. часть 4):

Фаза 2-3:

  • overview/architectural-anchor-and-business-model.md
  • overview/relation-to-implementation-baseline.md

Фаза 4 (новые домены):

  • reference/compliance-and-legal.md
  • reference/payment-domain.md
  • reference/search-and-discovery.md
  • reference/api-as-product.md
  • reference/data-platform-and-events-tracking.md
  • reference/ml-platform.md
  • reference/ab-testing-platform.md
  • reference/notification-and-communication.md
  • reference/media-and-content.md
  • reference/internationalization-and-localization.md
  • reference/analytics-and-bi.md
  • reference/economic-model.md

Фаза 5 (углубление существующих):

  • reference/tour-builder-operational-model.md
  • reference/booking-state-machine.md
  • reference/multi-tenant-isolation-strength.md

Фаза 6 (operations):

  • operations/runbooks-incident-playbooks.md
  • operations/sla-and-on-call-model.md
  • operations/disaster-recovery-and-capacity.md
  • расширение operations/settlement-and-reconciliation.md до dispute & reconciliation operations.

Фаза 8-9:

  • development/documentation-governance.md
  • development/team-and-staffing-plan.md

Часть 8. Что нужно сделать после прочтения этого манифеста​

Если читатель — пользователь (владелец платформы):

  1. Подтвердить переосмысление роли как зафиксированное.
  2. Дать команду на переход в фазу 1 (глубокая ориентация по home-to-go-api) или сразу в фазу 2 (создание architectural-anchor-and-business-model.md).
  3. Закрыть открытые развилки манифеста (часть 6) или зафиксировать их как открытые до момента достижения соответствующей фазы.

Если читатель — будущий член команды:

  1. Прочитать этот манифест полностью.
  2. Прочитать overview/index.md как «архитектурную основу второго круга» с пониманием, что некоторые формулировки в нём интерпретируются через призму этого манифеста.
  3. Прочитать reference/domain-model.md — каноничные сущности.
  4. Прочитать соответствующие задаче документы из reference/operations.

Если читатель — внешний ревьюер:

  1. Прочитать манифест.
  2. Запросить рабочий артефакт vitiana-api-platform-critical-analysis-2026-04-25.md для полного контекста дыр.
  3. Прочитать home-to-go-api (PLATFORM.md, HOTEL_DATABASE.md и связанные) для понимания первой реализации ingestion.

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