TimeMateBot - Бот учёта рабочего времени

🤖 Telegram бот для учёта рабочего времени в группах с расширенной админ-панелью.

✨ Возможности

👥 Для пользователей:

• Учёт смен: отметка прихода/ухода
• История смен: просмотр последних смен
• Статистика: личная статистика по часам
• Статус: кто сейчас на работе

👑 Для владельца группы:

• Автоматическое определение прав владельца
• Админ-панель с расширенными функциями
• Статистика по всем пользователям
• Детальная информация о любом сотруднике
• Метрики и аналитика по сменам
• Экспорт данных в CSV/JSON/TXT форматах

🚀 Быстрый старт

1. Клонирование репозитория

git clone <repository-url>
cd TimeMateBot

2. Настройка окружения

# Создание виртуального окружения
python -m venv venv
source venv/bin/activate  # Linux/Mac
# или
venv\Scripts\activate  # Windows

# Установка зависимостей
pip install -r requirements.txt

3. Конфигурация

# Копирование файла окружения
cp .env.example .env

# Редактирование .env файла
BOT_TOKEN=your_telegram_bot_token

4. Запуск

# Локальный запуск
python bot.py

# Или с помощью Docker
docker-compose up -d

📋 Требования

• Python 3.8+
• Telegram Bot Token (получить у @BotFather)
• Docker и Docker Compose (опционально)

🛠️ Структура проекта

TimeMateBot/
├── bot.py              # Основной файл запуска бота
├── handlers.py          # Обработчики команд пользователей
├── admin_handlers.py    # Админские функции
├── keyboards.py         # Клавиатуры бота
├── storage.py          # Хранилище данных
├── models.py           # Модели данных
├── config.py           # Конфигурация
├── requirements.txt     # Зависимости Python
├── Dockerfile          # Конфигурация Docker
├── docker-compose.yml  # Docker Compose конфигурация
├── .env.example        # Пример файла окружения
└── data/              # Папка с данными (создаётся автоматически)
    └── shifts.json     # Файл с данными о сменах

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

Основные команды:

• /start - Запуск бота и приветствие
• /admin - Админ-панель (только для владельца)
• /stats - Личная статистика
• /menu - Показать меню

Кнопки:

• 🟢 Пришёл - Начать смену
• 🔴 Ушёл - Закончить смену
• 📊 Статус - Кто сейчас на работе
• 📜 История - Последние смены

Админ-панель:

• 👥 Кто на смене - Все активные смены
• 📊 Статистика всех - Сводка по всем пользователям
• 🔍 Детали пользователя - Информация о конкретном сотруднике
• 📈 Метрики - Аналитика по сменам
• 📤 Экспорт данных - Выгрузка в файлы

📊 Экспорт данных

Бот поддерживает экспорт данных в трёх форматах:

📄 CSV

Имя,Username,Дата начала,Дата конца,Длительность
Иван Иванов,ivanov,27.03.2026 09:00,27.03.2026 17:00,8ч 0м

📋 JSON

{
  "export_info": {
    "date": "27.03.2026 15:30:45",
    "total_completed_shifts": 150,
    "active_shifts": 2
  },
  "shifts": [...]
}

📝 TXT

ЭКСПОРТ ДАННЫХ БОТА
==================================================
Дата экспорта: 27.03.2026 15:30:45
Всего завершенных смен: 150
Активных смен сейчас: 2
==================================================

27.03.2026 | Иван Иванов | 09:00-17:00 | 8ч 0м

🛡️ Безопасность

• Автоматическое определение владельца группы через Telegram API
• Проверка прав для всех админских функций
• Кеширование прав доступа для производительности
• Фильтрация только завершенных смен для экспорта

🤝 Вклад

Разработан с использованием:

• aiogram - асинхронный фреймворк для Telegram ботов
• APScheduler - планировщик задач
• Python 3.8+ с async/await

📝 Лицензия

MIT License - свободное использование и модификация

🐞 Поддержка

При обнаружении проблем:

1. Проверьте логи бота
2. Убедитесь в правильности токена
3. Проверьте права бота в группе