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

Главные выводы и проблемные зоны платформы

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

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

Этот документ фиксирует главный сводный вывод по текущему состоянию документации vitiana-api-platform.

Его задача — собрать в одном месте наиболее значимые проблемы, противоречия, риски и следующие шаги, которые вытекают из уже проведённых ревью. Это не замена исходных review-документов и не попытка переписать их заново. Это единая управленческая и архитектурная выжимка, по которой нужно принимать дальнейшие решения о развитии документации платформы.

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

Главные выводы этого документа основаны на двух review-документах, которые следует считать опорными источниками анализа:

  1. development/review-log.md
    Краткий независимый лог ревью, фиксирующий критические противоречия и явные структурные проблемы первого слоя документации.

  2. development/codex-architecture-review-2026-04-23.md
    Более глубокое архитектурное ревью, оценивающее не только ошибки и расхождения, но и зрелость самого концепта, его центр тяжести, доменные пробелы и риски преждевременной конкретизации.

Этот документ является не третьим независимым ревью, а именно синтезом этих двух материалов.

Краткий общий вердикт​

Текущий пакет документации платформы нельзя считать слабым. В нём уже есть заметная инженерная интуиция, хороший масштаб замысла и попытка думать не страницами и формами, а ядром платформы, слоями данных, интеграциями, ценовым контуром, каналами продаж и будущими операционными сценариями.

Но на текущем этапе это всё ещё не финальный архитектурный baseline, на который безопасно опираться как на завершённую проектную правду.

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

Иными словами:

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

Обновление Статуса На Текущий Момент​

На момент этой версии часть главных архитектурных пробелов уже закрыта отдельными несущими документами второго и третьего круга.

Уже созданы и встроены в общий каркас:

Также уже синхронизированы основные несущие reference-документы:

  • business-services.md
  • database-schema.md
  • storage.md
  • api-contracts.md
  • clients.md
  • suppliers.md
  • ingestion.md
  • overview/layers.md

Это меняет общий статус пакета:

  • главный архитектурный каркас уже не является только намерением;
  • центральные доменные оси уже зафиксированы;
  • основной риск сместился с “домен не оформлен” к “верхний narrative, operations и execution-model должны быть дотянуты до уже собранного каркаса”.
  • одновременно стало ясно, что distribution-grade maturity требует уже не только core domain, но и явных контуров clearing, post-booking, tenant enablement, usage governance и publication integrity.

Обновление Статуса После Усиления Distribution-И-Execution Слоя​

Следующий заметный пробел после сборки второго и третьего круга действительно находился не в Offer или Booking как таковых, а в том, что платформа ещё недостаточно явно удерживала industrial realities distribution-бизнеса:

  • partner-side financial control;
  • tenant-specific enablement and policy expression;
  • consumption economics of external API usage;
  • post-booking service reality;
  • integrity gating before external publication.

На текущем этапе и эти пробелы уже подняты в отдельные документы:

Это не означает, что execution-layer уже окончательно завершён. Но это означает, что критика вида “платформа сильна до booking, но не после него” или “platform API не держит financial and tenant logic” теперь уже должна обсуждаться в терминах глубины и согласованности этих документов, а не их полного отсутствия.

Отдельный следующий вопрос после этого слоя — не “какой модный стек выбрать”, а как сформировать implementation baseline, который будет согласован с уже собранной архитектурой и не разрушит разделение execution contours. На текущем этапе это уже оформлено в Implementation Technology Baseline — Рекомендуемый технологический фундамент реализации.

После этого следующим естественным шагом стали уже не новые доменные сущности, а технические baselines для async coordination and observability tooling. На текущем этапе и они уже зафиксированы отдельно:

Следующим шагом после этих baselines уже логично стал не новый общий обзор, а переход к implementation-oriented раскладке первых release units. Это теперь зафиксировано в Implementation Ready Breakdown — Первые release units, execution slices и порядок практической реализации.

Следующий слой после этого — не общий “API документ”, а первый implementation-ready contract package для этих release units. Он теперь зафиксирован в Initial Contract Package — Первый implementation-ready пакет контрактов платформы.

Следующий более формальный шаг после contract package — уже не общий API narrative, а bounded synchronous contract artifact. Он теперь зафиксирован в OpenAPI Skeletons And Resource Families — Первый bounded synchronous contract artifact.

Следующий парный шаг после bounded synchronous layer — уже не расплывчатая “event-driven идея”, а bounded asynchronous contract artifact. Он теперь зафиксирован в AsyncAPI Skeletons And Event Envelopes — Первый bounded asynchronous contract artifact.

Следующий более прикладной шаг после async skeleton — уже не просто перечисление event families, а первый release-unit-aware channel catalog. Он теперь зафиксирован в Channel Catalog Drafts By Release Unit — Первые channel families, producers, consumers и delivery expectations.

Следующий shape-level шаг после channel catalog — уже не только список каналов, а первые bounded payload family outlines для high-value channels. Он теперь зафиксирован в Payload Family Outlines For High-Value Channels — Первые bounded payload shapes для ключевых async channels.

Следующий concrete example-level шаг после payload family outlines — уже не только shape rules, а первые example payloads для наиболее критичных событий. Он теперь зафиксирован в Payload Examples For Top Critical Events — Первые example payloads для ключевых async событий.

Следующий полуформальный шаг после example-layer — уже не только illustrative JSON, а первый schema-draft package для этих критичных событий. Он теперь зафиксирован в Schema Draft Package For Top Critical Events — Первый полуформальный schema-layer для критичных async событий.

Следующий policy-layer после schema drafts — уже не только структура событий, а явные правила их безопасной эволюции. Он теперь зафиксирован в Version Evolution Policy For Async Event Contracts — Правила версии, совместимости и replay-дисциплины.

Следующий execution-policy шаг после version policy — уже не только правила эволюции, а явная матрица обработки и восстановления событий по schema families. Она теперь зафиксирована в Retry DLQ Replay Matrix By Schema Family — Исполнительная матрица доставки, повторов и восстановления.

Следующий release-gate шаг после этой матрицы — уже не только общая policy, а практический checklist готовности consumers по release units. Он теперь зафиксирован в Consumer Compatibility Checklist By Release Unit — Проверка готовности consumers к эволюции async contracts.

Следующий более формальный field-level шаг после этого checklist — уже не только schema drafts, а полуформальные field catalogs по критичным событиям. Он теперь зафиксирован в JSON Schema Like Field Catalogs For Top Critical Events — Полуформальные field catalogs для критичных async событий.

Следующий внешний boundary-level шаг после field catalogs — уже не только внутренние async contracts, а явная граница их безопасной внешней проекции на partner-facing async surface. Он теперь зафиксирован в Webhook Compatibility Checklist For External Async Notifications — Границы внешних async уведомлений и их совместимости.

Следующий paired release-gate шаг после webhook boundary — уже не только consumer readiness и не только внешний projection boundary, а producer-side дисциплина безопасного выпуска contract changes. Он теперь зафиксирован в Producer Readiness Checklist For Async Contract Changes — Проверка готовности producers к безопасному выпуску изменений async contracts.

Следующий catalog-level шаг после producer-side gate — уже не только правила совместимости, а явная раскладка того, какие внешние async projections вообще допустимы для разных surface-ов и классов партнёров. Он теперь зафиксирован в External Async Projection Catalog By Surface And Partner Class — Каталог внешних async-проекций по surface-ам и классам партнёров.

Следующий external example-level шаг после projection catalog — уже не только допустимые классы внешних уведомлений, а первые bounded payload examples для этих projections. Он теперь зафиксирован в Bounded Webhook Payload Examples For External Projections — Примеры внешних bounded webhook payloads.

Обновление Статуса После Завершения Фаз 0–9 (27.04.2026)​

Между 25.04.2026 и 27.04.2026 проведена крупная архитектурная переработка платформы — Фазы 0–9 development roadmap.

Обновление Статуса После Внешнего Архитектурного Ревью (30.04.2026)​

30.04.2026 получено внешнее архитектурное ревью платформы по абстрактному техническому заданию. Полный текст ревью с постатейными ответами архитектора зафиксирован в external-review-2026-04-30.md.

Общий вердикт ревью​

«Промышленный радикализм — попытка построить Stripe в мире Travel». Ревьюер признал архитектуру готовой к реализации Stage 1, при условии закрытия трёх критических gap'ов. Главный комплимент: «Платформа мыслит Офферами и Квотами, а не комнатами — это позволяет строить Tour Builder как ядро, а не как надстройку».

Что было закрыто по итогам ревью​

В ходе работы над интеграцией замечаний ревью закрыто 10 правок по 4 блокам приоритета.

Block 1 — критичное к Stage 1 (3 правки)​

  1. Conflict Resolution Playbook — добавлен в reference/data-governance-and-matching.md. Сводит уже существующие governance-механизмы (Source Precedence, Confidence Model, Manual Review) в операционный playbook для типовых сценариев конфликта данных от множества supplier'ов. Это самый важный gap из ревью — без него ingestion на 50 supplier'ов накопит «гнилой фундамент».
  2. Жёсткие гарантии завершения цикла unknown_external_state — добавлены в reference/booking-state-machine.md и связанное правило unknown_state_balance_release в reference/partner-finance-and-clearing.md. Hard timeout 15 минут (search-флоу), 4 часа (booking-флоу), 32 часа (post-confirmed). Гарантия не-блокировки партнёрского баланса навсегда. Cumulative circuit breaker против каскадных сбоев.
  3. Принцип «SDK как тонкая обёртка» — добавлен в reference/api-as-product.md. Снимает риск «raw API партнёры — граждане второго сорта»: SDK не несёт бизнес-логики, любая фича — first-class в API, raw-API партнёры получают тот же функционал.

Block 2 — закладка для Stage 2-3 (3 правки)​

  1. Inventory не-отельных доменов — создан новый документ reference/inventory-non-accommodation-domains.md. Каноничные модели для 5 segment-типов (flights, transfers, insurance, activities, ancillaries) с явной Quote-семантикой каждого, lifecycle и compliance-специфика. Закладка с Stage 1, активация с Stage 2-3.
  2. Stage 1 minimum для ML — добавлен раздел в reference/ml-platform.md. 5 MVP-моделей с явным минимальным data contract, требования к event schema, feature naming conventions, DWH partitioning. Принцип: накапливай данные в правильной схеме с нулевого дня.
  3. Каскадный drift и auto-replace — добавлен в reference/tour-builder-operational-model.md. Каскадный анализ влияния DriftEvent на весь тур, replacement candidates с ranking, threshold rules (negligible / noticeable / material), bundle integrity strict invariants.

Block 3 — финансовые уточнения (2 правки)​

  1. Settlement Split — добавлен в reference/partner-finance-and-clearing.md. Каноничное разделение ответственности при refund: supplier portion / platform portion (insolvency protection per Package Travel Directive) / customer portion / loss accounting. Insurance product как opt-in расширение.
  2. Long-Running Idempotency — добавлен в reference/eventing-and-queue-baseline.md. Каноничная семантика для длинных операций (саги Tour Builder): три фазы (in_progress / completed / expired), partial result в response, polling pattern, force retry mechanism. Это gap, не указанный в ревью, но обнаруженный архитектором при анализе.

Block 4 — коммуникационные (2 правки)​

  1. «Stripe в travel» elevator pitch — добавлен в overview/architectural-anchor-and-business-model.md. Формулировка ревьюера принята как каноничное краткое позиционирование платформы. Каждой аудитории (партнёр, инвестор, регулятор) — соответствующий вариант.
  2. Прозрачность тарификации для партнёра — добавлен в reference/economic-model.md. Закрытый перечень платных объектов, явные ставки, real-time dashboard с примером mockup'а, 4 каноничных профиля потребления (start agency, active B2B, enterprise, white-label). Снимает риск интерпретации «плата за сложность».

Замечания ревьюера, по которым позиция уточнена​

Два замечания не отвергнуты, но решение отличается от предложения ревьюера:

SDK-граждане первого сорта​

Ревьюер предупредил: «SDK партнёры могут стать привилегированной группой». Наше каноничное решение иное: SDK — тонкая обёртка над API, никакой бизнес-логики в SDK нет, raw-API партнёры получают функционально эквивалентный опыт. Это снимает риск через архитектурную дисциплину, не через регуляции.

Тарификация за «сложность»​

Ревьюер предупредил: «Партнёры не поймут плату за сложность запроса». Наше каноничное решение: мы не платим за сложность, мы платим за потребление с фиксированными ставками за чётко определённые объекты. Это устраняет проблему через прозрачность определений, не через изменение pricing model.

Что осталось зафиксировать (отложенные направления)​

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

  • Cruise как самостоятельный segment-тип vs композит (см. inventory-non-accommodation-domains.md, раздел открытых вопросов).
  • Bundle pricing для flight + accommodation: единый bundle price или два отдельных Quote с явной дисконтной структурой.

Решение по этим направлениям принимается при первой реальной потребности (cruise — при подключении первого cruise-supplier'а; bundle pricing — при первом крупном партнёре, который запросит явные bundle deals).

Влияние на roadmap​

Ревью не сдвинуло фазы roadmap'а:

  • Stage 1 (старт) остаётся достижимым — после закрытия Block 1 правок все критические gap'ы закрыты.
  • Stage 2 (изоляция сервисов) и Stage 3 (специализированная упаковка) получили дополнительные закладки (inventory non-accommodation, ML stage 1 minimum, cascading drift), но это обогащение, не задержка.
  • Stage 4 (multi-region) — не затронут.

Изменение приоритетной шкалы проблем​

Ревью подтвердило ранее зафиксированную shкалу проблем (см. раздел Приоритетная шкала проблем ниже). Главный совет ревьюера — «сфокусируйтесь на Governance данных» — уже соответствует приоритету №1 в нашей шкале (Главный вывод №9 — Governance и operational human-in-the-loop слой). Это совпадение приоритетов укрепляет уверенность в правильности архитектурного направления.

Метрика зрелости архитектурного процесса​

Получение содержательного внешнего ревью + системное закрытие 10 правок за один рабочий цикл — сигнал зрелости документного слоя. Ранее (до Фаз 0-9) такое ревью потребовало бы недель работы по реструктуризации; сейчас правки заняли часы и не сломали ни одной существующей связи между документами.

Это означает что link-graph integrity документного слоя достигла операционного уровня. Дальнейшие правки могут добавляться по этому же паттерну: внешнее ревью → audit-документ → постатейные ответы → block-priority list → точечные правки в конкретных документах.

Связь с Свод законов ИИ-агента​

Ревьюер явно отметил: «Тезисное обоснование имеется почти везде. Это делает ТЗ понятным для Senior-подрядчика». Это подтверждение что правило тезисного обоснования (см. feedback_thesis_based_justification.md в персональной памяти агента) работает как заявлено: каждое нетривиальное архитектурное решение в платформе содержит тезисы с альтернативами и trade-off, что делает архитектуру понимаемой и аудируемой.

Это важная мета-метрика процесса, не только содержания: документация платформы уже обеспечивает possibility of meaningful external review, а не только internal alignment.

Зафиксированы 5 архитектурных правил (development/)​

Закрыты 3 overview-документа​

Опубликованы 11 новых reference-документов (Фаза 4 — критические gaps)​

Опубликованы 3 reference-документа (Фаза 5 — углубление существующих)​

Опубликованы 3 operations-документа (Фаза 6 — operational maturity)​

Переработаны 3 проблемных документа (Фаза 7)​

Опубликованы 2 новых development-документа (Фазы 8–9)​

Что это меняет в общем статусе пакета​

Главный вывод №1 (архитектурный центр) закрыт. Архитектурная ось зафиксирована (правило 00000 + 6 архитектурных осей в overview/index.md), главный центр платформы — canonical model + Tour Builder как core + B2B API marketplace primary anchor. Это уже не размывается между несколькими возможными центрами тяжести.

Главный вывод №2 (доменная модель) закрыт. Доменная модель собрана как обязательная основа. Все 16 новых документов и переработанные ссылаются на доменную модель и не противоречат ей.

Главный вывод №3 (преждевременная финальность) частично закрыт. Старые версии clients.md и roadmap.md архивированы. deployment.md обогащён без архивации, потому что концептуальная база была здоровой. api-contracts.md и database-schema.md остаются как «ранние конкретизации» — их переработка — задача стадии 1 implementation baseline.

Появились новые столпы:

  • 4 столпа операционной зрелости (deployment ↔ runbooks ↔ SLA ↔ DR / capacity);
  • 3 столпа продуктовой зрелости (API as Product, Tour Builder partner-grade, B2C demonstration через vitrip.store);
  • 2 столпа governance (documentation-governance, team-and-staffing-plan);
  • 5 архитектурных правил-законов как явные нормативы.

Главный риск сместился: не «архитектура не оформлена», не «домен не сформирован» — а «implementation baseline ещё не начат». Стадия 0 development roadmap почти пройдена, стадия 1 — следующий шаг.

Открытые развилки (зафиксированные, требуют решения)​

Зафиксированы в разных документах. Сводный список наиболее значимых:

  1. Геополитический риск UA — primary deployment в EU (CZ/PL), UA как edge presence; финансовая инфраструктура за пределами UA. Зафиксировано в roadmap.md, требует регулярной переоценки.
  2. Выбор первого PSP — Stripe vs multi-PSP adapter с нулевого дня (см. payment-domain.md, решение на стадии 1).
  3. Multi-cloud DR — AWS как backup для OVHcloud (решение на стадии 4 при появлении enterprise-клиента).
  4. Open marketplace timeline — стадия 5 или 6 (решение в конце стадии 5).
  5. Geographic expansion sequencing — вторая волна (DE/AT/RO/SK или EU broader vs. CIS), решение по результатам стадии 4.
  6. Mobile-first vs web-first для Surface 5 (B2C) — решение на стадии 3.
  7. Single SDK vs per-language SDKs — решение на стадии 1 после партнёрских интервью.
  8. DPO requirement threshold — при каком объёме данных DPO становится mandatory.
  9. ADR (Architecture Decision Records) как отдельный формат — текущая модель: тезисное обоснование внутри документов; решение по результатам стадии 2.
  10. Public DocMap publication — когда открывать DocMap наружу (стадия 3 controlled external beta).

Следующий практический шаг​

Закрытие стадии 0 development roadmap (см. roadmap.md):

  1. провести финальный docs_lint по всем документам vitiana-api-platform — выполнено 27.04.2026;
  2. запустить tools/build_project_index.sh vitiana-api-platform — выполнено 27.04.2026;
  3. убедиться, что все 16 новых документов интегрированы в граф backlinks без невязок — выполнено;
  4. перейти к стадии 1 implementation baseline:
    • подготовить implementation slices для первого release unit;
    • подготовить supplier onboarding playbook для второго supplier (доказательство правила 00000);
    • развернуть Tier 1 backup и restore процедуру в dev окружении;
    • спроектировать первый production-capable execution contour.

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

Главный вывод №1. Архитектурный центр платформы ещё не зафиксирован окончательно​

Этот вывод был полностью справедлив для исходного первого слоя.

На текущем этапе центр платформы уже зафиксирован значительно жёстче:

  • canonical model;
  • offer-centric operational state;
  • commercial interpretation;
  • quote as commercial promise;
  • booking as transactional commitment;
  • tour composition;
  • governance and publication discipline.

Но риск полностью не исчез: теперь нужно удержать этот центр не только в reference-документах, но и в overview, operations и execution-oriented слоях.

В текущем наборе документов платформа одновременно тяготеет к нескольким возможным центрам тяжести:

  • platform-core для нормализованного hotel inventory;
  • booking platform;
  • partner API platform;
  • агентская B2B-платформа;
  • B2C-поверхность поиска и продажи;
  • Tour Builder как продуктовый differentiator.

На уровне vision это допустимо. Но на уровне проектирования это уже риск. Пока не закреплён главный архитектурный центр системы, почти все последующие решения остаются частично плавающими:

  • какие сущности главные, а какие производные;
  • где должен жить source of truth;
  • на каком уровне формируется offer;
  • какая модель пользователей и организаций считается базовой;
  • какое API является главным surface, а какое производным;
  • как должен выглядеть MVP.

Практический смысл​

Следующий слой документации должен зафиксировать не просто список модулей, а главный центр платформы. И только после этого корректно стабилизировать data model, API contracts и deployment shape.

Главный вывод №2. Не зафиксирована каноническая доменная модель​

Этот вывод уже частично закрыт за счёт Domain Model — Центральная доменная модель платформы.

Проблема сместилась:

  • не от отсутствия доменной модели,
  • а к задаче удержать её как обязательную основу для всех следующих execution-oriented документов.

Это самая важная проблема всего пакета.

Сейчас документы уже говорят про отели, комнаты, цены, доступность, бронирования, агентства, партнёров, туры, внешние API, но каноническая модель сущностей ещё не закреплена как единая и обязательная. Из-за этого разные документы описывают систему с разных точек зрения и местами противоречат друг другу.

Особенно критично отсутствие жёсткого разведения между следующими уровнями:

  • Property / Hotel как стабильная сущность объекта размещения;
  • RoomType / Product как тарифная или продуктовая единица;
  • Offer как конкретное предложение в конкретный момент;
  • AvailabilitySnapshot как краткоживущая фиксация доступности;
  • PriceSnapshot как краткоживущая фиксация цены;
  • Booking как результат подтверждённой коммерческой операции;
  • TourDraft / TourProposal как отдельный продуктовый домен, а не просто UI-фича.

Практический смысл​

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

Главный вывод №3. Документы слишком рано выглядят как финальные контракты​

Сильная сторона текущего пакета — конкретность. Но именно она же становится риском. Некоторые документы уже написаны так, будто underlying domain model завершена, хотя это ещё не так.

Особенно это касается:

  • reference/api-contracts.md;
  • reference/database-schema.md;
  • operations/deployment.md.

Они полезны как проектные намерения, но пока опасны как воспринимаемая финальная истина.

Риск​

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

  1. команда начнёт детализировать контракты и инфраструктуру;
  2. затем всплывут незакрытые доменные вопросы;
  3. после этого придётся переписывать уже формализованные технические решения.

Практический смысл​

Следующий слой документации должен сначала стабилизировать домен, а уже потом догонять API, БД и operations.

Главный вывод №4. Внутри первого слоя уже есть прямые противоречия, которые нельзя игнорировать​

По review-log и глубокому review уже выявлены конкретные противоречия, которые делают текущий пакет недостаточно надёжным как основание для реализации.

Критические противоречия​

  1. Название проекта и содержимое не совпадают. Slug и заголовок говорят Vitiana API Platform, а основной контент описывает vitrip.store.

  2. Все документы имеют статус черновика, но часть из них написана как будто решения уже приняты окончательно.

  3. Схема данных расходится между несколькими документами. storage.md, database-schema.md и business-services.md не описывают одни и те же сущности единообразно.

  4. Rate limits Partner API расходятся между документами.

  5. Формат API-ключей партнёров также расходится.

  6. В схеме отсутствуют необходимые сущности для уже заявленной логики. Например, persisting Partner API keys и refresh-token blacklist не доведены до явной модели хранения.

  7. Алгоритм hotel matching описан в нескольких местах по-разному.

  8. Тип coordinates в документации не согласован с фактическим использованием PostGIS-функций.

  9. Есть битые ссылки и признаки копипаста из HTML-экспорта.

  10. Не определена единая роль агент и её отношение к user, agency, partner и внутренним ролям.

Практический смысл​

Перед дальнейшим наращиванием объёма документации эти противоречия должны быть не просто замечены, а превращены в управляемый список обязательных развязок.

Главный вывод №5. Offer-level модель сейчас недоопределена, а без неё нельзя строить pricing и booking​

Этот вывод также уже частично закрыт.

Сейчас offer-level модель закреплена через связку:

Новый риск уже другой:

  • удержать различие между indicative price, quoted promise, repricing и settlement-relevant reality в будущих execution and operations документах.

Одна из самых опасных зон текущего контура — это отсутствие жёсткой модели offer.

Пока документация мыслит многое через hotel-centric оптику. Но платформе такого типа критично опираться именно на offer-level semantics:

  • supplier;
  • supplier product / room identifier;
  • occupancy;
  • meal plan;
  • cancellation terms;
  • validity window;
  • price snapshot;
  • availability snapshot;
  • revalidation policy.

Почему это критично​

Без этого почти неизбежно начнут смешиваться:

  • stable content;
  • dynamic availability;
  • quoted pricing;
  • confirmed booking state.

Именно здесь возникают самые дорогие ошибки будущей реализации.

Главный вывод №6. Tour Builder признан важным, но пока не описан как самостоятельный домен​

Этот вывод также уже закрыт отдельным документом:

Дальше проблема уже не в отсутствии доменного описания, а в глубине последующей operational and execution детализации.

Tour Builder в документации выглядит как одно из ключевых продуктовых преимуществ платформы. Это правильный сигнал. Но пока он описан скорее как мощная идея и сервисное обещание, чем как полноценный домен.

Пока недостаточно зафиксировано:

  • что такое тур как сущность;
  • кто владелец тура;
  • тур immutable или редактируемый draft;
  • как он связан с предложением и бронированием;
  • как он переживает drift цены и доступности;
  • какие компоненты кроме hotel stay входят в его состав;
  • как хранится история версий тура и коммерческого предложения.

Практический смысл​

Если Tour Builder действительно является core differentiator, его нельзя оставлять на уровне вторичного feature-description. Он должен получить отдельный domain-level документ.

Главный вывод №7. Tenancy, identity и access-модель пока распылены по разным документам​

Этот вывод существенно закрыт документом:

Дальнейший риск теперь находится не в conceptual gap, а в том, чтобы не потерять эту модель при детализации contracts, operations и finance-related workflows.

Система уже предполагает внутреннюю команду, агентства, партнёров, пользователей, API-клиентов, роли, ограничения и audit trail. Но единая модель того, как всё это связано, пока не собрана в один концептуальный слой.

Пока открыты фундаментальные вопросы:

  • что является tenant boundary;
  • agency и partner — это один тип организации или разные;
  • пользователь принадлежит агентству, партнёру или внутреннему контуру;
  • как соотносятся user, agent, agency member, partner client;
  • где живут permissions;
  • где живут quota и billing subject;
  • как организовать изоляцию данных между участниками.

Практический смысл​

Без этого невозможно стабильно проектировать:

  • auth;
  • access control;
  • partner API;
  • billing;
  • pricing overrides;
  • audit trail.

Главный вывод №8. Commercial domain пока недооформлен как самостоятельный слой​

Этот вывод закрыт отдельным документом:

Но отсюда появляется новый архитектурный приоритет:

  • удержать commercial axis как часть platform core, а не дать ему снова расползтись между pricing, booking, partner API и UI surfaces.

Документы уже затрагивают цены, комиссии, агентские условия, конвертацию валют, наценки и пересчёт. Но коммерческий слой пока ещё не оформлен как самостоятельная модель.

Нужно жёстко развести:

  • source price;
  • normalized base price;
  • pricing rule;
  • markup;
  • commission;
  • platform fee;
  • partner override;
  • final quoted price.

Практический смысл​

Пока коммерческий слой не выделен, система будет путать техническую цену поставщика с коммерческой ценой платформы.

Главный вывод №9. Governance и operational human-in-the-loop слой пока слабее технического контура​

Этот вывод уже частично ослаблен за счёт:

Но именно здесь остаётся один из главных незакрытых operational risks:

  • нужны более глубокие execution-level документы по operational review, exception handling, reconciliation и incident discipline.

Особенно это видно в ingestion и matching.

Техническая логика обработки, нормализации, очередей, retries и pipeline уже описана заметно сильнее, чем:

  • provenance на уровне полей;
  • merge policy;
  • source precedence;
  • confidence interpretation;
  • manual adjudication;
  • anomaly queues;
  • moderation / review surfaces.

То есть система уже хорошо думает о потоке данных, но ещё недостаточно думает о том, как этими данными управлять, когда поток начинает ошибаться.

Практический смысл​

Для такой платформы governance-слой не является вторичным улучшением. Он является обязательной частью production reality.

Главный вывод №10. Инфраструктурная уверенность местами опережает доменную зрелость​

operations/deployment.md и часть диаграмм уже уверенно описывают высокозрелую, масштабируемую, многокомпонентную инфраструктуру. Это само по себе не плохо. Но пока эта уверенность местами выше, чем зрелость доменных решений.

Основной риск​

Платформа может слишком рано зацементировать сложный operational shell вокруг ещё не до конца определённого ядра.

Практический смысл​

Инфраструктурные документы сейчас нужно читать как target operating model, а не как окончательно закреплённую форму запуска первой реальной версии.

Приоритетная шкала проблем​

Ниже — свод по значимости.

Уровень A. Блокирующие архитектурные проблемы​

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

На момент текущей версии часть прежних блокеров уже закрыта. Поэтому шкала ниже разделена на:

  • закрытые или в основном закрытые блокеры
  • актуальные блокеры следующего этапа

Закрытые или в основном закрытые блокеры​

  1. Зафиксирована каноническая доменная модель.
  2. Зафиксирована tenancy / identity / access-модель.
  3. Зафиксирована offer / quote / booking semantics.
  4. Зафиксирован коммерческий домен.
  5. Tour Builder описан как самостоятельный домен.

Актуальные блокеры следующего этапа​

  1. Верхний narrative-layer должен быть окончательно синхронизирован с новым несущим каркасом.
  2. Execution и operations-документы ещё не дотянуты до уровня нового reference-ядра.
  3. Нужна более жёсткая фиксация finance / reconciliation / settlement-operating workflows.
  4. Нужен следующий проход по observability, incident handling и operational control как по industrial execution layer.

Уровень B. Критические противоречия первого слоя​

Это уже найденные несовместимости и расхождения, которые разрушают доверие к текущему пакету как к единому baseline.

  1. Несовпадение имени проекта и содержимого.
  2. Несогласованный статус зрелости документов.
  3. Расхождения по схеме данных.
  4. Расхождения по Partner API limits.
  5. Расхождения по формату API-ключей.
  6. Отсутствующие сущности хранения для уже заявленной логики.
  7. Несогласованный matching algorithm.
  8. Несогласованная геомодель.
  9. Неопределённая модель агента.

Уровень C. Риски следующего этапа разработки документации​

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

  1. Слишком ранняя стабилизация API contracts.
  2. Слишком ранняя стабилизация database schema.
  3. Слишком ранняя стабилизация operations / deployment shape.
  4. Слабая governance-модель вокруг matching и supplier quality.
  5. Недостаточный human-in-the-loop контур для operational работы.

Что нельзя делать дальше​

На основании обоих review и этого синтеза нельзя считать правильным следующий порядок:

  1. сначала расширять API-контракты;
  2. затем детализировать БД;
  3. затем углублять deployment и infra;
  4. а уже потом возвращаться к доменным вопросам.

Это неправильная последовательность.

Также нельзя:

  • quietly ignore выявленные противоречия;
  • продолжать писать документы так, как будто модель уже окончательно принята;
  • путать hotel-centric и offer-centric уровень;
  • оставлять Tour Builder, tenancy и commercial model на уровне вторичных appendices.

На текущем этапе к этому добавляется ещё одно правило:

  • нельзя допустить, чтобы новый сильный reference-каркас снова разошёлся с overview, operations и execution-документами.

Что нужно делать дальше​

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

Порядок следующего этапа уже изменился, потому что базовые доменные документы созданы.

1. Дотянуть overview и synthesis-слой до нового каркаса​

Нужно, чтобы верхнеуровневые документы честно отражали уже собранный reference-baseline.

2. Усилить operations / deployment / execution-модель​

Нужны документы, которые объяснят:

  • как этот reference-baseline живёт в production;
  • как устроены observability и incident handling;
  • как работает operational control;
  • как выглядят recovery и replay processes.

3. Углубить finance-grade operational слой​

Нужны отдельные execution-level документы по:

  • settlement operations;
  • reconciliation;
  • refund/cancellation economics handling;
  • dispute and support workflows.

4. Удержать связность narrative → contracts → persistence → operations​

Следующий проход документации уже должен быть не про “создать недостающий домен”, а про удержание единой архитектурной оси через все уровни пакета.

Нужен отдельный документ по lifecycle тура, ownership model, versioning, proposal model и связи с booking.

5. Зафиксировать data governance and matching​

Нужен отдельный документ по provenance, merge policy, source precedence, confidence, moderation и manual review.

Только после этого можно безопасно и последовательно возвращаться к стабилизации:

  • API contracts;
  • database schema;
  • operations / deployment;
  • roadmap.

Роль этого документа в проекте​

Этот документ следует считать главным сводным документом выводов по первому слою документации платформы.

Его функция:

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

Исходные review-документы остаются опорными и обязательными для чтения, но именно этот документ должен использоваться как основной синтез проблемного поля перед началом следующего этапа проектирования платформы на бумаге.