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

Старый README сохранён как README.upstream.md.
2026-08-20 04:18:34 +09:00
@@ -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 сам подхватит магазин.