TRIDE.Offline — автономный режим клуба

1.Резюме

Решение. В клубе устанавливается TRIDE Edge — компактный автономный сервер (standalone Linux-сервис в Docker, мини-ПК или любой компьютер клуба). Edge держит зашифрованный снапшот данных клуба (клиенты, членства, расписание, брони, программы тренировок, идентификаторы СКУД, сотрудники и права), отвечает на запросы клиентских приложений в существующем формате API TRIDE, принимает локальные мутации в журнал операций (oplog) и, когда интернет возвращается, досылает их в облако — где они применяются штатными сервисами бэкенда, а не пишутся в базу напрямую.

Ключевой принцип — «без второго бэка». Edge не дублирует бизнес-логику облака: он кэширует read-данные и переиспользует минимальный набор правил (списание визита, ёмкость занятия, antipassback, верификация QR), вынесенных в общий пакет @tride/offline-core, который подключают и облако, и edge. Все накопленные офлайн-операции при синхронизации прогоняются через существующие модули бэкенда (booking, memberships, access_control, training_session) — с идемпотентными ключами и разрешением конфликтов.

Как это достигается малой кровью. Исследование кодовой базы показало, что фундамент уже готов: приложения несут весь UI-бандл локально (AppImage/Android), у Electron уже поднимаются локальные серверы и AceBase, у Android TV — SQLite-буфер статистики занятий с досылом; приём датчиков и живой рендер тренировки — полностью локальные; в execPost уже есть runtime-override адреса API (window.TRIDE_API_HOST), а конфиг клуба уже кэшируется на устройстве. Не хватает трёх вещей: локального источника данных и авторизации, локальных мутаций и локального решателя СКУД, локального движка старта занятий. Именно их закрывает TRIDE Edge.

2.Как устроен TRIDE сегодня

Факты аудита кодовой базы (frontend @ 8.0.7, backend, все пути — от корней репозиториев). Этот раздел — фундамент плана: каждый элемент архитектуры TRIDE.Offline ниже опирается на конкретные механизмы, уже существующие в коде.

2.1. Клиентские приложения и сборки

Один и тот же код SPA (Svelte 4 + Vite 4) собирается в несколько форм: Web/PWA, Electron (десктоп-консоли и ТВ-боксы), Capacitor 6 (Android/iOS, включая Android TV-флейвор tridetv). Флейворы app_versions/ (tride, rock, flowrow, cyclestar, way2fit + клубные через prepareclub) отличаются темой, иконками и конфигом — код один.

screenMode — режим клубного экрана (панель у тренажёров): устройство регистрируется в коллекции devices с screenmode: true, zone_id, screenmode_type; флаг приезжает в ответе devices/register / get.device.token (автологин по hw_id) и уводит приложение на маршрут /screen. TV-сборка дополнительно получает нативный watchdog (Foreground Service + WakeLock), ScreenRecoveryService (самовозврат на /screen) и периодическую очистку WebView-кэша вне тренировки.

2.2. Как клиент общается с облаком

Единый REST-транспорт execPost (frontend/src/lib/api/api.js): POST /<module>/<action>, тело — JSON {...params, access_token}. Адрес определяется каскадом: window.TRIDE_API_HOST (runtime-override, сегодня ставится только виджетами) → import.meta.env.VITE_API_HOST (вшит на билде) → дефолт. Сетевой сбой превращается в {error:'network_error'} и каждый вызов справляется сам — общего офлайн-кэша ответов сегодня нет.

Boot-последовательность авторизованного клиента: /auth/checktoken → /cycle/getmydata (профиль, права, клубы, screenmode) → параллельно /settings/get, /users/getsettings, /cycle/listmyclubs, /devices/register; конфиг клуба — /tride/club.getconfig (needauth:false — тема, меню, settings, network_settings, access) и уже кэшируется на устройстве в clubSettings_<club_id> + синхронное зеркало clubSettingsSync_<club_id> для раннего сидинга до рендера. Токен — JWT HS256, 15 минут, sid указывает на token_sessions; вход — SMS-код.

Realtime — socket.io (msgpack) на sockets_host: регистрация сокета через devices.register, подписки на модули-каналы (cycle, tride, devices…), пинг каждые 10 с, собственный реконнект-цикл. Чат — отдельный сокет. Датчики устройства уходят в облако усреднёнными батчами cycle/multidata раз в 3 с (volatile — при обрыве кадры для облака теряются, локальный рендер продолжает).

2.3. Тренировочный контур

Цепочка занятия сегодня:

Тренер запускает через пульт (/tride/sessions.start → tridemanager). Кадры датчиков (пульс/мощность/каденс) приходят на экран локально (UDP/BLE/HTTP — см. таблицу ниже), экран рендерит сам и шлёт батчи в облако; tridemanager маршрутизирует кадры участникам, пишет cycle_activities + session_graphs, рассылает pdata зонам. Финиш → updateStats → статусы брони completed → statsmanager/pulse/бейджи. Тренировочная программа — документ workouts: профиль-таймлайн блоков {зоны мощности/каденса/пульса, интервалы, повторения} + дорожки музыки/видео/триггеров; свои (club/library), сетевые и купленные (store + entitlements); версии в workout_versions.

2.4. Данные клуба (клиенты, записи, членства, СКУД)

Полный реестр — backend/app/system/db/mongo.collections.js (~560 коллекций, БД chat). Ключевые для офлайна:

2.5. Что сегодня переживает обрыв интернета

• уже есть UI-бандл на устройстве (Electron/Android), локальные медиа, кэш конфига клуба и темы, offline.html у PWA;
• уже есть приём датчиков и живой рендер идущего занятия на экране зоны;
• уже есть локальный буфер итогов участников (SQLite на TV / AceBase в Electron) с серверным досылом;
• уже есть единственная персистентная офлайн-очередь мутаций — health-активности (health:offline_queue), паттерн идемпотентности уже обкатан;
• нет локальной авторизации, источника read-данных, мутаций (записи/чекины), СКУД-решений, старта занятий. Это и есть объём TRIDE.Offline.

3.Задача и сценарии

Сценарий: у клуба пропадает интернет (провайдер/авария) на период от пары часов до двух суток. Клуб продолжает работать физически: клиенты приходят, тренировки идут, ресепшен продаёт… нет — обслуживает, двери должны открываться.

Вне scope (согласовано): продажи/оплаты/фискализация офлайн; SMS-вход новых пользователей офлайн; внешние CRM-синки; глобальные межклубные функции. Продажи исключены из плана сознательно: офлайн-фискализация — отдельная нерешённая тема (известный пробел offline-чеков), а финансовые рассинхроны дороже выгоды.

4.Выбор архитектуры: где живёт офлайн-ядро

Рассмотрены четыре варианта размещения локального сервера клуба. Согласовано: вариант B — standalone Linux-сервис.

5.Архитектура TRIDE.Offline

5.1. Режимы работы и переключение

5.2. Ключевые механизмы на стороне клиента (минимальный след)

В клиентское приложение добавляется один маленький модуль EdgeRouter (общий для web/electron/capacitor). Всё остальное — существующий код.

• Адрес edge приезжает из облака заранее: в tride/club.getconfig → network_settings.offline = {enabled, edge_host}. EdgeRouter сохраняет его рядом с уже кэшируемым конфигом клуба — к моменту обрыва адрес уже известен.
• Переключение API: сегодня execPost уже поддерживает runtime-override через window.TRIDE_API_HOST (api.js:10–11) — EdgeRouter просто ставит его при переходе в offline и убирает при возврате. Сокеты — аналогично через переопределение хоста в socketsManager (переподключение уже встроено его реконнект-циклом).
• Проба без таймаут-ожидания: при network_error от облака 2 раза подряд EdgeRouter пробует edge_host/status с таймаутом 1.5 с; успех → offline-режим; индикатор в топбаре + баннер ограничений.
• Web-клиенты, открывшие приложение уже в офлайне: облако недоступно, SPA не загрузится оттуда — но edge сам раздаёт web-бандл (кэш последней web-сборки + сгенерированный middleware-генератором index.html с APP_CONFIG.api_host = edge_host). QR-табличка «Wi-Fi клуба» на ресепшене ведёт на https://edge.tride.local.
• Экраны зон и СКУД-терминалы — настроены на edge постоянно (см. 8.2/8.3), для них переключения не существует.

6.Edge-нода: доставка и состав

6.1. Дистрибутив и требования

• Форма: docker-compose (tride-edge + том данных /data со снапшотом и oplog). Также поставляется bare-metal systemd-юнит для клубов без Docker.
• Железо (рекомендация): x86 мини-ПК (класс Intel N100), 8 ГБ RAM, 64 ГБ SSD, пассивное охлаждение, + USB-UPS. Потребление edge — десятки МБ RAM, диск ≤ 2 ГБ.
• Сеть: статический IP или DNS-имя в роутере клуба (edge.tride.local; edge дополнительно анонсирует себя по mDNS). HTTPS с самоподписанным сертификатом клуба (приложения TRIDE уже игнорируют self-signed на embedded-хостах — механика game.tride.ru).
• Активация: в админке TRIDE включается опция клуба «Offline» → генерируется edge_id + edge_secret (ротация в 1 клик, паттерн club_notify_providers / access_control.token) → клуб вводит их при первом запуске edge → edge делает первичную инициализацию (полный снапшот) и появляется в мониторинге.
• Self-update: edge сам обновляется из облака (тот же канал dist.tride.ru, образ/бандл с версией схемы снапшота и oplog — совместимость версий обязательна).

6.2. Внутренний состав edge

7.Синхронизация с облаком

Облако — всегда источник истины. Edge может отставать, но не расходиться: все офлайн-изменения — события (event-based), которые облако применяет и на их основе пересчитывает производные состояния (остатки визитов, сводки, статусы).

7.1. Pull: снапшот данных клуба

Новый сервис облака edge-sync (или модуль main) отдаёт снапшот и дельты по курсорам. Каждая сущность — курсор по updated_at (у BaseModel поле автоуправляется), soft-delete приезжает как removed:true. Частота: раз в 30–60 с по изменённым; полный реснапшот — при инициализации и раз в 7 суток (самопроверка целостности).

*Клуб 10 000 клиентов / 3 000 активных членств — типичный крупный. Итого снапшот 15–25 МБ, дельта за минуту — килобайты. Диск edge (с запасом на oplog и web-бандл) — < 2 ГБ.

7.2. Push: oplog мутаций

Каждая офлайн-мутация записывается в oplog с идемпотентным ключом и применяется облаком через существующие сервисы — это и есть «без второго бэка»: одна кодовая база бизнес-логики, два рантайма.

Порядок применения: батчи по 100 операций, строже по времени; ответ облака — пер-операционный статус (applied / conflict / rejected), edge обновляет oplog и локальное зеркало. Лимит попыток и карантин подозрительных — по паттерну synctasks (exsync).

7.3. Конфликты — политики по доменам

7.4. Свежесть и границы доверия снапшота

• offline_grace: авторизация по локальным сессиям — до 7 суток с последнего успешного синка; дальше только PIN сотрудника +QR-вход экранов (hw_id).
• СКУД: работает до 14 суток (пропуск клиента важнее; риск — устаревшие членства: продолжают пускать по действовавшему на момент снапшота; все проходы журналируются и сверяются после).
• Мутации брони — до 3 суток, дальше edge предлагает только просмотр (защита от расползания конфликтов).
• Все границы — настройки клуба (профили «строгий/сбалансированный»), по умолчанию сбалансированный.

8.Офлайн-домены: как работает каждый

8.1. Авторизация адаптированная

SMS-код офлайн невозможен, JWT живёт 15 минут. Решение — три пути входа в offline:

1. Уже авторизованные устройства (основной путь): edge валидирует подпись JWT (HS256 — секрет общий, edge доверенный компонент платформы), сверяет sid со снапшотом активных сессий клуба, не проверяет exp в пределах offline_grace. Права/клуб — из снапшота сессии. Работает для сотрудников, клиентов и экранов.
2. Экраны/боксы: штатный автологин по hw_id (club/get.device.token) — edge отдаёт тот же формат ответа из снапшота devices клуба.
3. Сотрудники без живой сессии: локальный PIN-вход (выбор профиля из снапшота + PIN; хэш ротируется через облако). Права — те же wildcard-наборы (rbac/permissions.js из общего пакета).

Новые клиентские регистрации офлайн — нет (осознанно). Сотрудник может завести черновик клиента (client.draft_add) для записи — дедуп при синке.

8.2. СКУД и проходы P0

• Терминал всегда настроен на edge (один раз при установке). Онлайн: edge — прозрачный прокси вебхука в облако (решение и журнал остаются штатными). Офлайн: решает локальный decideAccessCore из @tride/offline-core — тот же код, что в облаке, потому поведение и тексты причин отказа идентичны.
• QR: static (номер карты) работает тривиально; dynamic QrBlock верифицируется пер-клубным ключом из снапшота (ключ выдается edge при инициализации по TLS, хранится зашифрованным). TTL в офлайне расширяется политикой (×4), иначе клиентские QR протухали бы; одноразовость — локальный nonce-реестр, использованные nonces доезжают в облако (анти-replay).
• Списания визитов — локально по visit_charge (on_entry/on_exit — настройка уже в клубе); остаток локального зеркала уменьшается мгновенно, облако при синке подтверждает событиями. Внешние СКУД-владельцы (psport/1С клубы): локально не списываем, только пускаем и журналируем (уважаем их external_ownership).
• Антиpassback — по локальному зеркалу событий (30 дней в снапшоте + локальные).

8.3. Тренировки P0

• Программы: снапшот workouts покрывает свои, сетевые и купленные (entitlements) — тренер в offline запускает всё, что доступно клубу сегодня. Медиа: экраны играют предзагруженное (механизм offlinemedia/offlineworkouts уже существует), облачное видео/музыка офлайн недоступны — экраны переключаются на локальный плейлист/визуализацию.
• Экраны зон ходят на edge постоянно (сокеты и REST): в онлайне edge проксирует в облако (RTT датчиков зоны падает — сегодня батчи гоняются через облако), в офлайне обслуживает локально. Протокол событий не меняется: экран подписан на те же session_ready/pdata/….
• Lite-движок edge: занятие создаётся из снапшота расписания (ScheduleSession ±14 дней) или вручную тренером; посадка участников — из брони и по QR (ShowQR на экране → приложение/скан сотрудника → локальная проверка членства/брони); старт/пауза/финиш — с пульта тренера через edge-сокет.
• Данные: датчики продолжают приходить на экраны локально (уже так); экраны шлют батчи multidata на edge вместо облака — edge маршрутизирует участникам, рассылает pdata локальным зонам, копит графики. Чего edge не делает: сложные сводные итоги участников — их досчитывает облако при синке (штатная обработка ready_for_processing → statsmanager/pulse), экран же рендерит live сам, как сегодня.
• Результаты: граффики и activity-записи уходят в oplog (session.results) и применяются тем же путём, каким сегодня досылаются локальные SQLite-буферы экранов (sessions.syncparticipant) — то есть статистика, стрики, бейджи, пульс-сессии клиентов доедут штатно.
• Стриминг тренера, 3D-миры, глобальные соревнования — офлайн нет (п. 9).

8.4. Записи, чекины, расписание P0

• Просмотр расписания (±14 дней) и составов занятий — из снапшота; «кто записан/в листе ожидания/пришёл» — снапшот + локальные мутации (edge мержит по времени).
• Запись на занятие (сотрудник или клиент в Wi-Fi): локальная проверка ёмкости/waitlist/окна записи (booking_settings уже в модели), валидация по Joi-схеме из общего пакета, локальный документ брони, oplog booking.create. Списание визита пакета при записи (policy on_booking) — локально, событием.
• Чекины: ручной (сотрудник), по QR, автоматом от СКУД (check_in_method: access_control); no-show отмечается вручную/по правилам — всё в oplog.
• Отмена/перенос — аналогично, с политикой конфликтов из 7.3.

8.5. Данные клиентов на ресепшене P0 чтение ограниченная запись

• Поиск (имя/телефон) — FTS по снапшоту, карточка: контакт, клубное фото, статус, кастомные поля, теги; активные членства/пакеты с остатками и сроками, заморозки; предстоящие и прошедшие записи (снапшот + локальные); история проходов (30 дней + локальные).
• Запись офлайн ограничена: клубные поля профиля, комментарий, теги, статус; смена телефона/документов — онлайн-only. Персональные данные минимизированы в снапшоте (см. 10).

8.6. Клиенты в Wi-Fi клуба P1

• Установленные приложения (мобайл/Electron): входили до обрыва — работают через EdgeRouter (валидация локальной сессии по 8.1): расписание, свои записи/визиты, QR-пропуск (обновляется локально по club-ключу), запись на занятие.
• Web/PWA и новые устройства: открывают https://edge.tride.local — edge раздаёт SPA (кэш web-сборки + APP_CONFIG с api_host=edge). Вход — только если сессия жива (SMS офлайн нет); просмотр расписания и вход по QR-пропуску — для авторизованных.
• Чат, поддержка, AI-ассистент, пуши — офлайн скрыты из UI (баннер ограничений).

9.Чего офлайн не будет (осознанные ограничения)

10.Безопасность и 152-ФЗ

• Периметр: edge размещается в служебном VLAN/Wi-Fi (гостевая сеть — только до web-раздачи и API read-only клиента); доступ к мутациям — по правам ролей; edge_secret ротируется из админки.
• Секреты на площадке: пер-клубный QR-ключ, PIN-хэши, снапшот ПД. Меры: шифрование тома снапшота, ключи только в памяти процесса, аудит-лог локальных операций (кто/что/когда — уезжает в облако при синке), не хранить дольше grace-политики, авто-вайп при ротации edge_secret.
• Минимизация ПД в снапшоте (152-ФЗ): поля-минимум клиентов, документы/адреса не синкаются; кастомные поля исключаются флагом offline_sync:false; журнал доступа к карточкам в офлайне. Согласия клиентов не требуются сверх действующих (обработка в интересах клуба-оператора, средства на площадке клуба).
• Сценарий угона edge: секреты ротируются из облака (мгновенная инвалидация), снапшот зашифрован, мутации с украденного edge не примутся после ротации; heartbeat подписан.
• Аудит и наблюдаемость: heartbeat-метрики (возраст снапшота, глубина oplog, режим), алерты в админку: «клуб офлайн > 2 ч», «edge не выходил на связь > 24 ч», «конфликты после синка > N».

11.План внедрения

Оценки трудоёмкости — ориентировочные (1 разработчик-владелец + подключение второго на пиках Ф2/Ф3), недели чистой разработки без буферов на ревью/релизы.

12.Риски и открытые вопросы

Открытые вопросы (решаются на старте Ф0): модель тарификации опции; конкретная модель мини-ПК для рекомендации/поставки; политика TTL QR для офлайна (×4 — рабочая гипотеза, согласовать с безопасностью); глубина снапшота истории проходов (30 дней — гипотеза); нужен ли локальный поиск клиентов по частичному номеру телефона с маскированием (privacy-баланс); взаимодействие с клубами, где СКУД уже на psport/1С (только журналирование — подтвердить на пилоте).

13.Приложение: справочник по кодовой базе