Индивидуальные планы оборудования

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

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

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

Назначение

Цикл обслуживания по календарю или наработке конкретной единицы с собственным следующим сроком и историей выполнения.

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

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

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

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

Фильтры: equipment_id, maintenance_regulation_id, status, trigger_type, next_due_from/to.

Запросы

Для создания требуются equipment_id, title, trigger_type и starts_on. Правила календаря/наработки, значения типа и приоритета по умолчанию, anchor_date, generation_time, lead_time_days и окна выполнения совпадают с регламентами. Единица наработки берётся из оборудования и должна быть настроена. Начальный status=active; source, курсоры, revision и связь регламента задаются сервером. План по дате оборудования создаётся синхронизацией регламента, не ручным trigger_type=equipment_date.

scenario_defaults — JSON-объект с кодами активных полей выбранного сценария. Форматы значений совпадают с дополнительными полями: десятичная строка, логическое значение, строка выбранного варианта, массив строк для множественного выбора, денежный объект {amount, currency} или null. Значения "0", false и null сохраняют свои типы. Списки дней и вариантов передаются массивами; объект с ключом "0" не считается массивом. Если прежние значения по умолчанию противоречат друг другу и сохранены одновременно по коду и идентификатору поля, возвращается 409; исправьте их явно. Новые значения не создают временные заявки и не меняют снимки начатых заявок.

Изменение принимает доступные для записи поля и If-Resource-Version плана. Для плана, полученного из регламента, устанавливается regulation_overridden=true. Приостановка, возобновление и завершение принимают {} и версию плана. Переходы: active → paused, paused → active, active/paused → ended. Команда generate также принимает {} и версию; она создаёт заявку только для текущего наступившего цикла. Произвольную дату, номер цикла или принудительный запуск передать нельзя. Если срок не наступил, возвращается 409 MAINTENANCE_NOT_DUE. Ответ generate: 201 с новой заявкой или 200 с существующей. Остальные команды возвращают карточку плана. Изменения отражаются в meta.affected_resources.

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

Команда generate не синхронизирует общий регламент автоматически. Устаревшая версия унаследованных настроек, приостановленный регламент или неприменимый план возвращают 409. Незавершённая или неуспешная пакетная синхронизация текущей версии регламента также блокирует создание заявки. План с regulation_overridden=true сохраняет собственные настройки и допускает создание заявки после успешного завершения пакета, даже если его regulation_revision отличается от общей. Неактивное оборудование блокирует создание новых заявок. Повтор принятого запроса с прежним Idempotency-Key возвращает сохранённый ответ после проверки доступа. Повторная установка текущего состояния и изменение без новых значений сохраняют версию и не создают событие.

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

• Изменение плана регламента помечает его настройки как заданные отдельно от общего правила.
• generate одного цикла не создаёт дубль даже с разными Idempotency-Key.
• Курсор, last_completed_usage и next_cycle_number не принимаются из запроса.

Операции

GET /maintenance-plans

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

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

Параметры

Ответы

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

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

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

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

POST /maintenance-plans

Создание.

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

GET /maintenance-plans/{id}

Карточка.

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

Параметры

Ответы

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

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

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

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

POST /maintenance-plans/{id}/update

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

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

POST /maintenance-plans/{id}/pause

Пауза плана.

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

POST /maintenance-plans/{id}/resume

Возобновление.

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

POST /maintenance-plans/{id}/end

Завершение.

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

POST /maintenance-plans/{id}/generate

Создание заявки текущего допустимого цикла.

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