Тестовый проект: «кассовый аппарат» для вымышленного магазина.

Оглавление

Нажать на необходимую главу для быстрого перехода по странице:

1. Описание ТЗ
2. О выполненном проекте
   • Важные особенности проекта
   • Используемый стек
   • Внешнее ПО
3. Запуск и демонстрация проекта
   • Демонстрация приложения на удалённом сервере
   • Локальный запуск приложения с использованием Docker
   • Локальный запуск приложения без использования Docker
4. Тестирование приложения
   • Тестирование в Postman на удалённом сервере
   • Тестирование через Swagger на удалённом сервере
   • Тестирование в Postman при локальной установке
   • Тестирование через Swagger при локальной установке
5. Разработчики

Описание ТЗ

Перед получением информации о выполненном проекте предлагаю ознакомиться с подробной информацией о требованиях к проекту:

Открыть информацию

Требования:

1. Необходимо написать «кассовый аппарат» для вымышленного магазина.
2. При выполнении задания необходимо использовать Python 3 и Django, Django Rest Framework

Условия:

Описание принципа работы «кассового аппарата»:

Этап 1

Предварительно нужно будет написать модель данных для товара Item.

Модель должна содержать следующие поля:

  | id    | айди товара  |
  | title | наименование |
  | price | стоимость    |

На веб-узел {{root}}/cash_machine с помощью метода POST отправляется следующее тело запроса:

  {
      "items": [1, 2, 3]
  }

где items это массив id товаров модели Item.

При этом запросе сервер должен формировать чек в формате PDF.

Пример чека:

В чек должны записываться следующие поля:

1. Для каждой позиции товара:
   • Наименование
   • Общее количество
   • Общая стоимость
2. Итоговая сумма
3. Время создания чека в формате (ДД.ММ.ГГГГ Ч:М)

HTML-шаблон чека приложен к заданию. Подставить вышеуказанные поля туда можно с помощью Jinja2. Для работы с PDF рекомендуется использовать библиотеку pdfkit: https://pypi.org/project/pdfkit/

Сформированный PDF файл нужно просто сохранять в папку media

Затем сервер формирует ссылку на этот PDF-файл и кодирует его в QR-код, а затем высылает этот QR-код в качестве ответа на запрос. Для работы с QR-кодами рекомендуется использовать библиотеку qrcode: https://pypi.org/project/qrcode/

Этап 2

При сканировании QR-код будет совершаться запрос GET {{root}}/media/<наименование файла> который в ответ будет возвращать этот файл.

Решение нужно будет загрузить на GitHub, либо Gitlab, либо Bitbucket как публичный репозиторий

Рекомендации

Во время тестирования решения рекомендуется на Этапе 2 запускать сервер в локальной сети, чтобы была возможность тестирования сканирования QR-кода через телефон.

Для этого в settings.py в ALLOWED_HOSTS напишите следующее:

ALLOWED_HOSTS = ['*']

Затем при запуске приложения указывайте IP-адрес вашей машины в локальной сети.

Например: python manage.py runserver 192.168.0.1:8000

О выполненном проекте

Проект cash_machine представляет собой API для управления кассовыми чеками, с возможностью сохранения данных в формате PDF и генерации QR-кодов.

Важные особенности проекта

• Соблюдение ТЗ: Проект строго следует техническому заданию, реализуя генерацию HTML-шаблонов с использованием Jinja2, создание pdf-файлов с помощью pdfkit и генерацию QR-кодов с использованием qrcode. Все реализованные функции соответствуют поставленным задачам и обеспечивают требуемый функционал.

• Гибкость разворачивания: Проект обеспечивает легкость развертывания в любом окружении. Вы можете запустить его локально без контейнеров, локально с использованием Docker, а также проверить функционал приложения на удаленном сервере.

• Контейнеризация с Docker: Проект упакован в контейнеры с использованием Docker и Docker Compose, обеспечивая легкость развертывания в различных окружениях.

• Автоматизированное тестирование: Реализованы тесты для различных компонентов приложения, гарантируя надежность и корректность его работы. Тесты запускаются при развертывании контейнеров или могут быть запущены вручную для проверки функциональности.

• Автоматизация с pre-commit: В проекте реализован pre-commit, автоматизирующий проверку кода на соответствие стандартам перед каждым коммитом. Это обеспечивает единообразие кода и улучшает его качество.

• Логгирование для отслеживания действий: Внедрено логгирование, которое фиксирует ключевые действия приложения, обеспечивая прозрачность и отслеживание работы системы.

Используемый стек

• Python: Версия 3.11
• Django: Версия 4.2.7
• Django REST framework: Библиотека для разработки RESTful API.
• Jinja2: Шаблонизатор для генерации HTML-кода, обеспечивает динамичное форматирование данных в шаблонах.
• pdfkit с wkhtmltopdf: Инструментарий для создания PDF-файлов из HTML-шаблонов, обеспечивает форматирование и структурирование документов.
• qrcode: Библиотека для генерации QR-кодов, используется для создания уникальных идентификаторов и быстрой передачи информации.
• pytest: Фреймворк для тестирования приложения, автоматизирует процесс проверки корректности кода и функциональности приложения.
• drf-spectacular: Инструмент для автоматической генерации OpenAPI-спецификации API на основе кода Django REST Framework, обеспечивает документирование и взаимодействие с API.
• pre-commit: Автоматическая проверка и форматирование кода перед коммитом
• gunicorn: WSGI HTTP-сервер для обслуживания Django-приложения.

Внешнее ПО

• PyCharm: Интегрированная среда разработки Python.
• Docker: Контейнеризация приложения и зависимостей для легкого развертывания.
• Postman: Инструмент для тестирования и проверки функциональности API.
• Google Chrome: Браузер для проверки работоспособности приложения (через Swagger).
• Смартфон: Камера смартфона, поддерживающая сканирование QR-кодов для перехода на страницу с кассовым чеком.

Запуск и демонстрация проекта

Пользователь может проверить доступные пути API проекта, уже развёрнутом на удалённом сервере, либо развернуть проект на своей локальной машине (с использованием Docker или без).

Демонстрация приложения на удалённом сервере

Доступные пути API:

• http://158.160.48.231/cash_machine: веб-узел для принятия POST-запроса на генерацию QR-кода.

• http://158.160.48.231/api/v1/create_items/: веб-узел для загрузки тестового наполнения БД.

• http://158.160.48.231/api/v1/swagger-ui/#/: Swagger - Интерактивная документация API для ознакомления с функциональностью и возможными ошибками.

• http://158.160.48.231/api/v1/redoc/: Redoc - Интерактивная документация API для ознакомления с функциональностью и возможными ошибками.

Локальный запуск приложения с использованием Docker

Подробная инструкция (нажмите на эту строчку, чтобы открыть):

Для локальной установки проекта необходимо выполнить следующие шаги:

Установка и настройка внешнего ПО:

• Docker: Если у вас ещё не установлен Docker, следуйте инструкциям на официальном сайте Docker для вашей операционной системы: https://docs.docker.com/get-docker/. После установки убедитесь, что Docker Daemon запущен.
• Docker Compose: Установите Docker Compose, если он ещё не установлен. Docker Compose используется для управления многоконтейнерными приложениями. Инструкции по установке можно найти здесь: https://docs.docker.com/compose/install/

Запуск приложения:

• Клонирование репозитория

[email protected]:Leenominai/test_cash_machine.git

• Переход в рабочую папку приложения

cd backend

• Настройка файлов окружения: Создайте файл окружения .env в корне вашего проекта.
• Скопируйте все данные из файла .env.example в файл .env:
  • Сейчас в файле .env.example присутствуют значения всех необходимых переменных только для локальной проверки приложения, а для сервера все переменные скрыты в GitHub Secrets.
• Запуск контейнеров: Запустите приложение с помощью Docker Compose:

cd ..
cd docker_local
docker-compose up -d

• Создание профиля администратора:

docker exec -it test_backend bash
python manage.py createsuperuser
exit

Доступные пути API

• http://192.168.31.12:8000/cash_machine: веб-узел для принятия POST-запроса на генерацию QR-кода.

• http://192.168.31.12:8000/api/v1/create_items/: веб-узел для загрузки тестового наполнения БД.

• http://192.168.31.12:8000/api/v1/swagger-ui/#/: Swagger - Интерактивная документация API для ознакомления с функциональностью и возможными ошибками.

• http://192.168.31.12:8000/api/v1/redoc/: Redoc - Интерактивная документация API для ознакомления с функциональностью и возможными ошибками.

• http://192.168.31.12:8000/admin/ - Консоль администратора

  Параметры входа в консоль - какие были указаны при создании профиля администратора.

Локальный запуск приложения без использования Docker

Подробная инструкция (нажмите на эту строчку, чтобы открыть):

Для локальной установки проекта необходимо выполнить следующие шаги:

Запуск приложения:

• Клонирование репозитория

[email protected]:Leenominai/test_cash_machine.git

• Переход в рабочую папку приложения

cd backend

• Настройка файлов окружения: Создайте файл окружения .env в корне вашего проекта.
• Скопируйте все данные из файла .env.example в файл .env:
  • Сейчас в файле .env.example присутствуют значения всех необходимых переменных только для локальной проверки приложения, а для сервера все переменные скрыты в GitHub Secrets.

ВАЖНО: установка wkhtmltopdf и настройка pdfkit:

• Установить wkhtmltopdf на свою рабочую машину с официального сайта: https://wkhtmltopdf.org/
• Проверить место установки и скопировать путь к исполняемому файлу wkhtmltopdf.exe
• Скопированный путь прописать в PATH используемой ОС.
• Переход в папку с файлом settings.py

cd cash_machine/cash_machine

• Открыть views.py в рабочем приложении
• Указать скопированный путь в поле WKHTMLTOPDF_DOCKER_PATH на 134 строчке, вместо существующего.
• Сейчас выглядит так:

WKHTMLTOPDF_DOCKER_PATH = "/usr/bin/wkhtmltopdf"

• Будет выглядеть примерно так:

WKHTMLTOPDF_DOCKER_PATH = "C:\\Program Files\\wkhtmltopdf\\bin\\wkhtmltopdf.exe"

• Вернуться в корень проекта

cd ..
cd ..
cd ..

• Создание миграций и профиля администратора:

cd cash_machine
python manage.py makemigrations
python manage.py migrate
python manage.py createsuperuser

• Запуск приложения:

python manage.py runserver 192.168.31.12:8000

Доступные пути API

• http://192.168.31.12:8000/cash_machine: веб-узел для принятия POST-запроса на генерацию QR-кода.

• http://192.168.31.12:8000/api/v1/create_items/: веб-узел для загрузки тестового наполнения БД.

• http://192.168.31.12:8000/api/v1/swagger-ui/#/: Swagger - Интерактивная документация API для ознакомления с функциональностью и возможными ошибками.

• http://192.168.31.12:8000/api/v1/redoc/: Redoc - Интерактивная документация API для ознакомления с функциональностью и возможными ошибками.

• http://192.168.31.12:8000/admin/ - Консоль администратора

  Параметры входа в консоль - какие были указаны при создании профиля администратора.

Тестирование приложения

Тестирование в Postman на удалённом сервере

Для тестирования через программу Postman необходимо:

• Установить её на свою рабочую машину с официального сайта: https://www.postman.com/
• После установки необходимо перейти в раздел Workspaces
• Создать новый Request через +, либо изменить стандартный
• В шкалу URL необходимо ввести следующий адрес: http://158.160.48.231/cash_machine
• Слева от введённого адреса выбрать тип запроса: POST
• Далее, необходимо выбрать блок Body, раздел raw, тип JSON (синяя стрелочка с выбором чуть правее).
• Для загрузки используем следующий формат:

{
    "items": [1, 2, 3]
}

• Нажать кнопку Send (отправить запрос)

• После успешного выполнения запроса (в 1 раз может выполняться до 10 - задержка со стороны сервера) будет получен ответ системы с картинкой QR-кода:

  Пример ответа программы Postman с QR-кодом (нажмите на эту строчку, чтобы открыть):

  

• На данный QR-код необходимо навести камеру смартфона с включенным приложением, поддерживающим сканирование QR-кодов.

• После успешного сканирования QR-кода на вашем смартфоне произойдёт автоматическая переадресация на данный кассовый чек в вашем мобильном браузере по-умолчанию.

  Пример открываемого кассового чека (нажмите на эту строчку, чтобы открыть):

  

Примечания:

• На сервере уже создано тестовое наполнение в виде нескольких id, в том числе под номера 1, 2, 3.

• Если файлов с запрашиваемыми id не существует, либо если потребуется ввести иные id для генерации кассового чека с другими данными, то потребуются следующие действия:

• Создать новый Request через +, либо изменить стандартный

• В шкалу URL необходимо ввести следующий адрес: http://158.160.48.231/api/v1/create_items/

• Слева от введённого адреса выбрать тип запроса: POST

• Далее, необходимо выбрать блок Body, раздел raw, тип JSON (синяя стрелочка с выбором чуть правее).

• Для загрузки используем следующий формат (пример запроса, измените id на необходимые):

[
    {"id": 1, "title": "Макароны", "price": 80},
    {"id": 2, "title": "Огурцы", "price": 60},
    {"id": 3, "title": "Картошка", "price": 50}
]

• Далее снова повторить POST-запрос на следующий адрес: http://158.160.48.231/cash_machine, как было расписано выше.

Тестирование через Swagger на удалённом сервере

Открыть информацию

Для тестирования через Swagger на удалённом сервере необходимо:

• Необходимо перейти по следующему адресу в рабочем браузере: http://158.160.48.231/api/v1/swagger-ui/#/
• Открыть метод POST /cash_machine в блоке Кассовый чек - генерация QR-кода
• В описании метода находится пример запроса в формате JSON, можно использовать его:

{
    "items": [1, 2, 3]
}

• Нажать кнопку Try it out в правой части.

• В появившееся поле вместо существующие данные заменить JSON-запросом выше.

• Нажать синюю кнопку Execute под полем ввода.

• После успешного выполнения запроса будет получен ответ системы с картинкой QR-кода:

  Пример ответа программы Postman с QR-кодом (нажмите на эту строчку, чтобы открыть):

  

• На данный QR-код необходимо навести камеру смартфона с включенным приложением, поддерживающим сканирование QR-кодов.

• После успешного сканирования QR-кода на вашем смартфоне произойдёт автоматическая переадресация на данный кассовый чек в вашем мобильном браузере по-умолчанию.

• Кассовый чек будет вида:

  Пример открываемого кассового чека (нажмите на эту строчку, чтобы открыть):

  

Примечания:

• На сервере уже создано тестовое наполнение в виде нескольких id, в том числе под номера 1, 2, 3.

• Если файлов с запрашиваемыми id не существует, либо если потребуется ввести иные id для генерации кассового чека с другими данными, то потребуются следующие действия:

• Создать новый Request через +, либо изменить стандартный

• В шкалу URL необходимо ввести следующий адрес: http://192.168.31.12:8000/api/v1/create_items/

• Слева от введённого адреса выбрать тип запроса: POST

• Далее, необходимо выбрать блок Body, раздел raw, тип JSON (синяя стрелочка с выбором справа).

• Для загрузки используем следующий формат (пример запроса, измените id на необходимые):

[
    {"id": 1, "title": "Макароны", "price": 80},
    {"id": 2, "title": "Огурцы", "price": 60},
    {"id": 3, "title": "Картошка", "price": 50}
]

• Далее снова повторить POST-запрос на следующий адрес: http://192.168.31.12:8000/cash_machine, как было расписано выше.

ВАЖНО:

• Иногда запрос может выдать ошибку CSRF-токенов, которая проходит при отключении VPN, либо через некоторый промежуток времени. Если ошибка осталась - необходимо выполнять тестирование через другую сеть, либо через Postman.

Тестирование в Postman при локальной установке

Открыть информацию

Для тестирования через программу Postman при локальном запуске с использованием Docker или без необходимо:

• Установить её на свою рабочую машину с официального сайта: https://www.postman.com/
• После установки необходимо перейти в раздел Workspaces
• Создать новый Request через +, либо изменить стандартный
• В шкалу URL необходимо ввести следующий адрес: http://192.168.31.12:8000/api/v1/create_items/
• Слева от введённого адреса выбрать тип запроса: POST
• Далее, необходимо выбрать блок Body, раздел raw, тип JSON (синяя стрелочка с выбором справа).
• Для загрузки используем следующий формат (пример запроса, измените id на необходимые):

[
    {"id": 1, "title": "Макароны", "price": 80},
    {"id": 2, "title": "Огурцы", "price": 60},
    {"id": 3, "title": "Картошка", "price": 50}
]

• Далее создать новый Request через +, либо изменить стандартный
• В шкалу URL необходимо ввести следующий адрес: http://192.168.31.12:8000/cash_machine
• Слева от введённого адреса выбрать тип запроса: POST
• Далее, необходимо выбрать блок Body, раздел raw, тип JSON (синяя стрелочка с выбором справа).
• Для загрузки используем следующий формат:

{
    "items": [1, 2, 3]
}

• Нажать кнопку Send (отправить запрос)

• После успешного выполнения запроса будет получен ответ системы с картинкой QR-кода:

  Пример ответа программы Postman с QR-кодом (нажмите на эту строчку, чтобы открыть):

  

• На данный QR-код необходимо навести камеру смартфона с включенным приложением, поддерживающим сканирование QR-кодов.

• После успешного сканирования QR-кода на вашем смартфоне произойдёт автоматическая переадресация на данный кассовый чек в вашем мобильном браузере по-умолчанию.

  Пример открываемого кассового чека (нажмите на эту строчку, чтобы открыть):

  

Примечания:

• Если файлов с запрашиваемыми id не существует, либо если потребуется ввести иные id для генерации кассового чека с другими данными, то потребуются следующие действия:

Тестирование через Swagger при локальной установке

Открыть информацию

Для тестирования через Swagger на удалённом сервере необходимо:

• Необходимо перейти по следующему адресу в рабочем браузере: http://192.168.31.12:8000/api/v1/swagger-ui/#/
• Для тестирования необходимо загрузить в БД тестовые данные, для этого необходимо:
• Открыть метод POST /api/v1/create_items/ в блоке БД - заполнение базы данных (при необходимости)
• В описании метода находится пример запроса в формате JSON, можно использовать его:

[
    {"id": 1, "title": "Макароны", "price": 80},
    {"id": 2, "title": "Огурцы", "price": 60},
    {"id": 3, "title": "Картошка", "price": 50}
]

• Нажать кнопку Try it out в правой части.
• В появившееся поле вместо существующие данные заменить JSON-запросом выше.
• Нажать синюю кнопку Execute под полем ввода.
• Система выдаст JSON-ответ, который можно будет использовать в следующем методе.
• Открыть метод POST /cash_machine в блоке Кассовый чек - генерация QR-кода
• В описании метода находится пример запроса в формате JSON, можно использовать его:

{
    "items": [1, 2, 3]
}

• Нажать кнопку Try it out в правой части.

• В появившееся поле вместо существующие данные заменить JSON-запросом выше.

• Нажать синюю кнопку Execute под полем ввода.

• После успешного выполнения запроса будет получен ответ системы с картинкой QR-кода:

  Пример ответа программы Postman с QR-кодом (нажмите на эту строчку, чтобы открыть):

  

• На данный QR-код необходимо навести камеру смартфона с включенным приложением, поддерживающим сканирование QR-кодов.

• После успешного сканирования QR-кода на вашем смартфоне произойдёт автоматическая переадресация на данный кассовый чек в вашем мобильном браузере по-умолчанию.

• Кассовый чек будет вида:

  Пример открываемого кассового чека (нажмите на эту строчку, чтобы открыть):

  

Разработчики

Проект разработан и поддерживается Александром Рассыхаевым.

GitHub: Ссылка на GitHub профиль

Telegram: @Leenominai