Выполнение чек-листа ТО

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

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

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

Назначение

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

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

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

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

maintenance_checklists:read/write и «ТОиР — Обслуживание → Просмотр, Изменение»; изменение закрытой заявки или заявки закрытого родительского акта запрещено до возврата в работу. Право изменения паспорта оборудования, отдельные разрешения на чтение заявки и актов для команд не требуются. Проверяются текущая мастерская, неудалённое оборудование и клиент. Сохранённая запись об операции и событие учитывают исходную мастерскую и текущего родителя пункта; удалённый или перенесённый в другую заявку пункт не авторизуется по историческому снимку.

Запросы и результаты команд

• GET возвращает data.items и data.schedule_version, читает только сохранённые строки и не инициализирует сохранённый снимок. Query-параметры не поддерживаются.
• initialize: {}, If-Resource-Version заявки; 200, data.items — сохранённые результаты, data.schedule_version — версия заявки после команды. Существующие результаты не пересоздаются и сохраняют зафиксированные текст и обязательность. При отсутствии изменений версия и список affected_resources сохраняются.
• Создание ручного пункта: обязательный title (непустая строка до 255), необязательные description (строка до 10000 или null, default null) и is_required (boolean, default false). If-Resource-Version заявки; 201 с карточкой пункта. Сервер задаёт source=manual, is_completed=false и порядок. Передача source, completed_by, operation_id или is_completed при создании — 422.
• update: обязательная целая version >= 1 и хотя бы одно из полей is_completed (логическое значение) или note (строка до 10000 символов или null). Версия пункта передаётся в теле; If-Resource-Version не принимается. Успех — 200 с обновлённым пунктом. Отсутствующее поле сохраняется. Снятие отметки выполнения очищает completed_by и completed_at, сохраняя примечание, если note не передано. Оба поля изменяются вместе после одной проверки версии. title, description и is_required не принимаются. Пробелы по краям примечания удаляются, пустое значение сохраняется как null. Запрос с текущими значениями и актуальной версией не меняет запись и не создаёт событие; устаревшая версия возвращает 412 даже при совпадающем is_completed.
• Несовпадение версии пункта — 412; закрытая заявка — 409 MAINTENANCE_NOT_MUTABLE. Ошибка не сохраняет частичный результат. Версия заявки меняется вместе с пунктом и возвращается в meta.affected_resources.

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

• Команда устанавливает is_completed=true/false, а не toggle: повтор никогда не инвертирует результат.
• Ожидаемая версия проверяется под блокировкой; повтор с тем же ключом возвращает старую запись об операции до новой проверки перехода.
• Сервер назначает completed_by и completed_at; клиент не подделывает подпись другого мастера.
• Новые шаблонные изменения не переписывают сохранённый снимок выполнения.
• При инициализации шаблоны и работы читаются текущими чтениями. Пункты без operation_id различаются по собственному ID; несколько ручных пунктов оборудования и сценария не схлопываются в один.
• События maintenance_checklist.created и maintenance_checklist.updated содержат ссылку на пункт и его версию. Изменение пункта также обновляет версию заявки. Если сохранить результат целиком не удалось, изменения не применяются.

Операции

GET /maintenance-schedules/{schedule_id}/checklist-results

Сохранённые результаты.

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

Параметры

Ответы

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

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

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

curl --silent --show-error --globoff \
  "$API/maintenance-schedules/101/checklist-results" \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header "Accept: application/json"

POST /maintenance-schedules/{schedule_id}/checklist-results

Добавление ручного пункта.

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

POST /maintenance-schedules/{schedule_id}/checklist-results/initialize

Подготовка сохранённого чек-листа заявки.

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

POST /maintenance-schedules/{schedule_id}/checklist-results/{id}/update

Сохранение отметки выполнения и примечания с проверкой версии.

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