🏠 DutyLog

DutyLog — это Telegram-бот для учёта дежурств в общежитии. Простой, удобный и функциональный инструмент для управления часами дежурств резидентов.

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

Для резидентов

• 📊 Просмотр своих часов — отработанные и неотработанные часы всегда под рукой
• 📜 История операций — все начисления и списания с примечаниями
• 🏆 Топ общежития — кто больше всех отработал часов
• ❓ FAQ — ответы на частые вопросы

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

• 🏠 Управление резидентами — добавление, удаление, поиск и фильтрация
• ⏰ Начисление/списание часов — с обязательными примечаниями
• 🚪 Управление комнатами и этажами — структура общежития
• 📅 Отчётные периоды — месячные циклы учёта дежурств
• 📊 Excel-отчёты — автоматическая генерация отчётов за период
• 📈 Статистика — общая информация по системе
• 📢 Рассылка — отправка сообщений всем пользователям

Для создателя

• 👨‍💼 Управление админами — назначение и удаление администраторов
• 🔐 Полный контроль — доступ ко всем функциям системы

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

Требования

• Python 3.14+
• PostgreSQL
• Telegram Bot Token

Установка

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

git clone https://github.com/yourusername/dutylog.git
cd dutylog

2. Установите зависимости с помощью uv:

uv sync

3. Создайте конфигурационный файл:

cp config.example.toml config.toml

4. Заполните config.toml:

[bot]
token = "YOUR_BOT_TOKEN"
creator_id = 123456789  # Ваш Telegram ID

[database]
url = "postgresql+asyncpg://user:password@localhost:5432/dutylog"

5. Инициализируйте базу данных:

# Создайте структуру БД
uv run alembic upgrade head

# Загрузите начальные данные (этажи и комнаты)
psql -U user -d dutylog -f init_floors_rooms.sql

6. Запустите бота:

uv run python -m dutylog.application

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

dutylog/
├── src/dutylog/
│   ├── application/          # Слой приложения
│   │   └── bot/
│   │       ├── admin_dialogs/    # Диалоги для админов
│   │       ├── creator_dialogs/  # Диалоги для создателя
│   │       └── user_dialogs/     # Диалоги для пользователей
│   ├── domain/               # Доменная логика
│   │   └── schemas.py
│   ├── infrastructure/       # Инфраструктурный слой
│   │   ├── database/
│   │   │   ├── dao/          # Data Access Objects
│   │   │   ├── models/       # SQLAlchemy модели
│   │   │   └── repositories/ # Репозитории
│   │   └── utils/
│   └── services/             # Сервисный слой
│       └── report_service.py # Генерация отчётов
├── alembic/                  # Миграции БД
├── config.toml               # Конфигурация
└── pyproject.toml

🛠 Технологии

• aiogram 3.x — современный фреймворк для Telegram ботов
• aiogram-dialog — FSM-диалоги для aiogram
• SQLAlchemy 2.x — ORM для работы с БД
• asyncpg — асинхронный драйвер PostgreSQL
• dishka — DI-контейнер для Python
• openpyxl — генерация Excel-отчётов
• alembic — миграции базы данных

📊 Как работают отчётные периоды

DutyLog использует систему месячных отчётных периодов:

1. Создание периода — администратор создаёт новый период (обычно в начале месяца)
2. Активный период — в течение месяца все операции записываются в активный период
3. Закрытие периода — при создании нового периода старый автоматически закрывается
4. Генерация отчёта — после закрытия можно сгенерировать Excel-отчёт за период

Отчёт содержит:

• Все начисления и списания часов
• Информацию о резидентах и комнатах
• Username админа, который провёл операцию
• Примечания к каждой операции
• Автоматический подсчёт итогов

🔧 Разработка

Запуск в режиме разработки

# С автоперезагрузкой при изменении кода
uv run watchfiles "python -m dutylog.application" src/

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

uv run alembic revision --autogenerate -m "описание изменений"
uv run alembic upgrade head

Тестирование генерации отчётов

uv run python test_report_generation.py

📝 Конфигурация

Пример полного конфига (config.toml):

[bot]
token = "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz"
creator_id = 123456789

[database]
host = "localhost"
port = 5432
user = "postgres"
password = "1234"
database = "dutylog"

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

Мы открыты для предложений и улучшений! Если у вас есть идеи:

1. Создайте Issue с описанием предложения
2. Форкните репозиторий
3. Создайте ветку для вашей фичи
4. Отправьте Pull Request

📄 Лицензия

MIT 2025 kolo

---

Сделано с ❤️ для упрощения учёта дежурств в общежитиях