From 9a13827dbea1ff29dfb01e92ed731073158274fe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=92=D0=B8=D0=BA=D1=82=D0=BE=D1=80?= Date: Thu, 20 Aug 2026 04:18:29 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=BF=D0=BE=D0=B4=D1=80=D0=BE=D0=B1?= =?UTF-8?q?=D0=BD=D1=8B=D0=B9=20README=20(=D1=80=D0=B0=D0=B7=D0=B1=D0=BE?= =?UTF-8?q?=D1=80=20=D0=BF=D1=80=D0=BE=D0=B5=D0=BA=D1=82=D0=B0=20=D0=BF?= =?UTF-8?q?=D1=80=D0=B8=20=D0=BF=D0=B5=D1=80=D0=B5=D0=BD=D0=BE=D1=81=D0=B5?= =?UTF-8?q?=20=D0=B2=20Gitea)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Старый README сохранён как README.upstream.md. --- README.md | 147 ++++++++++++++++++++++----------------------- README.upstream.md | 103 +++++++++++++++++++++++++++++++ 2 files changed, 174 insertions(+), 76 deletions(-) create mode 100644 README.upstream.md diff --git a/README.md b/README.md index ac0f866..a937c57 100644 --- a/README.md +++ b/README.md @@ -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/`. 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 в коде нет. +- Токены ботов и платёжные реквизиты (номера карт, телефон СБП) хранятся в базе в открытом виде. diff --git a/README.upstream.md b/README.upstream.md new file mode 100644 index 0000000..ac0f866 --- /dev/null +++ b/README.upstream.md @@ -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 и журнал действий.