Отказы и простои

Все операции. Авторизация. Запросы и повторы.

Все пути в этом файле дополняют /api/v1 на домене организации.

Описание и ограничения

Назначение

Учёт остановок, ремонта, ожидания запчастей и восстановления с историей этапов и затратами.

Поля и назначение

Обязательность и null указаны в схемах каждой операции ниже.

Доступ и выборка

equipment_downtimes:read/write и права оборудования; стоимость и связанный акт требуют отдельных прав.

Фильтры: equipment_id, kind, state, started_from/to; незавершённые и восстановленные записи.

Чтение требует «ТОиР — Оборудование → Просмотр», запись — «ТОиР — Оборудование → Изменение»; действует проверка тарифа и модуля ТОИР. Текущие оборудование, клиент и объект проверяются заново. act_id возвращается как null без доступа к документу и его мастерской; запись требует «Акты приёма оборудования → Просмотр» и совпадения оборудования/клиента.

Стоимость — денежный объект amount/currency либо null. Чтение требует «Деньги → Просмотр», запись, включая очистку, — также «Деньги → Изменение». У связанного акта учитываются мастерские подключения и финансового права. Без акта стоимость доступна только при финансовом праве на всю организацию; иначе поле отсутствует. Сумма использует точность валюты организации и должна точно сохраняться в десятичном значении с двумя знаками после точки, без округления. Для JPY допустимо amount="100", для KWD — "100.000", но "100.001" отклоняется.

Список поддерживает sort=id/-id и пагинацию по курсору с размером страницы от 1 до 100 записей; started_from/to — включительные YYYY-MM-DD. История принимает только sort и page; её поля: id, equipment_downtime_id, state, occurred_at. Карточка не принимает параметров запроса, поддерживает ETag/304 после авторизации. GET не изменяет бизнес-данные.

Запросы и версии

Создание требует equipment_id, kind=unplanned/planned, непустой title и started_at. Допустимы cause, remedy, restoration_cost и три связи из таблицы. started_at и occurred_at — ISO 8601 с обязательным смещением либо Z, с точностью до секунды; сервер сохраняет тот же момент. Поля состояния, restored_at, reported_by и счётчики не принимаются из JSON.

Update — частичное изменение. Оборудование, вид, начало, исходный дефект и предыдущий отказ можно исправить только до первого перехода, пока существует единственное начальное событие stopped. Исправление начала обновляет это событие атомарно. После появления истории эти поля защищены ошибкой 409/DOWNTIME_HISTORY_PROTECTED. Название, причина, результат, стоимость и согласованная связь с актом остаются редактируемыми; отсутствие поля сохраняет значение.

Transition принимает state и необязательный occurred_at, по умолчанию текущий момент. Update и transition требуют If-Resource-Version из карточки: отсутствие — 428, несовпадение — 412. Версия — обычный секундный updated_at с ограничением совпавшей секунды из concurrency.md.

Создание возвращает 201, update/transition — 200 с карточкой, operation_id, affected_resources и warnings. Одинаковые значения не меняют версию и не создают событие. Повтор ключа возвращает исходный ответ, но перепроверяет исходные и текущие оборудование/клиента/объект, финансовые права и мастерские. Перенос владельца закрывает старую запись об операции ошибкой 404.

Правила и связи

• Сервер проверяет пересечение периодов одной единицы под блокировкой.
• Текущее состояние, ожидание и событие этапа изменяются атомарно.
• Восстановление имеет время позже остановки; события не идут в будущее и не задним числом до текущего этапа.
• Закрытый простой не открывается произвольным update; новый отказ связывается через previous_downtime_id.

Операции

GET /equipment-downtimes

Список с фильтрами и пагинацией.

Доступ. Разрешения подключения: equipment_downtimes:read. Права сотрудника: «ТОиР — Оборудование → Просмотр». Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.

Параметры

Ответы

Каждый ответ содержит новый X-Request-Id в заголовке. Общие транспортные отказы и правила повтора действуют также при отказе до контроллера; см. ошибки.

Пример запроса

Запускается из каталога комплекта после настройки переменных в быстром старте. Замените демонстрационные идентификаторы 101 и UUID идентификаторами доступных записей. $RESOURCE_VERSION берётся из GET владельца версии, описанного выше. Для нового действия сохраните новый ключ; для повтора используйте прежний.

curl --silent --show-error --globoff \
  "$API/equipment-downtimes" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json"

POST /equipment-downtimes

Создание.

Доступ. Разрешения подключения: equipment_downtimes:write. Права сотрудника: «ТОиР — Оборудование → Изменение». Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.

Параметры

Тело запроса

Content-Type: application/json. Тело обязательно.

Ответы

Каждый ответ содержит новый X-Request-Id в заголовке. Общие транспортные отказы и правила повтора действуют также при отказе до контроллера; см. ошибки.

У принятого POST Location и meta.operation_id указывают на журнал операции; ETag отсутствует. При повторе запроса сохраняются исходные data/meta, добавляется Idempotency-Replayed: true. Версии передавайте по назначению, указанному в описании ресурса.

Пример запроса

Запускается из каталога комплекта после настройки переменных в быстром старте. Замените демонстрационные идентификаторы 101 и UUID идентификаторами доступных записей. $RESOURCE_VERSION берётся из GET владельца версии, описанного выше. Для нового действия сохраните новый ключ; для повтора используйте прежний.

curl --silent --show-error --globoff --request POST \
  "$API/equipment-downtimes" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: example:v1-equipment-downtimes-create:001" \
  --header "Content-Type: application/json" \
  --data-binary '@examples/requests/v1.equipment-downtimes.create.json'

GET /equipment-downtimes/{id}

Карточка.

Доступ. Разрешения подключения: equipment_downtimes:read. Права сотрудника: «ТОиР — Оборудование → Просмотр». Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.

Параметры

Ответы

Каждый ответ содержит новый X-Request-Id в заголовке. Общие транспортные отказы и правила повтора действуют также при отказе до контроллера; см. ошибки.

Пример запроса

Запускается из каталога комплекта после настройки переменных в быстром старте. Замените демонстрационные идентификаторы 101 и UUID идентификаторами доступных записей. $RESOURCE_VERSION берётся из GET владельца версии, описанного выше. Для нового действия сохраните новый ключ; для повтора используйте прежний.

curl --silent --show-error --globoff \
  "$API/equipment-downtimes/101" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json"

GET /equipment-downtimes/{id}/events

История этапов простоя.

Доступ. Разрешения подключения: equipment_downtimes:read. Права сотрудника: «ТОиР — Оборудование → Просмотр». Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.

Параметры

Ответы

Каждый ответ содержит новый X-Request-Id в заголовке. Общие транспортные отказы и правила повтора действуют также при отказе до контроллера; см. ошибки.

Пример запроса

Запускается из каталога комплекта после настройки переменных в быстром старте. Замените демонстрационные идентификаторы 101 и UUID идентификаторами доступных записей. $RESOURCE_VERSION берётся из GET владельца версии, описанного выше. Для нового действия сохраните новый ключ; для повтора используйте прежний.

curl --silent --show-error --globoff \
  "$API/equipment-downtimes/101/events" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json"

POST /equipment-downtimes/{id}/update

Изменение разрешённых полей.

Доступ. Разрешения подключения: equipment_downtimes:write. Права сотрудника: «ТОиР — Оборудование → Изменение». Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.

Параметры

Тело запроса

Content-Type: application/json. Тело обязательно.

Ответы

Каждый ответ содержит новый X-Request-Id в заголовке. Общие транспортные отказы и правила повтора действуют также при отказе до контроллера; см. ошибки.

У принятого POST Location и meta.operation_id указывают на журнал операции; ETag отсутствует. При повторе запроса сохраняются исходные data/meta, добавляется Idempotency-Replayed: true. Версии передавайте по назначению, указанному в описании ресурса.

Пример запроса

Запускается из каталога комплекта после настройки переменных в быстром старте. Замените демонстрационные идентификаторы 101 и UUID идентификаторами доступных записей. $RESOURCE_VERSION берётся из GET владельца версии, описанного выше. Для нового действия сохраните новый ключ; для повтора используйте прежний.

curl --silent --show-error --globoff --request POST \
  "$API/equipment-downtimes/101/update" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: example:v1-equipment-downtimes-update:001" \
  --header "If-Resource-Version: $RESOURCE_VERSION" \
  --header "Content-Type: application/json" \
  --data-binary '@examples/requests/v1.equipment-downtimes.update.json'

POST /equipment-downtimes/{id}/transition

Переход stopped / repair / waiting_parts / restored.

Доступ. Разрешения подключения: equipment_downtimes:write. Права сотрудника: «ТОиР — Оборудование → Изменение». Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.

Параметры

Тело запроса

Content-Type: application/json. Тело обязательно.

Ответы

Каждый ответ содержит новый X-Request-Id в заголовке. Общие транспортные отказы и правила повтора действуют также при отказе до контроллера; см. ошибки.

У принятого POST Location и meta.operation_id указывают на журнал операции; ETag отсутствует. При повторе запроса сохраняются исходные data/meta, добавляется Idempotency-Replayed: true. Версии передавайте по назначению, указанному в описании ресурса.

Пример запроса

Запускается из каталога комплекта после настройки переменных в быстром старте. Замените демонстрационные идентификаторы 101 и UUID идентификаторами доступных записей. $RESOURCE_VERSION берётся из GET владельца версии, описанного выше. Для нового действия сохраните новый ключ; для повтора используйте прежний.

curl --silent --show-error --globoff --request POST \
  "$API/equipment-downtimes/101/transition" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: example:v1-equipment-downtimes-transition:001" \
  --header "If-Resource-Version: $RESOURCE_VERSION" \
  --header "Content-Type: application/json" \
  --data-binary '@examples/requests/v1.equipment-downtimes.transition.json'