Терминал 8Ball POS — настройка и управление

Руководство для владельцев и администраторов клуба: как с нуля настроить терминал (касса на стойке), подключить оборудование и облако, завести справочники и вести смену.

Терминал — это десктоп-приложение (Windows/macOS), которое работает локально (своя база на месте) и синхронизируется с облаком (бекофис, отчёты, Telegram, публичные брони). Управление светом столов идёт через USB-контроллер PowerAnt (RS-232).

• Язык: русский. Валюта по умолчанию — BYN.
• Облако (бэкенд): https://billiard-backend.vercel.app
• Бекофис: https://billiard-backoffice.vercel.app

Параллельно с этим документом в самом приложении есть встроенная справка: раздел Инструкции в меню (Начало работы, Смена, Столы, Клиенты и лояльность, Печать, Инвентарь, Продажи и отчёты, Telegram-бот). Этот гайд — про настройку и администрирование; встроенные инструкции — про ежедневные операции.

#1. Роли и вход

Вход на терминал — по PIN-коду (4–8 цифр, экранная или физическая клавиатура).

Заводские PIN при первом запуске базы:

Сразу смените заводские PIN (раздел Пользователи) — это первое, что нужно сделать. Сброс всего состояния = удалить файл базы billiard-echo.db из папки данных приложения (userData).

Меню слева (зависит от роли):

• Основное (все роли): 🎱 Игровые столы, 📋 Смена, 🗓 Бронирования, ⚖️ Штрафы, 📖 Инструкции.
• Управление (владелец/админ): 🧾 Продажи, 🧑‍💼 Клиенты, 🏓 Остаток, 📚 Журнал смен, 📝 Журнал событий, 🔌 COM-порт / Свет, ⚙️ Настройки (только владелец).

Внизу боковой панели — индикаторы состояния смены (открыта/закрыта, номер) и COM-порта (подключён/нет, имя порта), а также профиль и выход.

#2. Первый запуск: активация терминала

При первом запуске (терминал ещё не привязан к клубу) — два варианта:

#Вариант А. «Активировать существующий» (по лицензионному ключу)

Если поставщик уже создал клуб и выдал ключ:

1. Выберите «Активировать существующий».
2. URL бэкенда — https://billiard-backend.vercel.app (подставлен по умолчанию).
3. Лицензионный ключ — вида ECHO-XXXX-XXXX (поле само форматирует ввод).
4. После успеха увидите название клуба и «Лицензия до …».

#Вариант Б. «Зарегистрировать новый клуб» (самообслуживание)

Мастер из 3 шагов — заводит новый клуб и пробную лицензию:

1. Подключение: URL бэкенда, название клуба (из него предлагается slug), slug публичной страницы броней (латиница, цифры, дефис, напр. 8ball-center), инвайт-код (если требует поставщик).
2. Реквизиты: юр.название, страна (по умолч. Беларусь), город, юр.адрес, УНП, валюта (BYN), email, телефон, сайт, время окончания смены (по умолч. 03:00).
3. Карточка: краткое описание для страницы броней, URL логотипа (с предпросмотром), приём онлайн-броней (вкл по умолчанию).

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

Подробный «под ключ»-сценарий подключения клуба к облаку (с device-токеном и Telegram) описан в docs/backoffice-onboarding.md.

#3. Облачная синхронизация

Настройки → Синхронизация. Без облака терминал работает, но не будет ни отчётов в бекофисе, ни публичных броней, ни облачного Telegram-бота.

1. Включите синк.
2. URL бэкенда: https://billiard-backend.vercel.app.
3. Device-токен: вставьте токен, выданный поставщиком (выпускается в бекофисе: Клубы → Терминалы → «Выпустить токен», показывается один раз) → Сохранить.
4. Нажмите «Проверить» — покажет связь и расхождение часов (ms). Статус станет «Облачный синк активен».

При первом синке:

• вверх уезжают существующие клиенты/тарифы/сессии (бэкфилл);
• вниз тянется облачный конфиг (для клиентов — двусторонне, по правилу «кто позже изменил»);
• если включён облачный Telegram-бот, локальный long-polling выключается.

Режим терминала: «Управление» (полный) или «Kiosk» (если включён режим киоска).

#4. Оборудование: COM-порт и свет (PowerAnt)

Меню → 🔌 COM-порт / Свет. Нужен для управления светом над столами. Без железа большинство функций работает, но реальный свет включаться не будет.

#Подключение

1. В блоке Подключение выберите порт из списка (кнопка 🔄 Обновить обновляет список).
2. Выберите скорость: 9600 (стандарт PowerAnt) / 19200 / 38400 / 115200.
3. Нажмите 🔌 Подключить. Статус станет зелёным: «Подключён · COMx».
4. Диагностика (когда подключено): 🔍 Опросить (??), 📣 Широковещательно (!??), ?= Состояние, Отключить.

#Определитель реле (сопоставление «реле ↔ стол»)

Появляется при подключении. Сетка кнопок A–H — клик включает/выключает свет на конкретном реле (=A вкл / =a выкл). Так вы определяете, какая буква соответствует какому столу в зале, и затем проставляете буквы при настройке столов. Кнопка «Выключить включённые» гасит всё, что включали этим инструментом.

Ниже — лог соединения (последние 200 строк: → отправка, ← приём, ⚠ ошибка) и справочник протокола PowerAnt (??↵ опрос, =A↵/=a↵ вкл/выкл, +=↵ успех).

#5. Настройки (только владелец)

Раздел ⚙️ Настройки разбит по секциям:

• Заведение: название клуба (только чтение — меняется в бекофисе).
• Оформление: тема Ночная (Casino Noir) / Дневная (живой предпросмотр); формат отображения валюты (символ / код / без символа).
• Печать: режим — выкл / TCP/ESC-POS (термопринтер по сети: host + порт 9100) / Системный (выбор принтера из списка ОС). Ширина 58 мм (32 симв.) или 80 мм (48 симв.), автопечать чека. Кнопка «Тестовый чек».
• Фискальная касса (iKassa): включение, облачный режим, host, порт (по умолч. 37015), PIN, имя кассира. Кнопки «Найти кассу» и «Проверить связь».
• Синхронизация: см. раздел 3.
• Рабочие переключатели: режим Kiosk (вступает в силу после перезапуска), буквы реле.
• Лицензия: статус (пробная/платная) и срок; «Запросить продление» (с комментарием) — заявка уходит поставщику.
• Система: версия приложения, разработчик, «Открыть логи».

#6. Пользователи (PIN-доступ)

Управление учётными записями сотрудников терминала.

• Список с аватарами и ролью; у себя — метка «(это вы)».
• Новый/Изменить: имя, роль (Владелец / Администратор / Оператор), PIN 4–6 цифр (при правке пусто = не менять).

Ограничения: админ не может создавать владельцев и не может удалять владельца; себя удалить нельзя. Эти же пользователи редактируются и в бекофисе (раздел Пользователи) и синхронизируются.

#7. Столы и тарифы

#Тарифы (📋 в «Управлении» / страница Тарифы)

• «Создать тариф»: название, цена за час (в валюте клуба), цвет, время действия (HH:MM–HH:MM, пусто = круглосуточно), дни недели (пусто = каждый день), столы (на каких применяется).
• Оба поля времени заполняются вместе или оба пустые.
• В списке расписание читается как «HH:MM–HH:MM · Пн, Вт, Чт» либо «круглосуточно / каждый день».

#Столы

Назначьте каждому столу букву реле (A–H, определённую через «Определитель реле» — см. раздел 4), тип игры и доступные тарифы. Справочник столов и тарифов синхронизируется с бекофисом — там же его можно редактировать.

#8. Штрафы

⚖️ Штрафы. Сумма штрафа = базовая величина × множитель.

• Базовая величина — задаёт владелец/админ (оператор только видит). От неё считаются все штрафы.
• Каталог штрафов: название + множитель (Nх базовой) → авторасчёт суммы. Создание/правка/удаление — владелец/админ.
• Применяется штраф к клиенту со страницы Клиенты (выбор из каталога + комментарий).

#9. Товары / инвентарь (🏓 Остаток)

Каталог управляется в бекофисе (цена, залог, расходник, активность). На терминале видно текущий остаток и его можно править (кнопка «Изменить» → число → ОК). Выдача/возврат инвентаря клиенту происходит в окне оплаты на столе (см. ниже): выбор товара → количество → «Выдать» (плюс залог), позже «Вернуть» (залог возвращается).

#10. Лояльность и клиенты

• Лояльность: уровни (порог суммы → скидка % и начисление бонусов %) и акции (временные скидки/бонусы с расписанием и периодом). Обычно настраивается в бекофисе и синхронизируется.
• Клиенты: поиск по имени/телефону/карте; карточка (имя, телефон, код карты, QR, заметки); персональная скидка (с причиной), корректировка бонусов, начисление штрафа. История по клиенту в 3 вкладках: бонусы, сессии (с экспортом CSV), штрафы.

#11. Ежедневная работа

#Смена (📋 Смена)

• Открыть смену: введите «Внесение в кассу» (остаток налички с прошлой смены) → ▶ Открыть смену. При открытии терминал проверяет связь с облаком.
• В открытой смене видно: номер, время и кто открыл, внесение, и статистику (сессии, выручка, наличные, безнал) + список сессий.
• X-отчёт (промежуточный) — кнопка 🧾 X-отчёт: итоги без закрытия смены, с печатью.
• Закрыть смену: показывается «К изъятию (наличные в кассе)» → введите сумму инкассации → ⏹ Подтвердить закрытие. Если смена открыта >24 ч — предупреждение с быстрым закрытием.

#Игровые столы (🎱)

Сверху — число активных столов, включённого света и текущая выручка.

• ▶ Старт: выбор тарифа (если действует несколько) и длительности. Варианты: пресеты 15/30/45/60/90/120 мин, своё число минут, 💰 По сумме (вводите сумму — система считает время по тарифу), ∞ Открытая игра.
• ▶+ Продлить: +15 / +30 / +60 мин.
• 💳 Оплатить / ⏹ Стоп: окно оплаты — метод (Наличные / Безнал / Сборная), сумма (авторасчёт), лояльность (поиск клиента, скидки/бонусы; персональная скидка требует PIN админа), 🎱 Инвентарь (выдача/возврат), 🖨 Печать чека, ✓ Подтвердить оплату.
  • В поле «Наличными» вводится сумма, которую дал клиент: меньше остатка — принимается как предоплата, больше — программа показывает сдачу, а в чек идёт только остаток. Безналом больше остатка провести нельзя (сдачи с карты не бывает).
  • Перед списанием открывается окно подтверждения оплаты со способом, суммой и сдачей.
  • В окне «Предоплата» сдача считается только для пакета (фиксированная сумма); у открытой игры сумма ещё растёт, поэтому «больше отыгранного» — это оплата вперёд.
• ⚙ Сервис: сервисный режим стола (свет включён, игра заблокирована — для обслуживания).
• Когда время истекло — карточка краснеет, пульсирует и звучит сигнал (повтор каждые 30 с).

#Устройства (🖥)

Всё оборудование зала в одном разделе (принтеры переехали сюда из «Настроек»).

• Принтеры — как раньше: мультипринтер по ролям (чеки, отчёты, бар, кухня, предчек).
• Экран кухни и бара — тумблер и порт локального сервера; тут же адрес, который открывают на планшете.
• Привязанные устройства — «+ Добавить экран»: опишите, что это за устройство и где оно стоит, выберите функцию (Экран кухни или Экран бара) — касса выдаст шестизначный код привязки. Код вводят один раз на самом экране; после этого он получает заказы только своей секции: кухня — позиции из кухонных категорий, бар — из барных. Код можно перевыпустить, экран — выключить или удалить; в списке видно, когда устройство последний раз выходило на связь.

Пока в списке нет ни одного устройства, экраны работают как раньше — без кода. Клубы, где кухонный планшет уже настроен, после обновления ничего не теряют.

#Бронирования (🗓)

Список броней (имя, телефон, стол, время, статус, источник: Терминал/Сайт/Бэкофис/Telegram). Подтвердить / Отмена; «Новая бронь» — стол, имя, телефон, дата, время с/до, тип игры, заметки. Список обновляется каждые 60 с, новые брони показываются всплывающим уведомлением со звуком.

#12. Отчёты и журналы

• 🧾 Продажи: вкладки Чеки (фильтры: номер/период/стол), Выручка (по дням), Методы оплаты, Z-Отчёты (по сменам, с печатью Z-отчёта).
  • Клик по строке чека открывает карточку: если оплату приняли не тем способом, здесь меняется метод оплаты (наличные / безнал / сборная) с комментарием-причиной. Сумма чека не редактируется, правка доступна владельцу и админу и пишется в журнал. Уже пробитый фискальный чек этим не переписывается — касса требует отдельной коррекции.
• 📚 Журнал смен: карточки смен с итогами (всего смен, выручка, нал, безнал).
• 📝 Журнал событий: лог действий. Оператор видит события текущей смены; владелец/админ — последние 500 событий, с кнопкой «Очистить».

#13. Telegram-бот (✈️)

Меню → Telegram. Статус интеграции, имя клуба (для заголовков сообщений), Bot Token (из @BotFather), Chat ID, и переключатели уведомлений (открытие/закрытие смены, изменение тарифа, сервис стола). Кнопки «Отправить тест» и «Проверить» (валидирует токен и тянет имя бота).

Уведомление «сервис стола» уходит, когда стол ставят в сервисный режим или на тех. работы (и когда снимают): стол, сотрудник, время. Событие пишется и в журнал (тип «Сервис»).

При активном облачном синке ботом управляет облако (вебхук); команды бота настраиваются на стороне бэкенда. Уведомления (включая сервис столов) в этом режиме отправляет облако, а переключатели живут в бекофисе — Интеграции → Телеграм-бот.

#14. Печать чеков

В Настройки → Печать выберите режим (TCP/ESC-POS или системный), ширину (58/80 мм) и при желании автопечать на подтверждении оплаты. Кнопка «Тестовый чек» проверяет печать. Чек содержит шапку (логотип, название клуба, УНП, номер чека, дату, оператора), тело (стол, тариф, время, метод оплаты, скидка) и итог. X-отчёт печатается со страницы Смена, Z-отчёт — из раздела Продажи.

#15. Лицензия и продление

Статус и срок лицензии — в Настройки → Лицензия. Предупреждения:

• за ≤14 дней — баннер «Лицензия истекает через N дн.»;
• за ≤3 дней — окно при запуске;
• по истечении — красный баннер «Доступ ограничен: срок лицензии истёк» + контакты поддержки, ключевые действия (открыть смену, старт игры) блокируются.

Продление: Настройки → Лицензия → «Запросить продление» (можно с комментарием) — заявка уходит поставщику, который одобряет её в бекофисе (раздел Лицензии).

#16. Режим киоска (Kiosk)

Включается в Настройки → Рабочие переключатели → Kiosk (вступает в силу после перезапуска). Экран блокируется поверх; для разблокировки — клик и ввод PIN администратора. Удобно для точек самообслуживания, чтобы клиенты не лезли в управление.

#Чек-лист настройки нового терминала

1. Активировать терминал (ключ или регистрация нового клуба) — раздел 2.
2. Включить и проверить облачный синк — раздел 3.
3. Подключить COM-порт / PowerAnt, определить реле — раздел 4.
4. Настроить печать и (при наличии) фискальную кассу — разделы 5 и 14.
5. Сменить заводские PIN и завести сотрудников — раздел 6.
6. Завести столы (буквы реле) и тарифы (расписание) — раздел 7.
7. Настроить штрафы, лояльность, проверить остаток товаров — разделы 8–10.
8. (Опц.) Подключить Telegram-бот — раздел 13.
9. Открыть тестовую смену, запустить/оплатить стол, напечатать чек — проверить связку целиком.

Бекофис 8Ball — руководство владельца клуба

Бекофис — это облачная веб-админка для владельца клуба: дашборды, отчёты, CRM, лояльность и настройка справочников (тарифы, столы, товары). Терминал в клубе работает локально и синхронизируется с этим же облаком, поэтому изменения, сделанные здесь, прилетают на терминал, а продажи/смены с терминала — сюда.

• Адрес: https://billiard-backoffice.vercel.app
• Открывается в браузере (Chrome / Edge / Safari) на любом устройстве — компьютере, планшете, телефоне.
• Язык интерфейса: русский. Валюта по умолчанию — BYN.

Что делает поставщик (супер-администратор), а что — владелец, разведено намеренно. Регистрация клуба, выпуск лицензий и токенов терминалов — зона поставщика (см. раздел «Для поставщика» в конце). Всё остальное в этом документе — для вас, владельца.

#1. Вход

1. Откройте https://billiard-backoffice.vercel.app.
2. На экране «8Ball Бекофис — Вход для сотрудников клуба» введите email и пароль, которые вам выдал поставщик при подключении клуба.
3. Нажмите Войти.

Если данные неверны — увидите «Неверный email или пароль». Сессия сохраняется в браузере; кнопка выхода — справа вверху рядом с вашим именем.

#Роли в бекофисе

Вы всегда работаете в контексте своего клуба — переключателя клубов у владельца нет (он есть только у поставщика).

#Лицензия — что вы видите

Сверху может появляться баннер о состоянии лицензии:

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

Продление лицензии запрашивается с терминала (Настройки → Лицензия → «Запросить продление») и одобряется поставщиком. Контакты поддержки показываются прямо в баннере.

#2. Что где в меню

Меню слева разбито на два блока:

Основное (день-в-день):

• Дашборд — продажи за сегодня (по часам и столам) и сводка за текущий месяц.
• Аналитика — когда и где клуб зарабатывает: часы, дни недели, тепловая карта, столы.
• Отчёты — отчёт за период и детализация смены (X/Z).
• Финансы — счета на оплату от поставщика.
• Бронирования — заявки на брони столов.
• SMS — сколько сообщений ушло, рассылки клиентам, проверка шлюза.
• Смены — список и детализация смен.
• Журнал — лог событий (аудит).

Конфигурация (справочники, меняются редко):

• Тарифы, Столы, Лояльность, Клиенты, Остаток (товары/инвентарь), Пользователи (PIN-доступ к терминалу), Настройки, Telegram.

#3. Дашборд

Открывается первым. Три блока сверху вниз:

Сегодня. Выручка с начала суток, число чеков, средний чек, нал/безнал и часы игры. Под выручкой и чеками — сравнение со вчерашним днём на это же время (не с целыми вчерашними сутками: в полдень сравнивать текущие полдня с чужим полным днём бессмысленно). Ниже — график продаж по часам и таблица по столам: сколько чеков, выручки и часов игры принёс каждый стол сегодня.

Текущий месяц (с 1-го числа до сейчас): выручка, наличные, безнал, число сессий, скидки, потраченные бонусы.

Программа лояльности — сколько клиентов и на какую сумму накоплено бонусов (это ваш «долг» перед клиентами).

Ссылка «Подробная аналитика →» ведёт в раздел Аналитика, где тот же разрез строится за любой период.

#3а. Аналитика продаж

Раздел отвечает не на вопрос «сколько заработали» (это Отчёты), а на вопрос когда и на каких столах. По нему видно, какие вечера действительно пиковые, какие часы зал работает впустую и какой стол простаивает.

#Выбор периода

Верхний ряд кнопок — длительность: День, 2 дня, Неделя, Месяц, Квартал, Год, Свой период. Второй ряд — какой именно: текущий или предыдущий (для дня — «Сегодня» / «Вчера»). Неделя считается с понедельника, месяц/квартал/год — календарные. «Свой период» открывает поля дат (конец дня включительно).

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

#Итоги периода

Выручка, чеки, средний чек, выручка за день, нал/безнал, часы игры, доля бара и кухни, скидки с бонусами, возвраты и нетто-выручка. Под выручкой и числом чеков — дельта к предыдущему окну той же длины: текущая неделя сравнивается с прошлой, август — с июлем. Зелёная стрелка вверх, красная вниз; «—» значит, что в прошлом окне продаж не было.

#Пики периода

Три карточки: лучший день, лучший день недели и пиковый час — с суммой и числом чеков. Это ответ в одну строку на вопрос «когда у нас пик».

#Графики

• Выручка по дням — столбик на каждый день периода; дни без продаж остаются пустыми слотами, чтобы провал был виден. Пиковый день подсвечен золотом.
• Продажи по часам суток и по дням недели — с переключателем метрики: Выручка / Чеки / Занятость.
• Тепловая карта «день недели × час» — 7 строк на 24 колонки. Чем ярче ячейка, тем больше выручка в этот час этого дня недели. Пустая ячейка — продаж не было.

Наведите курсор на любой столбец или ячейку — во всплывающей подсказке точные цифры.

Как считается время. Чек относится к тому часу и дню, когда открыли стол, а не когда рассчитали гостя: пик продаж — это время, когда приходят люди. Поэтому игра с 22:30 до 01:15 попадёт выручкой в час 22. А вот занятость размазана по реальным часам игры — та же игра даст 30 минут часу 22, по 60 часам 23 и 00 и 15 минут часу 01. Часы и дни нарезаются по часовому поясу клуба (Настройки → смещение времени).

#По столам

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

#Разбивки

По тарифам, по типам игр, по операторам, по способам оплаты и топ позиций бара и кухни (сколько штук продано и на какую сумму).

#4. Отчёты

#Отчёт за период

1. Выберите даты с и по (конец дня включительно).
2. Нажмите построить.

Получите:

• сводку (выручка, наличные, безнал, сессии, скидки, бонусы);
• разбивку по тарифам, по столам, по операторам (количество, сумма, доля %);
• столбчатый график по дням.

#Детализация смены (X/Z-отчёт)

Введите номер/идентификатор смены — получите карточку смены: когда открыта/закрыта, кто открыл/закрыл, сумма внесения и инкассации, итоги (выручка, нал, безнал, сессии, скидки, бонусы), список сессий и разбивку по тарифам и столам. То же доступно по клику в разделе Смены.

#5. Смены

Список закрытых и открытых смен за выбранный период: номер, время открытия/закрытия, оператор, выручка, инкассация, нал/безнал. Клик по строке раскрывает полную карточку смены (см. X/Z выше). Открытая смена помечена статусом «Открыта» (это X-отчёт), закрытая — «Закрыта» (Z-отчёт).

#6. Финансы (счета)

Здесь видны счета на оплату, которые выставляет поставщик (например, за лицензию/обслуживание): номер счёта, назначение, сумма к оплате, статус (оплачен/ожидает), номер платёжки, дата и сумма платежа, прикреплённый акт (PDF).

Для владельца это раздел для просмотра: создание счетов, ввод оплат и загрузка актов — на стороне поставщика. Зелёным помечены оплаченные счета, жёлтым — ожидающие оплаты.

Email для счетов — на этот адрес приходят копии PDF-счетов. Если не указан, счёт можно скачать только в бекофисе.

«Выставлять счёт на месяц автоматически» (включено по умолчанию) — за 10 дней до окончания подписки счёт на 1 месяц формируется сам по ставке вашего клуба и уходит:

• файлом (PDF) в Telegram-чат клуба,
• письмом на «Email для счетов».

Если предыдущий счёт ещё не оплачен, новый не выставляется — в напоминании придёт номер неоплаченного. Тумблер выключает только авто-выставление; сами напоминания об окончании подписки приходят всегда (см. «Telegram-бот»).

#7. Бронирования

Заявки на брони столов из всех источников (сайт, Telegram, бекофис, терминал).

• Фильтры: период (по умолчанию сегодня … +14 дней) и статус (все / ожидает / подтверждена / активна / завершена / отменена / неявка).
• Таблица: время, имя клиента, телефон, стол, тип игры, статус, источник.
• Действия по заявке:
  • Подтвердить (для «ожидает») → статус «подтверждена»;
  • Неявка / Отмена (для ожидающих/подтверждённых);
  • Удалить (корзина).

#Создать бронь вручную

Кнопка «Новая бронь» → форма:

• имя клиента (обязательно), телефон (обязательно, минимум 5 цифр);
• тип игры: любой / русский / пул;
• стол: автоподбор или выбрать вручную;
• начало (дата и время) и длительность (60 / 90 / 120 / 180 / 240 мин).

#7а. SMS

Раздел показывает, сколько сообщений клуб отправил, за что именно и во сколько это обходится. Считаются все SMS: коды подтверждения на сайте брони, сообщения «бронь подтверждена», ваши рекламные рассылки и проверки шлюза.

#Чем считается расход

Оператор берёт деньги не за сообщение, а за сегмент. Кириллицей в один сегмент помещается 70 символов; если текст длиннее — он режется на части по 67 символов, и каждая часть оплачивается отдельно. Поэтому текст на 150 символов стоит втрое дороже текста на 60.

В бесплатный порог и в счёт идёт всё, что ушло в шлюз, включая сообщения, которые шлюз отклонил. Не считаются: отправки в тестовом режиме, некорректные номера и сообщения, не ушедшие из-за сбоя на нашей стороне.

#Вкладка «Сводка»

• Итоги за период: всего сообщений, успешно, неуспешно, сегментов.
• По видам сообщений — за что уходит расход. Коды и подтверждения брони вы не контролируете, а рассылки — ваш выбор; разбивка показывает соотношение.
• По дням — динамика с полоской нагрузки.
• Расход и бесплатный порог — по месяцам: сколько сегментов израсходовано, сколько включено в тариф, что сверх порога и на какую сумму. Месяц с превышением помечается «к выставлению» и попадает в ближайший счёт одной строкой с указанием периода и количества. Уже выставленный месяц помечается «в счёте» и повторно не выставляется.

#Вкладка «Журнал отправок»

Каждая попытка: когда, на какой номер, какого вида, текст, сколько сегментов и чем закончилось. При отказе показывается ответ шлюза — именно его нужно показывать поддержке провайдера. Текст кода подтверждения в журнале не хранится (в колонке «Текст» стоит «код не сохраняется») — код не должен быть виден администраторам.

#Вкладка «Рассылки»

Массовая отправка по вашей базе клиентов — акции, новости, приглашения.

1. «Новая рассылка» → название (клиентам не отправляется) и текст.
2. Можно сузить аудиторию: по уровню лояльности и по тому, играл ли клиент за последние N дней.
3. Кнопка «Рассчитать» покажет до отправки: сколько получателей, сколько сегментов, сколько осталось от бесплатного порога и сколько придётся доплатить. Там же — точный текст, который получит клиент.
4. Только после расчёта появляется кнопка отправки.

Что важно знать:

• Клиенты без телефона и номера из стоп-листа в рассылку не попадают.
• Если один и тот же номер заведён в нескольких карточках, сообщение уйдёт один раз — и оплачено будет один раз.
• Если в тексте нет упоминания отписки, к нему автоматически добавляется строка «Отказ от рассылок — у администратора клуба». Напишете свою формулировку — она останется как есть.
• У одной рассылки есть потолок получателей; он задаётся поставщиком.
• Идущую рассылку можно отменить — отправка остановится на ближайшей пачке; уже отправленные сообщения вернуть нельзя.
• Одновременно идёт только одна рассылка.

#Стоп-лист рассылок

Номера, которым рассылки не уходят. Добавляйте сюда всех, кто попросил не писать. Коды подтверждения и подтверждения брони таким клиентам по-прежнему приходят — это ответ на их собственное действие, а не реклама.

Входящие SMS система не принимает, поэтому отписку заводит сотрудник вручную.

#Вкладка «Проверка шлюза»

Отправка проверочного сообщения на свой номер. Показывает, откуда взяты логин и пароль, кто указан отправителем, и что именно ответил шлюз. Между проверками — пауза 30 секунд.

Если написано «включён тестовый режим», сообщения не отправляются никому: код только пишется в лог сервера. Это состояние легко не заметить, поэтому оно выводится отдельным предупреждением.

#8. Журнал событий

Аудит-лог: время, тип события, сообщение, сотрудник. Фильтры — период (по умолчанию 7 дней) и тип (все / смена / синхронизация / тариф / товары / клиент). Удобно, чтобы посмотреть «кто что менял».

#9. Тарифы

Цена за час и расписание действия тарифа. Эти тарифы синхронизируются на терминал и применяются при старте игры.

• Список: название (с цветовой меткой), цена/час, временное окно, дни недели.
• «Новый тариф» / иконки правки и удаления.

#Форма тарифа

• Название (обязательно), цена за час, цвет.
• Расписание (галочка): включите, чтобы ограничить тариф по времени (с HH:MM до HH:MM) и дням недели; без галочки тариф действует круглосуточно и всю неделю.

Какие тарифы доступны на конкретном столе — задаётся на странице Столы.

#10. Столы

Игровые столы клуба и их привязка к реле PowerAnt (управление светом над столом).

• Список: название, буква реле (A–H), тип игры, позиция, тариф по умолчанию.
• «Новый стол» / правка / удаление.

#Форма стола

• Название (обязательно).
• Реле — буква из доступных (по умолчанию A–H); если буква уже занята, показывается, за каким столом она закреплена.
• Позиция — порядок в зале (необязательно).
• Тип игры — универсальный / русский / пул.
• Тариф по умолчанию (необязательно).
• Разрешённые тарифы — какие тарифы можно выбрать на этом столе (множественный выбор).

Чтобы точно сопоставить «буква реле ↔ конкретный стол», используйте «Определитель реле» на терминале (страница COM-порт / Свет): он по очереди включает свет на столах.

#11. Лояльность

Три вкладки: Уровни, Акции, Купоны.

#Уровни

Накопительные уровни клиента: название, порог (сумма потраченного, чтобы достичь уровня), скидка %, начисление бонусов %, цвет, порядок. Клиент автоматически поднимается по уровням по мере роста суммы покупок.

#Акции (промо)

Временные скидки/повышенные бонусы:

• скидка % и бонус %;
• расписание (с HH:MM до HH:MM, дни недели — необязательно);
• период действия (с даты по дату — необязательно, пусто = бессрочно);
• переключатель «Промо включено»;
• «Ограничить количество применений» — от 1 до 10 000 000. Каждое применение скидки в окне оплаты уменьшает остаток; когда лимит исчерпан, акция перестаёт предлагаться кассиру (и её бонусный % больше не начисляется). Без галочки — без ограничения. Колонка «Применений» в списке показывает «использовано / лимит». Счётчик ведёт терминал: в бэкофисе он появится после ближайшей синхронизации.

#Купоны

Разовые коды на скидку % или бесплатное время. Кроме кода, значения, срока и заметки задаётся количество применений (1 — одноразовый, как раньше; до 10 000 000 — купон принимается, пока не исчерпан). Колонка «Применений» показывает «использовано / лимит»; статус «Использован» появляется, когда применения закончились. Погашения приезжают с терминала синхронизацией.

#12. Клиенты (CRM)

• Поиск по имени / телефону / коду карты.
• Список: имя, телефон, уровень лояльности, персональная скидка %, баланс бонусов.
• «Новый клиент» и по каждой строке — корректировка бонусов, штрафы, правка, удаление.

#Карточка клиента

Имя (обязательно), телефон, уровень лояльности, код карты, QR-код, персональная скидка % с комментарием-причиной, заметки.

#Корректировка бонусов

Кнопка корректировки → введите сумму (положительная — начислить, отрицательная — списать) и комментарий. История изменений сохраняется.

#Штрафы клиента

Просмотр начисленных штрафов (синхронизируются с терминала): дата, название, комментарий, сумма и итог «Штрафов: N на сумму M».

#13. Остаток (товары/инвентарь)

Каталог товаров и инвентаря, который выдаётся/продаётся на терминале (кии, мячи, напитки, и т.п.).

• Список: название (метка «расходник», если применимо), цена, залог, остаток, активность.
• «Новый товар» / правка / удаление.

#Форма товара

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

#Отчёт по продажам товаров

Выберите период → итоги (выручка, количество), разбивка по товарам и по типу операции (выдача / возврат / расход / корректировка).

#14. Пользователи (PIN-доступ к терминалу)

Сотрудники, которые входят на терминале по PIN-коду.

• Список: имя, роль (Владелец / Администратор / Оператор).
• «Новый пользователь» / правка / удаление.

#Форма пользователя

• Имя (обязательно), роль, PIN — 4–8 цифр (при правке оставьте пустым, чтобы не менять).

Роли на терминале:

• Владелец — полный доступ, включая Настройки.
• Администратор — справочники, продажи, история, COM-порт; без раздела Настройки.
• Оператор — только запуск/остановка игр и текущая смена.

#15. Настройки

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

• Карточка клиента (реквизиты): тип субъекта (ЮЛ / ИП / физлицо), контакты, юр.название и форма, УНП, банковские реквизиты, подписант, юридический и почтовый адреса, страна/город/сайт, код валюты, время окончания смены, формат отображения валюты (символ / код / без символа).
• Реле PowerAnt: список букв реле через пробел (по умолчанию A–H для 8 столов).
• Бронирования: приём онлайн-броней, название клуба, slug (адрес публичной страницы броней), описание, URL логотипа, шаг слота, мин/макс длительность брони, смещение от UTC, параметры SMS (отправитель, логин, пароль).
  • Часы работы задаются по дням недели: строка на каждый день, галочка «работаем / выходной» и два поля времени. Кнопка «Как в понедельник — всю неделю» копирует расписание на все дни. Закрытие в 00:00 означает полночь (конец суток); работу после полуночи (например, до 02:00) задать пока нельзя — форма не даст сохранить. Выходной день закрывает онлайн-брони на эту дату.
• Прочие параметры: редактор «ключ-значение» для нетиповых настроек.

#15а. Устройства

Экраны кухни и бара клуба. Заводятся и здесь, и на кассе — список общий (синхронизация двусторонняя). У каждого устройства: описание («что и где»), функция (Экран кухни / Экран бара), код привязки и отметка, когда экран последний раз был на связи.

Экран подключают так: на планшете открывают адрес кассы (он показан в разделе «Устройства» терминала) и вводят код. Кнопка «Новый код» перевыпускает его — старый перестаёт работать, экран нужно привязать заново. Выключенный экран заказы не получает.

#16. Telegram-бот

Уведомления и бот лояльности для клуба.

• Токен бота (из @BotFather) и Chat ID (для группы — отрицательный).
• Уведомления: открытие смены, закрытие смены, изменение тарифа, новые брони, постановка стола в сервис / на тех. работы.
• «Зарегистрировать вебхук» — привязывает бота к облаку (после добавления новых команд бота регистрацию нужно повторить).

При активной облачной синхронизации ботом управляет облако (вебхук), а локальный long-polling на терминале выключается.

#Сервис столов

Когда оператор ставит стол в сервисный режим или на тех. работы (и когда снимает), в чат уходит сообщение: что за стол, кто переключил и когда. Событие приезжает с терминала синхронизацией — обычно в пределах минуты. Тумблер «Уведомлять о постановке стола в сервис / тех. работы» выключает эти сообщения; сама запись в журнале (тип «Сервис столов») остаётся.

#Окончание подписки

За 10 и 5 дней до окончания подписки, а также в день отключения в чат приходит напоминание: до какого числа оплачено и что в 23:59 дня истечения доступ к терминалу будет заблокирован. Эти сообщения не отключаются — иначе блокировка стала бы неожиданной.

К первому напоминанию (за 10 дней) прикладывается автоматически выставленный счёт на месяц — если это включено в разделе Финансы и поставщик задал ставку клуба.

#Для поставщика (супер-администратор)

Эти разделы видит только супер-администратор платформы (не владелец клуба). Сюда же относится переключатель клубов справа вверху.

#Роли сотрудников Help: «Поддержка» и «Менеджер»

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

Заводятся такие сотрудники не руками в бекофисе, а каналом интеграции с Help — раздел «Сотрудники БО» их не создаёт.

Ограничение. «Менеджеру» бэкенд не отдаёт список клубов (доступ есть только к v1/finance), поэтому переключатель в шапке для него просит ввести идентификатор клуба вручную — взять его пока негде, кроме бекофиса супер-администратора. Чтобы «Менеджер» мог выбирать клуб из списка, нужно разрешить ему чтение списка клубов на бэкенде.

#Клубы

• Список всех клубов, правка, мягкое удаление (клуб исчезает из списков, данные не стираются).
• «Новый клуб» — быстрая форма (название + часовой пояс) или мастер из 2 шагов:
  1. Клуб и каталог: название, slug (латиница), часовой пояс, онлайн-брони, описание, логотип.
  2. Реквизиты: организация, страна/город, юр.адрес, УНП, валюта, сайт, email, телефон, время окончания смены, формат валюты.
• Внутри клуба:
  • Терминалы — «Выпустить токен» (имя терминала → одноразовый токен, показывается один раз; его вставляют в Настройки терминала) и отзыв токена;
  • Сотрудники — добавление логинов бекофиса (email, пароль ≥6, имя, роль owner/admin/viewer).

#Лицензии

• Заявки на продление от терминалов — «Одобрить» с новой датой окончания.
• Ключи лицензий по клубу — «Выпустить ключ» с датой окончания (по умолчанию +1 год).
• Активные терминалы — ближайшая дата окончания лицензии и статус продления.

Напоминания клубам об окончании подписки бэкенд рассылает сам: раз в час обходит клубы и в интервале 10:00–12:00 по времени клуба шлёт сообщение за 10 / 5 / 0 дней до блокировки (в день отключения окно шире — 08:00–22:00, чтобы последнее предупреждение точно ушло до 23:59). К первому сработавшему напоминанию прикладывается авто-счёт. Одна веха на один срок лицензии отправляется ровно один раз — после продления отсчёт начинается заново для нового срока.

Проверить/догнать вручную (только super_admin):

POST /v1/license/expiry-notify/run
{ "clubId": "<uuid>", "milestone": 10, "force": true }   # прислать сообщение сейчас
{ "dryRun": true }                                        # сухой прогон по всем клубам

force обходит окно по времени клуба, dryRun ничего не отправляет и не пишет в БД. Защита от повторов сохраняется: если веха для этого срока уже отправлена, запрос её не продублирует.

#SMS: обзор и прейскурант

В разделе SMS супер-администратору доступны две дополнительные вкладки.

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

«Тарификация» — два уровня настроек:

• Общий прейскурант — бесплатный порог сегментов в месяц, цена сегмента сверх порога и потолок получателей одной рассылки. Действует для всех клубов без индивидуальных значений.
• Индивидуально для клуба (клуб выбирается переключателем вверху) — те же три поля плюс тумблер «Разрешить рассылки». Пустое поле означает «по общему прейскуранту», заполненное перекрывает его. Тумблер — рубильник на случай жалоб на спам: он гасит только массовые рассылки, коды подтверждения и подтверждения брони продолжают уходить.

Как превышение попадает в счёт: при генерации счёта клубу (вручную или авто-счётом к окончанию подписки) бэкенд добирает завершённые календарные месяцы с превышением, за которые ещё не выставлял, и добавляет по строке на каждый месяц. Текущий месяц не берётся — он не закончился. Глубина добора — 3 месяца назад, чтобы после долгого перерыва в счёт не прилетело начисление за полгода. Повторное выставление невозможно: на пару (клуб, месяц) стоит уникальный ключ.

Порог считается по календарному месяцу в поясе UTC+3 — одинаково для всех клубов, иначе сводка по платформе не сходилась бы с суммой строк по заведениям.

#Подключение нового клуба «под ключ»

Автоматизировано скриптом — см. docs/backoffice-onboarding.md: один запуск создаёт клуб, owner-логин, device-токен терминала и (опц.) настраивает Telegram-бота.

#Частые вопросы

• Изменил тариф/товар в бекофисе — почему не видно на терминале? Изменения приезжают при ближайшей синхронизации терминала. Убедитесь, что на терминале включён облачный синк и он активен.
• Продажи с терминала не видно в отчётах? Терминал заливает смены/сессии в облако при синке; проверьте связь на терминале (Настройки → Облачный синк → «Проверить»).
• Истекает лицензия. Продление запрашивается с терминала и одобряется поставщиком; следите за баннером и за разделом Финансы.
• Сбросить пароль входа в бекофис — обратитесь к поставщику (управление логинами — на его стороне).