Rewrite README

2026-09-09 11:21:49 +03:00
parent 8d8361ab8f
commit 4a84b442a5
1 changed files with 143 additions and 20 deletions
@@ -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
+<img width="1447" height="248" alt="thisORthat_logo" src="https://github.com/user-attachments/assets/fee632cf-f778-4a72-95d7-bee2f8602bc0" />

-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 и контейнеризации сервисов.
+
+<img width="1800" height="1244" alt="thisORthat_telegram" src="https://github.com/user-attachments/assets/172e8243-f6da-4dcf-a362-74fa18ce68e9" />
+
+
+## Технологический стек, подходы и инструменты
+
+В ходе разработки были применены современные технологии, обеспечивающие высокую производительность, масштабируемость и безопасность:
+
+### 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
+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 сообщество, библиотеки и фреймворки
+Выражаю глубокую благодарность разработчикам и мейнтейнерам ключевых библиотек и инструментов, на которых построен проект.