1. Общие положения

1.1. Описание.

Система регистрации чеков в электронной очереди производства, состоит из двух основных компонентов:

• Django - приложение самой электронной очереди и печати номеров заказов
• Приложение сборщик данных по продажам из касс Set Retail 10 (Crystal)
• Каждый компонент запускается в своем Docker контейнере. Названия контейнеров elq и api_import соответственно.
• Приложение доступно по следующим портам:
  • 8000 - веб-интерфейс электронной очереди
  • 631 - настройка CUPS

1.2. Требования к размещению и функционированию

• Если настройка и установка происходит из сети магазина, то на период установки необходимо отключить Firewall, это можно сделать через бота управления mikrotik магазина. После завершения настройки, Firewall нужно включить.
• Для работы приложения Электронная очередь требуется Docker, версия не ниже 20.10.17, Linux или Windows.
• Все настройки Django передаются через переменные окружения, в файле .env.
• Настройки Приложение сборщик данных в файле main.json.
• Для печати номера заказов должен быть настроен принтер SAM4s ELLIX50. Принтер должен быть доступен через сетевое соединение.
• Подробное описание файла настроек .env и main.json и настройка CUPS в разделе 2.3. Установка и настройка приложения.

2. Установка и настройка

2.1. Установка Docker

2.1.1.Установка Docker на примере Ubuntu 20.04

• Обновляем индексы apt

 sudo apt-get update

 sudo apt-get install \
    ca-certificates \
    curl \
    gnupg \
    lsb-release

• Добавляем GPG ключ Docker

 sudo mkdir -p /etc/apt/keyrings

 curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

• Подключаем репозиторий Docker

 echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

• Устанавливаем Docker Engine

 sudo apt-get update

 sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin

• Проверяем версию

docker --version

2.1.2. Настройка запуска Docker без sudo

• Создаем группу docker

sudo groupadd docker

• Добавляем текущего пользователя $USER в группу docker

sudo usermod -aG docker $USER

• Применяем изменения

newgrp docker

• Проверяем запуск без sudo

docker run hello-world

2.2. Установка Docker в Windows

2.2.1. Установка Docker Desktop

Устанавливается как обычное приложение, ссылка для скачивания -> Docker Desktop.

2.2.2. Установка git

git не входит в стандартную поставку Windows, поэтому его нужно установить отдельно, Git for Windows. Установка стандартная, с параметрами по умолчанию.

2.2.3. Отличия от инструкции по настройке в Linux

Шаги по настройке в Windows практически не отличаются, и отдельно их расписывать нет смысла, нужно просто заменить действия по переименованию файлов и редактированию, на те как они выполняются в Windows. Команды по запуску docker совпадают по синтаксису и выполняются в том же порядке.

2.3. Установка и настройка приложения

2.3.1. Запуск контейнеров

• Клонируем репозиторий приложения

git clone https://github.com/MyEternityOrg/elq

• Переходим в директорию проекта

cd elq

• Настройки Django приложения находятся в файл .env. Переименовываем файл с примерами настроек в .env

mv .env.sample .env

• Вносим изменения, если необходимо. Важным является ключ API_KEY к интерфейсу получения кассовых чеков, его необходимо сохранить и указать в настройках Приложения сборщик данных в файле main.json.
• CALC_PRINT_TICKETS - настройка режима печати, -1 - печать по количеству отделов +2 слипа, >0 - строго заданное количество, 0 - печатать только 1 слип.
• PRINT_PAPER_W / PRINT_PAPER_H - настройка шаблона печати Ширина/Высота слипа, под ширину система осуществит обрезку текста.

nano .env

API_KEY = 'secret_key_here'
SQL_ENGINE = 'django.db.backends.sqlite3'
SQL_DB_NAME = './elq.sqlite3'
SQL_DB_USER = 'user'
SQL_DB_PASSWORD = 'pass'
SQL_DB_HOST = '.'
SQL_DB_PORT = 1433
SQL_OPTIONS = '{}'
CALC_PRINT_TICKETS = 0
PRINT_PAPER_W = 57
PRINT_PAPER_H = 120

• Настраиваем Приложения сборщик данных. Переименовываем файл с примерами настроек в main.json

mv ./api_import_receipts/main.json.sample ./api_import_receipts/main.json

• Редактируем файл, нужно указать ключ API_KEY из файла .env и настроить ip адреса касс.

nano ./api_import_receipts/main.json

Пример настройки для Магазина 116 :

{
  "api": "http://elq:8000/devices/import_receipt/",
  "api_key": "secret_key_here",
  "timer": 3,
  "cashes": [
    {
      "sql_server": "10.1.16.11"
    },
    {
      "sql_server": "10.1.16.12"
    },
    {
      "sql_server": "10.1.16.13"
    },
    {
      "sql_server": "10.1.16.14"
    },
    {
      "sql_server": "10.1.16.15"
    }
  ]
}

• Запускаем контейнеры

docker compose up -d

• Дожидаемся сбора образов и запуска. Проверяем, что контейнеры в статусе up

docker ps -a

• Если возникли проблемы, можно посмотреть лог

docker logs elq

docker logs api_import

2.3.2. Настройка CUPS

• Для печати талонов нужно настроить принтер в службе CUPS, она доступа по адресу. Логин/пароль print.

http://ip_сервера:631/

• Добавляем принтер с подключением через socket, в строке подключения указываем

socket://ip_принтера:6001

• Важно запомнить имя под которым добавляется принтер, например ELLIX50. Его затем нужно будет указать в веб интерфейсе Django приложения
• на этапе выбора модели нужно подгрузить PPT файл. Для модели SAM4s ELLIX50 файл можно скачать по прямой ссылке git
• Для проверки можно отправить тестовую страницу на печать

2.3.3. Настройка приложения

• Приложение доступно по ссылке. Логин/пароль магазина shop 123

http://ip_сервера:8000/

• В разделе администрирования настраиваются Кассы и Принтеры. ВАЖНО. Имя принтера нужно взять из раздела 2.3.2. Настройка CUPS

http://ip_сервера:8000/admin/

2.3.4. Внесение правок в файлы конфигурации

Если нужно внести изменения в файлы в уже развернутом приложении:

• для изменения файла main.json

cd elq
docker exec -it api_import /bin/sh
nano ./elq/api_import_receipts/main.json

• для изменения файла .env

cd elq
docker exec -it elq /bin/sh
nano ./elq/.env

после внесения правок, нужно отключиться от контейнера и выполнить перезапуск

exit
docker compose stop
docker compose up -d

2.3.5. Установка обновлений

Обновления устанавливаются автоматически из github при перезапуске контейнеров.

cd elq
docker compose stop
docker compose up -d

3. Интеграция

Интерфейс

http://ip_сервера:8000/devices/import_receipt/

принимает входящие POST запросы и регистрирует чеки. В заголовке запроса должен быть передан api_key, в теле запроса файл импорта чека.

Для ограничения доступа к post интерфейсу получения кассовых чеков можно задать свой собственный api_key, в файле .env

API_KEY = 'secret_key_here'

Пример, для curl:

curl -H "key:secret_key_here" --data "@receipt_1.json" http://127.0.0.1/devices/import_receipt/ > reply_1.json

Пример файла импорта чека:

• cash_id - Номер кассы
• shift_id - Номер смены.
• check_id - Номер чека в смене.
• check_date - Дата чека.
• wares - Массив товаров (сгруппирован по товарам с суммой по количеству)
  • ware_code - Код товара в чеке.
  • ware_count - Количество товара в чеке.

{
  "cash_id": 1,
  "shift_id": 1,
  "check_id": 1,
  "check_date": "2022-11-17",
  "wares": [
    {
      "ware_code": "48566",
      "ware_count": 4
    },
    {
      "ware_code": "51356",
      "ware_count": 1
    },
    {
      "ware_code": "72542",
      "ware_count": 1
    }
  ]
}

Файл ответа с информацией о номере очереди:

В случае успешной регистрации, система вернет номер очереди doc_number>0.

В случае ошибки - система вернет doc_number=0 и описание ошибки.

В случае, когда действий не требуется (нечего регистрировать) система вернет doc_number=-1 и сообщение.

Пример файла ответа:

{
  "doc_number": -1,
  "error": "Already have receipt with number 1 for cash 1 in 2022-11-21"
}