Общие регламенты обслуживания

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

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

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

Назначение

Правило обслуживания группы оборудования по клиенту, объекту, договору, моделям, типам или явному набору единиц.

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

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

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

maintenance_regulations:read/write и «ТОиР — Обслуживание → Просмотр, Изменение», тариф, мастерская и право доступа ко всему выбранному составу.

Создание и новый выбор состава требуют «ТОиР — Оборудование → Просмотр»; выбор клиента, объекта или договора дополнительно требует «Клиенты и поставщики → Просмотр». Отдельные разрешения на чтение этих ресурсов для команд не требуются. Для lifecycle существующего регламента достаточно документированного разрешение на запись и «ТОиР — Обслуживание → Изменение», с проверкой текущих мастерских, действующего состава и затрагиваемых планов. Запись об операции сохраняет использованные разрешения и ссылки для повторной проверки текущего доступа.

Фильтры: scope_type, customer_id, customer_site_id, service_contract_id, status, trigger_type, updated_since.

Создание, изменение и команды

Для создания требуются title (1–255), scope_type, trigger_type и starts_on. Значения по умолчанию: type=preventive, priority=medium, status=active, generation_time="09:00", lead_time_days=0, ends_on=null, scenario_id=null, assigned_user_id=null, scenario_defaults={}, completion_window_value=null, completion_window_unit=day. status задаётся сервером и изменяется только pause/resume/end. Для выбора мастерской принимается workshop_id; если доступно несколько и связь не определяет одну, отсутствие — 422 WORKSHOP_REQUIRED.

Не относящиеся к выбранной области применения связи не принимаются. excluded_equipment_ids по умолчанию [], максимум 100; все массивы ID — множества, дубликаты дают 422.

calendar_pattern=interval по умолчанию. Для calendar допустимы weekdays с week_days (1=пн…7=вс) и month_days с month_days (1…31; 0=последний день), без повторов. Такие шаблоны используют fixed, lead_time_days=0 и interval_unit=week/month соответственно; несовместимые явно переданные значения — 422. Значения по умолчанию применяются только при создании, update сохраняет отсутствующие поля и заново проверяет итоговое правило. Смена trigger требует явно очистить несовместимые ранее заданные поля через null/[]; сервер не оставляет старую часть правила действующей.

pause/resume/end/sync принимают {} и If-Resource-Version регламента. Допустимы active→paused, paused→active, active/paused→ended; ended не возобновляется. Текущее состояние повторно установить можно с changed=false. Создание возвращает 201, остальные завершённые команды — 200 с карточкой и meta.affected_resources. Для парка более 100 единиц create/update/sync принимаются как 202: сохраняются правило, ревизия и сохранённая операция, затем синхронизируются планы с результатом по каждой единице. Новая генерация этой ревизии начинается после успешной синхронизации. Ошибки доступны в журнале; частичный пакет не помечается succeeded и не маскируется под атомарное применение. Входные массивы более 100 элементов в возвращают 422; большой парк выбирается разрешение подключения клиента/объекта/модели/типа/договора.

Граница 100 учитывает объединение прежнего и нового состава: замена 2 прежних единиц на 99 новых также требует пакетного режима. Для больших наборов pause/resume/end тоже возвращают 202: состояние самого регламента сохраняется при принятии, применимость планов согласуется по единицам с сохранением истории. Пока пакет выполняется, новое действие по этому регламенту получает 409 MAINTENANCE_SYNC_IN_PROGRESS; исходный ключ возвращает свою запись об операции.

У ответа 202 data.operation_id и data.state="processing" описывают принятие, data.regulation содержит карточку принятого правила; location указывает на журнал, Retry-After равен 2. Повтор POST сохраняет исходный 202 и тело даже после завершения worker. Финальный исход читается через GET журнала: state, http_status, error, resource_refs, response и items по каждой единице. Отзыв текущего доступа блокирует выдачу закрытых данных; ответ о принятии очищается по общему TTL и не освобождает ключ.

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

scenario_defaults использует общий типизированный объект по кодам полей сценария, как у индивидуальных планов. Значения не приводятся к строке автоматически: "0", false и null сохраняют смысл. JSON-объект с числовыми ключами не заменяет JSON-массив идентификаторов, дней или вариантов. Defaults передаются индивидуальным планам; существующие снимки начатых заявок не переписываются.

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

• Общий регламент хранит правило, а план единицы — независимый цикл и историю.
• Локальные regulation_overridden сохраняются при изменении общего правила.
• Пауза/исключение оборудования сохраняют существующие планы и заявки.
• Для equipment_date после выполнения или отмены требуется новая дата, а не бесконечное создание того же ТО.
• Большие наборы оформляются восстановимой операцией с ограниченным числом элементов и журналом.

Операции

GET /maintenance-regulations

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

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

Параметры

Ответы

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

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

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

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

POST /maintenance-regulations

Создание.

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

GET /maintenance-regulations/{id}

Карточка.

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

Параметры

Ответы

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

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

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

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

POST /maintenance-regulations/{id}/update

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

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

POST /maintenance-regulations/{id}/pause

Приостановка действия регламента.

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

POST /maintenance-regulations/{id}/resume

Возобновление действия регламента.

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

POST /maintenance-regulations/{id}/end

Завершение регламента.

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

POST /maintenance-regulations/{id}/sync

Согласование состава оборудования и индивидуальных планов.

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