# Home Assistant Telegram Bot

Telegram-бот для удалённого доступа к домашнему ассистенту. Работает на отдельном VPS и общается с backend через REST API.

Документация backend: [корневой README](../README.md) (auth, PostgreSQL, RAG, nginx `client_max_body_size` для фото).

## Возможности

- Привязка API-токена Home Assistant через чат Telegram
- Отдельная chat-сессия «Telegram» на каждого пользователя
- Диалог с ассистентом (SSE-стриминг ответа)
- Дублирование оповещений (`notice`, `character`) из всех сессий пользователя

## Требования

- Python 3.12+ или Docker
- Telegram Bot Token ([@BotFather](https://t.me/BotFather))
- Доступный с VPS URL backend Home Assistant (HTTPS рекомендуется)

Backend должен быть доступен по адресу вида:

```
https://your-home-server.example.com/api/v1
```

Если backend за reverse proxy, пробросьте порт `8080` или маршрут `/api/v1` наружу. CORS для бота не нужен.

## Быстрый старт (Docker)

```bash
cd telegram-bot
cp .env.example .env
# заполните TELEGRAM_BOT_TOKEN и HA_API_BASE_URL
docker compose up -d --build
docker compose logs -f
```

## Быстрый старт (без Docker)

```bash
cd telegram-bot
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
# заполните .env
python -m bot.main
```

## Переменные окружения

| Переменная | Описание |
|------------|----------|
| `TELEGRAM_BOT_TOKEN` | Токен от BotFather |
| `HA_API_BASE_URL` | Base URL API, например `https://home.example.com/api/v1` |
| `POLL_INTERVAL_SEC` | Интервал polling оповещений (по умолчанию 30) |
| `DATA_DIR` | Каталог для SQLite (`./data`) |
| `ALLOWED_TELEGRAM_IDS` | Опционально: whitelist Telegram user id через запятую |

## Создание API-токена на домашнем сервере

### Через веб-интерфейс

Settings → Пользователи → создать пользователя. Токен показывается один раз — сохраните его.

### Через CLI

```bash
cd ~/to_services/Home_assistant
docker compose exec backend python scripts/create_user.py myuser --display-name "Имя"
```

Токен будет выведен в консоль.

## Использование бота

1. `/start` — инструкция
2. Отправьте API-токен одним сообщением
3. После успешной привязки удалите сообщение с токеном из истории Telegram
4. Пишите ассистенту обычным текстом

### Команды

| Команда | Описание |
|---------|----------|
| `/start` | Приветствие и инструкция |
| `/help` | Справка |
| `/whoami` | Текущий пользователь HA |
| `/logout` | Отвязать токен |
| `/newchat` | Новая сессия «Telegram» |

## Оповещения

Фоновый worker каждые `POLL_INTERVAL_SEC` секунд:

1. Опрашивает `GET /pomodoro/status` и `GET /reminders` (счётчики seq)
2. Загружает новые сообщения из **всех** chat-сессий пользователя
3. Отправляет в Telegram сообщения с ролями `notice` и `character`

Это покрывает напоминания, помидоро, homelab, fitness и другие системные оповещения без изменений backend.

## Безопасность

- API-токен хранится в SQLite на VPS (`DATA_DIR/bot.db`)
- Токен виден в истории Telegram при отправке — удалите сообщение после привязки
- Используйте `ALLOWED_TELEGRAM_IDS`, чтобы ограничить доступ к боту
- Не коммитьте `.env` с реальными токенами

## Деплой на VPS

```bash
git clone <repo> && cd Home_assistant/telegram-bot
cp .env.example .env
nano .env
docker compose up -d --build
```

Обновление:

```bash
git pull
docker compose up -d --build
```

## Проверка

1. Привязать токен → `/whoami` показывает имя
2. Написать «Привет» → ответ ассистента
3. Создать напоминание через web → notice в TG за ~30–60 с
4. Второй Telegram-аккаунт с другим HA-токеном → изолированные чат и оповещения

## Структура

```
telegram-bot/
  bot/
    main.py           # entrypoint
    config.py         # env
    ha_client.py      # REST + SSE клиент
    sse.py            # парсер SSE
    storage.py        # SQLite
    notify_worker.py  # polling оповещений
    handlers/         # команды и чат
  Dockerfile
  docker-compose.yml
  requirements.txt
```