Развертка сервиса

Установка Docker

Для MacOS

Colima является бесплатной альтернативой Docker Desktop для MacOS и Linux и представляет из себя инструмент для управления контейнерами Docker.

1. Необходимо удалить Docker Desktop, если он установлен.

2. Для непосредственной установки Colima будем использовать Homebrew командой консоли (далее мы будем всё время использовать консоль для управления):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

3. Таким же образом установите сам Docker и Colima:

brew install docker

brew install docker-compose

brew install --HEAD colima

4. После установки запустите виртуальную машину:

Для процессоров Apple Silicon (M1/M2/ARM), Lima >=0.14, MacOS >=13.0:

colima start --arch aarch64 --vm-type=vz --vz-rosetta

Для процессоров Intel:

colima start --vm-type=vz (последний аргумент для Lima>=0.14, MacOS >= 13.0)

5. Убедитесь, что Colima запущена:

colima status

INFO[0000] colima is running using macOS Virtualization.Framework <...>

6. Откройте командную строку и выполните команду:

docker -v

Если отобразится версия Docker, это означает, что установка Docker прошла успешно.

7. Теперь можно использовать Docker.

Для Astra Linux

Установка должна выполняться от имени пользователя, являющегося администратором системы (при включенном МКЦ - пользователя с высоким уровнем целостности).

1. Для установки Docker требуется выполнить следующие команды:

sudo apt update
sudo apt install docker.io

2. После установки Docker рекомендуется предоставить администратору право работать с контейнерами не используя sudo:

sudo usermod -aG docker $USER

3. Откройте командную строку и выполните команду:

docker -v

Если отобразится версия Docker, это означает, что установка Docker прошла успешно.

4. Теперь можно использовать Docker.

Для Windows

Рассмотрим установку Docker Desktop for Windows — это Community-версия Docker для систем Microsoft Windows.

1. Включите функции Hyper-V Containers Window. Для этого перейдите в панель управления - установка и удаление программ - включение или отключение компонентов Windows. Активируйте пункт Hyper-V, который включает Hyper-V Managment Tools, Hyper-V Platform.

Также это можно выполнить через powershell или dism (все команды необходимо выполнять с правами администратора).

Powershell:

Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All

DISM:

DISM /Online /Enable-Feature /All /FeatureName:Microsoft-Hyper-V

2. Скачайте установщик Docker (Docker Desktop Installer) с Docker Hub: https://docs.docker.com/docker-for-windows/install

3. Запустите установщик Docker Desktop Installer.exe и ожидайте, пока он скачает все необходимые компоненты.

4. После установки система потребует перезагрузки. Перезагрузитесь и войдите в систему.

5. После входа может возникнуть запрос на установку дополнительного компонента WSL2. Перейдите по ссылке и скачайте необходимый пакет с официального сайта Microsoft.

6. После скачивания выполните установку WSL2, после которой снова потребуется перезагрузка.

7. Откройте командную строку и выполните команду:

docker -v

Если отобразится версия docker, это означает, что установка docker в Windows прошла успешно.

8. Теперь можно использовать Docker.

Установка сервиса

1. Скачайте архив проекта из репозитория GitHub. Для этого в репозитории необходимо нажать зелёную кнопку <> Code и в появившемся меню нажать Download ZIP. (https://github.com/Krebkel/A.NCJsonService)

2. Разархивируйте скачанный архив проекта.

3. В терминале выполните следующую команду для создания хранилища контейнеров:

docker volume create pgdata

4. Откройте в терминале директорию с проектом, в которой лежит файл Dockerfile. Все следующие команды необходимо выполнять из этой директории - корня проекта.

5. В терминале необходимо сбилдить проект командой:

docker build -t document .

Обратите внимание, что в конце команды есть точка. В терминале должна через некоторое время появиться строка:

Successfully tagged document:latest

5. После успешного билда запустите сервис вместе с базой данных командой:

docker-compose -f docker-compose.yml up

6. В терминале выполните команду:

docker ps

Должны появиться строки в виде таблицы, в которой в столбце IMAGE есть следующие записи:

document:latest

postgres:13

7. Сервис готов к работе.

Запуск и использование сервиса

1. Скомпилируйте проект

2. Откройте в браузере страницу localhost:80/Swagger/Index.html. Появится список API.

3. Работа с товарами

3.1. Для добавления в базу данных товара необходимо использовать запрос POST /api/Wares с параметрами name - уникальное наименование, value - цена, property - примечания или свойства товара. Уникальный первичный ключ id генерируется автоматически.

3.2. Для получения списка всех товаров необходимо использовать запрос GET /api/Wares без параметров.

3.3. Для получения конкретного товара необходимо использовать запрос GET /api/Wares/{id} с параметром id - первичного ключа товара.

3.4. Для изменения товара в базе данных необходимо использовать запрос PUT /api/Wares/{id} с параметрамиid - первичного ключа товара.name - уникальное наименование, value - цена, property - примечания или свойства товара.

3.5. Для удаления товара из базы данных необходимо использовать запрос DELETE /api/Wares/{id} с параметром id - первичного ключа товара.

3.6. Для импорта в базу данных товаров из файла JSON необходимо использовать запрос POST /api/Wares/import. Уникальный первичный ключ id генерируется автоматически. Файл JSON должен иметь следующую структуру:

[ { "Name":"Товар1", "Value":10, "Property":"Хороший", "Id":1 }, { "Name":"Товар2", "Value":20, "Property":"Вкусный", "Id":2 } ]

Уникальный первичный ключ id генерируется автоматически. Требуются уникальные свойства name. Возможен импорт одного товара.

3.7. Для экспорта из базы данных товаров в файл JSON необходимо использовать запрос GET /api/Wares/export без параметров. Файл JSON будет иметь следующую структуру:

[ { "Name":"Товар1", "Value":10, "Property":"Хороший", "Id":1 }, { "Name":"Товар2", "Value":20, "Property":"Вкусный", "Id":2 } ]

3.8. Для экспорта из базы данных конкретного товара в файл JSON необходимо использовать запрос GET /api/Wares/{id}/export с параметром id - первичного ключа товара. Файл JSON будет иметь следующую структуру:

[ { "Name":"Товар1", "Value":10, "Property":"Хороший", "Id":1 } ]

4. Работа с заказами

4.1. Для добавления в базу данных заказа необходимо использовать запрос POST /api/Orders с параметрами id - уникальный номер заказа, date - дата заказа, note - примечание к заказу. Уникальный первичный ключ id и дата заказа генерируется автоматически.

4.2. Для получения списка всех заказов необходимо использовать запрос GET /api/Orders без параметров.

4.3. Для получения конкретного заказа необходимо использовать запрос GET /api/Orders/{id} с параметром id - первичного ключа заказа.

4.4. Для изменения заказа в базе данных необходимо использовать запрос PUT /api/Orders/{id} с параметрамиid - первичного ключа заказа.number - уникального номера заказа, date - даты заказа, note - примечания заказа.

4.5. Для удаления заказа из базы данных необходимо использовать запрос DELETE /api/Orders/{id} с параметром id - первичного ключа заказа.

4.6. Для импорта в базу данных заказов из файла JSON необходимо использовать запрос POST /api/Orders/import. Уникальный первичный ключ id генерируется автоматически. Файл JSON должен иметь следующую структуру:

[ {"Order": { "Number":"Заказ1", "Date":"2024-07-10T07:18:04.277+00:00", "Note":"Примечание1", "Id":1 }, "Positions": [ { "WareId":1," OrderId":1, "Id":1 }, { "WareId":2, "OrderId":1, "Id":2 } ] }, {"Order": { "Number":"Заказ2", "Date":"2024-07-10T07:18:04.277+00:00", "Note":"Примечание2", "Id":2 }, "Positions": [ { "WareId":3, "OrderId":2, "Id":3 }, { "WareId":4, "OrderId":2, "Id":4 } ] }
]

Уникальный первичный ключ id заказа генерируется автоматически. Требуются уникальные свойства number. Возможен импорт одного заказа.

4.7. Для экспорта из базы данных товаров в файл JSON необходимо использовать запрос GET /api/Wares/export без параметров. Файл JSON будет иметь следующую структуру:

[ {"Order": { "Number":"Заказ1", "Date":"2024-07-10T07:18:04.277+00:00", "Note":"Примечание1", "Id":1 }, "Positions": [ { "WareId":1," OrderId":1, "Id":1 }, { "WareId":2, "OrderId":1, "Id":2 } ] }, {"Order": { "Number":"Заказ2", "Date":"2024-07-10T07:18:04.277+00:00", "Note":"Примечание2", "Id":2 }, "Positions": [ { "WareId":3, "OrderId":2, "Id":3 }, { "WareId":4, "OrderId":2, "Id":4 } ] }
]

4.8. Для экспорта из базы данных конкретного заказа в файл JSON необходимо использовать запрос GET /api/Orders/{id}/export с параметром id - первичного ключа заказа. Файл JSON будет иметь следующую структуру:

[ {"Order": { "Number":"Заказ1", "Date":"2024-07-10T07:18:04.277+00:00", "Note":"Примечание1", "Id":1 }, "Positions": [ { "WareId":1," OrderId":1, "Id":1 }, { "WareId":2, "OrderId":1, "Id":2 } ] } ]

5. Работа с позициями заказа

5.1. Для добавления в базу данных позиции конкретного заказа необходимо использовать запрос POST /api/Positions/{orderId}/positions с параметрами orderId - первичного ключа заказа (id заказа), wareId - первичного ключа товара (id товара). Уникальный первичный ключ id позиции генерируется автоматически.

5.2. Для получения списка всех заказов необходимо использовать запрос GET /api/Positions/byOrder/{orderId} с параметрами orderId - первичного ключа заказа (id заказа).

5.3. Для удаления конкретной позиции из заказа необходимо использовать запрос DELETE /api/Positions/{orderID}/positions/{wareId} с параметром orderId - первичного ключа заказа (id заказа), wareId - первичного ключа товара (id товара).

6. Работа с событиями

6.1. Для добавления в базу данных события можно воспользоваться импортом из JSON файла и ручным вводом. Чтобы ввести данные вручную, необходимо использовать запрос POST api/Events с параметрами name и value. Первичный ключ события id и время прихода события timestamp генерируются автоматически.

6.2. Для добавления в базу данных события из JSON файла необходимо использовать запрос POST api/Events/import. Файл JSON будет иметь следующую структуру:

[ { "name":"Событие1", "Value":10 }, { "name":"Событие2", "Value":20 } ]

Уникальный первичный ключ id события и время прихода события timestamp генерируются автоматически. Возможен импорт одного события.

6.3. Для получения списка сумм событий необходимо использовать запрос GET /api/Events с параметрами startTime - времени начала отсчета и endTime - времени окончания отсчета, являющимися строками в формате "ДД.ММ.ГГГГ ЧЧ:ММ:СС" (к примеру, 02.02.2024 10:10:00 или 10.07.2024 16:36:22) в часовом поясе UTC. Результатом запроса будет список пар "Время: Сумма", где "Время" является строкой даты в формате "ДД.ММ.ГГГГ ЧЧ:ММ:СС" (к примеру, 02.02.2024 10:10:00 или 10.07.2024 16:36:22) в часовом поясе UTC, а "Сумма" - это сумма атрибутов value для всех событий в базе данных за минуту, последующую за обозначенным временем. В случае отсутствия данных в сумме выводится ноль. Пример:

{ "10.07.2024 13:21:00": 0, "10.07.2024 13:22:00": 10, "10.07.2024 13:23:00": 10, "10.07.2024 13:24:00": 0, "10.07.2024 13:25:00": 40, "10.07.2024 13:26:00": 0, "10.07.2024 13:27:00": 0, "10.07.2024 13:28:00": 0, "10.07.2024 13:29:00": 0 }

7. Интерактивная работа с сервисами не через Swagger

Для удобства присутствуют базовые интерактивные функции на странице localhost:80/Index.html. Через них можно работать с заказами, товарами и событиями, добавлять и удалять позиции в заказе, импортировать и экспортировать JSON файлы (формат таких файлов описан выше), есть расчет суммы позиций в заказе.

Рекомендуется использовать браузер Chrome. Замечена некорректная работа интерактивных функций в браузере Safari. Корректная работа фронта не гарантируется.