Эндпоинты телеметрии и аналитики

Данный раздел содержит исчерпывающую Swagger-спецификацию программных интерфейсов микросервисов сбора телеметрии (HeatBalance.IoTService) и предиктивной аналитики (HeatBalance.AnalyticsService).

---

1. Спецификация HeatBalance.IoTService

Базовый путь: /api/v1/iot.

1.1. Приём пакета полевой телеметрии (POST /api/v1/iot/telemetry)

Высокопроизводительная точка входа для полевых контроллеров (ПЛК) и Edge-шлюзов. Для снижения накладных расходов не требует тяжеловесного протокола OAuth2, авторизуясь по статическому 256-битному токену датчика.

Заголовки запроса:

• Content-Type: application/json
• X-Device-Token: <КРИПТОГРАФИЧЕСКИЙ_ТОКЕН_ДАТЧИКА> (Обязательный)

Пример тела запроса:

{
  "dryMaterialMass": 12500.0,
  "initialMoisture": 14.8,
  "finalMoisture": 1.2,
  "airTemperature": 22.5,
  "recirculateTemp": 235.4
}

Ответ (202 Accepted):

{
  "logId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "Pending"
}

Коды ошибок:

• 401 Unauthorized: заголовок X-Device-Token отсутствует или не найден в реестре устройств;
• 400 Bad Request: передан невалидный JSON.

Пример cURL:

curl -X POST "https://heatbalance.ru/api/v1/iot/telemetry" \
  -H "X-Device-Token: 7f9a2b8c4d1e0f3a6b5c7d8e9f0a1b2c" \
  -H "Content-Type: application/json" \
  -d '{"dryMaterialMass": 12500.0, "initialMoisture": 14.8}'

---

1.2. Управление реестром датчиков (/api/v1/iot/devices)

Требуется авторизация Bearer <JWT-токен>.

• GET /api/v1/iot/devices: возвращает список всех датчиков пользователя с токенами доступа и датой последней активности lastSeenAt.
• POST /api/v1/iot/devices: регистрация нового измерительного канала.

Тело запроса CreateDeviceRequest:

{
  "name": "Термопара свода зоны сушки №2",
  "calculationType": 2,
  "datasetId": "8c7b6a5e-4d3c-2b1a-0f9e-8d7c6b5a4a3b",
  "sensorType": 0
}

Примечание: sensorType принимает значения от 0 до 14 согласно номенклатуре датчиков системы.

Ответ (201 Created):

{
  "id": "c1a2b3c4-d5e6-7f8a-9b0c-1d2e3f4a5b6c",
  "ownerId": "b2f65a12-88d3-4f91-9c3a-8b1e0f3a6b5c",
  "name": "Термопара свода зоны сушки №2",
  "calculationType": 2,
  "datasetId": "8c7b6a5e-4d3c-2b1a-0f9e-8d7c6b5a4a3b",
  "sensorType": 0,
  "accessToken": "a8f3b2c1e4d567890123456789abcdef",
  "createdAt": "2026-09-18T17:00:00Z",
  "lastSeenAt": null
}

• PUT /api/v1/iot/devices/{id}: обновление имени, шаблона датасета или типа датчика.
• DELETE /api/v1/iot/devices/{id}: удаление датчика и всех накопленных телеметрических логов.

---

1.3. Управление технологическими группами (/api/v1/iot/groups)

• GET /api/v1/iot/groups: получение перечня виртуальных агрегатов пользователя.
• POST /api/v1/iot/groups: объединение отдельных датчиков в виртуальную печь.

Тело запроса CreateDeviceGroupRequest:

{
  "name": "Камерная печь №1 — Технологический контур",
  "calculationType": 2,
  "datasetId": "8c7b6a5e-4d3c-2b1a-0f9e-8d7c6b5a4a3b",
  "deviceIds": [
    "c1a2b3c4-d5e6-7f8a-9b0c-1d2e3f4a5b6c",
    "d2b3c4d5-e6f7-8a9b-0c1d-2e3f4a5b6c7d"
  ]
}

---

1.4. Инициация расчёта агрегата (POST /api/v1/iot/groups/{id}/calculate)

Запускает алгоритм динамического слияния JSON Deep Merge:

1. Извлекает базовую геометрию печи из DatasetService;
2. Извлекает самые последние по времени показания всех привязанных к группе датчиков;
3. Формирует расчетный вектор и направляет его в термодинамический движок;
4. Публикует команду SaveRunCommand в шину сообщений.

Ответ (200 OK):

{
  "id": "7b6a5e4d-3c2b-1a0f-9e8d-7c6b5a4a3b2c",
  "groupId": "f3a2b1c0-d9e8-7f6a-5b4c-3d2e1a0b9c8d",
  "timestamp": "2026-09-18T17:15:00Z",
  "status": 1,
  "efficiency": 0.7124,
  "mergedPayloadJson": "{\"dryMaterialMass\": 10000, \"initialMoisture\": 14.8, ...}",
  "resultJson": "{\"efficiency\": 0.7124, \"totalInputKJPerHour\": 1520000.0, ...}",
  "errorMessage": null
}

---

2. Спецификация HeatBalance.AnalyticsService

Базовый путь: /api/v1/analytics. Все эндпоинты требуют авторизации Bearer <token> с ролью Admin (Policy = AuthPolicies.Admin).

Общие Query-параметры фильтрации:

• scope: область анализа:
  • all: все источники данных (по умолчанию);
  • conveyor, chamber, electric, drum: фильтрация по конкретному типу агрегата;
  • iot: выборка исключительно по данным промышленного IoT.
• calculationType: числовой идентификатор печи (1: Conveyor, 2: Chamber, 3: Electric, 4: Drum).
• days: глубина ретроспективного анализа в днях (7, 30, 90, 365).

---

2.1. Сводные технологические показатели (GET /api/v1/analytics/summary)

Возвращает интегральные показатели эффективности, тренд и топ ключевых рекомендаций.

Запрос:

GET /api/v1/analytics/summary?scope=all&days=30 HTTP/1.1
Host: heatbalance.ru
Authorization: Bearer <ADMIN_JWT_TOKEN>

Ответ (200 OK):

{
  "averageEfficiency": 68.45,
  "minEfficiency": 54.20,
  "maxEfficiency": 76.80,
  "trend": "down",
  "totalCalculations": 142,
  "anomalyCount": 3,
  "topRecommendations": [
    {
      "parameterName": "airFlowCoefficient",
      "parameterLabel": "Коэффициент расхода воздуха (α)",
      "currentValue": 1.35,
      "optimalValue": 1.15,
      "deltaPercent": 14.8,
      "action": "decrease",
      "impact": "high"
    }
  ]
}

---

2.2. Временной ряд тренда КПД (GET /api/v1/analytics/efficiency-trend)

Предоставляет массив точек мгновенных расчётов, значения сглаженной кривой SMA (окно windowSize, по умолчанию 5) и параметры линейной аппроксимации МНК.

Ответ (200 OK):

{
  "points": [
    {
      "timestamp": "2026-09-18T10:00:00Z",
      "efficiency": 72.5,
      "smoothedEfficiency": null,
      "label": "Камерная печь №1"
    },
    {
      "timestamp": "2026-09-18T14:00:00Z",
      "efficiency": 71.8,
      "smoothedEfficiency": 72.1,
      "label": "Камерная печь №1"
    }
  ],
  "trend": "down",
  "slope": -0.1425,
  "averageEfficiency": 71.95
}

---

2.3. Журнал технологических аномалий (GET /api/v1/analytics/anomalies)

Выполняет стандартизацию Z-Score по всем входным параметрам расчётов и возвращает записи, превышающие критические границы $|z| \ge 2.0$.

Ответ (200 OK):

[
  {
    "logId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "timestamp": "2026-09-18T16:20:00Z",
    "entityName": "Камерная печь №1 — цех огнеупоров",
    "fieldName": "Температура наружной стенки",
    "value": 84.2,
    "expectedMean": 64.89,
    "zScore": 2.44,
    "severity": "warning"
  },
  {
    "logId": "4ba96f75-6828-4673-c4fd-3d074f77bfb7",
    "timestamp": "2026-09-18T16:25:00Z",
    "entityName": "Электропечь сопротивления №3",
    "fieldName": "Сила тока",
    "value": 42.0,
    "expectedMean": 220.5,
    "zScore": -3.85,
    "severity": "critical"
  }
]

---

2.4. Прогноз эксплуатационной деградации (GET /api/v1/analytics/degradation)

Экстраполирует наклон кривой КПД методом наименьших квадратов и вычисляет ориентировочную дату достижения критического порога (threshold, по умолчанию 15.0%).

Ответ (200 OK):

{
  "currentSlope": -0.2429,
  "currentAvgEfficiency": 44.82,
  "estimatedThresholdDate": "2027-01-05T12:00:00Z",
  "thresholdEfficiency": 15.0,
  "riskLevel": "low"
}

---

2.5. Рекомендации по оптимизации уставок (GET /api/v1/analytics/recommendations)

Сопоставляет текущий технологический вектор с лучшим историческим эталоном агрегата (Benchmark Matching) и возвращает приоритизированный перечень регулирующих воздействий.

Ответ (200 OK):

[
  {
    "parameterName": "dryMaterialMass",
    "parameterLabel": "Масса сухого материала",
    "currentValue": 8200.0,
    "optimalValue": 10000.0,
    "deltaPercent": 22.0,
    "action": "increase",
    "impact": "high"
  },
  {
    "parameterName": "airFlowCoefficient",
    "parameterLabel": "Коэффициент расхода воздуха (α)",
    "currentValue": 1.35,
    "optimalValue": 1.15,
    "deltaPercent": 14.8,
    "action": "decrease",
    "impact": "medium"
  }
]