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

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

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

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

Назначение

Регистрация и устранение конкретных дефектов единицы, создание корректирующего ТО или гарантийного ремонта.

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

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

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

equipment_defects:read требует «ТОиР — Оборудование → Просмотр» и «ТОиР — Обслуживание → Просмотр»; запись — equipment_defects:write, «ТОиР — Оборудование → Просмотр» и «ТОиР — Обслуживание → Изменение». Право изменения паспорта оборудования для записи дефекта не требуется. Проверяется доступ к текущему оборудованию и существующему клиенту; недоступный родитель даёт 404.

Создание ТО дополнительно требует maintenance_schedules:write, гарантийного акта — acts:write, «Акты приёма оборудования → Просмотр», «Акты приёма оборудования → Изменение» и доступ к клиенту по штатным правилам создания акта. Мастерская должна входить в разрешённые подключения и сотруднику. Владелец сохраняет полный доступ, ограничения подключения действуют и для него.

Фильтры: filter[equipment_id], filter[customer_id], filter[status], filter[severity], filter[found_from], filter[found_to]. Границы календарного периода включаются. Клиент фильтра определяется по текущему оборудованию, а не по историческому внутреннему полю дефекта. Пагинация идёт курсором по id; неизвестные параметры отклоняются. Карточка поддерживает ETag/304 после авторизации.

Тела команд

Для создания требуются equipment_id и непустой title до 255 символов. description — до 10000 символов или null, severity — low/medium/high/critical (по умолчанию medium), found_date — DATE Y-m-d или null (при отсутствии — текущий календарный день организации). reported_by берётся из владельца токена, customer_id выводится из оборудования; оба поля не принимаются от клиента.

Изменение принимает только переданные RW-поля. Update, resolve и обе конвертации требуют If-Resource-Version исходного дефекта. Версия — секундный updated_at; изменение в одной секунде может не изменить её. Запрос без изменений сохраняет версию и не публикует событие. Resolve принимает {}, устанавливает текущий день организации и сохраняет первоначальную дату при повторе. Устранение до даты обнаружения отклоняется с 409; изменение found_date на день после уже зафиксированного устранения — 422.

create-maintenance принимает { "workshop_id": 1, "planned_date": "2026-12-02" }. workshop_id обязателен, дата необязательна и по умолчанию равна дню организации. Создаётся корректирующая заявка с важностью и описанием дефекта через штатный сервис, включая снимок сценария и чек-лист. Заголовок с префиксом ограничен 255 символами.

create-warranty-act принимает { "workshop_id": 1, "status_id": 2, "stock_id": 3 }. Обязательна мастерская; статус и склад необязательны только при наличии допустимых штатных значения по умолчанию: создания акта. Проверяется открытый статус ремонта и активный склад этой мастерской. Создаётся ремонтный акт для текущего клиента оборудования, с его моделью/серийным номером и описанием рекламации. Оборудование связывается с актом; устанавливается гарантийный флаг. Предыдущий ремонт выбирается штатным поиском и расчётом срока гарантии только среди доступных подключению актов того же клиента, текущими чтениями строк работ/товаров и справочников. Совпадение серийный номера с чужим клиентом или недоступной мастерской не даёт связи. Обязательные дополнительные поля акта проверяются штатно; конвертация их не обходит.

Обе конвертации возвращают карточку дефекта со связанным ID, 201 при создании документа и 200, если документ уже существовал. Повтор с тем же ключом возвращает исходный статус и тело. Новый ключ не создаёт второй документ; версия и affected_resources при таком запрос без изменений сохраняются. Для нового документа устранённого дефекта возвращается 409 DEFECT_ALREADY_RESOLVED; существующая связь остаётся доступна по обычным правилам. Другая запрошенная мастерская при существующей доступной связи даёт 409 DEFECT_DOCUMENT_CONFLICT.

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

• Справочник Defect и конкретный EquipmentDefect — разные ресурсы.
• Конвертация блокирует текущее оборудование и дефект в общей с панелью транзакции. Создание документа, связи, записи об операции и события атомарны. Сбой откатывает весь результат и не расходует ключ.
• Выбор мастерской и открытого статуса гарантийного акта проверяется в контексте API; нельзя брать первый попавшийся статус или мастерскую.
• Клиент дефекта выводится из оборудования, а не принимается для переноса дефекта.
• Перенос на другую единицу допустим только без созданных документов и без устранения; иначе 409 DEFECT_HISTORY_PROTECTED. Повтор запроса проверяет исходное и текущее оборудование, исходную мастерскую и текущий связанный документ; отзыв доступа не раскрывает сохранённое тело.
• События: equipment_defect.created, equipment_defect.updated, equipment_defect.resolved; у конвертации также есть событие создания соответствующего документа. В JSON не попадают внутренние имена полей и классов моделей.

Операции

GET /equipment-defects

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

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

Параметры

Ответы

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

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

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

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

POST /equipment-defects

Создание.

Доступ. Разрешения подключения: equipment_defects: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-defects" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: example:v1-equipment-defects-create:001" \
  --header "Content-Type: application/json" \
  --data-binary '@examples/requests/v1.equipment-defects.create.json'

GET /equipment-defects/{id}

Карточка.

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

Параметры

Ответы

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

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

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

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

POST /equipment-defects/{id}/update

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

Доступ. Разрешения подключения: equipment_defects: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-defects/101/update" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: example:v1-equipment-defects-update:001" \
  --header "If-Resource-Version: $RESOURCE_VERSION" \
  --header "Content-Type: application/json" \
  --data-binary '@examples/requests/v1.equipment-defects.update.json'

POST /equipment-defects/{id}/resolve

Фиксация устранения.

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

Параметры

Тело запроса

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

Тело — пустой 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-defects/101/resolve" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: example:v1-equipment-defects-resolve:001" \
  --header "If-Resource-Version: $RESOURCE_VERSION" \
  --header "Content-Type: application/json" \
  --data-binary '@examples/requests/v1.equipment-defects.resolve.json'

POST /equipment-defects/{id}/create-maintenance

Создание корректирующей заявки ТО.

Доступ. Разрешения подключения: equipment_defects: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-defects/101/create-maintenance" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: example:v1-equipment-defects-create-maintenance:001" \
  --header "If-Resource-Version: $RESOURCE_VERSION" \
  --header "Content-Type: application/json" \
  --data-binary '@examples/requests/v1.equipment-defects.create-maintenance.json'

POST /equipment-defects/{id}/create-warranty-act

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

Доступ. Разрешения подключения: equipment_defects: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-defects/101/create-warranty-act" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: example:v1-equipment-defects-create-warranty-act:001" \
  --header "If-Resource-Version: $RESOURCE_VERSION" \
  --header "Content-Type: application/json" \
  --data-binary '@examples/requests/v1.equipment-defects.create-warranty-act.json'