Спецификация микросервисов

В данном разделе приведена подробная техническая спецификация всех 10 автономных микросервисов, входящих в состав программного комплекса «UrFU HeatBalance». Все сервисы разработаны на базе платформы .NET 10 (net10.0) и языка программирования C# 13/14 с использованием общих инфраструктурных библиотек HeatBalance.Contracts и HeatBalance.ServiceDefaults.

---

1. HeatBalance.Gateway (Шлюз API)

1.1. Назначение и функции

Шлюз API является единой входной точкой (Reverse Proxy) для всех клиентских обращений к программному комплексу. Построен на базе библиотеки Microsoft YARP (Yet Another Reverse Proxy).

1.2. Выполняемые задачи:

• Маршрутизация внешних HTTP-запросов к соответствующим внутренним контейнерам Docker-сети.
• Трансформация URL-путей (Path Transformation): трансляция внешних путей вида /api/chamber/* во внутренние /api/v1/chamber/*.
• Балансировка нагрузки и проверка состояния доступности целевых кластеров (Active/Passive Healthchecks).
• Централизованное управление политиками междоменного взаимодействия (CORS).

1.3. Таблица ключевых маршрутов YARP:

Маршрут (Route ID)	Входной шаблон пути	Целевой кластер (Cluster ID)	Внутренний адрес кластера
auth	/connect/{**catch-all}, /api/auth/{**catch-all}	auth-cluster	http://auth:8080
datasets	/api/v1/datasets/{**catch-all}	dataset-cluster	http://dataset-service:8080
runs	/api/v1/runs/{**catch-all}	run-cluster	http://run-service:8080
reports	/api/v1/reports/{**catch-all}	report-cluster	http://report-service:8080
chamber	/api/v1/chamber/{**catch-all}	chamber-cluster	http://chamber-kiln-service:8080
conveyor	/api/v1/conveyor/{**catch-all}	conveyor-cluster	http://conveyor-kiln-service:8080
electric	/api/v1/electric/{**catch-all}	electric-cluster	http://electric-kiln-service:8080
drum	/api/v1/drum/{**catch-all}	drum-cluster	http://drum-dryer-service:8080
iot	/api/iot/{**catch-all}, /api/v1/iot/{**catch-all}	iot-cluster	http://iot:8080
analytics	/api/analytics/{**catch-all}, /api/v1/analytics/{**catch-all}	analytics-cluster	http://analytics:8080

---

2. HeatBalance.Auth (Сервис аутентификации и авторизации)

2.1. Назначение и стек технологий

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

• Технологический стек: .NET 10, OpenIddict 5.x, ASP.NET Core Identity, Entity Framework Core, PostgreSQL (база данных heat_balance_auth).
• Внутренний порт: 8080 (внешний порт для прямого доступа 5001).

2.2. Архитектура безопасности:

• Поддерживаемые протоколы: OAuth 2.0 (Resource Owner Password Credentials Grant, Refresh Token Grant) и OpenID Connect.
• Формат токенов: JSON Web Token (JWT), подписанный асимметричным ключом RSA (длина ключа 2048 бит).
• Клеймы токена (Claims): sub (уникальный идентификатор пользователя), name, email, role (User, Admin).
• Ролевые политики (Authorization Policies):
  • RequireUserRole — доступ к штатным расчётным модулям и персональным датасетам.
  • RequireAdminRole — доступ к общесистемной предиктивной аналитике, сквозному аудиту телеметрии и эндпоинтам мониторинга /health.

---

3. HeatBalance.DatasetService (Сервис управления датасетами)

3.1. Назначение и архитектура

Сервис реализует функции создания, хранения, версионирования и загрузки именованных наборов исходных данных (датасетов) для проведения расчётов.

• Технологический стек: .NET 10, EF Core, PostgreSQL (база данных heat_balance_datasets), StackExchange.Redis, MassTransit.
• Внутренний порт: 8080 (внешний порт 5100).

3.2. Ключевые механизмы:

• Изоляция данных (Per-User Data Isolation): при каждом запросе извлекается клейм sub. Запросы возвращают только те датасеты, где OwnerId совпадает с текущим пользователем.
• Двухуровневое кэширование (Redis Cache-Aside):
  • Запрос датасета по ID сначала проверяет наличие ключа dataset:{id} в распределённой памяти Redis 7.0 (время жизни ключа TTL = 24 часа).
  • При создании, модификации или удалении датасета кэш немедленно инвалидируется.
• Событийная интеграция: при удалении датасета публикуется сообщение DatasetDeletedEvent в брокер RabbitMQ для оповещения зависимых сервисов.

---

4. HeatBalance.RunService (Сервис журнала истории расчётов)

4.1. Назначение и структура

Хранилище результатов всех проведённых вычислений (ручных через интерфейс и автоматических по телеметрии).

• Технологический стек: .NET 10, EF Core, MassTransit Consumer.
• Внутренний порт: 8080 (внешний порт 5200).

4.2. Модель данных CalculationRunEntity:

• Id (Guid) — уникальный идентификатор записи.
• CalculationType — тип агрегата (Chamber, Conveyor, Electric, Drum).
• Timestamp — точное время фиксации расчёта (UTC).
• Efficiency — вычисленный итоговый КПД установки ($\eta$, %).
• InputPayloadJson — полный сериализованный вектор исходных параметров.
• ResultPayloadJson — полная структура результатов (статьи прихода/расхода тепла, удельный расход топлива).
• IsIoT (boolean) — признак автоматического запуска по телеметрии.

4.3. Асинхронная обработка:

Сервис содержит консьюмер SaveRunConsumer, который подписан на очередь SaveRunCommand из RabbitMQ. Это обеспечивает гарантированное сохранение результатов без блокировки вызывающих сервисов.

---

5. HeatBalance.ReportService (Сервис формирования отчётности)

5.1. Назначение

Генерация официальных технических отчётов по результатам тепловых расчётов в формате PDF.

• Внутренний порт: 8080 (внешний порт 5300).
• Функционал: принимает JSON-структуру расчёта, валидирует данные и формирует документ стандарта A4, содержащий сводные таблицы балансовых статей, диаграмму тепловых потерь и заключение о режиме работы.

---

6. Вычислительные сервисы (Расчётные движки)

Все расчётные сервисы являются stateless-модулями, использующими общую математическую библиотеку HeatBalance.Math.

6.1. HeatBalance.ChamberKilnService (Камерная печь)

• Порт: 5102.
• Особенности модели: расчёт горения топлива, прямоточный режим и режим рециркуляции газов с расчётом кратности $r$ и коэффициента $\Delta\alpha$.

6.2. HeatBalance.ConveyorKilnService (Конвейерная печь)

• Порт: 5101.
• Особенности модели: непрерывное перемещение материала, учёт теплопотерь металлической конвейерной ленты и роликовых опор.

6.3. HeatBalance.ElectricKilnService (Электрическая печь)

• Порт: 5103.
• Особенности модели: электронагрев сопротивлением (ТЭНы), расчёт электрической мощности по закону Джоуля-Ленца, баланс вентиляционного воздуха.

6.4. HeatBalance.DrumDryerService (Сушильный барабан)

• Порт: 5104.
• Особенности модели: модель выносной топки сгорания газа, кинетика испарения влаги из сыпучего слоя, гидродинамическое сопротивление барабана.

---

7. HeatBalance.IoTService (Сервис промышленного IoT)

7.1. Назначение и стек

Высокопроизводительный сервис приёма телеметрических потоков, управления промышленными датчиками и автоматического запуска вычислений.

• Технологический стек: .NET 10, EF Core, PostgreSQL (база данных heat_balance_iot), MassTransit Publisher.
• Внутренний порт: 8080 (внешний порт 5400).

7.2. Модели сущностей:

• IoTDevice: физический датчик (Id, Name, AccessToken, SensorType от 1 до 15, CalculationType, DatasetId, OwnerId, LastSeenAt).
• DeviceGroup: технологическая группа связанных датчиков агрегата (Id, Name, CalculationType, DatasetId, DeviceIds, OwnerId).
• TelemetryLog: журнал единичных пакетов телеметрии с проверкой статуса парсинга.
• GroupTelemetryLog: журнал агрегированных расчётов по группам датчиков.

7.3. Алгоритм группового расчёта:

1. Загрузка базового шаблона датасета по DatasetId.
2. Извлечение последних зарегистрированных показаний датчиков группы из TelemetryLog.
3. Глубокое наложение параметров (JSON Deep Merge) поверх шаблона.
4. Вызов соответствующего расчётного микросервиса (Chamber, Conveyor, Electric, Drum).
5. Сохранение вычисленного КПД ($\eta$) и отправка команды SaveRunCommand в шину RabbitMQ.

---

8. HeatBalance.AnalyticsService (Сервис предиктивной аналитики)

8.1. Назначение и стек

Сквозной аналитический модуль предприятия. Реализует математико-статистические алгоритмы обработки исторических рядов без применения непрозрачных сторонних библиотек.

• Технологический стек: .NET 10 Web API, HttpClientFactory, авторизация [Authorize(Policy = Admin)].
• Внутренний порт: 8080 (внешний порт 5007).

8.2. Источники агрегации данных:

• RunService: история расчётов операторов за выбранный период (days).
• DatasetService: нормативные параметры технологических режимов.
• IoTService: оперативные журналы телеметрии и групп.

8.3. Реализованный алгоритмический аппарат:

1. Сглаживание тренда (SMA, $N=5$): фильтрация технологического шума временных рядов КПД и вычисление вектора тренда (Slope).
2. Детекция технологических аномалий (Z-Score): расчёт среднеквадратичного отклонения параметров. При $|z| \ge 2{,}0$ — статус warning, при $|z| \ge 3{,}0$ — статус critical.
3. Прогнозирование деградации футеровки (МНК): аппроксимация ряда КПД линейной функцией $\eta(t) = a + bt$ и экстраполяция даты достижения критического порога $\eta = 15\%$.
4. Бенчмаркинг и генератор рекомендаций: сопоставление параметров с наилучшим историческим режимом ($\eta_{\max}$) и расчёт требуемых технологических поправок ($\Delta\%$).