diff --git a/README.md b/README.md index b75646a..4f653aa 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,154 @@ -# this OR that +# this OR that | Telegram Mini App -Telegram mini-app where you have to choose one of two things. -## Installation +thisORthat_logo -1. Installing the repository: -```bash -git clone https://github.com/IgorVolochay/thisORthat + +## Описание проекта + +[«this OR that»](https://t.me/thisorthat_rubot?startapp) — это интерактивное веб-приложение формата Telegram Mini App, предлагающее пользователю сделать выбор между двумя альтернативными вариантами («Это или То»). Сразу после голосования открывается статистика голосов других участников, открывается доступ к обсуждению в комментариях, реакциям (лайки / дизлайки), а также предоставляется возможность создать собственную карточку. + +### Идея и источник вдохновения +Вдохновением для проекта послужил русскоязычный ресурс [thisorthat.ru](https://thisorthat.ru), где собраны тысячи вопросов для размышления. Основная цель данного проекта - адаптировать и переосмыслить эту механику в современный экосистемный формат **Telegram Mini App**. + +> [!NOTE] +> **Это pet-проект.** Проект носит исключительно некоммерческий, учебно-исследовательский характер. Он был создан для отработки и демонстрации практических навыков проектирования асинхронных бэкендов, построения событийно-ориентированной архитектуры (Event-Driven Architecture), интеграции очередей сообщений, работы с Telegram WebApp API и контейнеризации сервисов. + +thisORthat_telegram + + +## Технологический стек, подходы и инструменты + +В ходе разработки были применены современные технологии, обеспечивающие высокую производительность, масштабируемость и безопасность: + +### Backend & Асинхронная экосистема +* **Python 3.12+**: основной язык разработки сервисов. +* **[FastAPI](https://github.com/fastapi/fastapi)**: высокопроизводительный асинхронный веб-фреймворк для реализации REST API. +* **[Motor](https://github.com/mongodb/motor)**: асинхронный драйвер для интеграции с базой данных MongoDB. +* **[Pydantic v2](https://github.com/pydantic/pydantic)**: строгая валидация входящих и исходящих данных через типизированные схемы. +* **[aio-pika](https://github.com/mosquito/aio-pika)**: асинхронный клиент для взаимодействия с брокером сообщений RabbitMQ. +* **[aiogram 3](https://github.com/aiogram/aiogram)**: асинхронный фреймворк для Telegram-бота модерации. +* **[FastAPI-guard](https://github.com/rennf93/fastapi-guard)**: модуль rate limiting, защита от попыток проникновения, а также временная блокировка подозрительных IP-адресов. +* **[Loguru](https://github.com/Delgan/loguru)**: структурированное логирование. +* **[Pytest](https://github.com/pytest-dev/pytest)**: тестовый фреймворк для покрытия эндпоинтов, логики карточек и проверки безопасности. + +### Frontend +* **[React 19](https://github.com/react/react)**: библиотека для построения динамичного пользовательского интерфейса (SPA). +* **Telegram WebApp API**: интеграция с окружением мессенджера (Haptic Feedback для тактильного отклика, автоматическая адаптация к системной теме Telegram, SafeArea и управление кнопками). +* **Vanilla CSS & Flexbox/Grid**: адаптивная верстка под любые размеры мобильных экранов, плавные микро-анимации, кастомные скроллбары и модальные окна без утяжеления сторонними CSS-библиотеками. + +### Базы данных и очереди +* **[MongoDB](https://www.mongodb.com/)**: NoSQL база данных для гибкого хранения карточек, голосов пользователей, профилей и древовидных комментариев. +* **[RabbitMQ](https://www.rabbitmq.com/)**: брокер сообщений, обеспечивающий отказоустойчивую буферизацию задач между бэкендом и ботом модерации. + +### Архитектурные подходы и паттерны +* **Event-Driven Moderation (EDA)**: отправка предложенных пользователями карточек в очередь сообщений без задержек основного пользовательского API. +* **Zero-Trust авторизация через Telegram**: валидация подписи `initData` по алгоритму HMAC-SHA256 с использованием секретного ключа бота. +* **Защита API и Rate Limiting**: многоуровневая фильтрация запросов через FastAPI-guard с возвратом специализированных экранов блокировки на фронтенде при превышении лимитов. +* **Service-Oriented Architecture (SOA)**: разделение приложения на изолированные контейнеры: БД, брокер, API-сервис и бот. + +--- + +## Архитектура проекта и взаимосвязь компонентов + +Проект построен по сервисной архитектуре, где каждый компонент выполняет строго отведенную роль: + +```mermaid +flowchart TD + subgraph Client["Клиентская часть"] + TMA["Telegram Mini App (React 19)"] + end + + subgraph CoreBackend["Бэкенд инфраструктура"] + API["FastAPI REST Backend :5000"] + Mongo[("MongoDB Database :27017")] + RMQ[["RabbitMQ Broker :5672"]] + Bot["Telegram Модерация Bot (aiogram 3)"] + end + + subgraph TelegramCloud["Инфраструктура Telegram"] + TGUser["Пользователь Telegram"] + TGAdmin["Администратор в Telegram"] + end + + %% Взаимодействия + TGUser <--> |Запуск Mini App / initData| TMA + TMA <--> |REST API запросы / Голосование / Комментарии| API + API <--> |Асинхронные запросы через Motor| Mongo + API --> |Публикация новой карточки в очередь moderation| RMQ + RMQ --> |Потребление карточки из очереди| Bot + Bot --> |Уведомление с кнопками Одобрить / Отклонить| TGAdmin + TGAdmin --> |Инлайн-решение| Bot + Bot --> |Защищенный вызов API с MODERATION_SECRET| API ``` -### Manual setup: +### Сценарии взаимодействия: +1. **Пользовательский сценарий:** + - Пользователь открывает Mini App внутри Telegram. Приложение передает `initData`, которая верифицируется бэкендом. + - Пользователь получает случайные пары карточек из MongoDB, делает выбор, голосует, оставляет комментарии и реакции. +2. **Пайплайн предложения и модерации карточек:** + - Пользователь предлагает свою карточку через интерфейс приложения. + - Сервис FastAPI сохраняет карточку в MongoDB со статусом ожидания и мгновенно публикует событие в очередь `moderation` брокера **RabbitMQ**. + - Сервис **Telegram Bot** (aiogram) слушает очередь, получает карточку и пересылает ее в чат администратора (`TG_ADMIN_CHAT_ID`) с инлайн-кнопками «Одобрить ✅» / «Отклонить ❌». + - Администратор принимает решение в Telegram. Бот выполняет защищенный внутренний запрос к API (`/card_accept` или `/card_reject`) с заголовком `MODERATION_SECRET`, после чего статус карточки в базе обновляется. + +--- + +## Краткое руководство по запуску + +Для запуска проекта на локальной машине потребуются установленные **Docker**, **Docker Compose** и **Node.js** (версии 18+). + +### Шаг 1. Конфигурация окружения +Создайте файл переменных окружения `.env` в корне проекта на основе образца `.env_example`: -2. The project is written in Python3.9. Make sure you have it on your system. Go to the project folder, create a virtual environment and download pip requirements: ```bash -cd ./thisORthat -python3.9 -m venv venv -source ./venv/bin/activate -pip3 install -r ./app/requirements.txt +cp .env_example .env ``` -3. Installing MongoDB database. You can use the [official manual](https://www.mongodb.com/docs/manual/installation/) to install MongoDB manually, or use a [Docker image](https://hub.docker.com/r/mongodb/mongodb-community-server) to run the container: -```bash -docker run --name mongodb -d -p 27017:27017 -e MONGO_INITDB_ROOT_USERNAME=user -e MONGO_INITDB_ROOT_PASSWORD=pass mongodb/mongodb-community-server -``` -### Docker Compose setup: +Заполните ключевые параметры в `.env`: +* `TG_BOT_TOKEN` — токен вашего Telegram-бота от [@BotFather](https://t.me/BotFather). +* `TG_ADMIN_CHAT_ID` — ваш Telegram ID или ID чата для модерации карточек. +* `MODERATION_SECRET` — произвольная секретная строка для взаимодействия между ботом и API. +* При необходимости скорректируйте учетные данные MongoDB и RabbitMQ. Для локальной разработки без валидации Telegram `DEV_MODE` можно оставить равным `true`. + +### Шаг 2. Сборка фронтенда +Соберите статическую версию React-приложения: -2. Use docker-compose to automatically build the entire project. For correct build, it is better to use docker-compose version 1.29.2: ```bash -docker-compose up --build -``` \ No newline at end of file +cd frontend +npm install +npm run build +cd .. +``` + +### Шаг 3. Запуск сервисов через Docker Compose +Запустите сборку и старт всех сервисов в фоновом режиме: + +```bash +docker compose up -d --build +``` + +После завершения запуска будут активны следующие компоненты: +* **Backend API:** `http://localhost:5000` (документация Swagger доступна по адресу `http://localhost:5000/docs` при `DEV_MODE=true`). +* **Панель RabbitMQ Management:** `http://localhost:15672` (логин и пароль задаются в `.env`). +* **MongoDB:** порт `27017`. +* **Telegram Bot:** сервис подключится к Telegram и начнет обработку очереди модерации. + +--- + +## Контакты + +* **Автор:** Волочай Игорь (Igor Volochay) +* **Telegram:** [@VIAproger](https://t.me/VIAproger) +* **Email:** [pseudo.developer.ru@gmail.com](mailto:pseudo.developer.ru@gmail.com) +* **GitHub репозиторий:** [https://github.com/IgorVolochay/thisORthat](https://github.com/IgorVolochay/thisORthat) + +--- + +## Благодарности + +### Идейный вдохновитель +* **[thisorthat.ru](https://thisorthat.ru)** — оригинальный проект, послуживший источником вдохновения для идеи, концепции дилемм и механики выбора. + +### Open-Source сообщество, библиотеки и фреймворки +Выражаю глубокую благодарность разработчикам и мейнтейнерам ключевых библиотек и инструментов, на которых построен проект. \ No newline at end of file