🔄 ShiftTrack

Telegram-бот для регистрации и отслеживания рабочих смен сотрудников

Производственный MVP для автоматизации учёта рабочего времени с использованием геолокации и видео-подтверждения

Возможности • Установка • Использование • Технологии • Лицензия

📋 Содержание

О проекте
Возможности
Технологии
Архитектура
Установка
Конфигурация
Использование
API и команды
Разработка
Лицензия

🎯 О проекте

ShiftTrack — это производственный Telegram-бот для автоматизации учёта рабочего времени сотрудников. Система позволяет работникам регистрировать начало и окончание смен с привязкой к объектам, подтверждая это геолокацией и видео-кружками.

Основные преимущества:

✅ Автоматизация — регистрация смен через Telegram
✅ Верификация — подтверждение через геолокацию и видео
✅ Контроль — блокировка множественных активных смен
✅ Отчёты — экспорт данных в Google Sheets
✅ Безопасность — хранение видео в S3 с автоочисткой
✅ Аналитика — журнал всех действий и событий

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

Для работников 👷

🔵 Начало смены
- Выбор объекта из списка
- Отправка геолокации
- Подтверждение видео-кружком
- Автоматический расчёт времени
🔴 Завершение смены
- Отправка геолокации
- Подтверждение видео-кружком
- Автоматический расчёт длительности смены
📊 История смен
- Просмотр всех своих смен
- Информация о длительности и объектах

Для администраторов 👨‍💼

🏢 Управление объектами
- Добавление новых объектов
- Привязка геолокации и адреса
- Активация/деактивация объектов
👥 Управление пользователями
- Назначение роли работника
- Управление доступом
📈 Мониторинг и отчёты
- Просмотр всех активных смен
- Принудительное закрытие смен
- Экспорт отчётов в Google Sheets
- Журнал всех действий

Системные функции ⚙️

🗄️ Хранение данных
- PostgreSQL для основных данных
- S3-совместимое хранилище для видео
- Redis для FSM состояний
🧹 Автоматическая очистка
- Удаление видео через 14 дней
- Фоновый воркер для обслуживания
📝 Логирование
- Полный журнал действий
- Отслеживание административных операций

🛠 Технологии

Основной стек

Python 3.11 — язык программирования
aiogram 3.x — фреймворк для Telegram ботов
PostgreSQL — основная база данных
SQLAlchemy 2.0 (async) — ORM для работы с БД
Alembic — миграции базы данных
Redis — FSM состояния и кэширование

Интеграции

Amazon S3 / совместимые хранилища — хранение видео
Google Sheets API — экспорт отчётов
Docker & Docker Compose — контейнеризация

Инструменты разработки

pytest — тестирование
pytest-asyncio — асинхронное тестирование

🏗 Архитектура

┌─────────────────┐
│  Telegram Bot   │
│   (aiogram)     │
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
┌───▼───┐  ┌──▼────┐
│ Redis │  │  FSM  │
│ (FSM) │  │ States│
└───────┘  └───────┘
         │
┌────────▼─────────┐
│   PostgreSQL     │
│  - users         │
│  - objects       │
│  - shifts        │
│  - logs          │
└──────────────────┘
         │
┌────────▼─────────┐
│   S3 Storage     │
│   (Videos)       │
└──────────────────┘
         │
┌────────▼─────────┐
│ Background Worker│
│  (Cleanup Jobs)  │
└──────────────────┘

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

ShiftTrack/
├── app/
│   ├── bot/
│   │   ├── handlers/       # Обработчики команд
│   │   ├── keyboards/      # Клавиатуры
│   │   ├── middleware/     # Middleware
│   │   └── states.py       # FSM состояния
│   ├── db/
│   │   ├── models.py       # SQLAlchemy модели
│   │   ├── repository.py   # Репозитории
│   │   └── base.py         # База БД
│   ├── services/
│   │   ├── s3_service.py           # S3 интеграция
│   │   ├── video_service.py        # Работа с видео
│   │   └── google_sheets_service.py # Google Sheets
│   ├── main.py             # Точка входа бота
│   ├── worker.py           # Фоновый воркер
│   └── config.py           # Конфигурация
├── alembic/                # Миграции БД
├── tests/                  # Тесты
├── docker-compose.yml      # Docker Compose
├── Dockerfile              # Docker образ
└── requirements.txt        # Зависимости

📦 Установка

Требования

Python 3.11+
Docker & Docker Compose (рекомендуется)
PostgreSQL 16+ (если локально)
Redis 7+ (если локально)
Аккаунт Telegram Bot (через @BotFather)
S3-совместимое хранилище
Google Cloud Project (для Google Sheets API)

Быстрый старт с Docker

Клонируйте репозиторий

git clone https://github.com/Mendegar/ShiftTrack.git
cd shift-track

Создайте файл .env

cp .env.example .env

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

Отредактируйте .env файл (см. Конфигурация)

Запустите через Docker Compose

docker-compose up --build -d

Примените миграции

docker-compose exec bot alembic upgrade head

Проверьте логи

docker-compose logs -f bot

Локальная установка

Установите зависимости

pip install -r requirements.txt

Запустите PostgreSQL и Redis

docker-compose up -d postgres redis

Настройте .env файл
Примените миграции

alembic upgrade head

Запустите бота

python -m app.main

Запустите воркер (в отдельном терминале)

python -m app.worker

⚙️ Конфигурация

Переменные окружения

Создайте файл .env в корне проекта:

# Telegram Bot
BOT_TOKEN=your_bot_token_from_botfather

# PostgreSQL
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_DB=shift_tracking
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_secure_password

# Redis
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_DB=0

# S3 Storage
S3_ENDPOINT_URL=https://s3.amazonaws.com
S3_ACCESS_KEY_ID=your_access_key
S3_SECRET_ACCESS_KEY=your_secret_key
S3_BUCKET_NAME=shift-videos
S3_REGION=us-east-1

# Google Sheets API
GOOGLE_SHEETS_CREDENTIALS_PATH=credentials.json
GOOGLE_SHEETS_SPREADSHEET_ID=your_spreadsheet_id

# Timezone
TZ=Europe/Moscow

# Logging
LOG_LEVEL=INFO

Настройка Telegram Bot

Создайте бота через @BotFather
Получите токен и добавьте в .env

Настройка Google Sheets API

Создайте проект в Google Cloud Console
Включите Google Sheets API
Создайте Service Account
Скачайте JSON-ключ и сохраните как credentials.json
Создайте Google Sheets таблицу
Поделитесь таблицей с email из Service Account (read/write доступ)

Настройка S3

Можно использовать:

AWS S3
MinIO
DigitalOcean Spaces
Другие S3-совместимые хранилища

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

Для работников

Начало работы

Отправьте /start боту для регистрации
Начало смены
- Нажмите "Начать смену"
- Выберите объект из списка
- Отправьте геолокацию (кнопка "Отправить геолокацию")
- Отправьте видео-кружок (удерживайте кнопку камеры в Telegram)
Завершение смены
- Нажмите "Завершить смену"
- Отправьте геолокацию
- Отправьте видео-кружок
Просмотр истории
- Нажмите "Моя история"
- Просмотрите все свои смены за последние 30 дней

Для администраторов

Доступ к админ-панели
- Отправьте /start боту
- Нажмите "Админ панель"
Добавление объекта
- Админ панель → "Добавить объект"
- Введите название
- Введите адрес (опционально)
- Отправьте геолокацию объекта
Добавление работника
- Админ панель → "Добавить работника"
- Введите Telegram ID пользователя
- Пользователь должен сначала написать боту /start
Просмотр активных смен
- Админ панель → "Активные смены"
- Выберите смену для принудительного закрытия (при необходимости)
Экспорт отчёта
- Админ панель → "Экспорт отчёта"
- Введите период:
  - Число дней (например: 7 для последних 7 дней)
  - Или диапазон дат: 2024-01-01 2024-01-31
- Отчёт будет экспортирован в Google Sheets

🎮 API и команды

Пользовательские команды

Команда	Описание
`/start`	Регистрация и главное меню

Кнопки главного меню

Для работников:

🟢 Начать смену — начать новую смену
🔴 Завершить смену — завершить активную смену
📋 Моя история — просмотр истории смен

Для администраторов:

🟢 Начать смену — начать смену (как работник)
🔴 Завершить смену — завершить смену
📋 Моя история — просмотр истории
⚙️ Админ панель — доступ к административным функциям

FSM состояния

Бот использует конечные автоматы (FSM) для управления диалогами:

ShiftStartStates — процесс начала смены
ShiftEndStates — процесс завершения смены
AdminStates — административные операции

🧪 Разработка

Запуск тестов

# Все тесты
pytest

# С подробным выводом
pytest -v

# Конкретный тест
pytest tests/test_repository.py

Создание миграций

# Автоматическая генерация миграции
alembic revision --autogenerate -m "description"

# Применение миграций
alembic upgrade head

# Откат миграции
alembic downgrade -1

Структура базы данных

См. alembic/versions/001_initial_migration.py для полной схемы БД.

Основные таблицы:

users — пользователи системы
objects — рабочие объекты
shifts — смены сотрудников
logs — журнал действий
admin_actions — действия администраторов
video_cleanup — очередь на удаление видео

Стиль кода

Проект следует PEP 8. Рекомендуется использовать:

black для форматирования
flake8 для проверки стиля
mypy для проверки типов

📊 Схема базы данных

users
├── id (BIGINT, PK) - Telegram ID
├── full_name
├── username
├── role ('worker' | 'admin')
├── is_active
└── created_at

objects
├── id (INT, PK)
├── name
├── address
├── latitude (DECIMAL 9,6)
├── longitude (DECIMAL 9,6)
├── radius_m
├── is_active
└── created_at

shifts
├── id (INT, PK)
├── user_id (FK → users)
├── object_id (FK → objects)
├── start_time
├── end_time
├── start_latitude, start_longitude
├── end_latitude, end_longitude
├── start_video_file_id, start_video_url
├── end_video_file_id, end_video_url
├── duration_minutes
├── status ('open' | 'closed' | 'forced_closed')
└── created_at

logs
├── id (INT, PK)
├── shift_id (FK → shifts, nullable)
├── user_id (FK → users)
├── action
├── timestamp
└── payload (JSON)

admin_actions
├── id (INT, PK)
├── admin_id (FK → users)
├── target_user_id (FK → users, nullable)
├── action
├── timestamp
└── payload (JSON)

video_cleanup
├── id (INT, PK)
├── file_id
├── shift_id (FK → shifts)
├── s3_key
├── delete_after
├── deleted
└── deleted_at

🚀 Развёртывание

Production рекомендации

Безопасность
- Используйте сильные пароли для БД
- Храните секреты в переменных окружения
- Не коммитьте .env файлы
- Используйте SSL/TLS для подключений
Мониторинг
- Настройте логирование в файлы
- Используйте систему мониторинга (Prometheus, Grafana)
- Настройте алерты
Резервное копирование
- Регулярно бэкапьте PostgreSQL
- Настройте автоматические бэкапы S3
Масштабирование
- Используйте несколько инстансов бота
- Настройте Redis кластер для высокой нагрузки
- Используйте connection pooling для БД

🤝 Вклад в проект

Мы приветствуем вклад в проект! Пожалуйста:

Fork репозиторий
Создайте feature branch (git checkout -b feature/amazing-feature)
Commit изменения (git commit -m 'Add amazing feature')
Push в branch (git push origin feature/amazing-feature)
Откройте Pull Request

📝 Changelog

v1.0.0 (2024)

✨ Начальная версия
✅ Базовая функциональность регистрации смен
✅ Админ-панель
✅ Интеграция с Google Sheets
✅ Автоматическая очистка видео

🐛 Известные проблемы

Видео удаляются через 14 дней (можно настроить в коде)
Нет проверки геолокации на принадлежность объекту (можно добавить)
Google Sheets экспорт требует ручной настройки credentials

📄 Лицензия

Этот проект лицензирован под лицензией MIT - см. файл LICENSE для деталей.

👨‍💻 Авторы

ShiftTrack Team

Разработка: Mendegar

🙏 Благодарности

aiogram за отличный фреймворк
Сообщество Python за инструменты и библиотеки
Всем контрибьюторам проекта

Сделано с ❤️ для автоматизации рабочего процесса

⭐ Если проект полезен, поставьте звезду!

Report Bug • Request Feature • Documentation

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
alembic		alembic
app		app
tests		tests
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
alembic.ini		alembic.ini
docker-compose.yml		docker-compose.yml
requirements.txt		requirements.txt

License

Mendegar/ShiftTrack

Folders and files

Latest commit

History

Repository files navigation