Обзор Ось 6 — Связь с реализацией (резюме простыми словами)

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

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

Этот документ — резюме шестой архитектурной оси платформы для непрофильного читателя. Он не заменяет каноничный документ Связь с реализацией (ось 6), а служит коротким и понятным введением для тех, кто не работает с архитектурой каждый день: руководителей, новых членов команды, внешних консультантов, партнёров на этапе знакомства.

Цель резюме — чтобы любой грамотный читатель за 10–15 минут понял, что у нас уже работает в коде сейчас, как это соотносится с целевой архитектурой, какой технический долг есть и каким путём мы будем переходить от первой реализации к зрелой платформе.

О чём документ

Документ описывает шестую из шести архитектурных осей платформы — связь с реализацией. Простыми словами: это «мост между мечтой и реальностью». Архитектура vitiana-api-platform — целевая модель того, какой платформа должна стать. Существующая реализация — то, что уже работает и приносит пользу сегодня. Эта ось показывает: где они совпадают, где расходятся, какой долг накопился и как мы планируем переходить от текущего состояния к целевой архитектуре, не сломав работающее.

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

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

Каноничная модель платформы — архитектурный приоритет (правило 00000). Существующая реализация — это первая итерация слоёв приёма данных и базового хранилища.

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

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

Что такое существующая реализация

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

Что уже работает

• Адаптер первого поставщика — рабочая интеграция с одним из туристических поставщиков, готова к production (с апреля 2026).
• Загрузчик каталога — первый прогон завершён, в системе 127 304 отеля и 4,6 миллиона фотографий.
• Географическая цепочка — 182 страны синхронизированы с переводами на русский и украинский, картой соответствий поставщиков.
• База отелей — таблицы созданы, схема выполнена.
• Архитектура пользователей — 18 таблиц для пользователей и организаций.
• Хранилище событий и тем — первая итерация захвата событий.
• Справочник удобств — 145 каноничных понятий и 224 маппинга для первого поставщика.
• Исследование интеграции второго поставщика — в работе.

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

• Партнёрский программный интерфейс (нет тестовой среды, нет портала разработчика, нет процесса сертификации).
• Закрытая поверхность конструктора туров.
• Полноценная агентская рабочая поверхность.
• Внутренняя операционная поверхность (только частично через административную панель).
• Витрина для конечных клиентов (только частично через текущий сайт).
• Сервис-к-сервису поверхность (без формальных контрактов между сервисами).
• Управляемые шина сообщений, поисковый движок, аналитическое хранилище.
• Платформа машинного обучения.
• Каркас A/B-тестирования.
• Многорегиональная конфигурация.
• Формальный план восстановления после аварий.
• Наблюдаемость уровня боевой эксплуатации.

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

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

Реализованная часть:

• Главные понятия — есть таблица отелей, но смешивает каноничный объект размещения и представление от поставщика.
• Понятия поставщиков — частично через поля с префиксом supplier_* в общей таблице, нужно вынести в отдельный слой следов поставщиков.
• Операционные понятия предложения — пока не реализованы как отдельный слой, предложения рассчитываются по запросу.
• Транзакционные понятия — пока не реализованы в боевой эксплуатации.
• Композиционные понятия (туры) — не реализованы.
• Понятия управления и проверки данных — не реализованы как слой.
• Понятия идентичности и доступа — есть таблицы пользователей и организаций (первая итерация), требует ревью под мульти-тенантную модель.
• География — реализовано полностью, направление верное.
• Справочник удобств — соответствует каноничной модели.

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

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

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

• Внутренняя операционная — частично через административную панель.
• Агентская рабочая — не реализована.
• Партнёрский интерфейс — текущая точка входа есть, но это адаптер приёма данных, а не партнёрский интерфейс. Это разная природа.
• Витрина для конечных клиентов — зачаточная реализация, нет оптимизации конверсии и продвинутых возможностей.
• Сервис-к-сервису — базовые внутренние интерфейсы, без формальных контрактов.
• Закрытая поверхность конструктора туров — не реализована.

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

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

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

Главное: платформа как продукт ещё не существует. Текущая реализация — это первая витрина для клиентов и прототип приёма данных. Полная разработка как продукта — фазы 2-4.

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

• Доменные события — частично через первую итерацию хранилища событий, требует разделения на доменные и аналитические.
• Аналитические события — не реализованы.
• Хранилище данных — базовая аналитика возможна через основную базу, но не оптимально для аналитических запросов в боевом объёме.
• Конвейеры обработки — не реализованы.
• Платформа машинного обучения — не реализована.
• Каркас A/B-тестирования — не реализован.

Главный технический долг: хранилище событий смешивает доменные и аналитические события — требуется разделение.

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

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

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

Технический долг (семь главных видов)

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

Долг 1. Однотенантная база данных

Текущая база спроектирована как однотенантная без идентификатора тенанта. Все существующие данные (более 100 тысяч отелей, география, фотографии) попадают в логически выделенный тенант по умолчанию при миграции. Требуется добавление колонок идентификатора тенанта во все таблицы, заполнение существующих данных значением «тенант по умолчанию», обновление всех запросов под фильтрацию по тенанту, политики безопасности на уровне строк.

Долг 2. Модель данных под форму конкретного поставщика

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

Конвергенция: каноничная схема объекта размещения, независимая от любого поставщика, на стадии 1; существующая таблица отелей остаётся как наследие в качестве хранилища сырых следов; слой маппинга — независимый от поставщика.

Долг 3. Отсутствие архитектуры на основе событий

Текущая реализация — синхронная архитектура запросов и ответов. Нет хранилища событий, нет асинхронной обработки для долгих операций.

Конвергенция: базовое хранилище событий на стадии 1-2; ключевые потоки (подтверждение бронирований, синхронизация поставщиков, уведомления) переводятся на событийную модель на стадии 2-3.

Долг 4. PHP-бэкенд для основных потоков

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

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

Конвергенция: новые сервисы пишутся на современных типизированных языках; существующий код PHP остаётся для наследуемых путей с постепенной миграцией; шлюз-обёртка для единого интерфейса.

Долг 5. Лёгкий фронтенд с ограниченными возможностями

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

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

Конвергенция: современный фреймворк для новых богатых поверхностей (агентская, партнёрская); существующий лёгкий фронтенд остаётся для витрины для клиентов на текущем этапе; общая дизайн-система между фреймворками.

Долг 6. Нет формального стека наблюдаемости

Нет агрегатора метрик, дашбордов, структурированных логов, распределённой трассировки. Эксплуатация работает по ситуации.

Конвергенция: стек наблюдаемости на стадии 1; структурированное журналирование обязательно для новых сервисов; распределённая трассировка на стадии 2.

Долг 7. Нет формальной дисциплины непрерывной интеграции и доставки

Развёртывание — частично ручное, частично автоматизированное.

Конвергенция: формальная дисциплина непрерывной интеграции и доставки на стадии 1; постепенный rollout с дисциплиной; процедуры отката.

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

Упрощённая сводка:

Каноничное понятие	Текущая реализация	План конвергенции
Объект размещения	Таблица отелей со смешением каноничного и поставщикового	Стадия 1: разделить на каноничные объекты и таблицу следов поставщика
Канонический продукт	Часть таблиц или поля	Стадия 1: ввести каноничный слой продуктов
Понятия поставщиков	Поля supplier_* в общей таблице	Стадия 1: вынести в отдельный слой следов
Сырая нагрузка от поставщика	Не сохраняется постоянно	Стадия 1: ввести постоянный слой следов
Сеанс синхронизации	Журналируется без полного следа	Стадия 1: ввести сеанс как сущность
Предложение	Не реализовано как постоянная сущность	Стадия 1: ввести каноничную сущность и сервис
Снимки доступности и цены	Не реализованы	Стадия 1: ввести операционный слой
Коммерческая фиксация	Не реализована	Стадия 1: ввести как каноничную сущность
Бронирование	Не реализовано в боевой эксплуатации	Стадия 1: ввести жизненный цикл с 14 состояниями
Намерение платежа, возврат	Не реализованы	Стадия 1 после выбора провайдера платежей
Запрос на изменение	Не реализован	Стадия 1-2
Конструктор туров (все понятия)	Не реализованы	Стадия 1-2
Организации, тенанты, рабочие пространства	Базовая реализация	Стадия 1: ревью под мульти-тенантную модель
Пользователи	Реализовано	Конвергенция через ревью схем
Партнёр, агентство	Возможно через типизацию организации	Стадия 1: ввести как специализации
Программный клиент, учётные данные	Не реализованы	Стадия 1: управление учётными данными интерфейса
Назначения ролей и прав	Базовая реализация	Стадия 1: ревью под модель прав
Рабочий контекст актора	Не постоянная сущность	Стадия 1: ввести как явное понятие
Управление данными (все понятия)	Не реализованы	Стадия 1: ввести слой управления
География	Реализовано полностью	Возможны мелкие уточнения
Удобства	Реализовано через справочник	Возможны мелкие уточнения

Путь конвергенции (по фазам)

Фаза 1 (Старт, 0-12 месяцев) — параллельная разработка каноничной модели

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

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

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

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

Цель: параллельная работа старой и новой реализаций; постепенное переключение.

Фаза 3 (Специализированная упаковка, 24-36 месяцев) — устаревание старой реализации

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

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

Фаза 4 (Многорегиональная, 36+ месяцев) — масштабирование

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

Каноничные приоритеты конвергенции

Приоритет 1 — критические пробелы, блокирующие боевую эксплуатацию

1. Миграция мульти-тенантности — добавить идентификатор тенанта во все таблицы, политики безопасности на уровне строк, автоматические проверки границы изоляции.
2. Миграция состояний бронирования — 14 каноничных состояний с обработкой неопределённого внешнего состояния.
3. Реализация платёжного домена — выбор провайдера платежей, поток намерения платежа, без хранения карточных данных на платформе.
4. Базовое соответствие регуляторам — уведомление о приватности, управление согласием, минимально жизнеспособный программный интерфейс прав субъекта данных, политики хранения.
5. Базовая безопасность — двухфакторная аутентификация для администраторов, менеджер секретов, журналирование событий безопасности.
6. Базовое восстановление после аварий — проверенная процедура резервного копирования и восстановления для критических данных.

Приоритет 2 — важные расширения

7. Сервис уведомлений — каноничный многоканальный сервис вместо точечных писем.
8. Поисковый сервис — выделение от прямых запросов к базе.
9. Базовое хранилище событий — для доменных событий.
10. Партнёрский интерфейс с жизненным циклом — тестовая среда плюс сертификация для второго поставщика (демонстрация правила 00000).
11. Слой-обёртка над медиа — каноничная модель медиа-ресурса.
12. Базовая интернационализация — каноничный язык, валюта, курсы обмена.

Приоритет 3 — для контролируемой внешней беты

13. Операционная модель конструктора туров — движок правил композиции, саги, обнаружение изменений.
14. Инфраструктура A/B-тестирования — флаги функций плюс платформа экспериментов.
15. Базовая аналитика — минимальный партнёрский дашборд.
16. Инструкции реагирования — для всех каноничных классов инцидентов.
17. Мониторинг соглашения об уровне обслуживания — метрики, цели, дашборды.
18. Автоматизация планирования мощности.

Что существующая реализация даёт стадии 1 как стартовый капитал

Несмотря на пробелы выше, существующая реализация предоставляет существенный стартовый капитал:

1. Более 100 тысяч отелей загружены — каноничная модель объекта размещения имеет реальные данные для тестирования.
2. 4,6 миллиона фотографий — медиа-основа существует, нужен только слой-обёртка.
3. Географическая цепочка (182 страны) — данные интернационализации и географии готовы.
4. Интеграция первого поставщика работает в боевом режиме — каноничная модель поставщика имеет реальный тестовый случай.
5. Боевая точка входа с реальным трафиком — операционная база.
6. Современная реляционная база — текущий стек для каноничной базы.

Это значительно снижает риск стадии 1 — мы строим на работающем фундаменте, а не в чистом поле.

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

Принцип 1. Удушающая лоза (strangler fig pattern)

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

Принцип 2. Сначала каноничная модель, потом реализация

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

Принцип 3. Изоляция тенантов с первого коммита

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

Принцип 4. Никакой жёсткой логики под конкретного поставщика

Любой новый код, касающийся приёма данных, написан независимо от поставщика, по паттерну адаптера. Захватная логика под одного поставщика в общем коде запрещена (правило 00000).

Принцип 5. Безопасность по дизайну

Любой новый путь кода проходит ревью безопасности до боевого развёртывания. Существующие точки входа без ревью безопасности — на удалении или с явным аудитом.

Принцип 6. Соответствие регуляторам по дизайну

Любая обработка персональных данных проходит ревью приватности. Существующие потоки без ревью приватности — аудит на стадии 1.

Принципы работы архитектора с существующей реализацией

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

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

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

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

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

Если каноничная модель несовместима с задеплоенной схемой:

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

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

• Каноничная доменная ось — текущие таблицы (отели, пользователи, события) — первая итерация подмножества каноничной модели, требует поэтапного рефакторинга.
• Поверхности взаимодействия — текущая реализация имеет частичное покрытие: сайт = зачаточная витрина для клиентов, административная панель = частичная внутренняя поверхность, точка входа = адаптер приёма данных (не партнёрский интерфейс).
• Платформа как продукт — не реализована в текущей реализации. Полная разработка в фазах 2-4.
• Ось данных и интеллекта — хранилище событий — первая итерация захвата событий, требует разделения. Платформа машинного обучения и A/B-тестирование не реализованы.
• Операционная ось — текущая инфраструктура — первая реализация стартовой фазы, но на стороннем провайдере. Миграция на основного провайдера — фаза 1.

Открытые вопросы (развилки)

• Параллельная разработка каноничной модели или сначала рефакторинг текущей. Делать рефакторинг параллельно с разработкой новой каноничной модели в фазе 1 или сначала закрыть документную базу и начать рефакторинг кода в фазе 2? Решается при обсуждении плана разработки.
• Сохранение текущей управляемой базы или миграция к основному провайдеру. Сохранить текущую управляемую базу для боевой эксплуатации или мигрировать вместе с остальной инфраструктурой? Решается при принятии решения о развёртывании стартовой фазы.
• Сложность скрипта миграции. При миграции данных из текущей схемы в каноничную — насколько сложным может быть скрипт миграции? Если сопоставление простое — прямой скрипт; если требуются ручные решения — необходим процесс управления данными для каждой спорной записи. Решается на фазе 2 при детальной разработке миграции.
• Что делать с уже существующими бронированиями. Если к моменту фазы 2 в существующей реализации появятся реальные боевые бронирования, как мигрировать их в каноничную модель? Рекомендация: не запускать боевые бронирования в текущей реализации до разработки каноничной модели в фазе 2. Если уже запущены — миграция через слепок плюс пересборка.

Что нельзя делать с этой осью

• Считать существующую реализацию образцом для каноничной архитектуры — наоборот, каноничная архитектура определяет, какой должна быть существующая реализация после конвергенции.
• Подгонять каноничную модель под текущие таблицы — это разрушает правило 00000 и привязывает архитектуру к конкретному поставщику.
• Останавливать боевую работу для миграции — миграция всегда параллельная с работающей системой по паттерну удушающей лозы.
• Игнорировать технический долг — каждый из семи видов долга должен быть явно зафиксирован, с явным путём конвергенции.
• Редактировать существующую реализацию без явного разрешения пользователя — это нарушение правил Свода законов.
• Откладывать критические пробелы (мульти-тенантность, состояния бронирования, платёжный домен, соответствие регуляторам, безопасность) на потом — они блокируют переход к боевой эксплуатации.

Итог

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

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

• Связь с реализацией (ось 6) — полный каноничный документ, источник истины этой оси.
• Главная архитектурная ось — карта всех шести осей платформы.
• Манифест переосмысления платформы — роль и принципы платформы.
• Каноничная доменная ось (ось 1) — словарь главных понятий.
• Поверхности взаимодействия (ось 2) — двери платформы к миру.
• Платформа как продукт (ось 3) — коммерческая модель и обещания обслуживания.
• Ось данных и интеллекта (ось 4) — события, аналитика, машинное обучение.
• Операционная ось (ось 5) — масштабирование, надёжность, инциденты.
• Обзор Ось 1 — резюме простыми словами — резюме первой оси по тому же шаблону.
• Обзор Ось 2 — резюме простыми словами — резюме второй оси по тому же шаблону.
• Обзор Ось 3 — резюме простыми словами — резюме третьей оси по тому же шаблону.
• Обзор Ось 4 — резюме простыми словами — резюме четвёртой оси по тому же шаблону.
• Обзор Ось 5 — резюме простыми словами — резюме пятой оси по тому же шаблону.
• Граф пересечений архитектурных осей — карта связей между всеми осями.