DutyLog/README.md

# 🏠 DutyLog

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

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

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

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

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

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

### Требования
- Python 3.14+
- PostgreSQL
- Telegram Bot Token

### Установка

1. Клонируйте репозиторий:
```bash
git clone https://github.com/yourusername/dutylog.git
cd dutylog
```

2. Установите зависимости с помощью [uv](https://docs.astral.sh/uv/):
```bash
uv sync
```

3. Создайте конфигурационный файл:
```bash
cp config.example.toml config.toml
```

4. Заполните `config.toml`:
```toml
[bot]
token = "YOUR_BOT_TOKEN"
creator_id = 123456789  # Ваш Telegram ID

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

5. Инициализируйте базу данных:
```bash
# Создайте структуру БД
uv run alembic upgrade head

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

6. Запустите бота:
```bash
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](https://docs.aiogram.dev/)** — современный фреймворк для Telegram ботов
- **[aiogram-dialog](https://aiogram-dialog.readthedocs.io/)** — FSM-диалоги для aiogram
- **[SQLAlchemy 2.x](https://www.sqlalchemy.org/)** — ORM для работы с БД
- **[asyncpg](https://github.com/MagicStack/asyncpg)** — асинхронный драйвер PostgreSQL
- **[dishka](https://dishka.readthedocs.io/)** — DI-контейнер для Python
- **[openpyxl](https://openpyxl.readthedocs.io/)** — генерация Excel-отчётов
- **[alembic](https://alembic.sqlalchemy.org/)** — миграции базы данных

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

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

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

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

## 🔧 Разработка

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

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

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

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

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

```bash
uv run python test_report_generation.py
```

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

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

```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

---

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