docs: подробный README (разбор проекта при переносе в Gitea)
Старый README сохранён как README.upstream.md.
Этот коммит содержится в:
+71
-76
@@ -1,103 +1,98 @@
|
||||
# BotShop v0.2.1
|
||||
# BotShop — панель управления несколькими Telegram-магазинами
|
||||
|
||||
BotShop — локальная платформа для запуска нескольких Telegram-магазинов из одной панели управления.
|
||||
Однопользовательская веб-панель на PHP, из которой обслуживается сразу несколько Telegram-ботов-магазинов. Каждому боту заводятся свои города, районы, товары, варианты и платёжные реквизиты; покупатель проходит в боте цепочку «город → район → товар → вариант → подтверждение» и получает карточку заказа с уникальной суммой к оплате (цена плюс случайная надбавка), оператор подтверждает поступление оплаты вручную в панели, после чего бот сообщает покупателю о подтверждении. Автоматической сверки платежей и приёма чеков нет по замыслу — решение принимает человек.
|
||||
|
||||
Проект рассчитан на легальную продажу цифровых и физических товаров: файлы, доступы, инструкции, мерч, услуги, коды, подписки, инфопродукты.
|
||||
Проект не связан с радиотематикой остальных репозиториев владельца и стоит отдельно.
|
||||
|
||||
## Безопасный scope
|
||||
## Стек
|
||||
|
||||
В проекте реализуется обычный магазин:
|
||||
- PHP 8 без фреймворка и без Composer: один файл-роутер `public/index.php` (панель + webhook), PDO/MySQL.
|
||||
- MySQL/MariaDB, схема в `database/schema.sql`.
|
||||
- Nginx + php-fpm (настраивается установщиком), systemd-юнит для polling-воркера.
|
||||
- Telegram Bot API (`https://api.telegram.org`) — два режима: webhook и long polling через `getUpdates`.
|
||||
- Frontend: серверный HTML со встроенным CSS прямо в `index.php`, без JS-сборки.
|
||||
|
||||
- несколько Telegram-ботов в одной панели;
|
||||
- каталог товаров;
|
||||
- выбор города и зоны доставки;
|
||||
- выбор товара и варианта;
|
||||
- итоговая карточка заказа;
|
||||
- баланс пользователя;
|
||||
- реферальная программа;
|
||||
- последний заказ;
|
||||
- связь с поддержкой;
|
||||
- ручная проверка оплаты оператором;
|
||||
- выдача цифрового товара только после подтверждённой оплаты;
|
||||
- журнал действий администратора и платежных решений.
|
||||
## Структура
|
||||
|
||||
Не реализуется:
|
||||
| Путь | Назначение |
|
||||
|---|---|
|
||||
| `install.sh` | Автоустановщик для Ubuntu/Debian: пакеты, MySQL, база и пользователь, импорт схемы, `storage/config.php`, учётка администратора, vhost Nginx, systemd-сервис `botshop-polling`. Разбирает опции `--local`, `--dir`, `--db-*`, `--admin-*`, `--no-polling`. |
|
||||
| `public/index.php` | Всё приложение: сессии, вход, дашборд, разделы «Боты / Города / Районы / Товары / Варианты / Реквизиты / Заказы / Логи», страница установки `/install`, обработчик Telegram-webhook `/webhook/<секрет>`. |
|
||||
| `public/.htaccess` | Rewrite всех запросов на `index.php` (для Apache; установщик настраивает Nginx, где то же делается через `try_files`). |
|
||||
| `scripts/polling.php` | Демон для работы без домена и SSL: раз за разом опрашивает `getUpdates` по всем активным ботам, повторяет логику диалога из `index.php`, хранит offset'ы в `storage/polling_offsets.json`, помечает просроченные заказы. |
|
||||
| `database/schema.sql` | 15 таблиц: `users`, `bots`, `bot_users`, `balance_ledger`, `shop_cities`, `shop_districts`, `shop_products`, `shop_product_variants`, `shop_stock_items`, `shop_payment_methods`, `shop_orders`, `shop_payments`, `support_tickets`, `telegram_updates`, `audit_logs`, `admin_logs`. |
|
||||
| `VERSION` | Версия панели (`0.1.1`). |
|
||||
| `storage/` | Создаётся установщиком, в git не хранится: `config.php` с реквизитами БД, логи, offset'ы polling. |
|
||||
| `README.upstream.md` | Прежний README автора: описание сценария заказа, статусов и заявленного «безопасного scope» магазина. |
|
||||
|
||||
- продажа запрещённых товаров;
|
||||
- скрытые адреса и тайники;
|
||||
- автоматическое признание оплаты только по нажатию пользователя;
|
||||
- обход платёжных правил;
|
||||
- анонимная схема без проверяемого учёта.
|
||||
## Как запустить
|
||||
|
||||
## Логика заказа
|
||||
|
||||
1. Пользователь открывает бота.
|
||||
2. Видит главное меню: каталог, баланс, рефералка, последний заказ, поддержка.
|
||||
3. Выбирает город.
|
||||
4. Выбирает зону доставки.
|
||||
5. Выбирает товар.
|
||||
6. Выбирает вариант.
|
||||
7. Получает итоговую карточку заказа.
|
||||
8. Выбирает действие: оплатить или отменить.
|
||||
9. После сообщения о платеже заказ уходит оператору на проверку.
|
||||
10. Оператор подтверждает оплату в панели.
|
||||
11. Система выдаёт цифровой товар из остатков и пишет событие в аудит.
|
||||
|
||||
## Статусы заказа
|
||||
|
||||
- `draft` — черновик;
|
||||
- `waiting_payment` — ожидает оплату;
|
||||
- `payment_review` — ожидает проверки оператором;
|
||||
- `paid` — оплата подтверждена;
|
||||
- `delivered` — товар выдан;
|
||||
- `cancelled` — отменён;
|
||||
- `refunded` — возвращён;
|
||||
- `expired` — истёк срок оплаты;
|
||||
- `rejected` — отклонён.
|
||||
|
||||
## Установка
|
||||
Установка на чистый сервер (от root):
|
||||
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install -y git curl
|
||||
cd /root
|
||||
git clone https://github.com/viktor138irk/bot.git botshop-installer
|
||||
git clone <адрес репозитория> botshop-installer
|
||||
cd botshop-installer
|
||||
sudo bash install.sh --local
|
||||
```
|
||||
|
||||
После установки:
|
||||
В конце установщик печатает адрес админки (`http://IP/login`), email и сгенерированный пароль администратора, имя базы и пароль БД — их нужно сохранить.
|
||||
|
||||
```text
|
||||
Админка: http://IP-СЕРВЕРА/login
|
||||
Email: admin@local.test
|
||||
Пароль: сгенерированный пароль
|
||||
```
|
||||
Ручная установка без `install.sh`: создать базу, залить `database/schema.sql`, направить веб-сервер на каталог `public/`, открыть `/install` и заполнить форму — страница сама создаст `storage/config.php` и администратора.
|
||||
|
||||
## Локальный режим
|
||||
|
||||
В локальном режиме домен и SSL не нужны. Telegram работает через polling-сервис:
|
||||
Локальный режим (без домена и SSL) работает через polling:
|
||||
|
||||
```bash
|
||||
systemctl status botshop-polling --no-pager
|
||||
journalctl -u botshop-polling -f
|
||||
```
|
||||
|
||||
## Структура
|
||||
Режим webhook: добавить бота в разделе «Боты» и нажать «Установить webhook» — панель вызовет `setWebhook` на адрес `<схема>://<хост>/webhook/<webhook_secret>`. Telegram требует HTTPS, поэтому этот режим применим только на домене с сертификатом; в репозитории настройки SSL нет.
|
||||
|
||||
```text
|
||||
install.sh # автоустановщик
|
||||
public/index.php # веб-панель и webhook endpoint
|
||||
scripts/polling.php # локальный Telegram polling worker
|
||||
database/schema.sql # схема базы
|
||||
storage/config.php # создаётся installer'ом, не хранится в git
|
||||
storage/logs/ # логи
|
||||
```
|
||||
Важно: `install.sh` не устанавливает код из текущего каталога — он клонирует и обновляет `https://github.com/viktor138irk/bot.git`. После переезда на Gitea переменную `REPO_URL` в начале `install.sh` нужно поменять, иначе установка и `git pull` будут тянуть старый репозиторий с GitHub.
|
||||
|
||||
## Roadmap
|
||||
## Конфигурация
|
||||
|
||||
- v0.2.1 — безопасный scope, совместимость схемы, главное меню бота;
|
||||
- v0.2.2 — раздел остатков и выдачи цифрового товара;
|
||||
- v0.2.3 — операторская проверка оплаты и аудит;
|
||||
- v0.2.4 — поддержка в панели;
|
||||
- v0.3.0 — роли операторов, улучшенный UI и журнал действий.
|
||||
Переменных окружения нет. Настройки задаются двумя способами.
|
||||
|
||||
1. Файл `storage/config.php` (создаётся установщиком или страницей `/install`, в git не попадает):
|
||||
|
||||
| Ключ | Назначение | Пример |
|
||||
|---|---|---|
|
||||
| `db_host` | Хост MySQL | `localhost` |
|
||||
| `db_name` | Имя базы | `botshop` |
|
||||
| `db_user` | Пользователь БД | `botshop_user` |
|
||||
| `db_pass` | Пароль БД | см. `storage/config.php` |
|
||||
|
||||
2. Параметры установщика (`install.sh`): `--dir` (каталог установки, по умолчанию `/var/www/botshop`), `--db-name`, `--db-user`, `--db-pass`, `--admin-email` (по умолчанию `admin@local.test`), `--admin-pass`, `--no-polling`. Пароли БД и администратора при отсутствии генерируются из 24 символов.
|
||||
|
||||
3. Настройки бота — в панели, раздел «Боты», хранятся в таблице `bots`:
|
||||
|
||||
| Поле | Назначение | Значение по умолчанию |
|
||||
|---|---|---|
|
||||
| `token` | Токен Telegram-бота, хранится в базе в открытом виде | — |
|
||||
| `webhook_secret` | Случайный сегмент URL webhook | генерируется |
|
||||
| `status` | `active` / `paused` / `error`; polling-воркер берёт только `active` | `paused` |
|
||||
| `welcome_text` | Первое сообщение бота | «Выберите город:» |
|
||||
| `min_add`, `max_add` | Диапазон случайной надбавки к сумме заказа, рублей | 1 и 19 |
|
||||
| `order_ttl_minutes` | Срок жизни заказа до статуса `expired` | 30 |
|
||||
| `referral_percent`, `*_pay_enabled`, `referral_enabled` | Поля в схеме есть, кодом не используются | — |
|
||||
|
||||
## Состояние
|
||||
|
||||
Прототип, заброшенный на ранней стадии. Все 14 коммитов сделаны в один день — 2026-05-18, последний коммит 2026-05-18.
|
||||
|
||||
Рабочей является только базовая ветка сценария: добавление бота, справочники, оформление заказа, ручное подтверждение оплаты оператором. Схема базы (коммит «Расширена схема под баланс рефералку и автовыдачу») ушла заметно дальше кода: баланс, рефералы, склад цифровых товаров, платежи и тикеты поддержки описаны в SQL, но ни панель, ни воркер с этими таблицами не работают. `VERSION` содержит `0.1.1`, `README.upstream.md` — `0.2.1`; фактическому коду соответствует 0.1.1.
|
||||
|
||||
## Что не доделано
|
||||
|
||||
- Расхождение статусов заказа между кодом и схемой. В `schema.sql` статус называется `waiting_payment`, а `public/index.php` и `scripts/polling.php` фильтруют по `status='waiting_pay'`. Из-за этого не работают: пометка просроченных заказов, счётчик «Ожидают оплату» на дашборде, кнопки «Оплачено»/«Отклонить» в списке заказов (условие `$r['status']==='waiting_pay'` никогда не выполняется) и проверка уникальности суммы в `generateAmount()`. Это первое, что нужно чинить.
|
||||
- Статусы `payment_review`, `delivered`, `refunded`, `rejected` из схемы кодом не выставляются; после `paid` заказ никуда не двигается, автовыдача товара из `shop_stock_items` не реализована.
|
||||
- Не реализованы: баланс (`balance_ledger`), реферальная программа, поддержка (`support_tickets`), журнал `audit_logs`/`admin_logs`, оплата с баланса и BTC, оплата картой через провайдера. В боте нет главного меню, команды `/start` не различаются — любое сообщение сбрасывает диалог на выбор города.
|
||||
- В панели нет редактирования и удаления записей: разделы городов, районов, товаров, вариантов и реквизитов умеют только добавлять и показывать список. Нет пагинации (жёсткие `LIMIT 200`/`LIMIT 300`), нет поиска и фильтров.
|
||||
- Действия «Оплачено» и «Отклонить» выполняются GET-ссылками без CSRF-проверки, тогда как формы токен проверяют.
|
||||
- Ролей нет: поле `users.role` есть, но код проверяет только факт входа; учётка администратора одна.
|
||||
- Логи `storage/logs/` создаются, но приложение в них ничего не пишет; ошибки polling идут в journald, ошибки панели — в лог PHP.
|
||||
- Тестов, CI, линтеров и файла зависимостей нет. Маркеров TODO/FIXME в коде нет.
|
||||
- Токены ботов и платёжные реквизиты (номера карт, телефон СБП) хранятся в базе в открытом виде.
|
||||
|
||||
@@ -0,0 +1,103 @@
|
||||
# BotShop v0.2.1
|
||||
|
||||
BotShop — локальная платформа для запуска нескольких Telegram-магазинов из одной панели управления.
|
||||
|
||||
Проект рассчитан на легальную продажу цифровых и физических товаров: файлы, доступы, инструкции, мерч, услуги, коды, подписки, инфопродукты.
|
||||
|
||||
## Безопасный scope
|
||||
|
||||
В проекте реализуется обычный магазин:
|
||||
|
||||
- несколько Telegram-ботов в одной панели;
|
||||
- каталог товаров;
|
||||
- выбор города и зоны доставки;
|
||||
- выбор товара и варианта;
|
||||
- итоговая карточка заказа;
|
||||
- баланс пользователя;
|
||||
- реферальная программа;
|
||||
- последний заказ;
|
||||
- связь с поддержкой;
|
||||
- ручная проверка оплаты оператором;
|
||||
- выдача цифрового товара только после подтверждённой оплаты;
|
||||
- журнал действий администратора и платежных решений.
|
||||
|
||||
Не реализуется:
|
||||
|
||||
- продажа запрещённых товаров;
|
||||
- скрытые адреса и тайники;
|
||||
- автоматическое признание оплаты только по нажатию пользователя;
|
||||
- обход платёжных правил;
|
||||
- анонимная схема без проверяемого учёта.
|
||||
|
||||
## Логика заказа
|
||||
|
||||
1. Пользователь открывает бота.
|
||||
2. Видит главное меню: каталог, баланс, рефералка, последний заказ, поддержка.
|
||||
3. Выбирает город.
|
||||
4. Выбирает зону доставки.
|
||||
5. Выбирает товар.
|
||||
6. Выбирает вариант.
|
||||
7. Получает итоговую карточку заказа.
|
||||
8. Выбирает действие: оплатить или отменить.
|
||||
9. После сообщения о платеже заказ уходит оператору на проверку.
|
||||
10. Оператор подтверждает оплату в панели.
|
||||
11. Система выдаёт цифровой товар из остатков и пишет событие в аудит.
|
||||
|
||||
## Статусы заказа
|
||||
|
||||
- `draft` — черновик;
|
||||
- `waiting_payment` — ожидает оплату;
|
||||
- `payment_review` — ожидает проверки оператором;
|
||||
- `paid` — оплата подтверждена;
|
||||
- `delivered` — товар выдан;
|
||||
- `cancelled` — отменён;
|
||||
- `refunded` — возвращён;
|
||||
- `expired` — истёк срок оплаты;
|
||||
- `rejected` — отклонён.
|
||||
|
||||
## Установка
|
||||
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install -y git curl
|
||||
cd /root
|
||||
git clone https://github.com/viktor138irk/bot.git botshop-installer
|
||||
cd botshop-installer
|
||||
sudo bash install.sh --local
|
||||
```
|
||||
|
||||
После установки:
|
||||
|
||||
```text
|
||||
Админка: http://IP-СЕРВЕРА/login
|
||||
Email: admin@local.test
|
||||
Пароль: сгенерированный пароль
|
||||
```
|
||||
|
||||
## Локальный режим
|
||||
|
||||
В локальном режиме домен и SSL не нужны. Telegram работает через polling-сервис:
|
||||
|
||||
```bash
|
||||
systemctl status botshop-polling --no-pager
|
||||
journalctl -u botshop-polling -f
|
||||
```
|
||||
|
||||
## Структура
|
||||
|
||||
```text
|
||||
install.sh # автоустановщик
|
||||
public/index.php # веб-панель и webhook endpoint
|
||||
scripts/polling.php # локальный Telegram polling worker
|
||||
database/schema.sql # схема базы
|
||||
storage/config.php # создаётся installer'ом, не хранится в git
|
||||
storage/logs/ # логи
|
||||
```
|
||||
|
||||
## Roadmap
|
||||
|
||||
- v0.2.1 — безопасный scope, совместимость схемы, главное меню бота;
|
||||
- v0.2.2 — раздел остатков и выдачи цифрового товара;
|
||||
- v0.2.3 — операторская проверка оплаты и аудит;
|
||||
- v0.2.4 — поддержка в панели;
|
||||
- v0.3.0 — роли операторов, улучшенный UI и журнал действий.
|
||||
Ссылка в новой задаче
Block a user
© 2026 StackWorks