428th-exchange-bot/README.md

428th Exchange Bot

Telegram-бот — прослойка между клиентом и менеджером.

Клиент пишет боту в личку. Менеджер отвечает в супергруппе с Topics: у каждого клиента своя тема. Клиент получает ответы от имени бота.

Требования

• Python 3.9+
• Бот от @BotFather
• Супергруппа с включёнными темами (Topics)

Быстрый старт

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# отредактируйте .env
python -m bot

Настройка Telegram

1. Создайте бота у @BotFather и скопируйте token в BOT_TOKEN.
2. Создайте супергруппу, включите Topics (настройки группы → Topics).
3. Добавьте бота в группу и сделайте администратором с правами:
   • Manage topics
   • Post messages
   • Delete messages (нужно для /del)
4. Узнайте chat_id группы и пропишите в MANAGER_GROUP_ID (обычно отрицательный, вида -100…).
   • Запустите бота, добавьте его в группу — в лог напишется id чата.
   • Либо перешлите любое сообщение из группы боту @userinfobot / аналогу.
5. Напишите боту /start с тестового аккаунта и отправьте сообщение — в группе появится новая тема.

Переменные окружения

Переменная	Описание
BOT_TOKEN	Token бота
MANAGER_GROUP_ID	Id супергруппы с Topics
DATABASE_PATH	Путь к SQLite (по умолчанию data/bot.db)
WELCOME_TEXT_RU / WELCOME_TEXT_UK	Опционально: приветствие для языка
ACK_TEXT_RU / ACK_TEXT_UK	Опционально: текст после первого сообщения клиента
COOLDOWN_TEXT_RU / COOLDOWN_TEXT_UK	Опционально: ответ при кулдауне
WELCOME_TEXT / ACK_TEXT / COOLDOWN_TEXT	Legacy: только для RU (UK не перезаписывается)
CLIENT_COOLDOWN_SECONDS	Кулдаун клиента в секундах (по умолчанию 5)

Как это работает

1. Клиент: /start → выбор языка (RU/UK) → приветствие, запись в SQLite.
2. Клиент пишет сообщение → бот создаёт тему (если ещё нет) и копирует сообщение менеджерам. На первое сообщение — «Спасибо, дальше вам будет отвечать менеджер»; дальше ack не повторяется.
3. Менеджер пишет в теме клиента → бот копирует содержимое клиенту в личку от своего имени.
4. Правки сообщений синхронизируются в обе стороны (текст и подписи).
5. Реакции синхронизируются в обе стороны.
6. Удаление: ответьте на сообщение командой /del — копия удалится и у клиента, и у менеджера.
7. Язык можно сменить командой /lang. Список услуг — кнопка под приветствием.

Сообщения бота в теме (копии от клиента) обратно клиенту не уходят.

Запуск

source .venv/bin/activate
python -m bot

Данные клиентов хранятся в SQLite (telegram_id ↔ topic_id). Рядом с bot.db могут появляться файлы -wal / -shm (режим WAL) — их тоже не нужно коммитить (data/ в .gitignore).

При старте бот проверяет MANAGER_GROUP_ID: супергруппа с Topics, бот — админ с правами Manage topics и Delete messages. При ошибке процесс завершится с понятным текстом в логе и stderr.

Деплой на VPS (Docker)

Нужны Docker и Docker Compose. Бот работает через long-polling — открывать порты не нужно, достаточно исходящего HTTPS к api.telegram.org. Запускайте один контейнер на один BOT_TOKEN.

git clone <repo-url> && cd 428th-exchange-bot
cp .env.example .env
# заполните BOT_TOKEN и MANAGER_GROUP_ID

mkdir -p data
# каталог должен быть доступен пользователю контейнера (uid 1000)
sudo chown -R 1000:1000 data

docker compose up -d --build
docker compose logs -f

SQLite лежит в ./data на хосте (DATABASE_PATH=/app/data/bot.db внутри контейнера). Бэкапьте эту папку (вместе с -wal / -shm, если они есть).

Полезные команды:

docker compose ps
docker compose restart
docker compose down          # остановить без удаления ./data
docker compose up -d --build # обновить код после git pull