From 67c60bcbb82bb7bac914345d8f2856adaca4d59f Mon Sep 17 00:00:00 2001 From: kolo Date: Sun, 1 Mar 2026 16:29:47 +0300 Subject: [PATCH] update --- README.md | 176 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 176 insertions(+) diff --git a/README.md b/README.md index e69de29..1778701 100644 --- a/README.md +++ b/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 + +--- + +Сделано с ❤️ для упрощения учёта дежурств в общежитиях