API docs by Redocly

Продажа песчано-гравийной смеси (3.0.0)

Описание

Разработать приложение, решающее задачу по управлению списком актов отгрузки песчано-гравийной смеси (ПГС).

Данные

Приложение считывает все данные из соответствующих CSV-файлов (разделитель – запятая) при старте приложения.

Список актов отгрузки ПГС

Имя файла с исходными данными передаётся приложению с ключом --swg-file

Id,Title,SWG,Measure,Count,Price,Cost,ShipmentDateTime,DumpTruck,Washing,Manager
de42a00f-7f43-4d10-808d-bee47fdeef49,Песчано-гравийная смесь (ПГС),Песок речной,т,36,640,22.3488,"2024-01-01T00:00:00",accfe76f-9a9e-4cb4-8876-d36daa22f924,True,de42a00f-7f43-4d10-808d-bee47fdeef49
2b52fcb1-34ec-48d2-95f2-b79f2d9c3c70,Песчано-гравийная смесь (ПГС),Щебень гранитный,м3,14,2660,36.1228,"2024-01-01T00:00:00",accfe76f-9a9e-4cb4-8876-d36daa22f924,True,de42a00f-7f43-4d10-808d-bee47fdeef49

Список самосвалов

Имя файла с исходными данными передаётся приложению с ключом --dump-trucks-file

Id,Model,Registration,Capacity,Volume
accfe76f-9a9e-4cb4-8876-d36daa22f924,KAMAZ-65951-СА,Д903ЧН,36.0,25
f8741785-4986-41ab-85d3-8b2fe522f9ed,МАЗ 5516А8-336,Э723ВЛ,37.0,26

Список работников (пользователей)

Имя файла с исходными данными передаётся приложению с ключом --employees-file

Id,Name,Position,RegistrationDateTime,Email,Role
de42a00f-7f43-4d10-808d-bee47fdeef49,Иванов Иван Иванович,Начальник смены,2024-01-01T00:00:00,IvanovII@crafted.su,Manager

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

Приложение запускается с помощью системы сборки Gradle, обязательные параметры:

  • --swg-file – имя файла с данными приложения
  • --dump-trucks-file – имя файла с данными приложения
  • --employees-file – имя файла с пользователями приложения
  • --port – порт, по которому доступен веб-сервер
  • --secret - секретный ключ для HMAC512, который используется для подписи JWT-токенов.
  ./gradlew run --args="--swg-file ../sample-data/swg.csv --dump-trucks-file ../sample-data/trucks.csv --employees-file ../sample-data/employees.csv --port 9000 --secret SECRET"

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

  Error: missing option --employees-file

  Error: file not found «abc.csv»

Аутентификация

Во время выполнения запроса пользователь может передать JWT-токен в HTTP-заголовке Authorization в формате Bearier. Отправка Bearier-токена через HTTP-форму или параметры URI не будет выполняться.

jwt

Токен содержит следующие ключи:

  • sub – имя пользователя, которому выдан токен (соответствует Employee→Login);
  • exp – время, когда токен станет невалидным.
Security Scheme Type: HTTP
HTTP Authorization Scheme: bearer
Bearer format: JWT

Для указанного пользователя определяется роль Employee→Role. В каждом запросе приведён список ролей, для которых допустимо выполнения запроса. Также присутствуют роли:

  • Owner – выполнение запроса разрешено владельцу объекта.

Все дополнительные роли и правила доступа приведены в описании маршрута.

Если в описании маршрута отсутствует блок Authorizations, маршрут доступен всем пользователям.

Если блок Authorizations присутствует, но список ролей пуст или all, маршрут доступен всем зарегистрированным пользователям вне зависимости от роли.

Базовые маршруты

Маршруты проверки работоспособности веб-сервера

Проверка, запущен ли веб-сервер

Маршрут обязательно должен быть реализован, при отсутствии приложение не будет проверяться.

Responses

ПГС

Методы, связанные со списком отгрузок ПГС

Получение списка ПГС

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

query Parameters
page
integer >= 1
Default: 1
Example: page=1

Номер страницы.

Если номер превышает максимально возможный, приложение возвращает пустой список.

Если номер передан и не является натуральным числом, приложение возвращает сообщение об ошибке.

records-per-page
integer
Default: 10
Enum: 5 10 20 50
Example: records-per-page=10

Количество записей на странице.

Если количество передано и не входит в указанный набор значений, приложение возвращает сообщение об ошибке.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Создание новой отгрузки

Идентификатор отгрузки генерируется автоматически.

Authorizations:
jwt
Request Body schema: application/json
required
Title
required
string

Наименование ПГС

SWG
required
string
Enum: "Песок речной" "Песок карьерный" "Щебень гранитный" "Щебень гравийный" "Щебень шлаковый" "Песчано-гравийная смесь"
Тип ПГС Насыпная плотность (т/м3)
Песок речной 1.5
Песок карьерный 1.5
Щебень гранитный 1.4
Щебень гравийный 1.43
Щебень шлаковый 1.17
Песчано-гравийная смесь 1.6
Measure
required
string
Enum: "м3" "т"

Единица измерения

Count
required
number <double> > 0

Отгруженное количество

Price
required
number <double> > 0

Цена за ед. измерения (руб.)

Cost
required
number <double> > 0

Стоимость (тыс. руб.)

ShipmentDateTime
string <date-time>
Default: "текущая дата и время"

Дата и время отгрузки

Washing
boolean
Default: false

Была ли оказана услуга мытья ТС?

DumpTruck
required
string <UUID>

Уникальный идентификатор самосвала

Manager
string <UUID>
Default: "работник, выполнивший запрос"

Уникальный идентификатор работника.

Только пользователь с ролью Manager может создавать отгрузки для других работников.

Пользователь с ролью Employee может создавать отгрузки только для себя.

Responses

Request samples

Content type
application/json
{
  • "Title": "Песчано-гравийная смесь (ПГС)",
  • "SWG": "Песок речной",
  • "Measure": "м3",
  • "Count": 36,
  • "Price": 640,
  • "Cost": 22.3488,
  • "ShipmentDateTime": "2024-01-01T00:00:00",
  • "Washing": true,
  • "DumpTruck": "accfe76f-9a9e-4cb4-8876-d36daa22f924",
  • "Manager": "de42a00f-7f43-4d10-808d-bee47fdeef49"
}

Response samples

Content type
application/json
{
  • "Id": "de42a00f-7f43-4d10-808d-bee47fdeef49"
}

Получение информации о ПГС

Authorizations:
jwt
path Parameters
shipment-id
required
string <UUID>
Example: de42a00f-7f43-4d10-808d-bee47fdeef49

идентификатор акта отгрузки ПГС

Responses

Response samples

Content type
application/json
{
  • "Id": "de42a00f-7f43-4d10-808d-bee47fdeef49",
  • "Title": "Песчано-гравийная смесь (ПГС)",
  • "SWG": "Песок речной",
  • "Measure": "м3",
  • "Count": 36,
  • "Price": 640,
  • "Cost": 22.3488,
  • "ShipmentDateTime": "2024-01-01T00:00:00",
  • "Model": "KAMAZ-65951-СА",
  • "Registration": "Д903ЧН",
  • "Washing": true,
  • "ManagerEmail": "IvanovII@crafted.su"
}

Редактирование акта отгрузки

Authorizations:
jwt
Request Body schema: application/json
required
Title
required
string

Наименование ПГС

SWG
required
string
Enum: "Песок речной" "Песок карьерный" "Щебень гранитный" "Щебень гравийный" "Щебень шлаковый" "Песчано-гравийная смесь"
Тип ПГС Насыпная плотность (т/м3)
Песок речной 1.5
Песок карьерный 1.5
Щебень гранитный 1.4
Щебень гравийный 1.43
Щебень шлаковый 1.17
Песчано-гравийная смесь 1.6
Measure
required
string
Enum: "м3" "т"

Единица измерения

Count
required
number <double> > 0

Отгруженное количество

Price
required
number <double> > 0

Цена за ед. измерения (руб.)

Cost
required
number <double> > 0

Стоимость (тыс. руб.)

ShipmentDateTime
string <date-time>

Дата и время отгрузки. Если отсутствует, то поле не изменяется.

Washing
boolean

Была ли оказана услуга мытья ТС. Если отсутствует, то поле не изменяется.

DumpTruck
required
string <UUID>

Уникальный идентификатор самосвала

Manager
string <UUID>

Уникальный идентификатор работника.

Только пользователь с ролью Manager может изменять работника на другого.

Responses

Request samples

Content type
application/json
{
  • "Title": "Песчано-гравийная смесь (ПГС)",
  • "SWG": "Песок речной",
  • "Measure": "м3",
  • "Count": 36,
  • "Price": 640,
  • "Cost": 22.3488,
  • "ShipmentDateTime": "2024-01-01T00:00:00",
  • "Washing": true,
  • "DumpTruck": "accfe76f-9a9e-4cb4-8876-d36daa22f924",
  • "Manager": "de42a00f-7f43-4d10-808d-bee47fdeef49"
}

Response samples

Content type
application/json
Example
{
  • "Value": "{",
  • "Error": "Missing a name for object member."
}

Получение списка отгрузок по типу ПГС

Список должен быть упорядочен по убыванию даты и времени отгрузки и возрастанию идентификатора

Authorizations:
jwt
query Parameters
by-swg-type
required
string (Swg-type)
Enum: "Песок речной" "Песок карьерный" "Щебень гранитный" "Щебень гравийный" "Щебень шлаковый" "Песчано-гравийная смесь"
Example: by-swg-type=Щебень гравийный

тип ПГС

page
integer >= 1
Default: 1
Example: page=1

Номер страницы.

Если номер превышает максимально возможный, приложение возвращает пустой список.

Если номер передан и не является натуральным числом, приложение возвращает сообщение об ошибке.

records-per-page
integer
Default: 10
Enum: 5 10 20 50
Example: records-per-page=10

Количество записей на странице.

Если количество передано и не входит в указанный набор значений, приложение возвращает сообщение об ошибке.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Получение списка отгрузок за период

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

Authorizations:
jwt
query Parameters
from
required
string <date>
Example: from=2024-01-01

Начало периода (дата отгрузки ≥ начало периода)

to
required
string <date>
Example: to=2024-02-01

Окончание периода (дата отгрузки ≤ окончание периода)

page
integer >= 1
Default: 1
Example: page=1

Номер страницы.

Если номер превышает максимально возможный, приложение возвращает пустой список.

Если номер передан и не является натуральным числом, приложение возвращает сообщение об ошибке.

records-per-page
integer
Default: 10
Enum: 5 10 20 50
Example: records-per-page=10

Количество записей на странице.

Если количество передано и не входит в указанный набор значений, приложение возвращает сообщение об ошибке.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Получение отчётной информации по объёму загрузки

Список должен содержать только те месяцы, для которых есть данные, и быть упорядочен по номеру месяца.

Authorizations:
jwt
query Parameters
year
required
integer >= 2000
Example: year=2024

отчётный год

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Регистрация накладной

Приложение разбирает накладную и создаёт:

  1. Самосвал. Если в списке самосвалов отсутствует объект с соответствующими полями Model и Registration, приложение создаёт новый объект.

    • Id генерируется уникальным,
    • Capacity соответствует весу отгрузки,
    • Volume соответствует весу отгрузки, поделённому на насыпную плотность.

  2. Акт отгрузки.

    • Id генерируется уникальным,
    • Measure=т,
    • ShipmentDateTime соответствует текущей дате и времени,
    • DumpTruck соответствует самосвалу, найденному по полям DumpTruckModel и DumpTruckRegistration,
    • Washing=false,
    • Manager соответствует пользователю, выполнившему запрос.
Authorizations:
jwt
Request Body schema: application/x-www-form-urlencoded
required
InvoiceTitle
required
string

Наименование ПГС

InvoiceType
required
string
Enum: "Песок речной" "Песок карьерный" "Щебень гранитный" "Щебень гравийный" "Щебень шлаковый" "Песчано-гравийная смесь"
Тип ПГС Насыпная плотность (т/м3)
Песок речной 1.5
Песок карьерный 1.5
Щебень гранитный 1.4
Щебень гравийный 1.43
Щебень шлаковый 1.17
Песчано-гравийная смесь 1.6
InvoiceWeight
required
number <double> > 0

Отгруженный вес

InvoicePrice
required
number <double> > 0

Цена за ед. измерения (руб.)

InvoiceCost
number <double> > 0
Default: "InvoicePrice * InvoiceWeight"

Стоимость (тыс. руб.)

DumpTruckModel
required
string

Модель транспортного средства

DumpTruckRegistration
required
string

Регистрационный номер ТС

Responses

Request samples

Content type
application/x-www-form-urlencoded
InvoiceTitle=%D0%9F%D0%B5%D1%81%D1%87%D0%B0%D0%BD%D0%BE-%D0%B3%D1%80%D0%B0%D0%B2%D0%B8%D0%B9%D0%BD%D0%B0%D1%8F%20%D1%81%D0%BC%D0%B5%D1%81%D1%8C%20%28%D0%9F%D0%93%D0%A1%29&InvoiceType=%D0%9F%D0%B5%D1%81%D0%BE%D0%BA%20%D1%80%D0%B5%D1%87%D0%BD%D0%BE%D0%B9&InvoiceWeight=36&InvoicePrice=640&InvoiceCost=22.3488&DumpTruckModel=KAMAZ-65951-%D0%A1%D0%90&DumpTruckRegistration=%D0%94903%D0%A7%D0%9D

Response samples

Content type
application/json
{
  • "ShipmentId": "de42a00f-7f43-4d10-808d-bee47fdeef49",
  • "DumpTruckId": "accfe76f-9a9e-4cb4-8876-d36daa22f924"
}

Самосвалы

Методы, связанные со списком самосвалов

Получение информации о самосвале

Authorizations:
jwt
path Parameters
dump-truck-id
required
string <UUID>
Example: accfe76f-9a9e-4cb4-8876-d36daa22f924

идентификатор самосвала

Responses

Response samples

Content type
application/json
{
  • "Id": "accfe76f-9a9e-4cb4-8876-d36daa22f924",
  • "Model": "KAMAZ-65951-СА",
  • "Registration": "Д903ЧН",
  • "Capacity": 32.5,
  • "Volume": 25,
  • "Shipments": [
    ]
}

Удаление самосвала

Authorizations:
jwt
path Parameters
dump-truck-id
required
string <UUID>
Example: accfe76f-9a9e-4cb4-8876-d36daa22f924

идентификатор самосвала

Responses

Response samples

Content type
application/json
{
  • "Error": "Некорректное значение переданного параметра X. Ожидается UUID, но получено текстовое значение"
}

Регистрация накладной

Приложение разбирает накладную и создаёт:

  1. Самосвал. Если в списке самосвалов отсутствует объект с соответствующими полями Model и Registration, приложение создаёт новый объект.

    • Id генерируется уникальным,
    • Capacity соответствует весу отгрузки,
    • Volume соответствует весу отгрузки, поделённому на насыпную плотность.

  2. Акт отгрузки.

    • Id генерируется уникальным,
    • Measure=т,
    • ShipmentDateTime соответствует текущей дате и времени,
    • DumpTruck соответствует самосвалу, найденному по полям DumpTruckModel и DumpTruckRegistration,
    • Washing=false,
    • Manager соответствует пользователю, выполнившему запрос.
Authorizations:
jwt
Request Body schema: application/x-www-form-urlencoded
required
InvoiceTitle
required
string

Наименование ПГС

InvoiceType
required
string
Enum: "Песок речной" "Песок карьерный" "Щебень гранитный" "Щебень гравийный" "Щебень шлаковый" "Песчано-гравийная смесь"
Тип ПГС Насыпная плотность (т/м3)
Песок речной 1.5
Песок карьерный 1.5
Щебень гранитный 1.4
Щебень гравийный 1.43
Щебень шлаковый 1.17
Песчано-гравийная смесь 1.6
InvoiceWeight
required
number <double> > 0

Отгруженный вес

InvoicePrice
required
number <double> > 0

Цена за ед. измерения (руб.)

InvoiceCost
number <double> > 0
Default: "InvoicePrice * InvoiceWeight"

Стоимость (тыс. руб.)

DumpTruckModel
required
string

Модель транспортного средства

DumpTruckRegistration
required
string

Регистрационный номер ТС

Responses

Request samples

Content type
application/x-www-form-urlencoded
InvoiceTitle=%D0%9F%D0%B5%D1%81%D1%87%D0%B0%D0%BD%D0%BE-%D0%B3%D1%80%D0%B0%D0%B2%D0%B8%D0%B9%D0%BD%D0%B0%D1%8F%20%D1%81%D0%BC%D0%B5%D1%81%D1%8C%20%28%D0%9F%D0%93%D0%A1%29&InvoiceType=%D0%9F%D0%B5%D1%81%D0%BE%D0%BA%20%D1%80%D0%B5%D1%87%D0%BD%D0%BE%D0%B9&InvoiceWeight=36&InvoicePrice=640&InvoiceCost=22.3488&DumpTruckModel=KAMAZ-65951-%D0%A1%D0%90&DumpTruckRegistration=%D0%94903%D0%A7%D0%9D

Response samples

Content type
application/json
{
  • "ShipmentId": "de42a00f-7f43-4d10-808d-bee47fdeef49",
  • "DumpTruckId": "accfe76f-9a9e-4cb4-8876-d36daa22f924"
}

Работники

Методы, связанные с работниками (пользователями приложения)

Получение списка работников

Список упорядочен по возрастанию ФИО и идентификатора

Authorizations:
jwt

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Акт отгрузки ПГС (Swg)

Id
string <UUID>

идентификатор акта отгрузки ПГС

Title
string

Наименование ПГС

SWG
string (Swg-type)
Enum: "Песок речной" "Песок карьерный" "Щебень гранитный" "Щебень гравийный" "Щебень шлаковый" "Песчано-гравийная смесь"
Тип ПГС Насыпная плотность (т/м3)
Песок речной 1.5
Песок карьерный 1.5
Щебень гранитный 1.4
Щебень гравийный 1.43
Щебень шлаковый 1.17
Песчано-гравийная смесь 1.6
Measure
string (Swg-measure)
Enum: "м3" "т"

Единица измерения

Count
number <double> > 0

Отгруженное количество

Price
number <double> > 0

Цена за ед. измерения (руб.)

Cost
number <double> > 0

Стоимость (тыс. руб.)

ShipmentDateTime
string <date-time>

Дата и время отгрузки

DumpTruck
string <UUID>

Транспортное средство, на которое осуществлялась отгрузка (соответствует DumpTruck→Id)

Washing
boolean

Была ли оказана услуга мытья ТС?

Manager
string <UUID>

Работник, зарегистрировавший отгрузку (Employee->Id)

{
  • "Id": "de42a00f-7f43-4d10-808d-bee47fdeef49",
  • "Title": "Песчано-гравийная смесь (ПГС)",
  • "SWG": "Песок речной",
  • "Measure": "м3",
  • "Count": 36,
  • "Price": 640,
  • "Cost": 22.3488,
  • "ShipmentDateTime": "2024-01-01T00:00:00",
  • "DumpTruck": "accfe76f-9a9e-4cb4-8876-d36daa22f924",
  • "Washing": true,
  • "Manager": "de42a00f-7f43-4d10-808d-bee47fdeef49"
}

Самосвал (DumpTruck)

Id
string <UUID>

Уникальный идентификатор самосвала

Model
string

Модель транспортного средства

Registration
string

Регистрационный номер ТС

Capacity
number <double> > 0

Грузоподъёмность

Volume
number <double> > 0

Объём кузова

{
  • "Id": "accfe76f-9a9e-4cb4-8876-d36daa22f924",
  • "Model": "KAMAZ-65951-СА",
  • "Registration": "Д903ЧН",
  • "Capacity": 32.5,
  • "Volume": 25
}

Работник (Employee)

Id
string <UUID>

Уникальный идентификатор работника

Name
string

ФИО работника

Position
string

Должность работника

RegistrationDateTime
string <date-time>

Дата и время регистрации в системе

Email
string

Электронная почта работника

Role
string (Роль пользователя)
Enum: "Employee" "Manager" "UserManager"

Роль, в зависимости от которой определяются возможности пользователя.

Роль Доступно
Employee Зарегистрированный работник
Manager Менеджер
UserManager Менеджер пользователей приложения
{
  • "Id": "de42a00f-7f43-4d10-808d-bee47fdeef49",
  • "Name": "Иванов Иван Иванович",
  • "Position": "Начальник смены",
  • "RegistrationDateTime": "2024-01-01T00:00:00",
  • "Email": "IvanovII@crafted.su",
  • "Role": "Employee"
}