diff --git a/README.md b/README.md index 60307e5..ad49307 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,73 @@ -# BotFactory v2.2 +# BotFactory (tg-bot.fun) -SaaS-платформа для Telegram-магазинов: платформенный админ-бот, боты управления магазинами, клиентские боты, FastAPI backend и React/Vite frontend. +SaaS-платформа для запуска Telegram-магазинов цифровых товаров. Владелец платформы регистрирует арендаторов (tenant), каждый арендатор получает магазин с двумя Telegram-ботами: бот управления (товары, реквизиты, кассиры, подтверждение оплат) и клиентский бот для покупателей (каталог, заказ, отправка чека, автовыдача товара после подтверждения). Платформа зарабатывает на комиссии с заказов по тарифам, включая индивидуальный постоплатный тариф с процентом от выручки предыдущего месяца. -## Что исправлено в v2.1 +Оплата принимается переводом на карту или по СБП: покупатель отправляет чек, кассир или владелец подтверждает заказ в боте управления, после чего клиентский бот автоматически выдаёт содержимое товара. Управление платформой доступно из платформенного бота-администратора и из веб-панели на React. -- Установщик больше не требует `python3.11` и `postgresql-14`. -- Поддержана чистая установка на Ubuntu 22.04 и 24.04 из стандартных репозиториев. -- Убран агрессивный `apt upgrade` во время установки. -- UFW больше не делает `reset`; установщик только добавляет правила 22/80/443. -- Платформенный бот вынесен из API-процесса в `botfactory-bots`, чтобы не запускать Telegram polling несколько раз. -- Исправлена выдача товара при подтверждении заказа из платформенного бота. -- При подтверждении заказа обновляются `stock`, `sold` и `received_total` карты. -- Активный клиентский бот магазина перезапускается при смене токена. -- Добавлен недельный тестовый тариф. -- Добавлен индивидуальный постоплатный тариф: процент от выручки предыдущего месяца + день оплаты, назначается только администратором вручную. -- Добавлены лёгкие миграции для новых полей биллинга. +Продукт рассчитан на развёртывание одной командой на выделенный сервер Ubuntu 22.04/24.04 с доменом и SSL. +Исходные README автора сохранены: `README.upstream.md` (полное описание версий 2.1–2.2) и `README_v2_2_1.md`. -## Hotfix v2.1.1 +## Стек -- Исправлены права `/opt/botfactory`, из-за которых nginx мог отдавать `500 Internal Server Error` на главной странице. -- Добавлена проверка `frontend/dist/index.html` после сборки. -- Сервис `botfactory-bots` больше не привязан к успешному старту API, только к сети/PostgreSQL/Redis. -- Добавлен аварийный скрипт восстановления: `scripts/repair_server.sh`. +- 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: + +```bash +apt update +apt install -y git +cd /opt +git clone botfactory-src +cd botfactory-src +bash install.sh +``` + +Установщик спрашивает: домен (или Enter для установки по IP), email для SSL, нужен ли `www` в сертификате, получать ли SSL сразу, токен платформенного бота, Telegram ID администраторов, пароль PostgreSQL (или автогенерация), ставки комиссий по тарифам. Итоговые данные сохраняются в `/opt/botfactory/install-info.txt`. + +Управление сервисами: + +```bash +systemctl status botfactory-api +systemctl status botfactory-bots +journalctl -u botfactory-api -f +journalctl -u botfactory-bots -f +``` + +SSL после настройки DNS: + +```bash +certbot --nginx -d <домен> --email --agree-tos --redirect +``` + +Восстановление после сбоя: ```bash cd /opt/botfactory-src @@ -32,120 +75,52 @@ git pull origin main bash scripts/repair_server.sh ``` -## Чистая установка на Ubuntu 22.04 +Локальная разработка отдельно не описана и из репозитория не восстанавливается автоматически: `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/`. -Под root: +Отдельного шага миграций нет: при старте API выполняется `create_all` и набор безопасных `ALTER TABLE`. Alembic в зависимостях есть, но миграции не заведены. -```bash -apt update -apt install -y git -cd /opt -git clone https://github.com/viktor138irk/tg-bot.fun.git botfactory-src -cd botfactory-src -bash install.sh -``` +## Конфигурация -Установщик спросит: +`.env` создаётся установщиком в `/opt/botfactory/.env`. Значения по умолчанию — в `backend/config.py`. -1. домен или Enter для установки по IP; -2. email для SSL; -3. нужно ли добавлять `www` в сертификат; -4. получить ли SSL сразу; -5. токен платформенного бота; -6. Telegram ID администраторов; -7. пароль PostgreSQL или автогенерацию; -8. комиссии по тарифам. +| Переменная | Назначение | Пример | +| --- | --- | --- | +| `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 они отдаются маскированными. -```bash -/opt/botfactory/install-info.txt -``` +## Состояние -## Управление сервисами +Рабочий продукт, доведённый до продакшн-развёртывания, но заброшенный сразу после релиза. Всего 5 коммитов, все от 2026-05-25 — репозиторий залит уже готовым кодом (v2.1 → v2.2.1) без истории разработки. Последний коммит — 2026-05-25 («Возвращен старый дизайн панели BotFactory v2.2.1»). -```bash -systemctl status botfactory-api -systemctl status botfactory-bots -systemctl restart botfactory-api -systemctl restart botfactory-bots -journalctl -u botfactory-api -f -journalctl -u botfactory-bots -f -``` +Кодовая база полная и связная: установщик, API, три типа ботов, супервизор, биллинг, веб-панель. Признаков реальной эксплуатации после мая 2026 в репозитории нет. -## SSL после настройки DNS +## Что не доделано -Если SSL не был получен во время установки, проверьте A-запись домена на IP сервера и выполните: - -```bash -certbot --nginx -d tg-bot.fun --email admin@tg-bot.fun --agree-tos --redirect -``` - -Если нужен `www`: - -```bash -certbot --nginx -d tg-bot.fun -d www.tg-bot.fun --email admin@tg-bot.fun --agree-tos --redirect -``` - -## Тарифы - -Стандартные тарифы: - -- `trial_week` — тест 7 дней; -- `trial`; -- `basic`; -- `pro`; -- `enterprise`. - -Индивидуальный тариф: - -- `postpaid_custom`; -- назначается только в платформенном боте администратором; -- комиссия считается как процент от выручки предыдущего месяца; -- день оплаты задаётся админом от 1 до 28; -- комиссия по заказам не списывается с баланса мгновенно, а начисляется в постоплату. - -## Структура ботов - -```text -Платформенный бот -└── статистика, пользователи, тарифы, балансы, заказы, постоплата, рассылка - -Магазин -├── Бот управления магазином -│ ├── товары -│ ├── карты/СБП -│ ├── кассиры -│ ├── токены клиентских ботов -│ └── подтверждение оплат -└── Клиентский бот магазина - ├── каталог - ├── создание заказа - ├── отправка чека - └── выдача товара после подтверждения -``` - -## Важно по безопасности - -Не публикуйте реальные Telegram bot token в GitHub, чатах и логах. Если токен уже засветился, перевыпустите его через BotFather. - - -## v2.2.0 - -- Демо-данные удалены из React-панели. -- Панель теперь читает реальные данные из PostgreSQL через `/api/admin/overview`. -- Добавлены рабочие API для создания пользователей, магазинов, товаров, карт, токенов бота магазина и кассиров. -- Добавлены API-действия: пополнение баланса, смена тарифа, назначение постоплаты, блокировка пользователя, активация резервного токена, подтверждение/отклонение заказов. -- Исправлен молчащий платформенный бот: aiogram больше не падает на `unexpected keyword argument dispatcher`. -- Исправлен повторный старт платформенного роутера после падения polling. -- Исправлены systemd service-файлы: `StartLimitIntervalSec` перенесён в `[Unit]`, добавлены `TimeoutStopSec` и `KillMode=mixed`. - -### Минимальная настройка после установки - -1. В веб-панели создайте пользователя-владельца. -2. Создайте магазин и укажите токен отдельного бота управления. -3. Добавьте токен покупательского бота магазина и сделайте его активным. -4. Добавьте карту/СБП-реквизиты. -5. Добавьте товар с контентом для автовыдачи. -6. Добавьте кассиров по Telegram ID, если нужны отдельные модераторы. -7. Перезапустите `botfactory-bots` или подождите до 30 секунд — runner сам подхватит магазин. +- **Админ-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 нет. +- Автоматических платежей нет: пополнение баланса арендатора и подтверждение оплат покупателей выполняются вручную администратором или кассиром. diff --git a/README.upstream.md b/README.upstream.md new file mode 100644 index 0000000..60307e5 --- /dev/null +++ b/README.upstream.md @@ -0,0 +1,151 @@ +# BotFactory v2.2 + +SaaS-платформа для Telegram-магазинов: платформенный админ-бот, боты управления магазинами, клиентские боты, FastAPI backend и React/Vite frontend. + +## Что исправлено в v2.1 + +- Установщик больше не требует `python3.11` и `postgresql-14`. +- Поддержана чистая установка на Ubuntu 22.04 и 24.04 из стандартных репозиториев. +- Убран агрессивный `apt upgrade` во время установки. +- UFW больше не делает `reset`; установщик только добавляет правила 22/80/443. +- Платформенный бот вынесен из API-процесса в `botfactory-bots`, чтобы не запускать Telegram polling несколько раз. +- Исправлена выдача товара при подтверждении заказа из платформенного бота. +- При подтверждении заказа обновляются `stock`, `sold` и `received_total` карты. +- Активный клиентский бот магазина перезапускается при смене токена. +- Добавлен недельный тестовый тариф. +- Добавлен индивидуальный постоплатный тариф: процент от выручки предыдущего месяца + день оплаты, назначается только администратором вручную. +- Добавлены лёгкие миграции для новых полей биллинга. + + +## Hotfix v2.1.1 + +- Исправлены права `/opt/botfactory`, из-за которых nginx мог отдавать `500 Internal Server Error` на главной странице. +- Добавлена проверка `frontend/dist/index.html` после сборки. +- Сервис `botfactory-bots` больше не привязан к успешному старту API, только к сети/PostgreSQL/Redis. +- Добавлен аварийный скрипт восстановления: `scripts/repair_server.sh`. + +### Быстрое восстановление на сервере + +```bash +cd /opt/botfactory-src +git pull origin main +bash scripts/repair_server.sh +``` + +## Чистая установка на Ubuntu 22.04 + +Под root: + +```bash +apt update +apt install -y git +cd /opt +git clone https://github.com/viktor138irk/tg-bot.fun.git botfactory-src +cd botfactory-src +bash install.sh +``` + +Установщик спросит: + +1. домен или Enter для установки по IP; +2. email для SSL; +3. нужно ли добавлять `www` в сертификат; +4. получить ли SSL сразу; +5. токен платформенного бота; +6. Telegram ID администраторов; +7. пароль PostgreSQL или автогенерацию; +8. комиссии по тарифам. + +После установки данные сохраняются в: + +```bash +/opt/botfactory/install-info.txt +``` + +## Управление сервисами + +```bash +systemctl status botfactory-api +systemctl status botfactory-bots +systemctl restart botfactory-api +systemctl restart botfactory-bots +journalctl -u botfactory-api -f +journalctl -u botfactory-bots -f +``` + +## SSL после настройки DNS + +Если SSL не был получен во время установки, проверьте A-запись домена на IP сервера и выполните: + +```bash +certbot --nginx -d tg-bot.fun --email admin@tg-bot.fun --agree-tos --redirect +``` + +Если нужен `www`: + +```bash +certbot --nginx -d tg-bot.fun -d www.tg-bot.fun --email admin@tg-bot.fun --agree-tos --redirect +``` + +## Тарифы + +Стандартные тарифы: + +- `trial_week` — тест 7 дней; +- `trial`; +- `basic`; +- `pro`; +- `enterprise`. + +Индивидуальный тариф: + +- `postpaid_custom`; +- назначается только в платформенном боте администратором; +- комиссия считается как процент от выручки предыдущего месяца; +- день оплаты задаётся админом от 1 до 28; +- комиссия по заказам не списывается с баланса мгновенно, а начисляется в постоплату. + +## Структура ботов + +```text +Платформенный бот +└── статистика, пользователи, тарифы, балансы, заказы, постоплата, рассылка + +Магазин +├── Бот управления магазином +│ ├── товары +│ ├── карты/СБП +│ ├── кассиры +│ ├── токены клиентских ботов +│ └── подтверждение оплат +└── Клиентский бот магазина + ├── каталог + ├── создание заказа + ├── отправка чека + └── выдача товара после подтверждения +``` + +## Важно по безопасности + +Не публикуйте реальные Telegram bot token в GitHub, чатах и логах. Если токен уже засветился, перевыпустите его через BotFather. + + +## v2.2.0 + +- Демо-данные удалены из React-панели. +- Панель теперь читает реальные данные из PostgreSQL через `/api/admin/overview`. +- Добавлены рабочие API для создания пользователей, магазинов, товаров, карт, токенов бота магазина и кассиров. +- Добавлены API-действия: пополнение баланса, смена тарифа, назначение постоплаты, блокировка пользователя, активация резервного токена, подтверждение/отклонение заказов. +- Исправлен молчащий платформенный бот: aiogram больше не падает на `unexpected keyword argument dispatcher`. +- Исправлен повторный старт платформенного роутера после падения polling. +- Исправлены systemd service-файлы: `StartLimitIntervalSec` перенесён в `[Unit]`, добавлены `TimeoutStopSec` и `KillMode=mixed`. + +### Минимальная настройка после установки + +1. В веб-панели создайте пользователя-владельца. +2. Создайте магазин и укажите токен отдельного бота управления. +3. Добавьте токен покупательского бота магазина и сделайте его активным. +4. Добавьте карту/СБП-реквизиты. +5. Добавьте товар с контентом для автовыдачи. +6. Добавьте кассиров по Telegram ID, если нужны отдельные модераторы. +7. Перезапустите `botfactory-bots` или подождите до 30 секунд — runner сам подхватит магазин.