mirror of
https://github.com/artemium428/428th-exchange-bot.git
synced 2026-09-15 16:56:20 +00:00
7588d74ceb
Stops repeating the ack on every client message so the private chat is not cluttered after the first contact. Co-authored-by: Cursor <cursoragent@cursor.com>
100 lines
5.5 KiB
Markdown
100 lines
5.5 KiB
Markdown
# 428th Exchange Bot
|
||
|
||
Telegram-бот — прослойка между клиентом и менеджером.
|
||
|
||
Клиент пишет боту в личку. Менеджер отвечает в супергруппе с **Topics**: у каждого клиента своя тема. Клиент получает ответы от имени бота.
|
||
|
||
## Требования
|
||
|
||
- Python 3.9+
|
||
- Бот от [@BotFather](https://t.me/BotFather)
|
||
- Супергруппа с включёнными темами (Topics)
|
||
|
||
## Быстрый старт
|
||
|
||
```bash
|
||
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](https://t.me/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`. Список услуг — кнопка под приветствием.
|
||
|
||
Сообщения бота в теме (копии от клиента) обратно клиенту не уходят.
|
||
|
||
## Запуск
|
||
|
||
```bash
|
||
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`.
|
||
|
||
```bash
|
||
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`, если они есть).
|
||
|
||
Полезные команды:
|
||
|
||
```bash
|
||
docker compose ps
|
||
docker compose restart
|
||
docker compose down # остановить без удаления ./data
|
||
docker compose up -d --build # обновить код после git pull
|
||
```
|