added RAG, Multiuser, TG bot

telegram-bot/README.md

@@ -0,0 +1,145 @@
+# Home Assistant Telegram Bot
+
+Telegram-бот для удалённого доступа к домашнему ассистенту Home Assistant. Работает на отдельном VPS и общается с backend через REST API.
+
+## Возможности
+
+- Привязка 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
+```