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

Architecture Surfaces — Поверхности архитектуры и границы взаимодействия (архивная версия 2.0)

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

⚠ Этот документ переведён в архивный режим 25.04.2026. Актуальный документ по поверхностям и контурам взаимодействия — overview/layers.md (новая версия 3.0). Документ сохранён как историческая запись второго круга документации.

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

Этот документ заменяет старый черновой взгляд на платформу как на линейный "слоистый стек" с единым API gateway и набором REST endpoint-ов поверх сервисов.

Его задача — зафиксировать более зрелую архитектурную оптику: платформа должна мыслиться через поверхности взаимодействия, доменные контуры и границы правды, а не просто через последовательность "suppliers -> ingestion -> business services -> API -> clients".

Этот документ нужен как промежуточный мост между:

  • обзорным архитектурным документом;
  • reference-документами по поставщикам, ingestion, storage, contracts и clients;
  • будущими более детальными документами второго слоя.

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

Что Второй Несущий Круг Требует От Карты Поверхностей​

После появления второго круга документов layers.md уже нельзя считать просто удачной общей картой.

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

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

карта поверхностей должна объяснять не только “кто с кем говорит”, но и где меняется статус истины, где возникает обязательство, где допускается только preview, а где уже появляется publishable or transactional fact.

Что Исправляет Новый Подход​

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

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

  • suppliers;
  • ingestion;
  • business services;
  • API layer;
  • clients.

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

  • contract surfaces;
  • доменные границы;
  • truth boundaries;
  • роль offer и quote;
  • различие между internal, agency, partner и client-facing surfaces.

Во-вторых, старый документ слишком рано цементировал инфраструктуру:

  • Traefik;
  • gRPC gateway;
  • Kubernetes ingress;
  • конкретные URL и deploy form.

Это уводит архитектурное мышление от домена к transport-механике.

В-третьих, старый текст продолжал поддерживать ложный тезис "один API для всех". После переписывания api-contracts.md и clients.md это уже нельзя считать допустимым.

Новый подход меняет фокус:

  1. сначала surfaces and boundaries;
  2. затем доменные контуры и потоки;
  3. затем правила взаимодействия;
  4. только потом transport and deployment form.

Почему Здесь Лучше Говорить О Surface-ах, А Не О Слоях​

Слово "слои" полезно только пока помогает. В какой-то момент оно начинает врать.

Проблема в том, что в реальной платформе:

  • один доменный контур может обслуживать несколько внешних surface-ов;
  • один surface может использовать несколько доменных контуров;
  • storage и governance не "лежат снизу", а пронизывают несколько уровней;
  • booking and quote path проходят не линейно через слои, а через series of controlled boundaries;
  • human-in-the-loop surface вообще плохо укладывается в линейную layer-модель.

Поэтому дальше разумнее мыслить платформу как набор архитектурных surface-ов и cross-cutting контуров.

Главные Поверхности Архитектуры​

На текущем этапе платформы нужно различать как минимум шесть ключевых архитектурных surface-ов.

1. External Supplier Surface​

Это поверхность контакта платформы с внешними поставщиками.

Здесь возникают:

  • supplier APIs and feeds;
  • file imports;
  • webhooks;
  • booking callbacks;
  • supplier auth and rate limits;
  • source-specific instability.

Это не просто "вход данных", а boundary between platform and uncontrolled external reality.

2. Ingestion And Normalization Surface​

Это поверхность, на которой внешняя supplier reality превращается в управляемый внутренний материал.

Здесь происходят:

  • raw trace capture;
  • normalization;
  • mapping and matching;
  • merge candidate preparation;
  • anomaly detection;
  • governance handoff;
  • downstream update signals.

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

3. Canonical Domain Surface​

Это поверхность канонического платформенного ядра.

Здесь живут:

  • canonical content and inventory;
  • offer semantics;
  • quote-relevant models;
  • booking truth;
  • tour composition objects;
  • identity/tenancy/commercial context;
  • governance outcomes.

Это не UI и не API gateway. Это смысловая сердцевина системы.

4. Operational Service Surface​

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

Сюда входят:

  • inventory capabilities;
  • offer assembly and refresh;
  • pricing/commercial logic;
  • booking state handling;
  • tour builder logic;
  • governance tooling;
  • operational control.

Это не финальная deploy-топология. Это рабочая service-facing проекция доменных обязанностей.

5. Contract Surface​

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

Сюда входят:

  • partner API contracts;
  • agency-facing application contracts;
  • internal operational contracts;
  • service-to-service contracts;
  • event/webhook contracts.

Здесь главным становится не transport itself, а contractual discipline.

6. Client And Operator Surface​

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

Сюда входят:

  • internal operational applications;
  • agency working applications;
  • partner integrations;
  • B2C/client-facing surfaces;
  • white-label and embedded surfaces.

Cross-Cutting Контуры, Которые Нельзя Запихнуть В Один "Слой"​

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

Storage And Truth Management​

Storage работает одновременно с:

  • supplier trace;
  • canonical model;
  • offer snapshots;
  • booking events;
  • governance;
  • caches and runtime state.

Поэтому storage — это не "нижний слой", а системный контур управления truth and lifetime.

Freshness, Revalidation And Publication Discipline​

Этот контур проходит одновременно через:

  • suppliers;
  • ingestion;
  • operational offer assembly;
  • contract surfaces;
  • client-facing presentation;
  • booking and proposal transitions.

Именно он определяет:

  • где данные можно показывать как indicative;
  • где требуется explicit revalidation;
  • где draft ещё не может быть опубликован;
  • где изменение должно быть остановлено governance-механизмом;
  • где возникает final transactional or published fact.

Governance And Human-In-The-Loop​

Governance пересекает:

  • ingestion;
  • canonical updates;
  • supplier quality;
  • booking exceptions;
  • partner operations;
  • internal review tools.

Его нельзя считать побочным admin-функционалом.

Identity / Tenancy / Commercial Context​

Эти контуры влияют одновременно на:

  • contracts;
  • clients;
  • offers;
  • pricing;
  • booking visibility;
  • partner capabilities;
  • operational tools.

Их тоже нельзя описывать как изолированный technical sublayer.

Главные Потоки Между Поверхностями​

1. Supplier Reality → Platform Canonicality​

Поток:

external supplier surface -> ingestion surface -> canonical domain surface

Смысл:

  • принять внешний сигнал;
  • сохранить trace;
  • нормализовать;
  • понять, что можно автоматически применить;
  • отделить сомнительное от надёжного;
  • обновить canonical model or route to governance.

2. Canonicality → Operational Offer Readiness​

Поток:

canonical domain surface -> operational service surface -> contract surface

Смысл:

  • взять канонический контекст;
  • собрать offer-oriented operational representation;
  • учесть freshness, commercial context and availability semantics;
  • сделать это пригодным для чтения или дальнейшего quote path.

Здесь особенно важно, что operational readiness ещё не равна publishable commitment.

3. Discovery → Quote → Booking​

Поток:

client surface -> contract surface -> operational service surface -> canonical + transactional truth

Смысл:

  • пользователь или партнёр начинает search/discovery;
  • получает candidate results and offers;
  • переходит к quote-level фиксации;
  • затем к booking-intent;
  • затем к booking state machine, которая уже взаимодействует и с внутренним transactional truth, и с supplier-side state.

Это важнейший поток платформы. Его нельзя редуцировать до обычного REST CRUD.

4. Internal Review And Exception Handling​

Поток:

canonical / operational signals -> governance surface -> internal operational surface

Смысл:

  • аномалии и конфликты попадают в review path;
  • оператор принимает решение;
  • решение возвращается в canonical and operational flows;
  • возникает audit trail.

При этом governance-решение может не только исправлять canonical layer, но и останавливать downstream publication или менять partner/client-visible promise.

5. Tour Composition And Proposal Lifecycle​

Поток:

agency working surface -> contract surface -> operational services -> draft/proposal/booking artifacts

Смысл:

  • пользователь собирает draft;
  • привязывает варианты, offers, quotes;
  • меняет состав;
  • публикует proposal;
  • часть элементов может перейти в booking.

Это отдельный архитектурный маршрут, а не “дополнительный endpoint рядом с booking”.

Почему API Gateway Не Является Архитектурным Центром​

Старая версия документа делала API layer почти главным фасадом системы. Это неверно.

API gateway и transport orchestration важны, но это:

  • enforcement and routing point;
  • security and rate layer;
  • observability entry point;
  • contract exposure mechanism.

Но это не место, где определяется:

  • доменная истина;
  • offer semantics;
  • booking lifecycle;
  • canonical merge policy;
  • supplier trust model.

Поэтому в архитектурной картине gateway должен занимать подчинённое место относительно contract and domain surfaces.

Почему "Один API Для Всех" Больше Нельзя Считать Базовым Тезисом​

После переписывания api-contracts.md и clients.md нужно жёстко зафиксировать:

единое доменное ядро не означает единый surface contract.

Разным поверхностям нужны разные формы:

  • internal operational surface;
  • agency working surface;
  • partner API surface;
  • B2C/client-facing surface;
  • service-to-service surface.

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

  • один и тот же payload shape;
  • один и тот же auth model;
  • один и тот же visibility model;
  • один и тот же versioning tempo;
  • один и тот же operational promise.

То же самое касается client and operator surfaces: единый domain core не означает единый presentation truth.

Транспорт И Инфраструктура Как Производный Уровень​

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

  • Traefik;
  • REST-to-gRPC gateway;
  • конкретный ingress model;
  • exact Kubernetes topology;
  • exact middleware chain composition.

Это всё может оказаться разумным implementation vector. Но это уже производный уровень, который должен следовать доменной и контрактной архитектуре.

Что Уже Можно Считать Разумным Направлением​

  • отдельная contract exposure boundary;
  • security/rate/observability enforcement point;
  • strongly typed internal service interactions;
  • support for async/event contracts;
  • environment separation for partner-facing integrations.

Что Пока Нельзя Считать Финально Зафиксированным​

  • точный API gateway product;
  • final transport matrix between all services;
  • final ingress and mesh strategy;
  • exact runtime split between gateway, BFF and service contracts.

Как Этот Документ Связан С Уже Переписанными Reference-Материалами​

Suppliers​

Suppliers Layer — Поставщики, source boundaries и управление внешней реальностью описывает внешний supplier boundary, который здесь обозначен как external supplier surface.

Ingestion​

Ingestion Layer — Приём, нормализация, маппинг и governance раскрывает ingestion surface как управляемый контур преобразования внешней реальности.

Business Services​

Business Services — Сервисная декомпозиция платформы раскрывает operational service surface в разрезе доменных сервисных контуров.

API Contracts​

API Contracts — Surface Contracts и правила внешнего взаимодействия раскрывает contract surface и разводит разные внешние и внутренние surface contracts.

Clients​

Clients Layer — Клиентские поверхности и рабочие модели раскрывает client and operator surface.

Storage​

Storage Layer — Модель хранения и жизненный цикл данных раскрывает truth and lifetime model, которая проходит через несколько архитектурных surface-ов сразу.

Database Schema​

Database Schema — Каноническая модель хранения платформы раскрывает, как эти surface-базированные различия закрепляются в persistent model.

Domain, Identity, Offer Semantics And Governance​

Что Должно Быть Перепроверено После Этого Документа​

После фиксации этого нового взгляда нужно перепроверить:

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

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

  • про gateway;
  • про transport layer;
  • про sandbox/live partner split;
  • про базовые идеи мониторинга и rate limiting;
  • про примерный shape ранних endpoints.

Но его нельзя больше считать source of truth, потому что он:

  • переоценивал layer-модель;
  • делал API центром архитектуры;
  • поддерживал тезис “один API для всех”;
  • слишком рано цементировал infra choices;
  • сохранял hotel-centric endpoint thinking.

Старый текст сохранён в архивной версии:

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

Для vitiana-api-platform архитектуру уже нельзя объяснять просто через набор слоёв и gateway-узел посередине. Гораздо точнее мыслить её как систему архитектурных surface-ов:

  • supplier boundary;
  • ingestion boundary;
  • canonical domain surface;
  • operational service surface;
  • contract surface;
  • client and operator surface.

Практически это означает:

  • доменная модель важнее transport topology;
  • truth boundaries важнее красивой layer-схемы;
  • API exposure не является центром платформы;
  • разные consumer-ы должны получать разные contracts and surfaces;
  • инфраструктура должна следовать архитектуре, а не подменять её.

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