Архитектура Mini App для MAX: фронт + бек + бот + интеграции (референс-схема)

Когда команда впервые берётся за Mini App для MAX, соблазн велик. Хочется быстро собрать интерфейс, прикрутить пару методов, научить бота отвечать на команды и считать, что система готова. На старте это выглядит бодро. Через месяц появляется авторизация, потом статусы заявок, затем CRM, уведомления, каталог, платёжный сценарий, личный кабинет — и аккуратная схема из четырёх блоков внезапно превращается в ящик с проводами, где каждый кабель подозрительно важный.

Архитектура Mini App для MAX решает этот вопрос ещё до первого неприятного сюрприза. Она отвечает на приземлённые вещи: кто за что отвечает, где живёт бизнес-логика, что хранить во фронте и что в бэкенде, как бот запускает Mini App, как сервис узнаёт пользователя, как отправлять статусные уведомления и как не утонуть в связке «бот + Mini App MAX», когда к проекту добавляются ERP, CRM, каталог, аналитика и очередь событий.

В «ОЧЕНЬ» такая архитектура уже работает в бою: меню и оплата живут в Mini App, заказы падают на рабочий стол персонала, а страницы меню дополнительно генерируются для поиска.

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

Нормальная архитектура Mini App в MAX держится на разделении ролей. Фронт отвечает за интерфейс и быстрые действия. Бэк хранит правду о данных и сценариях. Бот работает как точка входа, транспорт команд и канал уведомлений. Интеграции связывают систему с внешним контуром.

Ниже разложим систему на понятные компоненты, соберём референс-схему и разберём, где хранить состояние, как строить интеграцию Mini App с backend и как запускать сценарий так, чтобы бот и Mini App не спорили друг с другом за право быть центром вселенной.

Платформа MAX устроена так, что мини-приложение подключается через чат-бота. В справке для разработчиков указано, что добавить мини-приложение без бота нельзя, а URL Mini App настраивается в разделе «Чат-бот и мини-приложение → Настроить». Там же выбирается кнопка открытия приложения. Для Mini App нужен валидный HTTPS URL. Если адрес остаётся статичным, приложение можно обновлять без замены самой точки входа. При открытии нового мини-приложения текущее закрывается. Внутри MAX для открытия ссылок Mini App используется openMaxLink, а не обычный внешний переход.

Это уже задаёт базовую модель: бот в MAX не декоративный элемент, а обязательная дверная ручка для Mini App. Значит, архитектура должна строиться вокруг этой реальности, а не в отрыве от неё.

В рабочем варианте система делится на четыре слоя:

1. Фронт Mini App. Интерфейс, экраны, формы, карточки, каталоги, фильтры, пошаговые сценарии, локальное UI-состояние.

2. Бэкенд приложения. API, бизнес-логика, авторизация, хранение сущностей, правила доступа, оркестрация сценариев, работа с очередями и интеграциями.

3. Бот MAX. Точка входа в сценарий, команды, диплинки, статусные сообщения, напоминания, передача контекста при запуске Mini App.

4. Интеграционный контур. CRM, ERP, каталог, платежи, склад, внутренние кабинеты, сервисы идентификации, аналитика, уведомления.

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

MAX Bridge подключается в Mini App через библиотеку max-web-app.js, после чего приложению становится доступен глобальный объект window.WebApp, через который Mini App взаимодействует с клиентом MAX и интерфейсом устройства. У MAX есть и собственная UI-библиотека, рассчитанная на React 18+ и единообразную работу на iOS и Android.

Из этого следует практичный вывод: фронт Mini App должен быть тонким. Его задача не в том, чтобы хранить бизнес-правду, а в том, чтобы быстро показать состояние, собрать действие пользователя и отправить запрос дальше.

Во фронте стоит держать:

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

Во фронте не стоит держать:

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

Это ключевой вопрос — на нём ломается половина проектов.

Короткий ответ: UI-состояние хранится во фронте. Бизнес-состояние — на бэкенде. Контекст коммуникации живёт в связке бота и бэка.

Состояние фронта подходит для коротких сценариев, которые не страшно потерять:

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

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

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

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

• стартовый payload;
• идентификатор чата и пользователя;
• ссылка на сценарий, токен запуска Mini App;
• сообщение о статусе, краткий контекст для нотификации.

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

В MAX есть диплинки. Для бота формат использует параметр start, для Mini App работает startapp. В документации указан формат https://max.ru/?startapp=, где payload может передавать дополнительный контекст. Поддержка диплинков есть в актуальных версиях клиентов MAX для iOS и Android.

Удобная механика запуска:

1. Пользователь нажимает кнопку в боте или внешнюю ссылку.
2. В диплинке передаётся payload.
3. Mini App получает контекст запуска.
4. Фронт отправляет payload на бэкенд.
5. Бэкенд проверяет, что это за сценарий.
6. Бэкенд возвращает нужный экран или состояние.
7. Mini App открывает пользователя сразу в нужной точке.

Примеры payload: startapp=order_123, repeat_payment, promo_summer, doc_sign, slot_appointment.

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

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

Хорошая схема бэка для Mini App:

• API gateway или основной API — принимает запросы от Mini App и внутренних сервисов;
• сервис авторизации — пользователь, токены, сессия, связка с профилем MAX;
• сервис сценариев — этап пользователя, что можно, какой экран открыть;
• сервис уведомлений — команды боту на статусные сообщения;
• сервис интеграций — CRM, ERP, каталог, склад, billing, документооборот;
• хранилище данных — долгое состояние, журналы, сущности, связки.

Для большинства бизнес-кейсов этого достаточно. Нет смысла дробить систему на десять микросервисов, если у вас Mini App на запись к врачу или заявка на кредит с тремя экранами. Микросервисы уместны, когда продукт и нагрузка уже доросли до реальной потребности.

Для чат-ботов MAX доступен Bot API. Токен выдаётся на платформе партнёров в разделе интеграции, в HTTP-запросах его передают через заголовок Authorization. Для получения событий у бота есть webhook и альтернатива в виде long polling — это удобно для статусных уведомлений и асинхронных сценариев.

Рабочая схема уведомлений:

1. Пользователь запускает Mini App через бота.
2. На бэкенде создаётся сущность (заказ, заявка).
3. Бэкенд сохраняет связку с пользователем MAX и чатом.
4. Внешняя интеграция меняет статус.
5. Сервис событий ловит изменение.
6. Сервис уведомлений отправляет сообщение в бот.
7. Бот сообщает новый статус и даёт кнопку открытия Mini App.
8. Пользователь возвращается в приложение уже с актуальным состоянием.

Бот не вычисляет статусы сам — он получает готовое событие от бэкенда. Архитектура остаётся чистой: бот сообщает, сервер решает.

Когда говорят «интеграция Mini App с backend», часто представляют набор REST-методов и думают, что работа почти сделана. Проблема начинается позже: нужно связать запуск по диплинку, права доступа, статусы, повторный вход, уведомления, ошибки интеграций и историю действий.

Три принципа:

1. Backend-first логика — все бизнес-правила на сервере.
2. Идемпотентные сценарии — повторный запрос не ломает процесс.
3. Событийная модель для статусов — изменение в CRM или ERP не ждёт ручного обновления пользователя.

Если проект рассчитан на рост, полезно сразу заложить:

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

На этом этапе архитектура Mini App для MAX перестаёт быть витриной и превращается в сервисную систему.

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

2. Спокойнее поддержка. Ошибка в UI не роняет бизнес-состояние. Сбой интеграции не заставляет бота придумывать правду на лету.

3. Быстрее запуск новых сценариев. Один бот может вести в разные ветки Mini App через payload и диплинки.

4. Нормальная аналитика. Появляется понятный маршрут: вход из бота, открытие Mini App, действие на экране, смена статуса, повторный визит.

Если проект планируется всерьёз, удобнее думать о нём сразу как о сервисе с несколькими каналами входа. Разработка Mini App в мессенджере MAX редко сводится к вёрстке экранов — почти всегда всплывает архитектурный разговор.

Какую архитектуру Mini App в MAX выбрать для первого релиза?
Умеренная схема: Mini App на фронте, один основной backend, бот как канал входа и уведомлений, отдельный слой интеграций к CRM или ERP. Этого хватает для каталога, записи, личного кабинета, заявки, статусов и базовой аналитики. Важнее грамотно разделить роли компонентов, чем сразу строить «комбинат» из сервисов.

Где хранить состояние?
Короткое — во фронте. Бизнес-сущности, статусы, права, история — на бэкенде. В боте — только контекст запуска и привязка к каналу коммуникации. Сервер должен быть хозяином фактов.

Как бот и Mini App работают вместе без дублирования логики?
Бот — вход и уведомления. Mini App — интерфейс и действия. Бэкенд принимает решения и отдаёт истину по статусам. Бот не решает, можно ли оплатить заказ или какой шаг анкеты сейчас актуален — он передаёт команду и показывает статус с сервера.

Нужен ли MAX Bridge в каждом Mini App?
Если приложение должно нормально взаимодействовать с клиентом MAX, да: через него доступен window.WebApp и встраивание в клиентскую среду. Обходить эту связь неразумно для полноценного сценария.

Как строить интеграцию с backend, если уже есть сайт или личный кабинет?
Не плодить отдельную «правду» для MAX. Лучше общий backend или хотя бы общий домен бизнес-логики: сайт, кабинет и Mini App работают с одними сущностями; отличаются интерфейсы и точки входа.

Можно ли сделать Mini App для MAX без чат-бота?
Нет: в документации MAX это указано прямо. Подключать, управлять и запускать мини-приложение можно через чат-бота. Для бизнеса это плюс: сразу есть канал входа и уведомлений.

Как лучше запускать Mini App из бота?
Диплинки со startapp и короткий контекст в payload: идентификатор сценария, заказа, акции или ветки. Mini App отдаёт payload на сервер и запрашивает актуальное состояние — пользователь попадает сразу в нужную точку процесса.

Где хранить статус заказа или заявки?
На сервере. Во фронте — копия для отображения; в боте — уведомление по серверному событию. Так меньше рассинхрона между интерфейсом, чатом и внешними системами.

Webhook или long polling?
При нормальной инфраструктуре чаще логичен webhook: события быстрее, без постоянного опроса. Long polling подходит для простого или тестового контура. Платформа поддерживает оба варианта.

Если нужна помощь с архитектурой Mini App, ботом и интеграциями в MAX — команда Else Digital уже запускает такие проекты и может разобрать ваш кейс на созвоне.

Архитектура Mini App для MAX становится понятной, когда на неё смотрят не как на «веб-страничку внутри мессенджера», а как на сервисную систему: свой фронт, бэкенд, канал через бота и контур интеграций. Вопрос не в том, соберётся ли это технически — соберётся. Вопрос в том, выдержит ли схема рост через несколько месяцев, когда добавятся статусы, роли, уведомления, CRM и аналитика.

Референс-модель: фронт — интерфейс и быстрый отклик; бэк — бизнес-правда и логика; бот — открытие Mini App, контекст и смена статусов в чате; интеграции — связь с внешними системами. Самый частый промах — слишком ранняя экономия на структуре: логика размазывается по фронту и боту, а потом система ведёт себя как шкаф на кривом полу. Если смотреть на архитектуру как на фундамент, дальше проще и в разработке, и в сопровождении.