> ## 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.

# SeriesNotify: Telegram-уведомления о новых сериях и озвучках

> Telegram-уведомления о новых сериях и озвучках: Trakt/TMDB для эпизодов, Mirage/Collaps/VideoHub для озвучек, плагин Lampa для подписок.

**SeriesNotify** — фоновый Telegram-бот для Lampac NextGen: уведомления о выходе новых серий и появлении выбранной озвучки. Три подсистемы: трекер эпизодов (Trakt/TMDB), трекер озвучек (Mirage, Collaps, VideoHub), клиентский плагин Lampa для подписок.

Папка, `SkipModules` и секция `init.conf` — **`SeriesNotify`**.

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

<Steps>
  <Step title="Проверьте SkipModules">
    Уберите `SeriesNotify` из `BaseModule.SkipModules` в `init.conf` (в `base.conf` модуль в SkipModules по умолчанию).
  </Step>

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

  <Step title="Добавьте секцию SeriesNotify в 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>

<Warning>
  У каждого long-polling бота свой `bot_token`: `SeriesNotify`, [QRAuth](/modules/qr-auth) (`QRAuthBot`), [TelegramAuthBot](/modules/telegram-auth-bot). Один токен на два модуля даёт `409 Conflict`.
</Warning>

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

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "SeriesNotify": {
    "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={"theme":{"light":"github-light","dark":"github-dark"}}
🎬 Название сериала
🎙 Озвучка
📺 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={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "LampaWeb": {
    "customPlugins": [
      { "url": "{localhost}/tg-notify.js", "status": 1 }
    ]
  }
}
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.