> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lampac.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Tg-notify.bot: Telegram-уведомления о новых сериях

> Tg-notify.bot отслеживает выход новых серий через Trakt/TMDB и доступность озвучек через Mirage/Collaps и шлёт уведомления в Telegram.

**Tg-notify.bot** — это фоновый Telegram-бот для Lampac NextGen, который уведомляет пользователей о выходе новых серий любимых сериалов и появлении выбранной озвучки. Бот объединяет три подсистемы: трекер эпизодов через Trakt и TMDB, трекер озвучек через балансеры Mirage и Collaps, а также клиентский плагин Lampa для управления подписками.

## Включение модуля

<Steps>
  <Step title="Проверьте SkipModules">
    Убедитесь, что `Tg-notify.bot` или `TelegramBot` не добавлены в `BaseModule.SkipModules` в `init.conf`. Если имя есть в списке — удалите его.
  </Step>

  <Step title="Включите в manifest.json">
    В файле `Modules/Tg-notify.bot/manifest.json` установите `"enable": true`. По умолчанию в репозитории стоит `false`.
  </Step>

  <Step title="Добавьте секцию TelegramBot в init.conf">
    Скопируйте пример конфигурации ниже в `init.conf` и заполните свои токены.
  </Step>

  <Step title="Подключите клиентский плагин">
    Добавьте плагин в `LampaWeb.customPlugins` в `init.conf`.
  </Step>

  <Step title="Перезапустите сервер">
    Выполните `systemctl restart lampac` (Linux) или перезапустите контейнер (Docker).
  </Step>
</Steps>

<Warning>
  Если `bot_token` пустой, long polling не стартует. В лог будет записано предупреждение, но сервер продолжит работу.
</Warning>

## Конфигурация

Добавьте секцию `TelegramBot` в `init.conf`:

```json theme={null}
{
  "TelegramBot": {
    "enable": true,
    "bot_token": "ТОКЕН_ОТ_BOTFATHER",
    "tmdb_api_key": "ВАШ_КЛЮЧ_TMDB",
    "trakt_client_id": "",
    "lampac_host": "http://127.0.0.1:9118",
    "lampac_token": "",
    "kp_api_key": "",
    "check_interval_minutes": 60,
    "tmdb_lang": "ru-RU",
    "data_dir": "database/tgnotify"
  }
}
```

| Поле                     | Назначение                                                                                                       |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `bot_token`              | Токен бота от [@BotFather](https://t.me/BotFather). Обязателен для работы.                                       |
| `tmdb_api_key`           | Ключ TMDB v3 для обложек, описаний эпизодов и определения актуального сезона.                                    |
| `trakt_client_id`        | Client ID приложения Trakt. Если задан, используется как основной источник новых серий. Если пуст — только TMDB. |
| `lampac_host`            | Базовый URL Lampac для запросов к балансерам. Обычно локальный адрес `http://127.0.0.1:9118`.                    |
| `lampac_token`           | Токен `accsdb`. Обязателен, если включена защита `accsdb`, иначе балансеры вернут ошибку авторизации.            |
| `kp_api_key`             | Ключ kinopoiskapiunofficial.tech. Нужен для резолвинга `kinopoisk_id` по названию при поиске через VideoHub.     |
| `check_interval_minutes` | Период фоновой проверки подписок. По умолчанию 60 минут. Первый прогон через 2 минуты после старта.              |
| `tmdb_lang`              | Язык метаданных TMDB. По умолчанию `ru-RU` с фоллбэком на `en-US`.                                               |
| `data_dir`               | Каталог для хранения `users.json` и `subscriptions.json`. По умолчанию `database/tgnotify`.                      |

## Как работает бот

### Привязка аккаунта

Из вкладки «TG Подписки» в Lampa пользователь получает deep-link вида `/start link_{uid}`. Бот сохраняет связку `chat_id` с `lampac_uid` в файл `users.json`. После этого все подписки этого UID привязываются к Telegram-чату.

### Подписка на сериал

В карточке сериала плагин перехватывает кнопку уведомлений и показывает меню доступных озвучек. Выбор отправляется на эндпоинт `/api/tg/subscribe` и сохраняется в `subscriptions.json`.

### Фоновый цикл CheckAll

Раз в заданный интервал (и вручную по команде `/check`) бот выполняет проверку по каждой подписке:

1. **Новые серии** — запрос к Trakt или TMDB. Если озвучка не выбрана, уведомление шлётся о самом факте выхода эпизода.
2. **Озвучки** — параллельно опрашиваются Mirage, Collaps и VideoHub. Берётся максимальный доступный эпизод. Кто первый нашёл новую серию в нужной озвучке, от того и приходит уведомление.

Формат уведомления:

```text theme={null}
🎬 Название сериала
🎙 Озвучка
📺 S05E08 — Название эпизода

Описание (до 300 символов)
```

Уведомление сопровождается обложкой кадра из TMDB, если у эпизода есть `still_path`.

## Команды бота

| Команда   | Действие                                                  |
| --------- | --------------------------------------------------------- |
| `/start`  | Приветствие и привязка аккаунта через `/start link_{uid}` |
| `/list`   | Список активных подписок                                  |
| `/check`  | Принудительная проверка всех подписок в фоне              |
| `/help`   | Справка по использованию бота                             |
| `/unlink` | Отвязать Telegram-аккаунт от Lampac                       |

## HTTP API

| Метод  | Маршрут                                        | Назначение                                                               |
| ------ | ---------------------------------------------- | ------------------------------------------------------------------------ |
| `GET`  | `/tg-notify.js`                                | Раздача клиентского плагина с автозаменой `{localhost}` на реальный хост |
| `POST` | `/api/tg/subscribe`                            | Подписка на сериал с выбранной озвучкой                                  |
| `POST` | `/api/tg/unsubscribe`                          | Отписка от сериала                                                       |
| `GET`  | `/api/tg/status?tmdb_id=`                      | Статус подписки текущего пользователя                                    |
| `GET`  | `/api/tg/voices?title=&year=&season=&tmdb_id=` | Список доступных озвучек (Mirage + Collaps + VideoHub)                   |
| `GET`  | `/api/tg/link`                                 | Deep-link для привязки Telegram-аккаунта                                 |
| `GET`  | `/api/tg/subscriptions`                        | Все подписки пользователя с метаданными                                  |

Все маршруты, кроме `/tg-notify.js` и `/api/tg/voices`, требуют авторизации по `user_uid`.

## Подключение плагина в Lampa

Добавьте плагин в секцию `customPlugins` файла `init.conf`:

```json theme={null}
{
  "LampaWeb": {
    "customPlugins": [
      { "url": "{localhost}/tg-notify.js", "status": 1 }
    ]
  }
}
```

Плейсхолдер `{localhost}` автоматически заменяется на реальный адрес сервера. Плагин добавляет вкладку «TG Подписки» в Lampa и перехватывает кнопку уведомлений в карточке сериала.