Локальное окружение и сборка

1. Системные требования и стек инструментов разработчика

Для локальной разработки, сборки, отладки и запуска распределённого программного комплекса «UrFU HeatBalance» рабочая станция инженера должна удовлетворять следующим требованиям:

Компонент окружения	Рекомендуемая версия	Назначение в процессе разработки
Операционная система	Windows 10/11 x64, Ubuntu 22.04+, macOS	Хостовая операционная среда разработки
.NET SDK	.NET 10.0+	Компиляция и выполнение C# бэкенд-микросервисов
Node.js & npm	Node.js 20+ / 22 LTS	Сборка клиентского интерфейса React 19 и документации
Docker Engine & Compose	Docker Engine 26+ (WSL 2 backend)	Запуск локальных экземпляров СУБД, кэша Redis, брокера RabbitMQ
IDE / Редактор кода	Visual Studio 2022+ / VS Code / JetBrains Rider	Разработка C# (.NET) и веб-приложения
Git Client	Git 2.40+	Контроль версий и синхронизация с репозиторием
Оболочка автоматизации	PowerShell 7+ / Bash	Скрипты параллельного запуска микросервисов

1.1. Верификация установленного ПО

Перед началом работы проверьте корректность настройки переменных окружения (PATH):

# Проверка версии компилятора и SDK .NET
dotnet --version
dotnet --list-sdks

# Проверка окружения Node.js и npm
node -v
npm -v

# Проверка доступности Docker демона
docker --version
docker compose version

# Проверка клиента контроля версий
git --version

---

2. Пошаговая инициализация рабочего окружения

Шаг 1. Клонирование репозитория проекта

Склонируйте исходный код проекта с рекурсивным получением подмодулей (при наличии):

git clone https://github.com/ruzzel666/UrFU-HeatBalance-Microservices.git
cd UrFU-HeatBalance-Microservices

Шаг 2. Локальный запуск инфраструктурных сервисов

Для полноценной работы микросервисов на машине разработчика необходимы экземпляры PostgreSQL 15, Redis 7 и RabbitMQ 3. Рекомендуется запускать их через Docker Compose в изолированном фоновом режиме:

# Запуск только баз данных, кэша и брокера сообщений
docker compose up -d db redis rabbitmq

После запуска инфраструктурные порты будут доступны на локальном интерфейсе:

• PostgreSQL: localhost:5432 (пользователь: postgres, пароль: postgres)
• Redis: localhost:6379 (без пароля по умолчанию в dev-режиме)
• RabbitMQ AMQP: localhost:5672 (пользователь: guest, пароль: guest)
• RabbitMQ Management UI: http://localhost:15672

Шаг 3. Восстановление зависимостей и компиляция бэкенда

Перейдите в директорию серверной части backend/HeatBalanceSystem2 и выполните сборку решения:

cd backend/HeatBalanceSystem2

# Восстановление NuGet-пакетов
dotnet restore HeatBalanceSystem.sln

# Сборка решения в конфигурации Debug
dotnet build HeatBalanceSystem.sln

---

3. Регламенты локального запуска микросервисов

3.1. Пакетный запуск через скрипт автоматизации

В каталоге backend/HeatBalanceSystem2 подготовлен скрипт run-microservices.ps1, автоматизирующий очистку локальных портов, сборку и фоновый старт всех 11 микросервисов в виде изолированных фоновых заданий PowerShell (Jobs) с раздельным логированием в каталог logs/:

# Запуск из каталога backend/HeatBalanceSystem2
./run-microservices.ps1

Микросервис	Проект C# (.csproj)	Локальный сетевой адрес
Gateway (YARP)	src/Gateway/HeatBalance.Gateway	http://127.0.0.1:5000
Auth (OpenIddict)	src/Auth/HeatBalance.Auth	http://127.0.0.1:5001
DatasetService	src/Services/HeatBalance.DatasetService	http://127.0.0.1:5100
ConveyorKilnService	src/Services/HeatBalance.ConveyorKilnService	http://127.0.0.1:5101
ChamberKilnService	src/Services/HeatBalance.ChamberKilnService	http://127.0.0.1:5102
ElectricKilnService	src/Services/HeatBalance.ElectricKilnService	http://127.0.0.1:5103
DrumDryerService	src/Services/HeatBalance.DrumDryerService	http://127.0.0.1:5104
RunService	src/Services/HeatBalance.RunService	http://127.0.0.1:5200
ReportService	src/Services/HeatBalance.ReportService	http://127.0.0.1:5300
IoTService	src/Services/HeatBalance.IoTService	http://127.0.0.1:5400
AnalyticsService	src/Services/HeatBalance.AnalyticsService	http://127.0.0.1:5007

Для остановки всех параллельных сервисов нажмите комбинацию Ctrl+C в терминале выполнения скрипта.

3.2. Точечный запуск отдельного сервиса для отладки

Если требуется отладить конкретный микросервис (например, расчётное ядро камерной печи) с подключением отладчика Visual Studio или VS Code:

cd backend/HeatBalanceSystem2
dotnet run --project src/Services/HeatBalance.ChamberKilnService/HeatBalance.ChamberKilnService.csproj --urls "http://127.0.0.1:5102"

Интерактивная документация Swagger UI отдельного сервиса будет доступна по адресу: http://localhost:5102/swagger

---

4. Локальный запуск клиентского веб-приложения (Frontend)

Веб-клиент разработан на базе React 19 с использованием сборщика Vite.

4.1. Установка зависимостей и старт dev-сервера

cd frontend

# Чистая установка зависимостей из package-lock.json
npm ci

# Запуск локального сервера разработки с горячей перезагрузкой (HMR)
npm run dev

По умолчанию dev-сервер Vite открывает порт http://localhost:5173.

4.2. Конфигурация переменных окружения фронтенда

Для перенаправления запросов к локальному API Gateway создайте или проверьте файл frontend/.env:

# Базовый адрес API шлюза при локальной разработке
VITE_API_BASE_URL=http://localhost:5000/api

---

5. Локальный запуск портала технической документации (Docs)

Портал технической документации платформы построен на генераторе статических сайтов VitePress.

cd docs

# Установка зависимостей генератора документации
npm install

# Запуск локального сервера документации с поддержкой HMR
npm run dev

Документация станет доступна по адресу http://localhost:5173. Любые изменения в файлах .md отображаются в браузере в реальном времени.

Для верификации корректности всех ссылок, KaTeX-формул и Mermaid-диаграмм перед отправкой изменений выполните тестовую сборку:

npm run build

---

6. Профиль конфигурации и управление секретами

Для локальной разработки чувствительные данные (пароли к БД, секретные ключи подписи JWT-токенов) не должны фиксироваться в системе контроля версий.

6.1. Использование .NET User Secrets

Для безопасного переопределения строк подключения в микросервисах HeatBalance.Auth, HeatBalance.DatasetService, HeatBalance.RunService и HeatBalance.IoTService используйте встроенный инструмент Secret Manager:

# Инициализация секретов для сервиса авторизации
cd src/Auth/HeatBalance.Auth
dotnet user-secrets init
dotnet user-secrets set "ConnectionStrings:DefaultConnection" "Host=localhost;Port=5432;Database=heat_balance_auth;Username=postgres;Password=postgres"

6.2. Файлы appsettings.Development.json

В режиме ASPNETCORE_ENVIRONMENT=Development микросервисы автоматически подгружают локальные параметры, отключающие обязательное шифрование HTTPS внутри локальной сети и активирующие подробный вывод стека вызовов при возникновении исключений.