API docs by Redocly

Управление прачечной самообслуживания (3.0.0)

Описание

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

Данные

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

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

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

Id,Title,Type,StartDateTime,Condition,Capacity,Price,Duration,Specialist,Launderette
cf52ee99-f7d7-46d6-8e88-8137b99346e8,Стиральная машина Maytag 3RMTW 4905 TW,Стиральная машина,2024-01-02T00:00:00,true,8,300,45,de42a00f-7f43-4d10-808d-bee47fdeef49,24f43805-83e9-4687-bb52-c643bc93ec3b
a82eaf91-c83e-4819-991f-9175719a8ff1,Стиральная машина Maytag 3RMTW 4905 TW,Стиральная машина,2024-01-03T00:00:00,true,8,300,45,de42a00f-7f43-4d10-808d-bee47fdeef49,24f43805-83e9-4687-bb52-c643bc93ec3b
7c580384-403c-4664-9f94-66b40f75a724,Стиральная машина Maytag 3RMTW 4905 TW,Стиральная машина,2024-01-04T00:00:00,true,8,300,45,de42a00f-7f43-4d10-808d-bee47fdeef49,24f43805-83e9-4687-bb52-c643bc93ec3b
6c243167-63fc-47b8-ab8b-4db17c2f1d81,Стиральная машина Haier HCW12C,Стиральная машина,2024-01-05T00:00:00,true,12,350,55,de42a00f-7f43-4d10-808d-bee47fdeef49,24f43805-83e9-4687-bb52-c643bc93ec3b
657c2450-b03e-46f2-8d16-75fd14f47c6a,Стиральная машина Haier HCW12C,Стиральная машина,2024-01-06T00:00:00,false,12,350,55,de42a00f-7f43-4d10-808d-bee47fdeef49,24f43805-83e9-4687-bb52-c643bc93ec3b
6c2cea57-d99b-4356-98e1-c04899fe057b,Сушильная машина Haier HCD12C,Сушильная машина,2024-01-07T00:00:00,true,12,100,30,de42a00f-7f43-4d10-808d-bee47fdeef49,
32d9d122-26cf-47f0-b047-862ad4b68d3b,Сушильная машина Haier HCD12C,Сушильная машина,2024-01-08T00:00:00,true,12,100,30,de42a00f-7f43-4d10-808d-bee47fdeef49,

Список прачечных

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

Id,Address,PhoneNumber,WorkingHours
24f43805-83e9-4687-bb52-c643bc93ec3b,"город N, улица M, 13","+7 (999) 999-99-99","с 9.00 до 21.00. Без выходных"

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

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

Id,Name,RegistrationDateTime,Email,Role,Launderette
de42a00f-7f43-4d10-808d-bee47fdeef49,Иванов Иван Иванович,2024-01-01T00:00:00,IvanovII@crafted.su,User,24f43805-83e9-4687-bb52-c643bc93ec3b

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

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

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

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

Error: missing option --specialists-file

Error: file not found «abc.csv»

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

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

jwt

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

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

Для указанного пользователя определяется роль Specialist→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
[
  • {
    }
]

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

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

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

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

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

Type
required
string
Enum: "Стиральная машина" "Сушильная машина"

Тип оборудования

StartDateTime
string <date-time>
Default: "Текущие сутки и время «00:00:00»"

Начало эксплуатации

Condition
boolean
Default: true

Исправность оборудования

Capacity
required
number <double> > 0

Максимальная вместимость (кг)

Price
required
integer >= 0

Стоимость использования (руб)

Duration
required
integer > 0

Длительность цикла (мин)

Responses

Request samples

Content type
application/json
{
  • "Title": "Стиральная машина Maytag 3RMTW 4905 TW",
  • "Type": "Стиральная машина",
  • "StartDateTime": "2024-01-01T00:00:00",
  • "Condition": true,
  • "Capacity": 8,
  • "Price": 300,
  • "Duration": 60
}

Response samples

Content type
application/json
{
  • "Id": "cf52ee99-f7d7-46d6-8e88-8137b99346e8"
}

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

Выполнение запроса пользователям с ролями User и LaundryManager разрешено только для оборудования, размещённого в той же прачечной или не размещённого ни в какой в прачечной.

Authorizations:
jwt
path Parameters
machine-id
required
string <UUID>
Example: cf52ee99-f7d7-46d6-8e88-8137b99346e8

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

Responses

Response samples

Content type
application/json
{
  • "Id": "cf52ee99-f7d7-46d6-8e88-8137b99346e8",
  • "Title": "Стиральная машина Maytag 3RMTW 4905 TW",
  • "Type": "Стиральная машина",
  • "StartDateTime": "2024-01-01T00:00:00",
  • "Condition": true,
  • "Capacity": 8,
  • "Price": 300,
  • "Duration": 60,
  • "SpecialistEmail": "IvanovII@crafted.su",
  • "LaunderetteAddress": "город N, улица M, 13"
}

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

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

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

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

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

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

Type
string
Enum: "Стиральная машина" "Сушильная машина"

Тип оборудования

StartDateTime
string <date-time>

Начало эксплуатации

Condition
boolean

Исправность оборудования

Capacity
number <double> > 0

Максимальная вместимость (кг)

Price
integer >= 0

Стоимость использования (руб)

Duration
integer > 0

Длительность цикла (мин)

Specialist
string <UUID>

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

Разрешено только:

  • пользователю с ролью LaundryManager на работников той же прачечной,
  • пользователю с ролью Manager
Launderette
string or null <UUID>

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

Разрешено только:

  • пользователю с ролью LaundryManager из состояния null на прачечную, в которой работает пользователь,
  • пользователю с ролью Manager.

Responses

Request samples

Content type
application/json
{
  • "Title": "Стиральная машина Maytag 3RMTW 4905 TW",
  • "Type": "Стиральная машина",
  • "StartDateTime": "2024-01-01T00:00:00",
  • "Condition": true,
  • "Capacity": 8,
  • "Price": 300,
  • "Duration": 60,
  • "Specialist": "de42a00f-7f43-4d10-808d-bee47fdeef49",
  • "Launderette": "24f43805-83e9-4687-bb52-c643bc93ec3b"
}

Response samples

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

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

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

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

Authorizations:
jwt

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Статистика по сроку эксплуатации

Срок эксплуатации оборудования – разница между переданными моментом времени и началом эксплуатации.

Для корректной работы рекомендуется сравнивать даты с помощью методов minusMonths/plusMonths, minusYears/plusYears

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

Authorizations:
jwt
query Parameters
now
required
string <date-time>
Example: now=2026-01-01T00:00:00

Момент времени, для которого рассчитывается статистика

Responses

Response samples

Content type
application/json
{
  • "Пора менять": 2,
  • "Изношено": 1,
  • "Работает": 5,
  • "Новое": 3
}

Прачечные

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

Получение информации о прачечной

Authorizations:
jwt
path Parameters
launderette-id
required
string <UUID>
Example: 24f43805-83e9-4687-bb52-c643bc93ec3b

Идентификатор прачечной

Responses

Response samples

Content type
application/json
{
  • "Id": "24f43805-83e9-4687-bb52-c643bc93ec3b",
  • "Address": "город N, улица M, 13",
  • "PhoneNumber": "+7 (999) 999-99-99",
  • "WorkingHours": "с 9.00 до 21.00. Без выходных",
  • "Machines": [
    ]
}

Удаление прачечной

Для всего оборудования удаляемой прачечной значение Launderette устанавливается null.

Для всех работников, привязанных к прачечной, значение Launderette устанавливается null.

Разрешено только руководителю удаляемой прачечной.

Authorizations:
jwt
path Parameters
launderette-id
required
string <UUID>
Example: 24f43805-83e9-4687-bb52-c643bc93ec3b

Идентификатор прачечной

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Добавление прачечной

Приложение добавляет два объекта:

  1. Новую прачечную.

  2. Нового работника.
    Идентификатор работника и время регистрации генерируются автоматически.
    Роль соответствует LaundryManager, прачечная соответствует добавленной.

Authorizations:
jwt
Request Body schema: application/x-www-form-urlencoded
required
Address
required
string

Адрес прачечной. Не может быть пустым

PhoneNumber
required
string

Телефон. Не может быть пустым

WorkingHours
required
string

Режим работы. Не может быть пустым

Manager
required
string

ФИО работника. Не может быть пустым

ManagerEmail
required
string

Уникальная электронная почта работника. Не может быть пустой

Responses

Request samples

Content type
application/x-www-form-urlencoded
Address=%D0%B3%D0%BE%D1%80%D0%BE%D0%B4%20N%2C%20%D1%83%D0%BB%D0%B8%D1%86%D0%B0%20M%2C%2013&PhoneNumber=%2B7%20%28999%29%20999-99-99&WorkingHours=%D1%81%209.00%20%D0%B4%D0%BE%2021.00.%20%D0%91%D0%B5%D0%B7%20%D0%B2%D1%8B%D1%85%D0%BE%D0%B4%D0%BD%D1%8B%D1%85&Manager=%D0%9F%D0%B5%D1%82%D1%80%D0%BE%D0%B2%20%D0%9F%D1%91%D1%82%D1%80%20%D0%9F%D0%B5%D1%82%D1%80%D0%BE%D0%B2%D0%B8%D1%87&ManagerEmail=PetrovPP%40crafted.su

Response samples

Content type
application/json
{
  • "LaunderetteId": "24f43805-83e9-4687-bb52-c643bc93ec3b",
  • "SpecialistId": "de42a00f-7f43-4d10-808d-bee47fdeef49"
}

Подбор оборудования прачечной по весу и бюджету

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

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

path Parameters
launderette-id
required
string <UUID>
Example: 24f43805-83e9-4687-bb52-c643bc93ec3b

Идентификатор прачечной

query Parameters
weight
required
number <double> > 0
Example: weight=5.23

Вес (кг)

budget
required
integer > 0
Example: budget=300

Бюджет (руб)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Работники

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

Список работников

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

Ответ на запрос пользователя с ролью LaundryManager содержит только работников той же прачечной.

Authorizations:
jwt

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Сменить ответственного за оборудование

Для всего оборудования под ответственностью работника specialist-id-from сменить ответственного на работника specialist-id-to

Запрос пользователя с ролью LaundryManager разрешён только при условии, что specialist-id-from и specialist-id-to работают в той же прачечной.

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

Идентификатор работника, которого необходимо сменить

specialist-id-to
required
string <UUID>
Example: de42a00f-7f43-4d10-808d-bee47fdeef49

Идентификатор работника, на который необходимо сменить

Responses

Response samples

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

Оборудование (Machine)

Id
string <UUID>

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

Title
string

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

Type
string (Machine-type)
Enum: "Стиральная машина" "Сушильная машина"

Тип оборудования

StartDateTime
string <date-time>

Начало эксплуатации

Condition
boolean

Исправность оборудования

Capacity
number <double> > 0

Максимальная вместимость (кг)

Price
integer >= 0

Стоимость использования (руб)

Duration
integer > 0

Длительность цикла (мин)

Specialist
string <UUID>

Работник, ответственный за оборудование (Specialist→Id)

Launderette
string or null <UUID>

Прачечная, в которой установлено оборудование (Launderette→Id)

{
  • "Id": "cf52ee99-f7d7-46d6-8e88-8137b99346e8",
  • "Title": "Стиральная машина Maytag 3RMTW 4905 TW",
  • "Type": "Стиральная машина",
  • "StartDateTime": "2024-01-01T00:00:00",
  • "Condition": true,
  • "Capacity": 8,
  • "Price": 300,
  • "Duration": 60,
  • "Specialist": "de42a00f-7f43-4d10-808d-bee47fdeef49",
  • "Launderette": "24f43805-83e9-4687-bb52-c643bc93ec3b"
}

Прачечная (Launderette)

Id
string <UUID>

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

Address
string

Адрес прачечной

PhoneNumber
string

Телефон

WorkingHours
string

Режим работы

{
  • "Id": "24f43805-83e9-4687-bb52-c643bc93ec3b",
  • "Address": "город N, улица M, 13",
  • "PhoneNumber": "+7 (999) 999-99-99",
  • "WorkingHours": "с 9.00 до 21.00. Без выходных"
}

Работник (Specialist)

Id
string <UUID>

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

Name
string

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

RegistrationDateTime
string <date-time>

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

Email
string

Уникальная электронная почта работника

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

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

Роль Доступно
User Работник прачечной
LaundryManager Менеджер прачечной
Manager Менеджер пользователей приложения
Launderette
string or null <UUID>

Прачечная, в которой работает пользователь (Launderette→Id)

null означает, что пользователь не привязан к конкретной прачечной.

Если пользователи с ролями User и LaundryManager привязаны к прачечной, оборудование под их ответственностью расположено в той же прачечной.

Пользователь с ролью Manager никогда не привязан к прачечной.

{
  • "Id": "de42a00f-7f43-4d10-808d-bee47fdeef49",
  • "Name": "Иванов Иван Иванович",
  • "RegistrationDateTime": "2024-01-01T00:00:00",
  • "Email": "IvanovII@crafted.su",
  • "Role": "User",
  • "Launderette": "24f43805-83e9-4687-bb52-c643bc93ec3b"
}