first

README.md

@@ -0,0 +1,144 @@
+# 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