Seller Bot — это многофункциональный Telegram-бот, предназначенный для создания интернет-магазина цифровых товаров. Платформа позволяет продавать товары с различными моделями доступа: разовая покупка, подписка (с разными сроками действия), а также предлагать бесплатные товары.
- Telegram Bot API:
aiogram 3.x - База данных:
MySQL - ORM:
SQLAlchemy(с асинхронным драйвером, например,aiomysql) - Миграции БД:
Alembic - Конфигурация:
pydantic-settings(для.envфайлов) - Платежи:
aiocryptopay(CryptoBot), Telegram Stars API - Логирование: Стандартный модуль
loggingPython - Форматирование кода:
black,isort - Типизация:
mypy(рекомендуется для проверки)
- 🛒 Каталог товаров: Просмотр товаров с описаниями, ценами и изображениями.
- 💸 Покупка: Возможность купить товар или оформить подписку.
- 🏪 Пользовательский маркетплейс: Пользователи могут выставлять собственные цифровые товары на продажу (кроме подписок).
- ⭐ Отзывы: Возможность оставлять отзывы (оценка 1-5 звезд + текст) на продавцов после покупки их товаров.
- 👤 Личный кабинет:
- Управление профилем: установка кастомного отображаемого ника.
- Просмотр баланса (в долларах и рублях, с автообновлением курса).
- История покупок.
- История пополнений.
- История продаж (для своих товаров).
- Управление своими лотами на маркетплейсе.
- 💰 Пополнение баланса:
- Через CryptoBot (
aiocryptopay). - Через Telegram Stars (по курсу, установленному администратором).
- Через CryptoBot (
↔️ Перевод средств: Возможность отправлять деньги другим пользователям внутри бота.- 🎟️ Промокоды: Система промокодов для получения:
- Баланса.
- Бесплатных продуктов (в том числе на определенный срок).
- Скидок (на конкретный товар или на все товары).
- Бонусов к пополнению.
- 🔗 Реферальная система (5 уровней):
- Начальный: 3% на баланс от пополнений рефералов (доступно сразу).
- Продвинутый: 5% (от 5 рефералов + общая сумма их пополнений > $10).
- Профи: 10% (от 10 рефералов + общая сумма их пополнений > $30).
- Мастер: 15% (от 20 рефералов + общая сумма их пополнений > $50).
- Гуру: 20% + вечная скидка 25% на все платные товары и подписки площадки (от 50 рефералов + общая сумма их пополнений > $150).
- 📚 Категории товаров: Множество категорий для цифровых товаров (ПО, аккаунты, услуги, подписки и т.д.).
- 📞 Поддержка: Ссылка на пользователя-саппорта.
- ℹ️ Информация о боте: Отдельная секция с подробной информацией.
- 🌐 Смена языка: Система для поддержки нескольких языков (до 10 в будущем).
| Уровень Доступа | Возможности |
|---|---|
| 👑 Owner | Функции админа + полный доступ к управлению товарами площадки (добавление, редактирование, цены, варианты подписок), управление категориями, настройка курса Stars, управление промокодами, просмотр полной статистики, рассылки и оповещения. |
| 🛡️ Admin | Функции модератора + управление модераторами (добавление/удаление) + бан пользователей + отслеживание действий модераторов. |
| 🕵️ Moderator | Удаление лотов пользователей, нарушающих правила. |
- 🛍️ Управление товарами площадки: Добавление, редактирование, настройка цен, изображений, описаний, вариантов подписок.
- ⚖️ Разделение товаров: Товары площадки и товары пользователей управляются и отображаются раздельно.
- Асинхронность: Приложение полностью асинхронное.
- Курс валют: Автоматическое обновление курса рубля к доллару каждый час (по данным ЦБ РФ или другого надежного API).
- Логирование: Подробное логирование всех ключевых событий в боте.
- Разметка: Использование HTML-разметки для сообщений с применением смайликов для стилизации.
- CRUD API: Внутренний API (
app/db/crud.py) для удобной работы с запросами к БД.
seller_bot/
├── .venv/ # Виртуальное окружение Python
├── app/ # Основной код приложения
│ ├── __init__.py
│ ├── admin/ # Админ-панель
│ │ ├── __init__.py
│ │ ├── handlers.py
│ │ ├── keyboards.py
│ │ └── states.py
│ ├── common/ # Общие утилиты, константы, сервисы
│ │ ├── __init__.py
│ │ ├── constants.py
│ │ ├── middlewares/ # Общие middleware (не специфичные для aiogram)
│ │ ├── services/ # Вспомогательные общие сервисы
│ │ └── utils.py
│ ├── config/ # Конфигурация бота
│ │ ├── __init__.py
│ │ └── settings.py # Загрузка и валидация настроек из .env
│ ├── db/ # База данных
│ │ ├── __init__.py
│ │ ├── crud.py # CRUD-операции
│ │ ├── models.py # Модели SQLAlchemy
│ │ └── database.py # Настройка подключения, сессии
│ ├── handlers/ # Обработчики Telegram-событий
│ │ ├── __init__.py
│ │ ├── user_commands.py # /start, /profile, /help
│ │ ├── payments.py # Пополнения, выводы, история
│ │ ├── products.py # Каталог, покупки
│ │ ├── marketplace.py # Пользовательский маркет
│ │ └── referrals.py # Реферальная система
│ ├── keyboards/ # Генерация клавиатур
│ │ ├── __init__.py
│ │ ├── inline.py
│ │ └── reply.py
│ ├── locales/ # Файлы локализации (i18n)
│ │ ├── en/LC_MESSAGES/messages.po
│ │ └── ru/LC_MESSAGES/messages.po
│ ├── services/ # Основная бизнес-логика
│ │ ├── __init__.py
│ │ ├── payment_service.py
│ │ ├── product_service.py
│ │ ├── referral_service.py
│ │ └── user_service.py
│ ├── states/ # Состояния FSM
│ │ ├── __init__.py
│ │ └── user_states.py
│ ├── main.py # Точка входа для запуска бота
│ └── middlewares/ # Специфичные для aiogram middleware
│ ├── __init__.py
│ └── i18n_middleware.py # Middleware для интернационализации
├── migrations/ # Миграции базы данных (Alembic)
│ ├── versions/
│ ├── env.py
│ └── script.py.mako
├── tests/ # Автоматические тесты (pytest)
│ ├── __init__.py
│ └── ... # Файлы тестов
├── .env.example # Пример файла с переменными окружения
├── .gitignore # Игнорируемые Git файлы
├── alembic.ini # Конфигурация Alembic
├── requirements.txt # Зависимости Python
├── PRJ.md # Этот файл :)
└── README.md # Оригинальный README (можно удалить или оставить как краткую версию)
Соблюдение этих правил поможет обеспечить консистентность, читаемость и простоту поддержки кода.
- Язык идентификаторов: Все названия в коде (
переменные,функции,классыи т.д.) – на английском языке. - Комментарии и документация: Могут быть на русском для лучшего понимания. Публичные API – на английском.
- Стиль именования:
- Переменные и функции:
snake_case(e.g.,user_balance). - Классы:
CamelCase(e.g.,ProductItem). - Константы:
UPPER_SNAKE_CASE(e.g.,DEFAULT_CURRENCY). - Файлы и модули:
snake_case.py. - Пакеты (директории):
snake_case.
- Переменные и функции:
- PEP 8: Строгое соблюдение.
- Автоформатирование:
blackдля кода.isortдля импортов.- Настройте IDE на автоприменение при сохранении.
- Длина строки: 100-120 символов.
- Отступы: 4 пробела.
- Пустые строки: Для разделения логических блоков.
- Обязательно: Для всех публичных модулей, функций, классов, методов.
- Формат: Google Style или reStructuredText.
- Содержание: Назначение, аргументы, возвращаемые значения, исключения.
- Пример (Google Style):
def get_user_by_id(user_id: int, db_session: AsyncSession) -> User | None: """Fetches a user by their unique identifier. Args: user_id: The unique identifier of the user. db_session: The SQLAlchemy asynchronous session. Returns: The User object if found, otherwise None. """ # ... implementation ...
- Пример (Google Style):
- Внутристрочные комментарии: Объясняют почему код такой, а не что он делает.
- Обязательно: Для аргументов функций, возвращаемых значений, переменных.
- Улучшает читаемость, помогает статическим анализаторам (
mypy) и ИИ-ассистентам. - Используйте модуль
typing(List,Dict,Optional, etc.).
- Модуль
logging: Стандартный модуль Python. - Конфигурация: При запуске приложения.
- Уровни:
DEBUG,INFO,WARNING,ERROR,CRITICAL. - Содержание: Информативно, с контекстом (
user_id,error_details). - Формат: Временная метка, уровень, имя логгера, сообщение.
- Модели:
app/db/models.py. Имена таблиц: множественное число,snake_case(e.g.,users). - CRUD-операции: Инкапсулированы в
app/db/crud.py.- Принимают сессию SQLAlchemy.
- Асинхронные, если используется
aiomysql.
- Сессии БД: Управляются через
async_sessionmaker, передаются в CRUD и сервисы. - Миграции:
Alembic. Новая миграция при изменении моделей. - Асинхронность: Использовать асинхронный драйвер (e.g.,
aiomysql) иasyncSQLAlchemy.
- Переменные окружения: Для всех конфигурационных параметров.
- Файл
.env: Для локальной разработки (добавить в.gitignore). - Файл
.env.example: Шаблон необходимых переменных. - Загрузка и валидация:
pydantic-settingsвapp/config/settings.py.
- Разделение логики: Хэндлеры, клавиатуры, состояния (FSM), бизнес-логика (сервисы).
- Роутеры:
aiogram.Routerдля структурирования хэндлеров. - FSM: Для многошаговых диалогов.
- Клавиатуры: Генерация в
app/keyboards/. - HTML-разметка: Для форматирования сообщений.
- Middleware: Для сквозных задач (логирование, i18n, передача сессии БД).
- Планирование: С самого начала.
- Инструменты:
aiogram.contrib.middlewares.i18n.I18nMiddlewareилиfluentogram. - Строки: Оборачивать в функцию перевода (e.g.,
_("Some text")). - Файлы локализации:
.poфайлы вapp/locales/.
- Функции в
app/db/crud.py– внутренний API для доступа к данным. - Сервисный слой (
app/services/) использует CRUD-функции.
- Unit-тесты: Для бизнес-логики, сервисов, CRUD.
- Интеграционные тесты: Для проверки взаимодействия компонентов.
- Фреймворк:
pytest.
- KISS: Простой, понятный код.
- Модульность и Низкая Связность.
- Высокая Сплоченность.
- DRY (Don't Repeat Yourself).
- Читаемость.
- Консистентность.
- Явное лучше неявного.
- Осмысленные коммиты.
- Атомарные коммиты.
- Ветвление:
feature/имя-фичи,fix/описание-фикса. - Pull/Merge Requests: Для ревью кода.
(Здесь будут инструкции по установке зависимостей, настройке .env файла и запуску бота - будут добавлены позже)
# Пример команд для запуска (будет уточнено)
pip install -r requirements.txt
# Настройте .env файл на основе .env.example
alembic upgrade head
python app/main.pyЭтот документ является объединенной версией README.md, PROJECT_STRUCTURE.md и CODING_GUIDELINES.md.
Online store of digital goods -> Aiogram-based marketplace