update

README.md

@@ -0,0 +1,176 @@
+# 🏠 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]
+url = "postgresql+asyncpg://dutylog:password@localhost:5432/dutylog"
+```
+
+## 🤝 Вклад в проект
+
+Мы открыты для предложений и улучшений! Если у вас есть идеи:
+
+1. Создайте Issue с описанием предложения
+2. Форкните репозиторий
+3. Создайте ветку для вашей фичи
+4. Отправьте Pull Request
+
+## 📄 Лицензия
+
+MIT 2025 kolo
+
+---
+
+Сделано с ❤️ для упрощения учёта дежурств в общежитиях