Gift Bot

Gift Bot - это простой Telegram-бот, предназначенный для отправки поздравлений и сообщений вашим коллегам. Он поддерживает регистрацию пользователей, рассылку сообщений администраторами и управление пользователями.

Функции

• Регистрация и аутентификация пользователей.
• Функции администратора для отправки сообщений всем пользователям или выбранным пользователям.
• Блокировка/разблокировка пользователей через UI-клавиатуру.
• Назначение и снятие прав администратора.
• Ежедневная синхронизация никнеймов/имён из Telegram.

Установка

1. Клонируйте репозиторий:

   git clone https://github.com/saintvrai/gift-bot
   cd gift-bot

2. Установите зависимости:

   go mod tidy

3. Настройте бота:

   • Скопируйте .env.example в .env.
   • Заполните значения в .env:
     • SERVER_GINMODE, SERVER_PORT
     • PG_HOST, PG_PORT, PG_USER, PG_NAME, PG_PASSWORD, PG_SSLMODE
     • TELEGRAM_TOKEN, TELEGRAM_SECRET

4. Настройте базу данных:

   • Запустите миграции базы данных, расположенные в db/migrations.

5. Соберите и запустите бота:

   go build -o gift-bot
   ./gift-bot

Настройка команд в BotFather

Отправьте BotFather список команд в формате:

start - Приветствие и краткое описание
help - Показать список команд
chat - Показать ID чата
login - Регистрация в боте
message - Рассылка сообщения (только админы)
block - Заблокировать пользователей (только админы)
unblock - Разблокировать пользователей (только админы)
admin_add - Назначить администратора (только админы)
admin_remove - Снять права администратора (только админы)

Развертывание через Docker Compose

1. Убедитесь, что у вас установлен Docker и Docker Compose.

2. Убедитесь, что в .env заполнены значения:

   • PG_* используется и для приложения, и для Docker Compose.
   • SERVER_* и TELEGRAM_* используются приложением.

3. Запустите Docker Compose:

   docker-compose up -d

   Это создаст и запустит контейнеры для вашего Telegram-бота и PostgreSQL базы данных.

Использование

Подробное описание бизнес-логики и поведения бота для пользователей — в документации.

Команды

Для всех пользователей

• /start: Зарегистрируйтесь и начните взаимодействие с ботом.

  Бот поприветствует пользователя и предоставит краткое введение.

• /help: Показать список команд.

• /chat: Получите ваш уникальный ID чата.

  Бот ответит уникальным ID чата пользователя.

• /login: Войдите в бот, используя секретное слово.

  Бот попросит пользователя ввести секретное слово для аутентификации.

Для администраторов

• /message: Отправьте сообщение всем пользователям.

  Бот попросит администратора ввести сообщение. После этого предоставит список пользователей для исключения из рассылки. После выбора сообщение отправляется всем пользователям, которые не были исключены.

• /block: Заблокируйте пользователей.

  Бот покажет список пользователей с клавиатурой, где можно выбрать нескольких и нажать «Заблокировать».

• /unblock: Разблокируйте пользователей.

  Бот покажет список заблокированных пользователей с клавиатурой, где можно выбрать нескольких и нажать «Разблокировать».

• /admin_add: Назначить администратора.

  Бот покажет список пользователей для назначения.

• /admin_remove: Снять права администратора.

  Бот покажет список администраторов для снятия прав.

Примеры

• /start:

  /start
  

  Ответ бота:

  Привет, <username>! Это простой телеграм бот для поздравляшек своих близких коллег. Тут есть пару команд, чтобы ты мог начать получать сообщения! Если что-то будет не так, то ты всегда можешь написать своему администратору для устранения проблем.
  

• /message:

  /message
  

  Ответ бота:

  Введите сообщение, которое хотите отправить всем пользователям:
  

  После ввода сообщения:

  Выберите пользователей, которым не нужно отправлять сообщение. Для отмены нажмите «Отменить».
  

  Администратор выбирает пользователей для исключения и нажимает "Отправить".

• /block:

  /block
  

  Ответ бота:

  Выберите пользователей для блокировки. Для отмены нажмите «Отменить».
  

  Администратор выбирает пользователей и нажимает «Заблокировать».

Для добавления роли администратора определенному пользователю, ранее требовался доступ к БД. Теперь это можно сделать через /admin_add.

Поведение блокировки

• Заблокированные пользователи не получают рассылки (/message).
• По заблокированным пользователям не формируются уведомления о дне рождения.
• При попытке взаимодействия бот отвечает «Вы заблокированы.»

Периодические задачи

• Уведомления админам о ДР: ежедневно в 09:00 (Europe/Moscow).
• Синхронизация профилей (никнейм/имя/фамилия): ежедневно в 04:00 (Europe/Moscow).
  • Для уведомлений используется дедупликация: каждый админ получает одно уведомление по пользователю в день. Если отправка не удалась, попытка повторится на следующем запуске.

Антиспам

Лимит 10 запросов в минуту на chat_id. При превышении — одно предупреждение и далее игнор до конца окна.

Вклад

Если вы хотите внести вклад в этот проект, пожалуйста, откройте pull request или issue на GitHub.

Этот README предоставляет обзор проекта Gift Bot, его функций, инструкции по установке и примеры использования. Это должно помочь вам начать работу с ботом и понять его функциональные возможности.