163 lines
6.2 KiB
Markdown
163 lines
6.2 KiB
Markdown
# Reminder Bot
|
||
|
||
Telegram бот для создания повторяющихся напоминаний. Создавайте напоминания с любой периодичностью (каждые N дней), получайте уведомления в нужное время и управляйте ими через интерактивный интерфейс.
|
||
|
||
## Возможности
|
||
|
||
- ✅ Создание повторяющихся напоминаний с произвольной периодичностью
|
||
- 🕐 Настройка времени отправки уведомлений
|
||
- 📝 Редактирование текста, времени и периодичности
|
||
- ⏸ Пауза и возобновление напоминаний
|
||
- 🔁 Отложить напоминание на 1-3 часа или на завтра
|
||
- 📊 Статистика выполнения
|
||
- 🗑 Удаление напоминаний
|
||
|
||
## Технологии
|
||
|
||
- **Python 3.11+**
|
||
- **aiogram 3.x** - фреймворк для Telegram ботов
|
||
- **SQLAlchemy + aiosqlite** - асинхронная ORM и база данных
|
||
- **APScheduler** - планировщик задач
|
||
- **Docker + docker-compose** - контейнеризация
|
||
|
||
## Быстрый старт
|
||
|
||
### 1. Получите токен бота
|
||
|
||
Создайте бота через [@BotFather](https://t.me/BotFather) в Telegram и получите токен.
|
||
|
||
### 2. Настройте окружение
|
||
|
||
Скопируйте `.env.example` в `.env` и заполните:
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
Отредактируйте `.env`:
|
||
|
||
```env
|
||
BOT_TOKEN=ваш_токен_от_BotFather
|
||
DB_URL=sqlite+aiosqlite:///data/reminder.db
|
||
LOG_LEVEL=INFO
|
||
TZ=Europe/Moscow
|
||
POLLING_SKIP_UPDATES=true
|
||
```
|
||
|
||
### 3. Запуск с Docker (рекомендуется)
|
||
|
||
```bash
|
||
# Сборка и запуск
|
||
docker-compose up -d --build
|
||
|
||
# Просмотр логов
|
||
docker-compose logs -f reminder_bot
|
||
|
||
# Остановка
|
||
docker-compose down
|
||
```
|
||
|
||
### 4. Запуск без Docker
|
||
|
||
```bash
|
||
# Создать виртуальное окружение
|
||
python -m venv .venv
|
||
source .venv/bin/activate # Linux/Mac
|
||
# или
|
||
.venv\Scripts\activate # Windows
|
||
|
||
# Установить зависимости
|
||
pip install -r requirements.txt
|
||
|
||
# Создать директорию для БД
|
||
mkdir -p data
|
||
|
||
# Запустить бота
|
||
python -m bot.main
|
||
```
|
||
|
||
## Использование
|
||
|
||
### Основные команды
|
||
|
||
- `/start` - запуск бота и главное меню
|
||
- `/help` - справка по использованию
|
||
- `/cancel` - отменить текущее действие
|
||
|
||
### Создание напоминания
|
||
|
||
1. Нажмите **➕ Новое напоминание**
|
||
2. Введите текст напоминания
|
||
3. Выберите периодичность (или введите свою)
|
||
4. Укажите время в формате `ЧЧ:ММ` (например, `09:00`)
|
||
5. Подтвердите создание
|
||
|
||
### Управление напоминаниями
|
||
|
||
Нажмите **📋 Мои напоминания** для просмотра списка. Для каждого напоминания доступно:
|
||
|
||
- **✏️ Изменить** - редактирование текста, времени или периодичности
|
||
- **⏸ Пауза / ▶️ Возобновить** - приостановка и возобновление
|
||
- **🗑 Удалить** - удаление напоминания
|
||
|
||
### Действия при получении напоминания
|
||
|
||
- **✅ Выполнено** - отметить как выполненное (следующее через N дней)
|
||
- **🔁 Напомнить позже** - отложить на 1 час, 3 часа или завтра
|
||
- **⏸ Пауза** - приостановить напоминание
|
||
- **🗑 Удалить** - удалить напоминание
|
||
|
||
## Архитектура проекта
|
||
|
||
```
|
||
bot/
|
||
├── __init__.py
|
||
├── main.py # Точка входа
|
||
├── config.py # Конфигурация
|
||
├── logging_config.py # Настройка логирования
|
||
├── core/ # Инфраструктура
|
||
│ ├── bot.py # Инициализация бота
|
||
│ ├── scheduler.py # Планировщик напоминаний
|
||
│ └── middlewares.py # Middleware
|
||
├── db/ # База данных
|
||
│ ├── base.py # Engine и сессии
|
||
│ ├── models.py # ORM модели
|
||
│ └── operations.py # CRUD операции
|
||
├── handlers/ # Обработчики
|
||
│ ├── common.py # /start, /help, /cancel
|
||
│ ├── reminders_create.py # Создание напоминаний
|
||
│ ├── reminders_manage.py # Управление
|
||
│ ├── callbacks.py # Inline-кнопки
|
||
│ └── errors.py # Обработка ошибок
|
||
├── keyboards/ # Клавиатуры
|
||
│ ├── main_menu.py # Главное меню
|
||
│ ├── reminders.py # Кнопки напоминаний
|
||
│ └── pagination.py # Пагинация
|
||
├── services/ # Бизнес-логика
|
||
│ ├── reminders_service.py
|
||
│ ├── user_service.py
|
||
│ └── time_service.py
|
||
├── states/ # FSM состояния
|
||
│ └── reminder_states.py
|
||
└── utils/ # Утилиты
|
||
├── formatting.py
|
||
└── validators.py
|
||
```
|
||
|
||
## Разработка
|
||
|
||
Проект следует принципам:
|
||
|
||
- **Layered Architecture** - разделение на слои (handlers, services, db)
|
||
- **SOLID** - бизнес-логика в сервисах, handlers только валидируют и делегируют
|
||
- **Type Hints** - аннотации типов для всех публичных функций
|
||
- **PEP 8** - стиль кода Python
|
||
|
||
## Лицензия
|
||
|
||
MIT
|
||
|
||
## Поддержка
|
||
|
||
Если возникли проблемы или есть предложения, создайте issue в репозитории.
|