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

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

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

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

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

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

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

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

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

# Сборка образа
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. Установка зависимостей

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

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

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

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

cp .env.example .env

2. Отредактируйте .env файл с вашими настройками PostgreSQL:

DB_USER=postgres
DB_PASSWORD=your_password
DB_HOST=localhost
DB_PORT=5432
DB_NAME=telegram_bot

3. Убедитесь, что PostgreSQL запущен и база данных создана:

CREATE DATABASE telegram_bot;

3. Запуск API

# Из корневой директории проекта
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} - Удалить настройку

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

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

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"
     }'

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

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"
     }'

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

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

# Сборка и запуск всех сервисов
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 настроены следующие переменные:

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

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