API docs by Redocly

Инвентаризационный список техники (3.0.0)

Описание

Приложение, решающее задачу по управлению списком с данными.

Данные

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

Список элементов техники

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

Id,Equipment,Category,GuaranteeDate,IsUsed,Price,Location,ResponsiblePerson,User
1d0f861e-9d0c-4340-acad-69ade7b83085,"Монитор 19.5"" LG 20M47D",Монитор,2028-01-01,false,2800,склад,de42a00f-7f43-4d10-808d-bee47fdeef49,
4cc3098f-fa98-4312-b351-fce99fde825f,"Монитор 19.5"" Acer K202HQL",Монитор,2028-01-01,false,5700,склад,de42a00f-7f43-4d10-808d-bee47fdeef49,
bf7c82ce-334a-470b-89be-f7ae283ce564,"Системный блок Acer Intel Core i5-6500, RAM 16 ГБ, SSD 480 ГБ, Intel HD Graphics 530",ПК,2028-01-01,false,15300,склад,de42a00f-7f43-4d10-808d-bee47fdeef49,
f463afc0-3088-4ba4-92ae-5859faedc585,"Принтер Canon PIXMA G540 ",Принтер,2030-01-01,true,21550,"офис, кабинет № 26",de42a00f-7f43-4d10-808d-bee47fdeef49,de42a00f-7f43-4d10-808d-bee47fdeef49
d7494a0f-6929-4d71-9bbc-fb067356bfeb,IP-телефон Cisco CP-7940G,Телефон,2030-01-01,true,6100,"офис, кабинет № 26",de42a00f-7f43-4d10-808d-bee47fdeef49,de42a00f-7f43-4d10-808d-bee47fdeef49
fe385d95-f916-47c0-b042-557435b2e160,Проектор Epson EB-E20,Другое,2030-01-01,true,60600,"офис, кабинет № 15",de42a00f-7f43-4d10-808d-bee47fdeef49,de42a00f-7f43-4d10-808d-bee47fdeef49
f920444e-3741-497c-a6b2-b9fa1bc5b741,"Принтер Canon PIXMA G540 ",Принтер,2030-01-01,true,21550,"офис, кабинет № 15",de42a00f-7f43-4d10-808d-bee47fdeef49,de42a00f-7f43-4d10-808d-bee47fdeef49

Записи в журнале

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

Id,Equipment,ResponsiblePerson,Operation,Text,LogDateTime
29478648-3524-4d60-9176-22aad1c3bb4a,1d0f861e-9d0c-4340-acad-69ade7b83085,de42a00f-7f43-4d10-808d-bee47fdeef49,Приобретение,Приобретение,2024-01-01T00:00:00

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

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

Id,Name,RegistrationDateTime,Email,Position,Role
de42a00f-7f43-4d10-808d-bee47fdeef49,Иванов Иван Иванович,2024-01-01T00:00:00,IvanovII@crafted.su,Секретарь,Admin

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

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

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

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

Error: missing option --users-file

Error: file not found «abc.csv»

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

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

jwt

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

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

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

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

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

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

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

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

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

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

Responses

Инвентаризация

Методы, связанные с получением информации о технике

Получение списка техники

Список упорядочен по возрастанию типа техники лексикографически и id.

Authorizations:
jwt
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
[
  • {
    }
]

Добавление нового оборудования

Добавление нового оборудования:

  • Идентификатор оборудования генерируется автоматически.
  • IsUsed генерируется в зависимости от наличия поля User.
  • МОЛ устанавливается по пользователю, выполнившему запрос.

Добавление записи о новом оборудовании в журнал:

  • Идентификатор записи генерируется автоматически.
  • Идентификатор оборудования соответствует идентификатору нового оборудования.
  • Дата и время создания записи генерируются автоматически по текущей дате и времени.
  • МОЛ устанавливается по пользователю, выполнившему запрос.
Authorizations:
jwt
Request Body schema: application/json
required
Equipment
required
string

Наименование оборудования

Category
required
string
Enum: "Монитор" "ПК" "Телефон" "Принтер" "Другое"

Тип техники

GuaranteeDate
required
string <date>

Гарантийный срок

Price
required
number <double> >= 0

Балансная стоимость

Location
required
string

Место хранения

User
string or null <UUID>
Default: null

Пользователь оборудования (User→Id)
null соответствует IsUsed=false

Operation
required
string

Журналируемая операция. Поле не может быть пустым

Text
string
Default: ""

Комментарий к операции

Responses

Request samples

Content type
application/json
{
  • "Equipment": "Системный блок Acer",
  • "Category": "ПК",
  • "GuaranteeDate": "2028-01-01",
  • "Price": 15300,
  • "Location": "дома",
  • "User": "de42a00f-7f43-4d10-808d-bee47fdeef49",
  • "Operation": "Приобретение",
  • "Text": "Приобретение нового ПК в связи с поломкой предыдущего"
}

Response samples

Content type
application/json
{
  • "EquipmentId": "67bfcd12-6c8f-45fc-bc6b-265c23d7d881",
  • "LogId": "29478648-3524-4d60-9176-22aad1c3bb4a"
}

Получение информации о элементе техники

Authorizations:
jwt
path Parameters
equipment-id
required
string <UUID>
Example: 67bfcd12-6c8f-45fc-bc6b-265c23d7d881

Идентификатор техники

Responses

Response samples

Content type
application/json
{
  • "Id": "67bfcd12-6c8f-45fc-bc6b-265c23d7d881",
  • "Equipment": "Системный блок Acer",
  • "Category": "ПК",
  • "GuaranteeDate": "2028-01-01",
  • "IsUsed": true,
  • "Price": 15300,
  • "Location": "дома",
  • "ResponsiblePerson": "de42a00f-7f43-4d10-808d-bee47fdeef49",
  • "ResponsiblePersonName": "Иванов Иван Иванович",
  • "User": "de42a00f-7f43-4d10-808d-bee47fdeef49",
  • "UserName": "Иванов Иван Иванович",
  • "Log": [
    ]
}

Редактирование оборудования

Отсутствие необязательных полей (не required) подразумевает, что поля не изменяются.

Редактирование оборудования:

  • IsUsed генерируется в зависимости от наличия поля User.

Выполнение запроса пользователю с ролью User разрешено только для оборудования, которым он пользуется, и только для полей:

  • Location
  • Operation
  • Text

Выполнение запроса пользователю с ролью Admin разрешено только для оборудования под его ответственностью.

Добавление записи об изменении оборудования в журнал:

  • Происходит только если изменилось хотя бы одно поле, описывающее оборудование.
  • Идентификатор записи генерируется автоматически.
  • Дата и время создания записи генерируются автоматически по текущей дате и времени.
Authorizations:
jwt
path Parameters
equipment-id
required
string <UUID>
Example: 67bfcd12-6c8f-45fc-bc6b-265c23d7d881

Идентификатор техники

Request Body schema: application/json
required
Equipment
required
string

Наименование оборудования

Category
string
Enum: "Монитор" "ПК" "Телефон" "Принтер" "Другое"

Тип техники

GuaranteeDate
string <date>

Гарантийный срок

Price
number <double> >= 0

Балансная стоимость

Location
string

Место хранения

ResponsiblePerson
string <UUID>

Материально-ответственное лицо (User→Id)

Сохраняется в поле ResponsiblePerson обоих объектов: оборудования и записи в журнале.

User
string or null <UUID>

Пользователь оборудования (User→Id)
null соответствует IsUsed=false

Operation
required
string

Журналируемая операция. Поле не может быть пустым

Text
required
string

Комментарий к операции

Responses

Request samples

Content type
application/json
{
  • "Equipment": "Системный блок Acer",
  • "Category": "ПК",
  • "GuaranteeDate": "2028-01-01",
  • "Price": 15300,
  • "Location": "дома",
  • "ResponsiblePerson": "de42a00f-7f43-4d10-808d-bee47fdeef49",
  • "User": "de42a00f-7f43-4d10-808d-bee47fdeef49",
  • "Operation": "Приобретение",
  • "Text": "Приобретение нового ПК в связи с поломкой предыдущего"
}

Response samples

Content type
application/json
{
  • "LogId": "29478648-3524-4d60-9176-22aad1c3bb4a"
}

Списание оборудования

Элемент техники удаляется. Разрешено только для оборудования под ответственностью пользователя, выполнившего запрос.

Для удалённого оборудования добавляется запись в журнал:

  • Идентификатор записи генерируется автоматически.
  • Идентификатор оборудования соответствует идентификатору удалённого оборудования.
  • Материально-ответственное лицо соответствует МОЛ оборудования.
  • Поле Operation соответствует «Списание: [поле Equipment]» (например «Списание: Системный блок Acer»).
  • Дата и время создания записи генерируются автоматически по текущей дате и времени.
Authorizations:
jwt
path Parameters
equipment-id
required
string <UUID>
Example: 67bfcd12-6c8f-45fc-bc6b-265c23d7d881

Идентификатор техники

Responses

Response samples

Content type
application/json
{
  • "LogId": "29478648-3524-4d60-9176-22aad1c3bb4a"
}

Список свободной техники

Получение списка свободной (не использующейся) техники переданных типов.

Список упорядочен по возрастанию типа техники лексикографически и id.

Authorizations:
jwt
query Parameters
category
string
Enum: "Монитор" "ПК" "Телефон" "Принтер" "Другое"
Example: category=Монитор,Телефон

Тип техники.

Содержит ноль, один или несколько типов техники через запятую.

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

Тип техники должен точно соответствовать одному из указанных значений. Например, пк и телефон не являются корректными значениями.

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

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
time
required
string <date-time>
Example: time=2030-01-01T00:00:00.0

Дата и время в формате ISO

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
by-type
required
string
Enum: "category" "person"
Example: by-type=category

Тип статистики.

  • category – статистика по типу техники. Разрешено только пользователю с ролью Admin, учитывается только техника под его ответственностью.
  • person – статистика по материально ответственному лицу. Разрешено только пользователю с ролью Manager.

Статистика упорядочена по полю Category/Person лексикографически.

Responses

Response samples

Content type
application/json
Example
{
  • "StatisticsByCategory": [
    ]
}

Журнал

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

Authorizations:
jwt
path Parameters
log-id
required
string <UUID>
Example: 29478648-3524-4d60-9176-22aad1c3bb4a

Идентификатор записи в журнале

Responses

Response samples

Content type
application/json
{
  • "Id": "29478648-3524-4d60-9176-22aad1c3bb4a",
  • "Equipment": "67bfcd12-6c8f-45fc-bc6b-265c23d7d881",
  • "ResponsiblePerson": "de42a00f-7f43-4d10-808d-bee47fdeef49",
  • "Operation": "Приобретение",
  • "Text": "Приобретение нового ПК в связи с поломкой предыдущего",
  • "LogDateTime": "2024-01-01T00:00:00"
}

Редактирование записи в журнале

Разрешено только для записи под ответственностью пользователя, выполнившего запрос.

Authorizations:
jwt
path Parameters
log-id
required
string <UUID>
Example: 29478648-3524-4d60-9176-22aad1c3bb4a

Идентификатор записи в журнале

Request Body schema: application/x-www-form-urlencoded
required
Operation
required
string

Журналируемая операция. Поле не может быть пустым

Text
required
string

Комментарий к операции

Responses

Request samples

Content type
application/x-www-form-urlencoded
Operation=%D0%9F%D0%B5%D1%80%D0%B5%D0%B4%D0%B0%D1%87%D0%B0&Text=%D0%9F%D0%9A%20%D0%BF%D0%B5%D1%80%D0%B5%D0%B4%D0%B0%D0%BD%20%D0%9F%D0%B5%D1%82%D1%80%D0%BE%D0%B2%D1%83%20%D0%9F.%20%D0%9F.

Response samples

Content type
application/json
Example
{
  • "Operation": {
    },
  • "Text": {
    }
}

Работники

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

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

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

Authorizations:
jwt

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Добавление работника

Идентификатор генерируется автоматически. Дата и время регистрации соответствуют текущей дате и времени

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

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

Email
required
string

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

Position
required
string

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

Role
required
string (Роль пользователя)
Enum: "User" "Admin" "Manager"

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

Роль Доступно
User Работник
Admin Администратор
Manager Менеджер работников/пользователей приложения

Responses

Request samples

Content type
application/json
{
  • "Name": "Иванов Иван Иванович",
  • "Email": "IvanovII@crafted.su",
  • "Position": "Инженер",
  • "Role": "User"
}

Response samples

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

Элемент техники (Equipment)

Id
string <UUID>

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

Equipment
string

Наименование оборудования

Category
string
Enum: "Монитор" "ПК" "Телефон" "Принтер" "Другое"

Тип техники

GuaranteeDate
string <date>

Гарантийный срок

IsUsed
boolean

Используется или свободно

  • true – используется
  • false – свободно
Price
number <double> >= 0

Балансная стоимость

Location
string

Место хранения

ResponsiblePerson
string <UUID>

Материально-ответственное лицо (User→Id)

User
string or null <UUID>

Пользователь оборудования (User→Id)
null соответствует IsUsed=false

{
  • "Id": "67bfcd12-6c8f-45fc-bc6b-265c23d7d881",
  • "Equipment": "Системный блок Acer",
  • "Category": "ПК",
  • "GuaranteeDate": "2028-01-01",
  • "IsUsed": true,
  • "Price": 15300,
  • "Location": "дома",
  • "ResponsiblePerson": "de42a00f-7f43-4d10-808d-bee47fdeef49",
  • "User": "de42a00f-7f43-4d10-808d-bee47fdeef49"
}

Запись в журнале (Log)

Id
string <UUID>

Идентификатор записи в журнале.

Equipment
string <UUID>

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

ResponsiblePerson
string <UUID>

Материально-ответственное лицо (User→Id)

Operation
string

Журналируемая операция. Поле не может быть пустым

Text
string

Комментарий к операции

LogDateTime
string <date-time>

Дата и время создания записи

{
  • "Id": "29478648-3524-4d60-9176-22aad1c3bb4a",
  • "Equipment": "67bfcd12-6c8f-45fc-bc6b-265c23d7d881",
  • "ResponsiblePerson": "de42a00f-7f43-4d10-808d-bee47fdeef49",
  • "Operation": "Приобретение",
  • "Text": "Приобретение нового ПК в связи с поломкой предыдущего",
  • "LogDateTime": "2024-01-01T00:00:00"
}

Работник (User)

Id
string <UUID>

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

Name
string

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

RegistrationDateTime
string <date-time>

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

Email
string

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

Position
string

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

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

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

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