docs: подробный README (разбор проекта при переносе в Gitea)

Старый README сохранён как README.upstream.md.
Этот коммит содержится в:
2026-08-20 04:18:34 +09:00
родитель 717274d1c0
Коммит 6ba7afc7c6
2 изменённых файлов: 253 добавлений и 127 удалений
+102 -127
Просмотреть файл
@@ -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 <repo-url> 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 <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 нет.
- Автоматических платежей нет: пополнение баланса арендатора и подтверждение оплат покупателей выполняются вручную администратором или кассиром.
+151
Просмотреть файл
@@ -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 сам подхватит магазин.