tg-bot.fun/README.md

BotFactory (tg-bot.fun)

SaaS-платформа для запуска Telegram-магазинов цифровых товаров. Владелец платформы регистрирует арендаторов (tenant), каждый арендатор получает магазин с двумя Telegram-ботами: бот управления (товары, реквизиты, кассиры, подтверждение оплат) и клиентский бот для покупателей (каталог, заказ, отправка чека, автовыдача товара после подтверждения). Платформа зарабатывает на комиссии с заказов по тарифам, включая индивидуальный постоплатный тариф с процентом от выручки предыдущего месяца.

Оплата принимается переводом на карту или по СБП: покупатель отправляет чек, кассир или владелец подтверждает заказ в боте управления, после чего клиентский бот автоматически выдаёт содержимое товара. Управление платформой доступно из платформенного бота-администратора и из веб-панели на React.

Продукт рассчитан на развёртывание одной командой на выделенный сервер Ubuntu 22.04/24.04 с доменом и SSL.

Исходные README автора сохранены: README.upstream.md (полное описание версий 2.1–2.2) и README_v2_2_1.md.

Стек

• Backend: Python, FastAPI, Uvicorn (uvloop), SQLAlchemy 2.0 async, asyncpg, Pydantic v2 / pydantic-settings
• Боты: aiogram 3.7, FSM-хранилище в Redis
• БД: PostgreSQL (создаётся установщиком); Redis — FSM и кэш
• Frontend: React 18, Vite 5, react-router-dom, axios; сборка в статику
• Инфраструктура: nginx (статика + reverse proxy /api/), certbot/Let's Encrypt, systemd (botfactory-api, botfactory-bots), UFW
• Внешний API: Telegram Bot API
• В зависимостях присутствуют alembic, passlib[bcrypt], python-jose, pillow, aiofiles — фактически в коде не используются

Структура

Путь	Назначение
install.sh	Интерактивный установщик на чистый сервер: пакеты, PostgreSQL, Redis, venv, .env, сборка фронта, nginx, SSL, systemd-юниты
scripts/repair_server.sh	Аварийное восстановление установки (права /opt/botfactory, пересборка фронта, перезапуск сервисов)
backend/main.py	FastAPI: /api/health, /api/version, /api/admin/overview и админ-действия (арендаторы, магазины, товары, карты, токены, кассиры, пополнение, смена тарифа, постоплата, блокировка, подтверждение/отклонение заказов)
backend/models.py	Модели: Tenant, Shop, ShopToken, ShopMember, Product, PaymentCard, Order, BalanceTransaction, перечисления PlanEnum и OrderStatus
backend/database.py	Async-engine, сессии, init_db() — create_all плюс «лёгкие миграции» через ALTER TABLE ... IF NOT EXISTS
backend/config.py	Настройки из /opt/botfactory/.env, ставки комиссий по тарифам, список Telegram ID администраторов
backend/billing.py	Тарифы, ставки комиссии, проверка права магазина продавать, срок триала, расчёт постоплаты за предыдущий месяц и дата платежа
backend/platform_bot.py	Платформенный админ-бот: статистика, пользователи, тарифы, балансы, заказы, постоплата, рассылка (~33 КБ кода)
backend/ctrl_bot.py	Бот управления магазином: товары, карты/СБП, кассиры, токены клиентских ботов, подтверждение оплат (~35 КБ кода)
backend/shop_bot.py	Клиентский бот магазина: каталог, оформление заказа, отправка чека, выдача товара
backend/shop_bots_runner.py	Супервизор ботов: запускает платформенный бот и по одному боту на магазин, следит за сменой токенов и перезапускает нужный бот без рестарта сервера, перезапуск с экспоненциальной задержкой при падении
frontend/src/App.jsx	Вся веб-панель одним файлом (~1400 строк): арендаторы, магазины, товары, заказы, тарифы, транзакции
frontend/vite.config.js, index.html, src/style.css	Конфигурация и оформление панели (тёмная тема)
VERSION	2.2.1

Как запустить

Продакшн-установка под root на чистом Ubuntu 22.04/24.04:

apt update
apt install -y git
cd /opt
git clone <repo-url> botfactory-src
cd botfactory-src
bash install.sh

Установщик спрашивает: домен (или Enter для установки по IP), email для SSL, нужен ли www в сертификате, получать ли SSL сразу, токен платформенного бота, Telegram ID администраторов, пароль PostgreSQL (или автогенерация), ставки комиссий по тарифам. Итоговые данные сохраняются в /opt/botfactory/install-info.txt.

Управление сервисами:

systemctl status botfactory-api
systemctl status botfactory-bots
journalctl -u botfactory-api -f
journalctl -u botfactory-bots -f

SSL после настройки DNS:

certbot --nginx -d <домен> --email <email> --agree-tos --redirect

Восстановление после сбоя:

cd /opt/botfactory-src
git pull origin main
bash scripts/repair_server.sh

Локальная разработка отдельно не описана и из репозитория не восстанавливается автоматически: backend/config.py жёстко читает env_file = "/opt/botfactory/.env", UPLOAD_DIR по умолчанию — /opt/botfactory/uploads, а .env.example в репозитории отсутствует. Для локального запуска придётся вручную создать /opt/botfactory/.env, поднять PostgreSQL и Redis, затем запускать uvicorn main:app из backend/ и npm run dev (порт 3000) из frontend/.

Отдельного шага миграций нет: при старте API выполняется create_all и набор безопасных ALTER TABLE. Alembic в зависимостях есть, но миграции не заведены.

Конфигурация

.env создаётся установщиком в /opt/botfactory/.env. Значения по умолчанию — в backend/config.py.

Переменная	Назначение	Пример
DEBUG	Режим отладки; включает /api/docs и SQL-эхо	false
SECRET_KEY	Секретный ключ приложения; генерируется установщиком через openssl rand -hex 32	см. .env
DATABASE_URL	Подключение к PostgreSQL	postgresql+asyncpg://botfactory:<пароль>@127.0.0.1:5432/botfactory
DB_POOL_SIZE	Размер пула соединений	20
REDIS_URL	Redis для FSM-хранилища ботов	redis://127.0.0.1:6379/0
PLATFORM_BOT_TOKEN	Токен платформенного админ-бота Telegram	см. .env
PLATFORM_ADMIN_IDS	Telegram ID администраторов через запятую	123456789,987654321
API_HOST / API_PORT	Адрес и порт API за nginx	127.0.0.1 / 8000
DOMAIN	Домен установки	tg-bot.fun
ALLOWED_ORIGINS	CORS-источники через запятую	http://localhost:3000,https://tg-bot.fun
UPLOAD_DIR	Каталог загрузок, отдаётся nginx по /uploads/	/opt/botfactory/uploads
MAX_UPLOAD_MB	Лимит размера загрузки	10
COMMISSION_TRIAL_WEEK	Комиссия тарифа «Тест 7 дней», %	10
COMMISSION_TRIAL	Комиссия тарифа Trial, %	10
COMMISSION_BASIC	Комиссия тарифа Basic, %	7
COMMISSION_PRO	Комиссия тарифа Pro, %	5
COMMISSION_ENTERPRISE	Комиссия тарифа Enterprise, %	3
COMMISSION_POSTPAID_DEFAULT	Комиссия индивидуального постоплатного тарифа, %	5
POSTPAID_DEFAULT_DUE_DAY	День месяца для постоплаты (1–28)	5

Токены ботов магазинов хранятся в таблице shop_tokens в БД, а не в .env. В API они отдаются маскированными.

Состояние

Рабочий продукт, доведённый до продакшн-развёртывания, но заброшенный сразу после релиза. Всего 5 коммитов, все от 2026-05-25 — репозиторий залит уже готовым кодом (v2.1 → v2.2.1) без истории разработки. Последний коммит — 2026-05-25 («Возвращен старый дизайн панели BotFactory v2.2.1»).

Кодовая база полная и связная: установщик, API, три типа ботов, супервизор, биллинг, веб-панель. Признаков реальной эксплуатации после мая 2026 в репозитории нет.

Что не доделано

• Админ-API полностью без авторизации. Ни один эндпоинт /api/admin/* в backend/main.py не требует аутентификации, а nginx проксирует /api/ без basic-auth. Любой, кто знает адрес сервера, может создавать арендаторов, пополнять балансы, менять тарифы, подтверждать заказы и читать данные. SECRET_KEY, passlib и python-jose присутствуют, но механизм входа не реализован. Это критическая проблема, требующая исправления до эксплуатации.
• Мёртвый код во фронтенде: константы INIT_TENANT, INIT_SHOPS, INIT_CARDS, INIT_ORDERS, INIT_TX, MOCK_PLATFORM_TENANTS объявлены в App.jsx, но нигде не используются — остатки удалённых демо-данных.
• Вся веб-панель — один файл App.jsx на ~1400 строк, без разбиения на компоненты и без роутинга по страницам.
• Alembic в зависимостях, но миграции ведутся вручную через ALTER TABLE ... IF NOT EXISTS в database.py; комментарий в коде прямо называет это временным решением «до появления полного Alembic-процесса».
• Тестов нет, CI нет, линтеров нет.
• Неиспользуемые зависимости: pillow, aiofiles, httpx, python-multipart, aioredis (устаревшая, конфликтует с redis 5.x).
• Проглатывание исключений без обработки: backend/platform_bot.py:440 (except Exception: pass), backend/platform_bot.py:706, backend/shop_bots_runner.py:47.
• Загрузка файлов: каталог uploads монтируется и отдаётся nginx, но эндпоинтов загрузки в API нет.
• Автоматических платежей нет: пополнение баланса арендатора и подтверждение оплат покупателей выполняются вручную администратором или кассиром.