Журнал Дежурства

Система совместной работы над задачами для сменных работников.

Для чего?

• Для совместной работы над задачами сменными работниками, особенно когда они не встречаются лично.
• Постановка, учёт выполнения задач.
• "Передача дежурства" с автоматической генерацией отчета в формате Excel.
• Ознакомление работников с задачами, поручениями и документами с фиксацией времени ознакомления.

Особенности

• Контроль ознакомления пользователей с задачами и сообщениями о ходе их выполнения.
• Поток уведомлений (activity stream) о действиях пользователей в разделе "Журнал".
• Передача уведомлений для оперативного обновления фронтенда через WebSockets.
• Уведомление админов о событиях через Телеграм-бота.
• Разные варианты интерфейса, подходящие для разных ситуаций: классические server-side rendered Django-templates, удобные для работы с мобильных устройств или вывода на печать, и полноценное приложение на Vue 3 для динамичной работы с задачами и комментариями с десктопа.
• Сохранение предыдущей версии задачи, комментария при их изменении.
• Архив задач и комментариев (пользователи не могут их удалить бесследно).
• Архив отчетов в формате Excel.
• Личные задачи пользователей.
• Быстрый поиск по задачам и комментариям к ним.
• Поддержка Markdown в задачах, комментариях и поручениях.

Используемые технологии, фреймворки и библиотеки

Backend

Библиотека / фреймворк	Ссылки	Описание
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	Контейнеризация сервисов, из которых состоит проект, для обеспечения их слаженной работы.

Frontend

Библиотека / фреймворк	Ссылки	Описание
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	Очистка пользовательских данных во фронтенде от небезопасных тегов.

Developer Tools

Инструмент	Назначение
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

Django apps:

• journal
• documents
• users
• core

Директории и файлы:

• 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.py
• htmlcov/ - отчеты coverage.py (генерируются при запуске make up, make test).

Дополнительные команды manage.py

Команда

Описание

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
  • Introduction to Django Channels (testdriven.io)
  • Django and HTMX #21 - WebSocket Notifications with the HTMX WebSocket Extension and django-channels (YouTube)
• Vue.js
  • Vue + Django: Using .vue Files and the Vue CLI (Medium)
  • How To Parse And Render Markdown In Vuejs (OpenReplay Blog)