145 lines
5.0 KiB
Markdown
145 lines
5.0 KiB
Markdown
# Birthday Bot (bdbot)
|
||
|
||
Telegram-бот для отслеживания дней рождения и отправки тематических поздравлений в чатах.
|
||
|
||
## Возможности
|
||
|
||
- 📅 Отслеживание дней рождения пользователей
|
||
- 🎉 Автоматическая отправка тематических поздравлений
|
||
- 📊 Статистика по чатам
|
||
- 🔔 Уведомления о предстоящих днях рождения
|
||
- 🎨 12 тем для персонализации поздравлений
|
||
|
||
## Требования
|
||
|
||
- Python 3.12+
|
||
- PostgreSQL 14+
|
||
- Docker и Docker Compose (опционально)
|
||
|
||
## Установка
|
||
|
||
### Локальная установка
|
||
|
||
1. Клонируйте репозиторий:
|
||
```bash
|
||
git clone <repository-url>
|
||
cd bdbot
|
||
```
|
||
|
||
2. Установите зависимости:
|
||
```bash
|
||
pip install uv
|
||
uv pip install -e .
|
||
```
|
||
|
||
3. Создайте файл `.env` на основе `.env.example`:
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
4. Заполните `.env` файл:
|
||
```env
|
||
BOT_TOKEN=your_bot_token_here
|
||
DATABASE_URL=postgresql://user:password@localhost:5432/bdbot
|
||
NOTIFICATION_TIME=09:00
|
||
TIMEZONE=Europe/Moscow
|
||
```
|
||
|
||
5. Создайте базу данных PostgreSQL и убедитесь, что она доступна.
|
||
|
||
6. Запустите бота:
|
||
```bash
|
||
python main.py
|
||
```
|
||
|
||
### Docker Compose
|
||
|
||
1. Создайте файл `.env` (см. выше).
|
||
|
||
2. Запустите с помощью Docker Compose:
|
||
```bash
|
||
docker-compose up -d
|
||
```
|
||
|
||
## Использование
|
||
|
||
### Для администраторов чата
|
||
|
||
1. Добавьте бота в чат
|
||
2. Выдайте боту права администратора
|
||
3. Бот автоматически покажет статистику и предложит участникам поделиться днем рождения
|
||
|
||
### Для пользователей
|
||
|
||
1. Напишите боту в личку `/start`
|
||
2. Отправьте свой день рождения в формате `ДД.ММ` или `ДД.ММ.ГГГГ` (например: `15.03` или `15.03.1990`)
|
||
3. Выберите тему предпочтений из предложенных вариантов
|
||
4. Готово! Бот будет поздравлять вас во всех чатах, где вы состоите
|
||
|
||
### Команды в чатах
|
||
|
||
- `/stats` - Показать статистику: сколько человек поделились днем рождения
|
||
- `/week` - Показать дни рождения на ближайшие 7 дней
|
||
- `/month` - Показать дни рождения на ближайшие 30 дней
|
||
- `/help` - Показать справку по командам
|
||
|
||
### Обновление данных
|
||
|
||
Используйте команду `/update` в личке с ботом, чтобы обновить свой день рождения или тему предпочтений.
|
||
|
||
## Темы предпочтений
|
||
|
||
1. Автомобили
|
||
2. Спорт
|
||
3. Танцы
|
||
4. Музыка
|
||
5. Аниме
|
||
6. Игры
|
||
7. Книги
|
||
8. Кино
|
||
9. Путешествия
|
||
10. Еда
|
||
11. Технологии
|
||
12. Искусство
|
||
|
||
## Конфигурация
|
||
|
||
Все настройки находятся в файле `.env`:
|
||
|
||
- `BOT_TOKEN` - токен Telegram бота (получить у @BotFather)
|
||
- `DATABASE_URL` - строка подключения к PostgreSQL
|
||
- `NOTIFICATION_TIME` - время отправки поздравлений (формат: HH:MM, по умолчанию 09:00)
|
||
- `TIMEZONE` - часовой пояс (например: Europe/Moscow, UTC)
|
||
|
||
## Структура проекта
|
||
|
||
```
|
||
bdbot/
|
||
├── main.py # Точка входа
|
||
├── bot.py # Основной класс бота
|
||
├── config.py # Конфигурация
|
||
├── database.py # Модели базы данных
|
||
├── messages.py # Тематические поздравления
|
||
├── handlers/ # Обработчики событий
|
||
│ ├── group_handlers.py # Обработка событий в группах
|
||
│ ├── private_handlers.py # Обработка команд в личке
|
||
│ ├── command_handlers.py # Обработка команд в группах
|
||
│ └── scheduler.py # Планировщик поздравлений
|
||
├── Dockerfile # Docker образ
|
||
├── docker-compose.yml # Docker Compose конфигурация
|
||
└── .env.example # Пример конфигурации
|
||
```
|
||
|
||
## Разработка
|
||
|
||
Проект использует:
|
||
- Python 3.12+
|
||
- pyTelegramBotAPI для работы с Telegram API
|
||
- SQLAlchemy для работы с базой данных
|
||
- APScheduler для планирования задач
|
||
- PostgreSQL как основную БД
|
||
|
||
## Лицензия
|
||
|
||
from olly & cursor with <3
|