🐾 Cat Time Bot Z (FastAPI Edition)

Асинхронный Telegram-бот на базе Aiogram 3 и SQLAlchemy для геймифицированного учета рабочего времени и выездов IT-специалистов. Бот не только считает отработанные часы, но и награждает пользователей достижениями, повышает уровни (от "Укротителя USB" до "Архитектора Систем") и рассылает ежедневные сводки (погода, валюты ЦБ РФ, крипта).

✨ Ключевые возможности

• ⏱ Трекинг времени: Команды /join и /leave для фиксации прибытия и ухода с точек. Редактирование времени через /edit_start и /edit_end.
• 🎮 Геймификация: Умная система начисления опыта, сезонные ранги, 100 уникальных IT-званий и система достижений ("Первая кровь" и др.).
• 📊 Профиль: Личный кабинет (/profile) с графическим прогресс-баром и статистикой.
• ⏰ Фоновые задачи и рассылки (APScheduler):
  • /start_reminder ЧЧ:ММ — умное напоминание о транспортных расходах (динамически считает дни до конца месяца).
  • /start_leave_reminder ЧЧ:ММ — напоминание сотрудникам о незакрытых выездах (чтобы никто не забыл нажать /leave).
  • /start_stats ЧЧ:ММ — автоматическая отправка ежедневного отчета по выездам.
  • /start_news ЧЧ:ММ — ежедневный IT-дайджест и кот-антистресс.
  • Отключение: используйте приставку stop_ вместо start_ для точечной отмены (например, /stop_weather).
  • /stop_scheduler — полная отмена всех активных рассылок и напоминаний в текущем чате.
• 🌤 Ежедневные сводки:
  • /start_weather ЧЧ:ММ — детальная погода, прогноз, фазы луны и магнитные бури.
  • /start_currency ЧЧ:ММ — курсы фиатных валют с динамикой роста/падения.
  • /start_crypto ЧЧ:ММ — курсы основных криптовалют.

🛠 Стек технологий

• Python 3.10+
• Фреймворк: Aiogram 3.x
• База данных: SQLite + SQLAlchemy 2.0 (Асинхронная)
• Планировщик: APScheduler
• Тестирование: pytest, pytest-asyncio (In-memory БД)
• Логирование: Встроенный RotatingFileHandler (сохранение в logs/)

---

🐳 Запуск через Docker (Рекомендуется)

Это самый быстрый способ развернуть бота со всеми зависимостями и правильным часовым поясом.

1. Подготовка

Создайте в папке бота пустой файл базы данных (чтобы Docker не создал вместо него директорию):

touch cat_bot/sqlite.db

2. Запуск

(Если вы используете Linux/WSL и получаете ошибку прав доступа к сокету Docker, используйте команду с sudo):

sudo docker compose up -d --build

3. Первоначальная настройка (для новых пользователей)

Если вы запускаете бота впервые, наполните базу уровнями:

sudo docker compose exec cat_bot python main.py --init_levels

4. Миграция данных из архивного проекта

Если вы переходите с архивной версии cat_time_bot (Django):

1. Положите файл вашей старой базы в папку cat_bot/ под именем old_bot_database.db.
2. Выполните команду миграции внутри работающего контейнера:

sudo docker compose exec cat_bot python main.py --migrate_db

(Если возникает ошибка доступа к sqlite.db, выполните на хосте: sudo chmod 666 cat_bot/sqlite.db)

---

🚀 Локальный запуск (без Docker)

1. Подготовка окружения

Склонируйте репозиторий, перейдите в папку с ботом и создайте виртуальное окружение:

# Для Windows
python -m venv venv
venv\Scripts\activate

# Для Linux/macOS
python3 -m venv venv
source venv/bin/activate

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

Установите необходимые библиотеки:

pip install -r requirements.txt

3. Настройка переменных окружения

В корневой папке проекта создайте файл .env и добавьте туда ваши токены:

TELEGRAM_BOT_TOKEN=ваш_токен_от_BotFather
OPENWEATHER_TOKEN=ваш_ключ_от_OpenWeatherMap
CHAT_ID=id_вашего_чата_для_рассылок

4. Инициализация базы данных и уровней

Перед первым запуском необходимо загрузить в базу данных иерархию уровней (титулов). Перейдите в папку cat_bot и выполните:

cd cat_bot
python main.py --init_levels

5. Миграция данных (из архивного проекта)

Если вы переходите с архивной версии бота cat_time_bot (Django), которая больше не поддерживается, вы можете перенести свои данные локально:

1. Поместите файл вашей старой базы данных в папку cat_bot/ под именем old_bot_database.db.
2. Запустите команду миграции:

python main.py --migrate_db

Скрипт автоматически создаст таблицы в новой базе и адаптирует данные из таблиц Django (bot_) под новую структуру SQLAlchemy.*

6. Запуск бота

python main.py

---

🧪 Тестирование

Проект покрыт автоматизированными тестами с использованием параметризации. Тесты выполняются в изолированной in-memory базе данных, имеется настроенный CI/CD пайплайн (GitHub Actions). Для запуска тестов локально выполните команду в корне проекта:

pytest -v

---

📂 Структура проекта

Cat_Time_Bot_Z/
├── cat_bot/                # Основная директория бота и данные
│   ├── core/               # Настройки БД, модели (models.py), запросы (crud.py), логгер
│   ├── handlers/           # Обработчики команд (/profile, /join, /leave, рассылки)
│   ├── services/           # Бизнес-логика (статистика, сезоны, геймификация)
│   ├── scripts/            # Утилиты (init_level.py, migrate_db.py)
│   ├── tests/              # Автотесты (test_db.py, test_tasks.py, test_scheduling.py и др.)
│   ├── logs/               # Директория с ротируемыми логами
│   ├── sqlite.db           # Основная база данных
│   ├── old_bot_database.db # Архивный дамп для миграции (опционально)
│   └── main.py             # Точка входа, инициализация CLI и бота
├── venv/                   # Виртуальное окружение
├── docker-compose.yml      # Конфигурация Docker Compose
├── Dockerfile              # Инструкция для сборки Docker-образа
├── .dockerignore           # Исключения для Docker
├── pytest.ini              # Конфигурация для Pytest
├── requirements.txt        # Зависимости Python
└── .env                    # Секретные ключи (не коммитить!)

📝 Планы дальнейшего развития

• Перенос базы данных на PostgreSQL для production.
• Развертывание Web-админки на базе FastAPI.
• Упаковка проекта в Docker и деплой на сервер.
• Интеграция антистресс-API с котиками.
• Покрытие ключевого функционала автотестами и настройка CI.

🎉 Предложения и баги

Вы можете предложить свою идею, сообщить о баге или просто написать автору. Больше технических статей и гайдов можно найти на сайте riopass.ru.

🌟 Спасибо за внимание!