🏷️ Smart Price Monitor API & Telegram Bot

Smart Price Monitor — это асинхронный микросервисный проект, который позволяет пользователям отслеживать снижение цен на товары в интернет-магазинах. Пользователь взаимодействует с сервисом через удобного Telegram-бота, устанавливая желаемую цену. Как только цена падает до указанной отметки (или ниже), бот мгновенно присылает уведомление.

Проект разработан в качестве Pet Project для демонстрации навыков backend-разработки, построения микросервисной архитектуры и работы с асинхронными фреймворками Python.

---

🏗 Архитектура проекта

Проект разделен на 3 независимых компонента (микросервиса), которые общаются друг с другом через единую базу данных и REST API:

1. FastAPI Backend (main_api.py) — предоставляет RESTful API для управления пользователями и подписками. Включает JWT-аутентификацию для защиты эндпоинтов.
2. Telegram Bot (main_bot.py) — клиентский интерфейс, написанный на фреймворке Aiogram 3. Пользователи регистрируются, получают токен и через API добавляют товары в БД. ИСПОЛЬЗУЕТСЯ паттерн FSM (Машина состояний) для сбора данных (ссылка + цена).
3. Background Worker / Scheduler (main_scheduler.py) — фоновый процесс на основе APScheduler. Регулярно запускается, обходит активные товары в БД, парсит актуальные цены (httpx + BeautifulSoup4), обновляет историю изменения цен (PriceHistory) и отправляет алерты пользователям в Telegram.

graph TD
    User([👨‍💻 Пользователь]) -->|/add URL| Bot[🤖 Telegram Bot]
    Bot -->|POST /api/v1/subscriptions| API[⚡ FastAPI]
    API -->|Read/Write| DB[(🗄️ SQLite / PostgreSQL)]
    Worker[🕰️ APScheduler Worker] -->|Fetch URLs| Internet[🌐 Internet Shops]
    Internet -->|Parse HTML| Worker
    Worker -->|Update Price| DB
    Worker -.->|Notify via Aiogram| User

Loading

---

🛠 Технологический стек

• Язык: Python 3.10+
• Авторизация: JWT (JSON Web Tokens)
• Web-фреймворк: FastAPI + Uvicorn
• База Данных и ORM: SQLModel (на базе SQLAlchemy 2.0), aiosqlite (полностью асинхронный драйвер)
• Миграции: Alembic
• Бот фреймворк: Aiogram 3.6+
• Парсинг и HTTP-запросы: HTTPX (Async), BeautifulSoup4
• Фоновые задачи: APScheduler

---

⚙️ Установка и запуск (Локально)

1. Клонирование и подготовка окружения

Убедитесь, что у вас установлен Python >= 3.10.

git clone https://github.com/ВАШ_НИК/smart-price-monitor.git
cd smart-price-monitor
python -m venv .venv

# Активация на Windows:
.\.venv\Scripts\activate
# Активация на macOS/Linux:
source .venv/bin/activate

pip install -r requirements.txt

2. Настройка переменных окружения

Скопируйте пример конфига в рабочий файл .env и добавьте свой токен от Telegram Бота. Подключением к базе можно оставить по умолчанию (sqlite+aiosqlite:///data/db.sqlite3).

cp .env.example .env

В файле .env:

BOT_TOKEN=123456789:ABCDEF...  # Ваш токен от @BotFather
DB_URL=sqlite+aiosqlite:///data/db.sqlite3
API_HOST=127.0.0.1
API_PORT=8000
SECRET_KEY=сгенерируйте_случайную_строку_для_jwt_здесь

3. Применение миграций базы данных

alembic upgrade head

Команда создаст папку data/ и файл db.sqlite3 с готовыми таблицами.

4. Запуск сервисов

Архитектура требует независимого запуска трех процессов. Вы можете запустить их в трех разных окнах терминала (обязательно с активированным виртуальным окружением .venv):

Терминал 1 (Web API):

uvicorn main_api:app --reload --host 127.0.0.1 --port 8000

Документация Swagger станет доступна по адресу http://127.0.0.1:8000/docs

Терминал 2 (Telegram Bot):

python main_bot.py

Терминал 3 (Background Scheduler/Parser):

python main_scheduler.py

---

🧪 Как протестировать парсинг без магии?

Интернет-магазины (Ozon, Wildberries) активно используют Cloudflare и динамический рендеринг (React/Vue), что мешает извлечь цену базовым HTTPX запросом (необходим Selenium/Playwright).

Для демонстрации работы сервиса в проекте зашита специальная mock-логика. Просто отправьте боту ссылку: http://example.com/item/1 и установите желаемую цену (например 4500 руб). Парсер искусственно сгенерирует случайную цену, и если она окажется ниже вашей цели, вы моментально получите push-уведомление от бота.

---

📝 Дополнительная информация

• Модель данных использует связь Many-to-Many (Один пользователь может следить за десятком товаров, а один товар могут отслеживать разные пользователи, каждый со своей целевой ценой).
• Проект полностью покрыт асинхронным кодом, включая сессии к базе данных (через sqlmodel и sqlalchemy.ext.asyncio).
• Проект может быть развернут через Docker Compose (API + Redis + Celery + DB), но текущий вариант специально упрощен до APScheduler + SQLite для быстрого демонстрационного развертывания проверяющим в пару кликов без установки Docker.