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

Архитектурная основа платформы vitrip.store (архивная версия 2.0)

Версия: 2.0 (архивная) Дата: 23.04.2026 (создание), 25.04.2026 (архивация) Статус: Черновик (архивная версия)

⚠ Этот документ переведён в архивный режим 25.04.2026. Актуальная архитектурная основа платформы — overview/index.md (новая версия 3.0). Документ сохранён как историческая запись второго круга документации; решения, зафиксированные в нём, остаются валидными для тех частей, которые не противоречат новой архитектурной основе и манифесту переосмысления (overview/platform-vision-and-manifest.md).

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

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

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

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

Связь с другими ключевыми документами​

Этот документ нужно читать вместе со следующими опорными материалами:

Что Это За Платформа​

vitrip.store — это не просто каталог отелей, не просто агентский сайт и не просто набор API для внешних партнёров.

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

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

Таким образом, мы проектируем не “UI вокруг supplier API”, а операционное ядро туристической платформы, поверх которого могут существовать:

  • агентский B2B workflow;
  • внешние партнёрские интеграции;
  • клиентские поверхности;
  • внутренние административные и операционные инструменты;
  • конструктор туров и связанных коммерческих предложений.

Архитектурный Центр Платформы​

Главный архитектурный центр платформы должен быть зафиксирован жёстко:

Платформа строится вокруг канонического продуктового ядра, которое объединяет content, supplier products, offers, pricing, booking и tour composition.

Это означает следующее:

  • supplier-данные не являются центром системы;
  • веб-интерфейсы не являются центром системы;
  • partner API не является центром системы;
  • даже сама hotel-карточка не является достаточным центром системы.

Центр тяжести находится в связке:

  1. каноническое представление объекта размещения и его контента;
  2. supplier-specific продукты и условия;
  3. offer как актуализируемая коммерческая единица;
  4. price и availability как краткоживущие, но критически важные operational state;
  5. commercial policy как actor- and channel-aware слой интерпретации цены;
  6. booking как подтверждённая транзакционная фиксация;
  7. post-booking lifecycle как домен сопровождения уже проданного обязательства;
  8. partner finance and clearing как домен финансового допуска и взаиморасчётов distribution layer;
  9. tour composition как домен сборки и представления конечного туристического продукта.

Именно этот центр должен определять:

  • модель данных;
  • границы сервисов;
  • смысл API;
  • требования к revalidation;
  • правила repricing и quote validity;
  • правила кэширования;
  • модель пользователей и организаций;
  • operating model платформы.

Текущая Архитектурная Ось​

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

supplier reality
  → normalized and governed canonical model
  → integrity-gated publishable offer state
  → offerable operational state
  → channel-aware commercial interpretation
  → quote as commercial promise
  → booking as transactional commitment
  → post-booking operational reality
  → settlement-relevant downstream financial reality
  → partner clearing and tenant-specific enablement reality
  → tour composition and proposal publication

Это важно, потому что платформа больше не может мыслиться только как:

  • content + search;
  • hotel + room + booking;
  • supplier data + UI;
  • один API + одна цена для всех.

Текущий собранный каркас уже требует явного различия между:

  • supplier economics и platform commercial policy;
  • indicative price и quoted promise;
  • quoted promise и settlement-relevant figures;
  • settlement and supplier-side figures и partner clearing position;
  • internal working object и publishable surface object;
  • booking truth и downstream financial truth.

Именно эта ось теперь должна удерживать дальнейшее развитие всех reference- и operations-документов.

Что Платформа Не Должна Собой Представлять​

Чтобы не ошибиться в проектировании, важно зафиксировать и отрицательные границы.

Платформа не должна быть:

  • просто supplier proxy, который почти без собственной модели перепаковывает чужие ответы;
  • просто OTA-поиском по hotel inventory без жёсткой offer-semantic модели;
  • просто конструктором PDF-программ поверх нестабильных данных;
  • просто одним “универсальным API для всего” без различения разных surface contracts;
  • просто ранним Kubernetes-проектом, в котором инфраструктурная сложность обгоняет ясность домена.

Канонические Сущности Платформы​

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

1. Property​

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

Property описывает то, что относительно стабильно:

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

Property не должен напрямую заменять собой цену, availability или booking.

2. SupplierProperty​

Представление того же объекта в конкретной внешней системе.

Нужно для фиксации:

  • supplier-specific идентификаторов;
  • различий в naming;
  • различий в content и атрибутах;
  • источника данных;
  • confidence и provenance;
  • правил merge и precedence.

3. RoomType / Product​

Тарифная или продуктовая единица поставщика и/или канонического каталога.

Это не просто “комната” в бытовом смысле. Это то, что участвует в коммерческом и операционном контуре:

  • категория размещения;
  • состав occupancy;
  • тип размещения;
  • особенности bed configuration;
  • условия поставщика;
  • применимость к offer и booking pipeline.

4. Offer​

Одна из центральных сущностей платформы.

Offer — это конкретное предложение, пригодное для показа, quotation, revalidation и потенциального бронирования. Оно должно включать:

  • supplier и supplier product reference;
  • dates / stay interval;
  • occupancy;
  • room / meal / cancellation semantics;
  • currency context;
  • price semantics;
  • validity window;
  • revalidation status;
  • ограничения и коммерческие условия.

Платформа должна мыслить именно offer-centric категорией, а не только hotel-centric списком.

5. AvailabilitySnapshot​

Краткоживущая фиксация состояния доступности.

Это operational data, а не стабильная мастер-сущность. Она нужна для:

  • search;
  • quote pipeline;
  • booking pre-check;
  • revalidation;
  • диагностики расхождений между кэшем и upstream.

6. PriceSnapshot​

Краткоживущая фиксация технической и/или коммерчески нормализованной цены.

PriceSnapshot должен отличаться от:

  • supplier raw price;
  • normalized base price;
  • commercially adjusted price;
  • final quoted price.

7. Quote​

Quote — это не UI-проекция и не “ещё одна цена на карточке”, а actor-aware коммерческая фиксация.

Именно Quote должен удерживать:

  • quoted promise;
  • validity window;
  • applied commercial policy;
  • channel / tenant / workspace context;
  • переход к booking;
  • основания для revalidation или repricing.

8. Booking​

Транзакционная фиксация подтверждённой или partially-resolved коммерческой операции.

Booking — это не просто запись “пользователь выбрал отель”. Это домен со своими состояниями, отказами, компенсациями и audit trail.

9. TourDraft​

Редактируемая рабочая сборка будущего туристического продукта.

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

10. TourProposal​

Коммерчески представляемая версия тура.

Это уже не просто draft-сборка, а версия, которая может:

  • иметь историю;
  • иметь коммерческий контур;
  • использоваться для передачи клиенту;
  • быть связана с PDF/export;
  • становиться основанием для последующего бронирования или серии бронирований.

11. Agency​

Организация агентского типа, от имени которой работают пользователи и к которой могут применяться:

  • коммерческие условия;
  • ограничения доступа;
  • квоты;
  • отчётность;
  • settlement rules.

12. Partner​

Организация, взаимодействующая с платформой через внешний контрактный surface, включая Partner API и связанные с ним operational, legal и billing правила.

Partner не обязан быть тем же самым, что Agency.

13. User / AgentUser / InternalUser​

Субъекты, которые работают в платформе от разных контуров:

  • внутренний персонал;
  • сотрудники агентств;
  • пользователи партнёров;
  • сервисные клиенты и API-клиенты.

Именно здесь позже должна быть оформлена полноценная identity and tenancy model.

Источники Истины И Политика Freshness​

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

1. Master Data​

К master data относятся устойчивые данные, которыми платформа должна владеть как каноническим слоем:

  • property identity;
  • география;
  • классификаторы;
  • стабильный контент;
  • канонические связи между supplier representations;
  • организационные и пользовательские сущности;
  • долгоживущие коммерческие и permission rules.

Для этого слоя truth должен храниться в постоянной модели данных платформы.

2. Volatile Operational Data​

К volatile data относятся:

  • availability;
  • price snapshots;
  • quote-adjacent state;
  • search cache;
  • технические временные статусы;
  • revalidation results;
  • краткоживущие operational projections.

Этот слой по определению не должен отождествляться с полным source of truth на все случаи.

3. Truth Policy​

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

  • truth по content;
  • truth по canonical identity;
  • truth по operational availability;
  • truth по quoted commercial promise;
  • truth по quoted price;
  • truth по final booking state.
  • truth по settlement-relevant financial reality.

Эти truth-слои не обязаны жить в одном и том же месте и не обязаны иметь одинаковый срок актуальности.

4. Freshness Policy​

Для каждой критической категории данных нужно явно определить:

  • какой срок допустимой устарелости;
  • когда можно использовать cached approximation;
  • когда обязательна revalidation с supplier;
  • что можно показать пользователю как best effort;
  • что нельзя использовать без live recheck;
  • что сохраняется для аудита, даже если перестало быть актуальным operationally.

5. Revalidation Policy​

Особенно важно для:

  • перехода от search к quote;
  • перехода от quote к booking;
  • повторного открытия существующих предложений;
  • сборки тура из нескольких компонентов;
  • повторного расчёта при изменении курсов, supplier data или состава продукта.

Без explicit truth policy и freshness policy платформа неизбежно начнёт жить в нескольких конфликтующих реальностях.

Commercial Axis As Part Of Platform Core​

После фиксации Commercial Model — Коммерческая модель, цена, settlement и канальные условия коммерческий контур больше нельзя считать приложением к pricing.

Платформа обязана различать:

  • supplier economics;
  • normalized base price;
  • commercial rule output;
  • quoted commercial promise;
  • settlement-relevant figures.

Это меняет базовое понимание платформы:

  • цена больше не является одним полем price;
  • quote больше не является удобным UI-объектом;
  • repricing становится архитектурным, а не чисто техническим событием;
  • surface-ы получают разные commercial views;
  • booking и settlement больше нельзя описывать как одну и ту же денежную реальность.

Следовательно, commercial axis уже является частью platform core наравне с canonical inventory, offer model, booking domain и tour composition.

Текущая Зрелость Документационного Пакета​

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

Что Уже Можно Считать Несущим Каркасом​

  • обзорная архитектурная модель платформы;
  • центральная доменная модель;
  • tenancy / identity / access;
  • offer / quote / booking semantics;
  • commercial model;
  • tour builder domain;
  • data governance and matching;
  • синхронизированные documents по services, storage, database, contracts, clients, suppliers и ingestion.

Что Ещё Не Следует Считать Финально Закрытым​

  • operations/deployment shape как окончательную форму production rollout;
  • окончательные machine-readable API specs;
  • окончательную DDL-реализацию без следующего цикла детализации;
  • финальную operating policy для reconciliation, finance operations и incident workflows.

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

Документационный пакет уже перестал быть набором первичных черновиков. Но его всё ещё следует трактовать как сильный архитектурный baseline, который требует следующего прохода углубления в operations, finance-grade workflows, observability и execution model, а не как полностью закрытую implementation bible.

Внешние И Внутренние Surface Areas​

Одна из главных ошибок, которой нужно избежать: нельзя мыслить платформу как “один API для всех”, если под этим скрывается смешение разных типов клиентов и разных требований.

Платформа должна проектироваться через surface areas.

1. Internal Operational Surface​

Поверхность для внутренней команды и операторов.

Здесь должны жить:

  • мониторинг поставщиков;
  • review queues;
  • matching moderation;
  • anomaly handling;
  • booking exception handling;
  • partner key management;
  • ручные административные операции;
  • наблюдаемость и диагностика.

2. Agency Working Surface​

Рабочая поверхность для агентств и их пользователей.

Здесь должны жить:

  • поиск;
  • подбор;
  • quote workflow;
  • Tour Builder;
  • proposal generation;
  • история работы;
  • агентские цены и условия;
  • агентские действия по клиентским сценариям.

3. Partner API Surface​

Внешний контрактный surface для партнёрских систем.

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

  • versioning;
  • quotas;
  • scopes;
  • partner capability model;
  • SLA and freshness guarantees;
  • auditability;
  • deprecation policy.

4. B2C / Client-Facing Surface​

Если этот контур будет развиваться как самостоятельный канал, его нельзя автоматически считать копией agency surface.

У него могут быть свои:

  • правила отображения;
  • ограничение функций;
  • pricing visibility rules;
  • conversion mechanics;
  • legal and UX constraints.

5. Service-to-Service Surface​

Внутренняя поверхность для взаимодействия сервисов и доменных модулей.

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

Основные Доменные Контуры​

Ниже — не финальная сервисная карта, а карта доменных контуров, вокруг которых должна проектироваться платформа.

1. Supplier Ingestion And Normalization​

Контур приёма, парсинга, нормализации и первичной оценки данных поставщиков.

Сюда входят:

  • adapters;
  • ingestion jobs;
  • parsing;
  • normalization;
  • matching;
  • merge;
  • confidence model;
  • provenance capture.

2. Canonical Inventory And Content​

Контур канонических сущностей платформы.

Сюда входят:

  • property catalog;
  • canonical product model;
  • content model;
  • media;
  • classifications;
  • geo references;
  • stable searchable characteristics.

3. Offers / Pricing / Quote Pipeline​

Контур, в котором из канонических сущностей и supplier data рождается коммерчески пригодное предложение.

Сюда входят:

  • offer model;
  • availability snapshots;
  • price snapshots;
  • quote semantics;
  • revalidation rules;
  • cache policy;
  • quote lifetime.

4. Booking Domain​

Контур подтверждённой или partially-confirmed транзакции.

Сюда входят:

  • booking lifecycle;
  • supplier confirmation;
  • cancellation;
  • uncertain states;
  • rollback and compensation;
  • audit trail;
  • failure recovery.

5. Tour Builder Domain​

Контур сборки составного продукта.

Сюда входят:

  • draft lifecycle;
  • proposal lifecycle;
  • ownership;
  • history/versioning;
  • composition rules;
  • compatibility checks;
  • export and presentation layer.

6. Identity / Tenancy / Access​

Контур субъектов платформы и их границ.

Сюда входят:

  • users;
  • agencies;
  • partners;
  • roles;
  • permissions;
  • API clients;
  • quotas;
  • tenant isolation;
  • audit subjects.

7. Commercial Rules And Settlement​

Контур, в котором техническая цена превращается в коммерческий результат.

Сюда входят:

  • source price;
  • normalized price;
  • markup;
  • commission;
  • platform fee;
  • partner overrides;
  • quoted price;
  • settlement and reporting semantics.

8. Governance / Quality / Moderation​

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

Сюда входят:

  • provenance;
  • source precedence;
  • anomaly detection;
  • duplicate review;
  • manual adjudication;
  • data quality thresholds;
  • governance queues.

9. Operations / Observability / Recovery​

Контур эксплуатационной жизнеспособности платформы.

Сюда входят:

  • metrics;
  • alerting;
  • traceability;
  • incident handling;
  • operational tooling;
  • replay / retry safety;
  • recovery scenarios.

Архитектурные Принципы Платформы​

1. Supplier-Agnostic Core​

Ядро платформы не подстраивается под модели отдельных поставщиков. Supplier-specific особенности остаются на стороне adapters, mappings и provenance.

2. Offer-Centric Operational Model​

Платформа должна мыслить не только hotel-centric карточками, а offer-centric operational реальностью. Именно offer участвует в quote, pricing, revalidation и booking transition.

3. Separation Of Master And Volatile Data​

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

4. Domain-First Before Infra-First​

Сначала фиксируются доменные сущности, truth policy и operational semantics. Лишь потом стабилизируются конкретные технологии, deployment shapes и scale topology.

5. Explicit Truth And Revalidation Rules​

Платформа должна явно знать, что считается правдой, когда эта правда устаревает и в какой точке нужен live recheck.

6. Multi-Subject Design​

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

  • internal team;
  • agencies;
  • partners;
  • client-facing flows;
  • service clients.

Это влияет на модель доступа, API, коммерцию и аудит.

7. Auditability And Recoverability​

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

8. Human-In-The-Loop Where Needed​

Не все проблемные зоны платформы должны решаться только автоматикой. Matching, governance, anomaly handling и часть операционных сценариев обязаны иметь controllable manual path.

Высокоуровневая Архитектурная Схема​

Текущую архитектуру платформы на высоком уровне нужно понимать так:

Suppliers
  → Ingestion and Normalization
  → Canonical Data and Content
  → Offers / Pricing / Quote Logic
  → Booking and Tour Domains
  → External and Internal Surfaces
  → Operations / Governance / Observability

Это не окончательная схема процессов и не карта конкретных runtime-компонентов. Это правильный conceptual order, который должен управлять следующими слоями документации.

Технологический Вектор И Его Статус​

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

  • PostgreSQL / PostGIS;
  • Redis;
  • message-driven ingestion;
  • Go для части сервисов;
  • Rust для части ingestion-heavy задач;
  • API Gateway;
  • container-based deployment;
  • наблюдаемость и операционный мониторинг.

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

Причина проста:

  • доменные границы ещё не полностью стабилизированы;
  • offer-модель ещё не оформлена;
  • tenancy / identity / commercial слой ещё не собраны в жёсткие документы второго слоя;
  • часть current diagrams описывает target-state topology, а не обязательно ближайшую практическую форму запуска.

Следовательно, технологический стек уже важен, но должен подчиняться домену, а не замещать его.

Этап Зрелости И Ограничения Текущего Состояния​

На момент этой редакции платформа находится в состоянии расширенного архитектурного черновика.

Что уже можно считать сильным​

  • правильное стремление к supplier-agnostic ядру;
  • понимание, что нужны canonical data и не только supplier mirrors;
  • выделение ingestion как отдельного контура;
  • понимание важности pricing, booking, B2B surfaces и Tour Builder;
  • осознание, что платформа должна быть операционно управляемой.

Что ещё нельзя считать окончательно закреплённым​

  • окончательный архитектурный центр системы;
  • canonical domain model;
  • offer semantics;
  • commercial model;
  • tenancy and identity model;
  • governance contour;
  • final API boundary model;
  • final database truth model;
  • final deployment shape.

Что это означает практически​

Нельзя переходить сразу к уверенной стабилизации:

  • всех API contracts;
  • всей database schema;
  • всей infra topology;
  • всех service boundaries.

Прежде нужен второй слой документации.

Следующий Обязательный Слой Документации​

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

1. Центральная доменная модель​

Нужен сильный документ, который жёстко фиксирует:

  • сущности;
  • связи;
  • жизненные циклы;
  • границы;
  • source of truth.

2. Tenancy / Identity / Roles / Access​

Нужен отдельный документ по субъектам платформы, ролям, tenant boundaries, partner model и API-client model.

3. Offer / Pricing / Booking Semantics​

Нужен отдельный документ по:

  • offer;
  • snapshots;
  • quoted price;
  • revalidation;
  • booking states;
  • failure and compensation logic.

4. Tour Builder Domain​

Нужен отдельный документ, который описывает тур не как feature, а как полноценный домен.

5. Data Governance And Matching​

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

Только после этого можно безопасно возвращаться к глубокой стабилизации reference- и operations-документов.

Роль Старых Черновиков​

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

В частности, прежняя версия этого обзорного документа сохранена в:

Такие документы не следует считать актуальной source of truth, но их допустимо использовать как архив идеи, черновой материал и источник отдельных полезных формулировок или схемных ходов.

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

Документы ориентации и управления​

Текущие reference-черновики​

Эксплуатация и развитие​