Обзор API и аутентификация

1. Архитектура программных интерфейсов платформы

Все внешние клиентские запросы (веб-интерфейс React, полевые Edge-шлюзы, корпоративные MES/SCADA-системы) взаимодействуют с микросервисной платформой «UrFU HeatBalance» через единую точку входа — API Gateway (YARP) по протоколу HTTPS.

Базовые сетевые адреса:

• Промышленный контур (Production API): https://heatbalance.ru/api/ (портал документации доступен на https://heatbalance.online)
• Локальный контур разработчика (Local Dev): https://localhost:5000/api/ или http://localhost:5000/api/
• Версионирование API: все бизнес-эндпоинты платформы версионируются через префикс пути /api/v1/...

Соглашения о форматах данных:

1. Формат полезной нагрузки: application/json; charset=utf-8 (за исключением эндпоинта генерации токенов POST /connect/token, использующего application/x-www-form-urlencoded).
2. Формат дат и времени: стандарт ISO 8601 (UTC) с суффиксом Z, например: 2026-09-18T18:45:00.000Z.
3. Именование свойств JSON: нотация camelCase (например, dryMaterialMass, calculationType). Внутренний сериализатор .NET 10 настроен на PropertyNameCaseInsensitive = true, обеспечивая корректный парсинг свойств независимо от регистра символов.

---

2. Аутентификация и авторизация (OAuth 2.0 / OpenID Connect)

Платформа применяет стандартную модель централизованной аутентификации на базе OpenIddict и криптографических JSON Web Tokens (JWT).

2.1. Получение JWT токена доступа (Resource Owner Password Credentials)

Для получения токена оператор отправляет POST-запрос с учетными данными:

POST /connect/token HTTP/1.1
Host: heatbalance.ru
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=operator@urfu.ru&password=SecurePassword2026!&scope=openid profile email roles api offline_access

Параметры запроса:

• grant_type (обязательный): тип авторизации, значение password или refresh_token;
• username (обязательный): зарегистрированный email или имя пользователя;
• password (обязательный): пароль учетной записи;
• scope (обязательный): запрашиваемые области доступа (openid profile email roles api offline_access).

Успешный ответ (200 OK):

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ij...<truncated>...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "t_9a8b7c6d5e4f3a2b1c0d",
  "scope": "openid profile email roles api offline_access"
}

2.2. Структура полезной нагрузки токена (JWT Claims)

Декодированный токен содержит служебные идентификаторы для межсервисной изоляции пользователей:

{
  "iss": "https://heatbalance.ru/",
  "sub": "b2f65a12-88d3-4f91-9c3a-8b1e0f3a6b5c",
  "name": "Иванов Иван Иванович",
  "email": "operator@urfu.ru",
  "role": ["User", "Admin"],
  "scope": "api openid profile email roles",
  "nbf": 1789740000,
  "exp": 1789743600
}

2.3. Защита эндпоинтов (Bearer Token)

Для выполнения защищенных вычислений и операций с данными клиент обязан передавать полученный токен в HTTP-заголовке Authorization:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIs...

2.4. Аппаратная авторизация датчиков (X-Device-Token)

Для полевых контроллеров и шлюзов интернета вещей, не поддерживающих тяжеловесный протокол OAuth2, предусмотрен упрощенный криптографический заголовок:

X-Device-Token: 7f9a2b8c4d1e0f3a6b5c7d8e9f0a1b2c

Каждый токен генерируется криптографическим генератором случайных чисел (RandomNumberGenerator) и жестко привязывается к записи IoTDevice в базе данных.

---

3. Модель ролей и разграничение прав (RBAC)

В системе определены две роли пользователей и соответствующие политики безопасности (HeatBalance.ServiceDefaults.AuthPolicies):

Роль / Политика	Область действия	Разрешённые операции
User	Базовый технологический доступ	Создание, редактирование и расчёт собственных датасетов; просмотр собственной истории расчётов; регистрация своих IoT-устройств
Admin	Административный и аналитический доступ	Полный доступ ко всем модулям; вызов аналитических эндпоинтов /api/v1/analytics/*; просмотр и аудит оборудования всех пользователей цеха

При попытке несанкционированного доступа к аналитическим методам сервис возвращает статус 403 Forbidden.

---

4. Обработка ошибок и стандарт RFC 7807 (Problem Details)

В случае возникновения синтаксических ошибок, сбоев валидации входных диапазонов или внутренних исключений все микросервисы платформы возвращают стандартизированный ответ по спецификации RFC 7807 Problem Details:

{
  "type": "https://heatbalance.ru/errors/validation-failed",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "detail": "Входные параметры технологического расчета выходят за физически допустимые пределы.",
  "instance": "/api/v1/chamber/calculate",
  "errors": {
    "AirFlowCoefficient": [
      "Коэффициент расхода воздуха (alpha) должен находиться в диапазоне от 1.0 до 3.0."
    ],
    "WetMaterialMassFlowKgPerHour": [
      "Массовый расход сырья должен быть строго положительной величиной."
    ]
  }
}

Сводная таблица кодов состояния HTTP:

Код	Статус	Значение в контексте платформы HeatBalance
200	OK	Запрос успешно выполнен, возвращен результат теплового баланса или данные выборки
201	Created	Датасет или IoT-устройство успешно созданы в БД; заголовок Location содержит URL ресурса
202	Accepted	Пакет телеметрии принят и поставлен в очередь шины RabbitMQ на асинхронный расчёт
204	No Content	Ресурс (датасет, группа, устройство) успешно удален
400	Bad Request	Ошибка валидации физических параметров или некорректный синтаксис JSON
401	Unauthorized	Отсутствует заголовок Authorization: Bearer либо передан недействительный/истекший токен
403	Forbidden	Учетная запись не обладает ролью Admin (например, при запросе предиктивной аналитики)
404	Not Found	Запрашиваемый датасет, устройство или расчёт с указанным UUID не найден в базе данных
500	Internal Server Error	Необработанное исключение термодинамического движка или сбой базы данных
503	Service Unavailable	Брокер RabbitMQ или кэш Redis временно недоступны