Показания наработки

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

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

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

Назначение

Получение текущих показаний и регистрация новой наработки с проверкой единицы и генерацией обслуживания при достижении порога.

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

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

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

equipment_usage:read/write и «ТОиР — Оборудование → Просмотр, Изменение»; автоматическое создание ТО сохраняет тарифные ограничения.

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

POST принимает ровно reading (целое число JSON >= 0) и usage_unit_id (целое число JSON > 0), оба обязательны. If-Resource-Version не требуется. Если единица не настроена — 409 USAGE_UNIT_NOT_CONFIGURED; несовпадение — 422 USAGE_UNIT_MISMATCH, без записи. Ответ 200 содержит текущее состояние usage, changed и meta.affected_resources с созданными заявками. Не превышающее максимум показание успешно возвращает changed=false.

maintenance_interval и верхнеуровневый remaining_until_maintenance описывают интервал по умолчанию карточки. При наличии активных usage/hybrid-планов верхнеуровневый remaining_until_maintenance=null, а фактические пороги передаются в plans: { "id": 3, "next_due_usage": 1500, "remaining": 120 }. Отрицательный remaining означает превышение; отсутствие настроенного порога — null. Справочник единиц сам по себе не назначает единицу оборудованию.

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

• Показание reading, которое не превышает текущее, не меняет наработку. Ответ содержит changed=false и действующее показание.
• Единицы не конвертируются молча; замена/сброс счётчика не маскируется под обычное показание.
• Порог порождает заявку по действующим планам без дублей одного цикла.
• GET возвращает текущее состояние наработки. История всех показаний через этот ресурс недоступна.

Операции

GET /equipment/{id}/usage

Текущие показания, единица и порог обслуживания.

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

Параметры

Ответы

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

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

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

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

POST /equipment/{id}/usage

Регистрация показания.

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