🛍️ WB Position Bot

Telegram-бот для отслеживания позиций товаров на Wildberries

Мощный инструмент для продавцов на Wildberries, позволяющий автоматически отслеживать позиции своих товаров в поисковой выдаче по различным запросам с учётом региона и типа устройства.

---

📋 Возможности

• 🔍 Автоматическое отслеживание — проверка позиций каждые 10 минут
• 🔔 Умные уведомления — оповещения при падении позиции ниже порога
• 📦 Управление артикулами — добавление, удаление, просмотр товаров
• 🗺️ Региональный поиск — выбор федерального округа и города
• 📱 Поддержка устройств — отслеживание для PC, Android, iOS
• ⚙️ Гибкие настройки — индивидуальные пороги для каждой фразы
• ✅ Ручная проверка — мгновенная проверка позиций одного или всех товаров

---

🚀 Быстрый старт

Требования

• Python 3.11 или выше
• PostgreSQL 13 или выше
• Telegram Bot Token (получить у @BotFather)

Установка

1. Клонируйте репозиторий:

   git clone https://github.com/your-username/WbPositionBot.git
   cd WbPositionBot

2. Создайте виртуальное окружение:

   python -m venv .venv
   
   # Windows:
   .venv\Scripts\activate
   
   # Linux/MacOS:
   source .venv/bin/activate

3. Установите зависимости:

   pip install -r requirements.txt

4. Настройте окружение:

   Создайте файл .env в корне проекта:

   # Обязательные параметры
   TELEGRAM_TOKEN=your_bot_token_here
   DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/wb_bot
   
   # Опциональные параметры
   SCHEDULER_ENABLED=true
   DEFAULT_DEVICE=pc
   
   # Для режима webhook (опционально)
   WEBHOOK_URL=https://your-domain.com/webhook
   WEBHOOK_SECRET=your_secret_token
   APP_HOST=0.0.0.0
   PORT=8080
   
   # Для внешнего cron (опционально)
   CRON_SECRET=your_cron_secret

5. Создайте базу данных:

   CREATE DATABASE wb_bot;

6. Запустите бота:

   python bot.py

---

📖 Использование

Основные команды

• /start — Запуск бота и отображение главного меню
• /cancel — Отмена текущей операции

Функции бота

📦 Управление артикулами

1. Нажмите "📦 Артикулы"
2. Добавьте артикул (SKU товара)
3. Укажите поисковые фразы для отслеживания
4. Задайте пороговые позиции

🔎 Ручная проверка

1. Нажмите "🔎 Проверить позиции"
2. Выберите артикул или проверьте все сразу
3. Получите актуальные позиции с изображениями товаров

⚙️ Настройки

• Автообновление — включение/выключение автоматической проверки
• Устройство — выбор типа устройства (PC, Android, iOS)
• Регион — выбор федерального округа и города

---

🛠️ Вспомогательные скрипты

Получение dest кода региона

Используйте скрипт для получения кода региона по координатам:

python scripts/fetch_dest.py 55.7558 37.6176 Москва

Параметры:

• 55.7558 — широта
• 37.6176 — долгота
• Москва — название города

Сброс базы данных

python scripts/reset_db.py

⚠️ Внимание: Это удалит все данные из схемы wbpos!

---

🌐 Развертывание

Режим Polling (по умолчанию)

Просто запустите бота — он будет опрашивать Telegram API:

python bot.py

Режим Webhook

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

   WEBHOOK_URL=https://your-domain.com/webhook
   WEBHOOK_SECRET=your_secret_token

2. Запустите бота — он автоматически переключится в режим webhook.

Развертывание на Render.com

1. Создайте Background Worker
2. Укажите команду запуска: python bot.py
3. Добавьте переменные окружения из .env
4. Подключите PostgreSQL базу данных (Render предоставляет бесплатно)
5. Настройте Cron Job для внешнего триггера (опционально):

   GET https://your-app.onrender.com/cron?s=your_cron_secret
   

Развертывание на других платформах

Бот совместим с любыми платформами, поддерживающими Python и PostgreSQL:

• Heroku — используйте Procfile
• Railway — автоопределение Python проекта
• DigitalOcean — App Platform или Droplet
• VPS/Dedicated — systemd service

---

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

WbPositionBot/
├── app/
│   ├── config.py           # Настройки приложения
│   ├── scheduler.py        # Планировщик задач
│   ├── states.py           # FSM состояния
│   ├── data/
│   │   └── regions.py      # Справочник регионов
│   ├── db/
│   │   ├── base.py         # Настройка БД
│   │   └── models.py       # ORM модели
│   ├── handlers/
│   │   ├── start.py        # Главное меню
│   │   ├── articles.py     # Управление артикулами
│   │   ├── tracking.py     # Управление отслеживанием
│   │   ├── settings.py     # Настройки пользователя
│   │   └── manual_check.py # Ручная проверка
│   └── services/
│       ├── wb_client.py    # Клиент Wildberries API
│       └── tracker.py      # Логика отслеживания
├── scripts/
│   ├── fetch_dest.py       # Получение dest кода
│   └── reset_db.py         # Сброс БД
├── bot.py                  # Точка входа
├── requirements.txt        # Зависимости
├── runtime.txt             # Версия Python
├── render.yaml             # Конфигурация Render
└── README.md               # Документация

---

🗄️ База данных

Схема wbpos

Таблица users

• Хранит настройки пользователей
• Регион, устройство, флаг автообновления

Таблица articles

• Артикулы товаров пользователей
• Связь один-ко-многим с пользователями

Таблица trackings

• Поисковые фразы и пороги
• История проверок и уведомлений

---

🔧 Технологии

• aiogram 3.x — асинхронный фреймворк для Telegram Bot API
• SQLAlchemy 2.x — ORM для работы с БД
• asyncpg — асинхронный драйвер PostgreSQL
• APScheduler — планировщик задач
• aiohttp — асинхронный HTTP клиент/сервер
• Pydantic — валидация настроек
• loguru — удобное логирование

---

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

Добавление артикула с фразами

1. Нажмите "📦 Артикулы" → "➕ Добавить"
2. Введите SKU: 12345678
3. Введите фразы:
   кроссовки мужские=20
   кроссовки nike=15
   спортивная обувь=30
4. Готово! Бот начнёт отслеживание

Настройка региона

1. Нажмите "⚙️ Настройки" → "🗺️ Регион"
2. Выберите "Центральный"
3. Выберите "Москва"
4. Регион сохранён