Система совместной работы над задачами для сменных работников.
- Для совместной работы над задачами сменными работниками, особенно когда они не встречаются лично.
- Постановка, учёт выполнения задач.
- "Передача дежурства" с автоматической генерацией отчета в формате Excel.
- Ознакомление работников с задачами, поручениями и документами с фиксацией времени ознакомления.
- Контроль ознакомления пользователей с задачами и сообщениями о ходе их выполнения.
- Поток уведомлений (activity stream) о действиях пользователей в разделе "Журнал".
- Передача уведомлений для оперативного обновления фронтенда через WebSockets.
- Уведомление админов о событиях через Телеграм-бота.
- Разные варианты интерфейса, подходящие для разных ситуаций: классические server-side rendered Django-templates, удобные для работы с мобильных устройств или вывода на печать, и полноценное приложение на Vue 3 для динамичной работы с задачами и комментариями с десктопа.
- Сохранение предыдущей версии задачи, комментария при их изменении.
- Архив задач и комментариев (пользователи не могут их удалить бесследно).
- Архив отчетов в формате Excel.
- Личные задачи пользователей.
- Быстрый поиск по задачам и комментариям к ним.
- Поддержка Markdown в задачах, комментариях и поручениях.
| Библиотека / фреймворк | Ссылки | Описание |
|---|---|---|
| Python 3.10 | Сайт | Весь бэкенд написан на Python. |
| Django 4 | Docs | В основе всего приложения лежит замечательный фреймворк Django. |
| - Gunicorn | Docs | WSGI HTTP сервер для работы приложения Django. |
- whitenoise |
Docs | Приложение Django для раздачи статических файлов. Преимущества его использования перед Nginx для раздачи статики описаны тут. |
- djangorestframework |
Docs | Приложение Django для создания REST API, которое в проекте используется в основном Vue-фронтендом. |
- django-notifications-hq |
PyPI | Лента активности пользователей для Django. |
- django-bleach |
Docs | Очистка от HTML-тегов информации, вводимой на сайте пользователями, за исключением перечня допустимых тегов. |
- Daphne |
GitHub | ASGI WebSocket сервер для работы Django Channels. |
- Django-Channels |
Docs | Расширение Django для поддержки протокола WebSockets. Он используется в проекте для мгновенной передачи уведомлений о событиях с бэкенда на фронтэнд, для оперативного обновления интерфейса. |
- channels-redis |
GitHub | Библиотека для использования Redis в качестве бекэнда для Django-Channels. |
| SQLite | Docs | Данной БД вполне достаточно для работы проекта, поэтому она выбрана из-за простоты, удобства отладки и резервного копирования. |
Markdown |
Docs | Библиотека для конвертирования разметки Markdown в задачах, комментариях и поручениях в HTML для корректного отображения в шаблонах страниц. |
XlsxWriter |
Docs | Библиотека для генерации отчетов в формате Microsoft Excel. |
| Redis | Docs | Используется как бэкенд для Django-Channels, Celery, а также как БД для хранения количества просмотров задач и документов. |
| Celery | Docs | Система фоновой обработки задач. Используется для отправки уведомлений через Телеграм-бота. |
| Nginx | Docs | Реверс-прокси для HTTP и WebSockets, а также раздача медиафайлов. |
| Docker Compose | Docs | Контейнеризация сервисов, из которых состоит проект, для обеспечения их слаженной работы. |
| Библиотека / фреймворк | Ссылки | Описание |
|---|---|---|
| Bootstrap 5 | Docs | CSS фреймворк для упрощения верстки шаблонов страниц. |
| Font Awesome | Docs | Значки для кнопок, пунктов меню и т.д. |
| HTMX 1.8.4 | Docs | Замечательная библиотека для создания динамически обновляемых веб-страниц с минимум JavaScript. |
| Vue 3 | Docs | Используется для создания удобного реактивного интерфейса для работы со списком задач и комментариями к ним. |
| Axios | Docs | HTTP клиент. |
| Marked.js | Docs | Для конвертирования разметки Markdown в HTML во фронтенде. |
| DOMPurify | Docs | Очистка пользовательских данных во фронтенде от небезопасных тегов. |
| Инструмент | Назначение |
|---|---|
| Coverage.py | Инструмент для оценки полноты покрытия кода бэкенда тестами. Запускается командой make test. После выполнения команды, в директории ./htmlcov можно просмотреть подробнейший отчет. |
| Interrogate | Интсрумент для проверки наличия docstrings в коде бэкенда. Запускается командой make coverage. |
| Rollbar | Логирование ошибок при работе Django-бэкенда в продакшен. |
| Sentry | Логирование ошибок при работе Vue-фронтенда. |
Для установки и запуска проекта, необходимо склонировать репозиторий, создать файл docker-compose.yml по одному из
прилагаемых шаблонов (dev или prod), задать в нём корректные переменные окружения, и затем запустить командой
sudo docker compose up -d. При первом запуске необходимо также выполнить команду миграции БД и создать учетную запись
администратора:
git clone ttps://github.com/hazadus/journal
cd ./journal
cp ./docker-compose.prod.yml ./docker-compose.yml
nano ./docker-compose.yml
sudo docker compose up -d --build
sudo docker exec journal-web python -m manage migrate
sudo docker exec journal-web python -m manage createsuperuserДля корректного запуска проекта, необходимо установить следующие переменные окружения в файле docker-compose.yml:
| Переменная | Значение |
|---|---|
SECRET_KEY |
Стандартный secret key для Django. Должен быть идентичным для сервисов web и daphne для корректной работы. |
DEBUG |
Режим отладки приложения Django. False в продакшен, True при разработке. |
STATIC_ROOT |
Директория, в которую будут собираться статические файлы при выполнении команды python -m manage collectstatic. По умолчанию это staticfiles. |
HOST_NAME |
Адрес сайта вида http://127.0.0.1 (без / на конце). |
ROLLBAR_ACCESS_TOKEN |
Токен Rollbar, необходимо получить на их сайте. |
TELEGRAM_BOT_TOKEN |
Токен телеграм-бота для информирования. От имени этого бота будут отправляться уведомления администратору. |
TELEGRAM_ADMIN_ID |
ID админа в телеграм, который будет получать уведомления о событиях на сайте. |
Django apps:
journaldocumentsuserscore
Директории и файлы:
vue-tasks-table-view- приложение на Vue для варианта табличного вида списка задачstatic/vue/task-table-view- сюда генерятся файлы при сборке приложения Vue командойnpm run build.db.sqlite3- файл БД.media/files- файлы, загружаемые в качестве приложений к задачам и документам.media/images- изображения профилей пользователей.media/reports- отчеты, генерируемые командойcreate_report.data/redis- данные БД Redis.docker/nginx/default.conf- конфигурационный файл Nginx.docker/nginx/logs/- логи Nginx..coveragerc- настройкиcoverage.pyhtmlcov/- отчетыcoverage.py(генерируются при запускеmake up,make test).
| Команда | Описание |
|---|---|
create_report |
Создаёт отчет О передаче смены по текущим задачам и комментариям к ним в формате Excel. Генерирует файл Excel, в который выводятся активные на текущий момент задачи (каждая задача на отдельном листе) и все комментарии к ним. К файлу отчета создаётся запись в БД, и рассылаются уведомления о генерации отчета. Файлы сохраняются в директории ./media/reports/. Для автоматической генерации отчета в определенное время, рекомендуется настроить запуск команды по расписанию при помощи сервиса cron. |
При разработке проекта ставится цель максимального покрытия кода бэкенда качественными тестами. На настоящий момент, покрытие составляет более 84%.
Тесты запускаются стандартной для Django командой при запущенном в фоне (с опцией -d) проекте:
docker exec journal-web python -m manage testДля запуска с coverage.py:
docker exec journal-web coverage run --source='.' -m manage test
docker exec journal-web coverage htmlЛибо, при помощи make:
make testВ результате выполнения данных команд, в директории ./htmlcov можно просмотреть подробнейший отчет о покрытии
кода тестами в формате HTML.
Все запланированые изменения и доработки можно увидеть в разделе Issues.
- Из-за особенностей работы SQLite с кириллицей, поиск по задачам и комментариям к ним чувствителен к регистру кириллических символов в поисковом запросе.
В ходе разработки приложения было изучено множество справочных материалов, и самыми полезными и качественными из них хочется поделиться.
- Notifications
- How to set up user notifications for your Django app (Advantch Blog)
- Django Channels
- Vue.js
- Vue + Django: Using .vue Files and the Vue CLI (Medium)
- How To Parse And Render Markdown In Vuejs (OpenReplay Blog)