Telegram-бот: алёрты оператору, самопроверка трафика клиентом и бэкап БД

[Postlog]

Категория: feature · Приоритет: high · Размер: XL · Ранг: 3/10

Что построить

Секция «Telegram-бот» в настройках (env: токен бота, список admin chat IDs); опциональное поле «Telegram ID» в форме пользователя; бот шлёт оператору алёрты (истекающие/исчерпанные клиенты, ошибки провижининга), отвечает клиенту на /usage его остатком трафика/срока и по команде /backup шлёт дамп db/ файлом.

Паритет с конкурентами

3x-ui (бот: алёрты логина/CPU/исчерпания, /usage по email, бэкап БД документом), Hiddify (бот: создание юзеров, статус, рассылка), Marzban/Marzneshin (Telegram-интеграции). Бот — стандартная фича у всех.

Чего не хватает сейчас (код)

В subgen нет никакой Telegram-интеграции (ни в config.go, ни в сервисах, ни в cmd/). Нет воркера-демона помимо HTTP-сервера, нет диспетчера команд, нет экспортёра бэкапа SQLite. У пользователя нет поля Telegram ID (add_client.go шлёт tgId:0).

Зачем

Операторы ведут headless VPN-бизнес с телефона: алёрты, проверки и бэкапы без открытия панели; клиенты сами проверяют квоту, не дёргая поддержку. Net-new поверхность и одна из самых востребованных фич у целевой аудитории. Пара к бэкапу из #84.

Предлагаемая реализация

Горутина-воркер в cmd/service (или cmd/bot): long-poll Telegram Bot API через тонкий клиент internal/clients/telegram (один метод — один файл: SendMessage, SendDocument, GetUpdates; HTTP мокается). Конфиг SUBGEN_TG_BOT_TOKEN + SUBGEN_TG_ADMIN_IDS в config.go (только статика, прокидывается полями в main). Диспетчер команд + алёрты в internal/service/notify. ClientSpec.TgID для привязки клиента. Бэкап — стрим файла db/ как Telegram document. Бот — отдельный связный демон, не трогает ogen-сервер.

Затронутые файлы

• internal/clients/telegram/ (send_message.go, send_document.go, get_updates.go, client.go, contract.go) + тесты
• internal/service/notify/ (новый) + contract.go
• internal/config/{config.go,load.go}, cmd/service/main.go (или cmd/bot/main.go)
• internal/entity/panel.go (ClientSpec.TgID), internal/entity/user.go, migrations/NNNN-user-tgid.sql
• internal/handlers/web/static/ (поле Telegram ID)

---

_{Продуктовый ресёрч: изучены аналоги (Marzban/Marzneshin, 3x-ui, Remnawave, Hiddify, sub-store + клиентские стандарты импорта). Паритет и subgen-gap код-обоснованы. Ранг = продуктовый приоритет.}

[Postlog]

Issue #105 — Telegram-бот: алёрты оператору, самопроверка трафика клиентом и бэкап БД

🛠 План реализации

Резюме

Добавляем самостоятельный Telegram-демон: тонкий клиент internal/clients/telegram (long-poll + send), сервис internal/service/notify (диспетчер команд /usage,/backup + алёрты оператору), опциональный tgId у пользователя (прокидывается в провижининг 3x-ui и используется для резолва клиента в /usage), бэкап SQLite-файла документом. Бот — отдельный связный воркер в композиционном корне, ogen-сервер не трогает.

Контекст из кода (сверено с репозиторием)

• Telegram-интеграции нет нигде: ни в internal/config, ни в сервисах, ни в cmd/. В go.mod нет telegram-зависимостей. cmd/ содержит только service и subctl.
• Поле tgId в 3x-ui уже шлётся, но захардкожено нулём: internal/clients/xui/add_client.go:23 ("tgId": 0). 3x-ui требует tgId именно int (см. AGENTS.md, иначе 400).
• entity.ClientSpec (internal/entity/panel.go:58-64) — это то, что провижининг передаёт в AddClient; поля TgID там нет.
• Трафик/срок по подписчику уже агрегируются: fleet.Service.Fleet() → entity.Fleet.Sub(subID) → entity.Subscriber{Up,Down,Total,Expiry} (internal/service/fleet/build.go:73-82, internal/entity/fleet.go:36-44). Total=0 — безлимит, Expiry — ms epoch (0 = бессрочно). Это готовый источник для /usage — переиспользуем, ничего нового считать не надо.
• Резолв подписчика по пользователю: users.Repository уже умеет IDBySubID и Get (с SubID). Для /usage по Telegram-ID нужен обратный резолв tgId → user (sub_id) — новый репозиторный метод.
• Слой пользователя, куда добавляется tgId: entity.User, entity.UserCreateParams/UserEditParams (internal/entity/user.go), все SELECT-ы users (get.go, list_page.go, list.go — колонки перечислены явно), Create (create.go:23), сервис provisioning (CreateUser/EditUser строят entity.User и ClientSpec), хендлеры user_create/user_edit + их OpenAPI, фронт uForm (app.js:26,401,403,408).
• Бэкап: единственный bind-mount — это db/ (gitignored). Issue ссылается на пару-issue Периодический бэкап/restore SQLite-стора (единственный bind-mount — единственная копия) #84 (периодический backup/restore SQLite, OPEN) — там основная логика бэкапа; здесь /backup — лишь Telegram-триггер ручного дампа.
• Миграции — forward-only раннер, новый файл NNNN-*.sql (см. migrations/0002-users-description.sql как эталон ALTER).
• Деплой — Docker single-container (docker compose up -d), не systemd. Это влияет на выбор «горутина в cmd/service» vs «отдельный cmd/bot».

Решение по архитектуре (дефолт, если не указано иное в открытых вопросах)

• Бот — горутина-воркер внутри cmd/service, а не отдельный cmd/bot-бинарь. Причина: Docker-деплой одноконтейнерный (docker compose up -d один сервис), отдельный бинарь = второй контейнер/процесс-менеджер, чего инфраструктура сейчас не предполагает; бот и сервис делят один SQLite и один конфиг. Воркер стартует только если задан SUBGEN_TG_BOT_TOKEN (иначе тихо не запускается — фича опциональна). Запускается в run() рядом с mirror.Run(ctx) (cmd/service/main.go:113), завязан на тот же ctx для graceful-shutdown.
• notify — единственный потребитель telegram-клиента; клиент остаётся тупым адаптером (ноль бизнес-логики, ноль состояния кроме http.Client). Токен/admin-ids — аргументы методов/полей сервиса, не состояние клиента (по правилу «креды — параметром»).

---

Пошаговый план (снизу вверх)

1. Зависимость

• Решить: сырой HTTP-клиент Bot API своими руками (предпочтительно — соответствует правилу «тонкий клиент, один метод — один файл, HTTP мокается») vs внешняя либа (go-telegram-bot-api). Дефолт — свой клиент: нужны лишь 3 метода (getUpdates, sendMessage, sendDocument), внешняя либа притащит лишний API-surface и усложнит мок. Если выбираем свой — новых зависимостей в go.mod нет.

2. entity

• internal/entity/user.go:
  • User: добавить TgID *int64 (опционально; nil = не привязан). Тип *int64 — Telegram chat/user id это int64, nullable как Description.
  • UserCreateParams / UserEditParams: добавить TgID *int64.
• internal/entity/panel.go:
  • ClientSpec: добавить TgID int64 (3x-ui хочет int, 0 = не задан). Провижининг проставит 0, если User.TgID == nil.
• internal/entity/telegram.go (новый, по желанию): доменные типы для бота, без I/O — TgUpdate{UpdateID int64; ChatID int64; FromID int64; Text string}, TgMessage, TgDocument{Filename string; Data []byte}. Это выход telegram-клиента (DTO→domain маппинг, как у xui). Альтернатива — держать эти типы прямо в пакете telegram, но entity-вариант ровнее ложится на конвенцию.
• internal/entity/errors.go: при необходимости sentinel ErrUserNotFoundByTgID (если резолв tgId→user отдаёт not-found как доменную, а не sql.ErrNoRows). На усмотрение — /usage неизвестному tgId это пользовательский кейс, не ошибка; см. edge-cases.

3. Миграция БД

• Новый файл migrations/0004-users-tgid.sql:

  -- 0004: optional Telegram user/chat id binding (NULL = unbound). Lets the bot map an
  -- incoming /usage to a subscriber and 3x-ui carry tgId on the client.
  ALTER TABLE users ADD COLUMN tg_id INTEGER;

  Без UNIQUE: один Telegram-аккаунт теоретически может вести несколько ников; при /usage берём первого совпавшего или агрегируем (см. edge-cases). Если решаем «один tgId — один юзер», добавить CREATE UNIQUE INDEX ... WHERE tg_id IS NOT NULL (partial, NULL не конфликтуют) — открытый вопрос.

4. repository/users (один метод — один файл)

• Дополнить все SELECT-列ы tg_id: get.go:15, list_page.go (4 константных запроса + scan на стр. 31/35/39/43/69), list.go. Scan в *int64 (NULL → nil, как description).
• create.go:23: добавить tg_id в INSERT (u.TgID).
• Новый set_tg_id.go: SetTgID(ctx, userID int64, tgID *int64) error — по образцу set_description.go (используется в EditUser).
• Новый by_tg_id.go: ByTgID(ctx, tgID int64) (*entity.User, error) — SELECT ... WHERE tg_id=? + loadConnections; возвращает sql.ErrNoRows, если нет. Нужен боту для /usage. (Альтернатива — резолвить только sub_id: SubIDByTgID — достаточно, чтобы дёрнуть fleet.Sub. Предпочесть узкий SubIDByTgID(ctx, tgID) (string, error), т.к. боту нужен лишь sub_id для трафика — меньше лишнего.)

5. clients/telegram (тонкий адаптер; один метод — один файл; HTTP мокается)

Новый пакет internal/clients/telegram/:

• client.go: Client{hc *http.Client} + New() (по образцу xui/client.go); приватный do/postJSON к https://api.telegram.org/bot<token>/<method>. Токен — аргумент метода, не поле клиента (правило «креды на вызове»). Базовый URL — константа (или поле для тестового override через httptest).
• get_updates.go: GetUpdates(ctx, token string, offset int64, timeout int) ([]entity.TgUpdate, error) — long-poll (timeout секунд). Приватные wire-DTO (update/message/chat/from) → маппинг в entity.TgUpdate.
• send_message.go: SendMessage(ctx, token string, chatID int64, text string) error.
• send_document.go: SendDocument(ctx, token string, chatID int64, doc entity.TgDocument) error — multipart/form-data (поле document + chat_id); это единственный не-JSON путь.
• На каждый .go — *_test.go с httptest.Server/RoundTripper-моком, без живой сети (как add_client_test.go).
• Никакой бизнес-логики: клиент не знает про admin-ids, не парсит команды, не формулирует тексты.

6. service/notify (бизнес-логика бота)

Новый пакет internal/service/notify/:

• contract.go + mockgen: интерфейсы зависимостей —
  • tgClient: GetUpdates/SendMessage/SendDocument (узкий subset telegram-клиента).
  • usersReader: SubIDByTgID(ctx, tgID) (string, error) (или ByTgID).
  • fleetReader: Fleet(ctx) (*entity.Fleet, error) (как в users_get/contract.go).
  • backupSource: способ получить дамп БД — узкий контракт (Snapshot(ctx) (entity.TgDocument, error) или io.ReadCloser). Реализация бэкапа — из Периодический бэкап/restore SQLite-стора (единственный bind-mount — единственная копия) #84; здесь — потребитель. Если Периодический бэкап/restore SQLite-стора (единственный bind-mount — единственная копия) #84 ещё нет, дефолт: безопасная копия через SQLite Online Backup API / VACUUM INTO во временный файл (НЕ сырое чтение файла под WAL — иначе несогласованный снимок). См. риски.
• service.go: Service{client; users; fleet; backup; token string; adminIDs []int64; pollTimeout}. Конструктор New(...) принимает примитивные поля (token, adminIDs) — не *config.Config.
• run.go: Run(ctx) — long-poll-цикл: GetUpdates(offset)→ для каждого апдейта dispatch; offset = последний UpdateID+1; backoff при сетевой ошибке; выход по ctx.Done(). Логирование — slog на этом уровне (бот — фоновый демон без хендлера сверху; это осознанное исключение из «логирует только хендлер», как уже сделано в fleet.fetch slog.Warn для фоновой видимости — сослаться на этот прецедент в комментарии).
• dispatch.go: разбор команды (/usage, /backup, /start//help). Команды — типизированные константы, не магические строки в условиях (по правилу «сравнение содержимого строк — только осознанно»): можно switch firstToken(text) по объявленным const cmdUsage = "/usage" — это допустимо (разбор протокола Telegram, не доменный признак), пометить комментарием.
• usage.go: SubIDByTgID(fromID) → fleet.Sub(subID) → форматирование ответа (Up/Down/Total/Expiry; человеко-текст). Неизвестный tgId → вежливый ответ «привязка не найдена, обратитесь к оператору» (НЕ ошибка). Тексты — русские константы здесь (бот — слой представления для клиента; это не нарушает «человеко-текст только в хендлере», т.к. notify фактически и есть презентационный слой бота — зафиксировать в комментарии пакета).
• backup.go: проверка fromID ∈ adminIDs (иначе отказ) → backup.Snapshot → SendDocument. Только для админов.
• alerts.go: экспортируемые методы для алёртов оператору — NotifyExpiring/NotifyExhausted/NotifyProvisionError(ctx, ...) — шлют SendMessage всем adminIDs. Кто их вызывает — открытый вопрос (нужен периодический сканер флита на истечение/исчерпание; провижининг-ошибки сейчас возвращаются вверх, а не публикуются). Дефолт для первой итерации: завести ScanAlerts(ctx) тикер внутри notify, который раз в N минут берёт fleet.Fleet, находит подписчиков с Expiry в ближайшем окне или Up+Down >= Total>0, и шлёт алёрт (с дедупликацией в памяти, чтобы не спамить). Привязку provision-ошибок к боту — отложить (вынести в отдельный issue), чтобы не тащить notify в provisioning против data-flow.
• Тесты: TestService_Dispatch, TestService_Usage, TestService_Backup, TestService_ScanAlerts (table-driven, по одному Test{Type}_{Method} на метод; моки из своего contract.go).

7. service/provisioning — прокинуть TgID

• CreateUser (service.go:184): u := &entity.User{Name, SubID, Description, TgID: p.TgID}.
• EditUser (service.go:203-248): после ReplaceConnections/SetDescription — users.SetTgID(ctx, u.ID, tgID); добавить SetTgID в userRepo contract (provisioning/contract.go).
• syncPanels (service.go:393): в entity.ClientSpec{...} проставить TgID. Источник — u.TgID (deref или 0). Нужно протащить u.TgID в ClientSpec (значение 0, если nil).
• xui/add_client.go:23: "tgId": cs.TgID вместо литерала 0.

8. handlers (user_create / user_edit) + OpenAPI/ogen

• openapi/user_create.yaml + openapi/user_edit.yaml: добавить опциональное поле в requestBody:

  tgId:
    type: integer
    format: int64
    description: Optional Telegram user/chat id binding (validated server-side).

  Без value-constraints (правило: форма контракта в схеме, значения — в сервисе). Затем go generate ./internal/oas/.
• internal/handlers/user_create/handler.go и user_edit/handler.go: распаковать req.TgId (как Description: req.TgId.Get() → *int64) в UserCreateParams.TgID/UserEditParams.TgID. Валидация значения (если нужна, напр. tgId > 0) — sentinel в provisioning + локальная текст-константа в хендлере; по дефолту валидация не нужна (любой int64 принимаем, 0/отрицательные — на усмотрение, лучше не пускать ≤0: entity.ErrInvalidTgID → 400).
• Read-сторона: users_get (handler.go) и его openapi/users_get.yaml — отдавать tgId в строке пользователя (опционально), чтобы фронт показал привязку и заполнил форму редактирования.

9. config

• internal/config/config.go: добавить поля
  • TGBotToken string \env:"SUBGEN_TG_BOT_TOKEN"`` (опционально).
  • TGAdminIDs []int64 \env:"SUBGEN_TG_ADMIN_IDS" envSeparator:","`(caarlos0/env умеет слайсы; формат123,456`).
• internal/config/load.go: валидация — если TGBotToken != "", а TGAdminIDs пуст → ошибка (бот без админов не может слать алёрты/делать /backup). Иначе обе пустые = бот выключен.
• cmd/service/main.go (run()): если cfg.TGBotToken != "" — собрать telegram.New() + notify.New(tgc, usersRepo, fleetSvc, backup, cfg.TGBotToken, cfg.TGAdminIDs) и go notifySvc.Run(ctx) (и go notifySvc.ScanAlerts(ctx)), рядом с go mirror.Run(ctx) (main.go:113). Прокидываем конкретные поля, не Config.
• .env.example: добавить SUBGEN_TG_BOT_TOKEN= и SUBGEN_TG_ADMIN_IDS= с комментариями (опционально, бот off если пусто).

10. Фронт (internal/handlers/web/static/app.js + index.html)

• uForm (app.js:26,401,403): добавить поле tgId (строка/число). В openCreateUser/openEditUser — инициализировать из u.tgId. В save-payload (app.js:408) — добавить tgId (числом; пустое → не слать/null).
• В модалке пользователя — input «Telegram ID» (опционально), в токенах темы (Ant-dark, см. AGENTS.md — #23252b/#1668dc и т.д., без новых либ).
• В таблице пользователей — по желанию иконка/бейдж привязки Telegram (как иконка описания). Минимально — поле в форме.

---

Миграции БД

• Новый migrations/0004-users-tgid.sql:

  -- 0004: optional Telegram user/chat id binding (NULL = unbound).
  ALTER TABLE users ADD COLUMN tg_id INTEGER;

• Forward-only, чистый DDL, накатывается раннером migrations.Apply автоматически на старте. Не править базлайн 0001-init.sql.

OpenAPI/ogen

• Править openapi/user_create.yaml, openapi/user_edit.yaml, openapi/users_get.yaml (опциональное tgId, форма без value-constraints) → go generate ./internal/oas/.
• Telegram Bot API — это исходящий клиент к внешнему сервису, в OpenAPI subgen он не описывается (ogen — только для входящих HTTP-ручек subgen). Бот не добавляет ни одной субген-ручки.

Тесты

• clients/telegram (обязательно): TestClient_GetUpdates, TestClient_SendMessage, TestClient_SendDocument — table-driven, httptest.Server/RoundTripper-мок, проверка wire-формата запроса (path /bot<token>/sendMessage, тело, multipart для документа) и маппинга DTO→entity.Tg*.
• service/notify: TestService_Dispatch, TestService_Usage, TestService_Backup, TestService_ScanAlerts — моки tgClient/usersReader/fleetReader/backupSource из своего contract.go. Ветки: empty, success.* (трафик отрендерен, документ ушёл админу), error.downstream, error.unknown_tg_id, error.non_admin_backup.
• repository/users: тест на ByTgID/SubIDByTgID (если есть live-DB тест-инфраструктура у users — следовать существующему стилю *_test.go в пакете). create/list_page тесты — обновить ожидания на новую колонку.
• provisioning: обновить существующие service_test.go — ClientSpec.TgID теперь прокидывается; добавить кейс «TgID задан → в AddClient уходит ненулевой tgId» и «SetTgID вызван в EditUser».
• apitest (по желанию, чёрный ящик): расширить UserSuite — create/edit с tgId через сырой map[string]any, проверить, что read его возвращает. Telegram Bot API в apitest не мокается (внешний третий сервис) — бот в apitest не покрываем.

Документация

• CHANGELOG.md: одна запись ## 2026-06-12 — Telegram-бот: алёрты, /usage и /backup (#105) + 1–2 строки сути + ссылка на ADR.
• ADR обязателен (нетривиальное решение, несколько развилок): docs/decisions/0006-telegram-bot.md по шаблону 0000-template.md. Зафиксировать: (a) воркер в cmd/service vs отдельный cmd/bot (Docker single-container); (b) свой тонкий HTTP-клиент vs внешняя либа; (c) /usage-резолв через новую колонку users.tg_id + переиспользование fleet.Subscriber (а не новый расчёт трафика); (d) бэкап через SQLite-safe-snapshot (Online Backup/VACUUM INTO), а не сырое чтение файла под WAL; (e) почему notify держит русский человеко-текст (он и есть презентационный слой бота). Если Периодический бэкап/restore SQLite-стора (единственный bind-mount — единственная копия) #84 даёт API бэкапа — сослаться на него.

Риски и edge-cases

• WAL-консистентность бэкапа: сырое os.Open("db/subgen.db") под активной WAL-нагрузкой даёт несогласованный/битый снимок (WAL-страницы не в main-файле). Использовать SQLite Online Backup API или VACUUM INTO <tmp> и слать результат. Это пересекается с Периодический бэкап/restore SQLite-стора (единственный bind-mount — единственная копия) #84 — согласовать, чтобы не делать дважды.
• Размер документа: Telegram-лимит на sendDocument ботом ~50 МБ. Для большого db/ — предупредить/обрезать; на ранней стадии ОК.
• Безопасность /backup: дамп БД содержит секреты (токены панелей, sub_id). Строго гейтить по adminIDs; неадмину — отказ. Логировать запросы бэкапа.
• Спам алёртов: ScanAlerts без дедупликации зашлёт один и тот же алерт каждый тик. Нужен in-memory set «уже уведомили про subId+причину» (сбрасывается, когда условие ушло).
• Идемпотентность long-poll offset: терять offset при рестарте = повторная обработка апдейтов (Telegram держит апдейты ~24ч). Безвредно для /usage//backup (повторный ответ), но желательно подтверждать offset до обработки или хранить. Для XL-итерации — допустимо обрабатывать заново (документировать).
• tgId один на несколько ников: если не ставим UNIQUE — /usage найдёт первого; решить, агрегировать или отвечать «несколько привязок». См. открытые вопросы.
• 3x-ui tgId — int, не строка: уже учтено (cs.TgID int64 → число в JSON). При nil-User.TgID слать 0 (текущее поведение панели).
• Зависимость data-flow: алёрты provision-ошибок потребовали бы, чтобы provisioning знал о notify (верхний слой). Не делать — оставить алёрты на периодический скан флита; provision-error-алёрты вынести отдельным issue.

Зависимости/порядок

• Периодический бэкап/restore SQLite-стора (единственный bind-mount — единственная копия) #84 (периодический бэкап/restore SQLite) — даёт безопасный механизм снапшота БД; /backup здесь — его Telegram-триггер. Желательно делать после/совместно с Периодический бэкап/restore SQLite-стора (единственный bind-mount — единственная копия) #84 (переиспользовать его backupSource). Если Периодический бэкап/restore SQLite-стора (единственный bind-mount — единственная копия) #84 ещё не готов — реализовать минимальный safe-snapshot внутри notify и отметить как технический долг к интеграции с Периодический бэкап/restore SQLite-стора (единственный bind-mount — единственная копия) #84.
• Порядок внутри issue: entity → migration → repository → telegram-client → notify → provisioning/xui-правка → config → handlers/openapi (go generate) → фронт → CHANGELOG/ADR.

❓ Открытые вопросы (@Postlog)

1. Воркер бота — горутина в cmd/service или отдельный cmd/bot-бинарь/контейнер? Дефолт плана — горутина в cmd/service (single-container Docker). Если планируется масштабировать бот независимо — нужен отдельный бинарь и второй сервис в compose.
2. /backup — переиспользуем механизм из Периодический бэкап/restore SQLite-стора (единственный bind-mount — единственная копия) #84 или реализуем safe-snapshot прямо здесь? От ответа зависит контракт backupSource и нужно ли блокировать Telegram-бот: алёрты оператору, самопроверка трафика клиентом и бэкап БД #105 на Периодический бэкап/restore SQLite-стора (единственный bind-mount — единственная копия) #84.
3. users.tg_id — уникальный (один Telegram-аккаунт = один ник) или нет? От этого partial-UNIQUE-индекс в миграции и поведение /usage при нескольких привязках.
4. Алёрты оператору — что входит в первую итерацию? Дефолт — периодический скан флита на истекающих/исчерпанных (Expiry-окно + Total). Provision-ошибки требуют связи provisioning→notify (против data-flow) — предлагаю вынести отдельным issue. Подтвердите окно «скоро истекает» (напр. 3 дня) и интервал скана.