bot-telegram/API_README.md

# Telegram Bot API

FastAPI приложение для взаимодействия с Telegram ботом и базой данных PostgreSQL через SQLAlchemy.

## Структура проекта

```
bot-telegram/
├── api/                    # FastAPI приложение
│   ├── __init__.py
│   ├── main.py            # Основное приложение
│   ├── routers.py         # API маршруты
│   ├── schemas.py         # Pydantic схемы
│   └── config.py          # Конфигурация
├── database/              # Модули базы данных
│   ├── __init__.py
│   ├── database.py        # Подключение к БД
│   ├── models.py          # SQLAlchemy модели
│   └── ...
├── pyproject.toml         # Зависимости проекта
├── .env.example           # Пример переменных окружения
└── README.md
```

## Установка и настройка

### Способ 1: Запуск через Docker (рекомендуется)

#### 1. Запуск с Docker Compose

```bash
# Клонируйте репозиторий и перейдите в директорию
cd bot-telegram

# Запустите все сервисы (API + PostgreSQL)
docker-compose up -d

# Для просмотра логов
docker-compose logs -f api

# Остановка сервисов
docker-compose down
```

#### 2. Запуск с pgAdmin (опционально)

```bash
# Запуск с админкой для базы данных
docker-compose --profile admin up -d

# pgAdmin будет доступен по адресу: http://localhost:5050
# Email: admin@admin.com
# Password: admin
```

#### 3. Сборка только API контейнера

```bash
# Сборка образа
docker build -t telegram-bot-api .

# Запуск контейнера (требует запущенный PostgreSQL)
docker run -d \
  --name telegram-bot-api \
  -p 8000:8000 \
  -e DB_HOST=host.docker.internal \
  -e DB_PASSWORD=your_password \
  telegram-bot-api
```

### Способ 2: Локальная установка

#### 1. Установка зависимостей

```bash
# Используя uv (рекомендуется)
uv sync

# Или используя pip
pip install -e .
```

#### 2. Настройка базы данных

1. Создайте файл `.env` на основе `.env.example`:
```bash
cp .env.example .env
```

2. Отредактируйте `.env` файл с вашими настройками PostgreSQL:
```env
DB_USER=postgres
DB_PASSWORD=your_password
DB_HOST=localhost
DB_PORT=5432
DB_NAME=telegram_bot
```

3. Убедитесь, что PostgreSQL запущен и база данных создана:
```sql
CREATE DATABASE telegram_bot;
```

#### 3. Запуск API

```bash
# Из корневой директории проекта
python run_api.py

# Или с помощью uvicorn напрямую
uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload
```

API будет доступно по адресу: http://localhost:8000

## API Endpoints

### Общие endpoints

- `GET /` - Корневая информация
- `GET /health` - Проверка состояния приложения
- `GET /docs` - Swagger UI документация (автоматически)
- `GET /redoc` - ReDoc документация (автоматически)

### Пользователи (`/api/v1/users`)

- `GET /api/v1/users/` - Получить всех пользователей
- `GET /api/v1/users/{telegram_id}` - Получить пользователя по Telegram ID
- `POST /api/v1/users/` - Создать нового пользователя
- `PUT /api/v1/users/{telegram_id}` - Обновить пользователя
- `DELETE /api/v1/users/{telegram_id}` - Деактивировать пользователя

### Сообщения (`/api/v1/messages`)

- `GET /api/v1/messages/` - Получить сообщения с фильтрацией
- `GET /api/v1/messages/{message_id}` - Получить конкретное сообщение
- `POST /api/v1/messages/` - Создать новое сообщение

### Настройки бота (`/api/v1/settings`)

- `GET /api/v1/settings/` - Получить все настройки как словарь
- `GET /api/v1/settings/list` - Получить все настройки как список объектов
- `GET /api/v1/settings/{key}` - Получить настройку по ключу
- `POST /api/v1/settings/` - Создать или обновить настройку
- `PUT /api/v1/settings/{key}` - Обновить существующую настройку
- `DELETE /api/v1/settings/{key}` - Удалить настройку

## Примеры использования

### Создание пользователя

```bash
curl -X POST "http://localhost:8000/api/v1/users/" \
     -H "Content-Type: application/json" \
     -d '{
       "telegram_id": 123456789,
       "username": "john_doe",
       "first_name": "John",
       "last_name": "Doe",
       "language_code": "en"
     }'
```

### Создание сообщения

```bash
curl -X POST "http://localhost:8000/api/v1/messages/" \
     -H "Content-Type: application/json" \
     -d '{
       "telegram_message_id": 12345,
       "user_id": 1,
       "text": "Привет!",
       "message_type": "text"
     }'
```

### Настройка бота

```bash
curl -X POST "http://localhost:8000/api/v1/settings/" \
     -H "Content-Type: application/json" \
     -d '{
       "key": "welcome_message",
       "value": "Добро пожаловать в наш бот!",
       "description": "Приветственное сообщение для новых пользователей"
     }'
```

## Модели данных

### User (Пользователь)
- `id` - Внутренний ID
- `telegram_id` - Telegram ID пользователя (уникальный)
- `username` - Username в Telegram
- `first_name` - Имя
- `last_name` - Фамилия
- `language_code` - Код языка (по умолчанию 'ru')
- `is_active` - Активен ли пользователь
- `is_admin` - Является ли администратором
- `created_at` - Дата создания
- `updated_at` - Дата обновления

### Message (Сообщение)
- `id` - Внутренний ID
- `telegram_message_id` - ID сообщения в Telegram
- `user_id` - ID пользователя (внешний ключ)
- `text` - Текст сообщения
- `message_type` - Тип сообщения (text, photo, document, etc.)
- `created_at` - Дата создания

### BotSettings (Настройки бота)
- `id` - Внутренний ID
- `key` - Ключ настройки (уникальный)
- `value` - Значение настройки
- `description` - Описание настройки
- `created_at` - Дата создания
- `updated_at` - Дата обновления

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

| Переменная | Описание | По умолчанию |
|------------|----------|--------------|
| `DB_USER` | Пользователь PostgreSQL | `postgres` |
| `DB_PASSWORD` | Пароль PostgreSQL | `password` |
| `DB_HOST` | Хост PostgreSQL | `localhost` |
| `DB_PORT` | Порт PostgreSQL | `5432` |
| `DB_NAME` | Имя базы данных | `telegram_bot` |
| `API_HOST` | Хост API сервера | `0.0.0.0` |
| `API_PORT` | Порт API сервера | `8000` |
| `API_RELOAD` | Автоперезагрузка в dev режиме | `true` |
| `LOG_LEVEL` | Уровень логирования | `INFO` |

## Разработка

### Структура API

API организовано по модульному принципу:

- `main.py` - Основное приложение FastAPI
- `routers.py` - Определения маршрутов и бизнес-логика
- `schemas.py` - Pydantic схемы для валидации данных
- `config.py` - Конфигурация приложения

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

FastAPI автоматически генерирует интерактивную документацию:

- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

### Логирование

Приложение использует стандартный модуль `logging` Python. Уровень логирования можно настроить через переменную окружения `LOG_LEVEL`.

## Интеграция с Telegram ботом

Этот API предназначен для использования Telegram ботом. Бот может:

1. Регистрировать новых пользователей при первом взаимодействии
2. Сохранять все входящие сообщения
3. Получать и обновлять настройки бота
4. Управлять пользователями (активация/деактивация, права администратора)

Пример интеграции с aiogram или python-telegram-bot будет добавлен позже.

## Docker контейнеризация

### Структура Docker файлов

- **`Dockerfile`** - Многоступенчатая сборка для оптимизации размера образа
- **`docker-compose.yml`** - Оркестрация API + PostgreSQL + pgAdmin
- **`.dockerignore`** - Исключение ненужных файлов из контекста сборки
- **`init.sql`** - Скрипт инициализации базы данных

### Docker Compose сервисы

1. **`postgres`** - PostgreSQL 15 база данных (отдельный контейнер)
   - Порт: 5432
   - Данные сохраняются в Docker volume
   - Автоматическая проверка готовности

2. **`app`** - Единое приложение (API + database логика в одном контейнере)
   - Порт: 8000
   - Включает FastAPI сервер и все модули для работы с БД
   - Подключается к внешней PostgreSQL по сети
   - Автоматически ждет готовности БД

3. **`pgadmin`** - Веб-админка PostgreSQL (опционально)
   - Порт: 5050
   - Запускается только с профилем `admin`

### Команды Docker

```bash
# Сборка и запуск всех сервисов
docker-compose up --build -d

# Просмотр логов конкретного сервиса
docker-compose logs -f api
docker-compose logs -f postgres

# Перезапуск сервиса
docker-compose restart api

# Остановка и удаление контейнеров
docker-compose down

# Остановка с удалением volumes (ВНИМАНИЕ: удаляет данные БД)
docker-compose down -v

# Запуск только определенного сервиса
docker-compose up postgres -d

# Выполнение команд внутри контейнера
docker-compose exec api bash
docker-compose exec postgres psql -U postgres -d telegram_bot
```

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

В `docker-compose.yml` настроены следующие переменные:

```yaml
environment:
  # База данных
  DB_HOST: postgres
  DB_PORT: 5432
  DB_NAME: telegram_bot
  DB_USER: postgres
  DB_PASSWORD: password
  
  # API
  API_HOST: 0.0.0.0
  API_PORT: 8000
  API_RELOAD: "false"
  LOG_LEVEL: INFO
```

### Volumes и сети

- **Volume `postgres_data`** - Постоянное хранение данных PostgreSQL
- **Network `bot_network`** - Изолированная сеть для взаимодействия сервисов

### Производственное развертывание

Для продакшена рекомендуется:

1. Изменить пароли по умолчанию
2. Настроить внешние тома для данных
3. Использовать reverse proxy (nginx)
4. Настроить SSL сертификаты
5. Ограничить CORS origins

```bash
# Пример для продакшена
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
```