Документация ISPF

1. Функциональные характеристики

Для кого продукт

Что решает ISPF

Типичный стек SCADA/MES растёт отдельными модулями: OPC-сервер, historian, HMI, workflow, отчёты. ISPF объединяет их вокруг одного object tree с единым API и UI.

Диаграмма (Mermaid) — см. полную документацию на GitVerse.

Главный принцип

Бизнес-логика живёт на платформе — в blueprints, переменных, событиях, функциях и workflow дерева объектов. Платформа даёт generic-движки (CEL, bindings, BPMN, script runtime, драйверы); решение конфигурирует их декларативно. Bundle deploy — это упаковка конфигурации, а не отдельный runtime. Кратко: application-principles. Детали: architecture. Бэклог: roadmap.

Ключевые возможности

• - Единая модель — устройство, дашборд, workflow и правило тревоги — узлы дерева; логика через variables, events, functions и BPMN.
• - Bundles, а не форки ядра — отраслевые решения деплоятся как конфигурация в механизмы платформы (applications).
• - Стек — Spring Boot 4, Java 25, PostgreSQL/TimescaleDB, React 19, REST + WebSocket; опционально NATS/MQTT/Keycloak.
• - ~60 driver packs (не внутри ispf-server.jar; maturity разный — см. drivers).
• - Платформа AGPL v3 — опционально Enterprise dual-license; driver packs и application bundles могут иметь отдельные условия (license, plugins).

Возможности продукта

1. Object tree

Центральная абстракция. У каждого узла есть путь (root.platform.devices.pump-01), тип, переменные, события и функции.

Подробнее: object-model, glossary.

2. Модели (шаблоны)

BlueprintDefinition описывает набор переменных, событий, функций и CEL-привязок. MIXIN’ы auto-apply только при непустом Applicability condition (CEL). Демо-blueprint mqtt-sensor-v1 — fixture через templateId.

Подробнее: blueprints, 0018-fixture-models-and-cel-applicability.

3. Драйверы устройств

SPI DeviceDriver связывает протоколы с переменными объектов. Администратор задаёт driverId, конфигурацию и point mapping; runtime опрашивает устройство и пишет значения в дерево.

Демо после первого старта:

Подробнее: drivers.

4. Дашборды и HMI

Dashboard Builder (admin) и Operator HMI (read-only) используют одни и те же виджеты:

Привязка данных: objectPath (статика) или selectionKey (выбор строки таблицы). Сетка layout — 84×8 (dashboards).

Подробнее: dashboards, scada, справочник виджетов: widgets.

5. Workflow (BPMN)

Визуальный BPMN-редактор в Web Console. Service tasks (в т.ч. вызов application functions), user tasks (очередь оператора), gateway с CEL, параллельные ветки, signals и NATS.

Подробнее: workflows.

2. Установка

Попробовать ISPF (≈15 минут)

Вариант A — all-in-one JAR (быстрее всего)

Скачайте ispf-*-portable.zip с GitVerse Releases (JDK 25). Распакуйте, затем:

# Windows: двойной клик по start.bat
# Linux / macOS:
./start.sh

Отдельный PostgreSQL не нужен — portable использует встроенный H2 (после первого старта файл data/ispf-local.mv.db).

Откройте http://localhost:8080 — логин admin / admin. Дальше с §2 Вход (порт 8080 вместо 5173).

Вариант B — из исходников

Требования

1. Запуск API + консоли

# Терминал 1 — профиль local (H2 file DB; sync небольшого набора dev driver packs)
./gradlew :packages:ispf-server:bootRun --args="--spring.profiles.active=local"

# Терминал 2 — Web Console
cd apps/web-console && npm install && npm run dev

bootRun по умолчанию вызывает syncDevDriverPacks (≈8 packs). Полный каталог: -Dispf.driver.packs=all.

2. Вход (local)

Пустая БД создаёт пользователей: admin / admin (также developer / developer, operator / operator). Войдите через экран логина Web Console.

API (Bearer — нужен для большинства вызовов):

TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}' | jq -r .token)

curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/v1/objects

Заголовок X-ISPF-Role по умолчанию выключен (ispf.security.local-role-header-enabled=false). Не рассчитывайте на селектор Role в шапке для обычного local. Подробнее: security.

3. Первые шаги в UI

1. 1. Откройте дерево объектов — ветка root.platform.
2. 2. Раскройте devices → demo-sensor-01 — temperature, threshold, alarm.
3. 3. Дважды кликните dashboards.demo-sensor — Dashboard Builder.
4. 4. Раскройте alert-rules → temperature-threshold-exceeded — CEL-правило.
5. 5. Дважды кликните workflows.demo-alarm-handler — демо BPMN.
6. 6. Режим оператора: http://localhost:8080?mode=operator (all-in-one JAR) или http://localhost:5173?mode=operator (Vite), или вход как operator.

Язык: селектор в шапке (English удобен для OSS-скриншотов).

4. Старт драйвера demo-sensor

curl -X POST "http://localhost:8080/api/v1/drivers/runtime/start?devicePath=root.platform.devices.demo-sensor-01" \
  -H "Authorization: Bearer $TOKEN"

Температура — синусоида; при превышении порога срабатывают alarmActive и alert rule.

Дальше после демо

• - Обзор продукта · Модель объектов · Дашборды · Автоматизация
• - Разработчик решений — реальный bundle
• - Архитектура · API

3. Эксплуатация

Руководство оператора

Руководство для пользователей с ролью operator — мониторинг оборудования, задачи из work queue, события и отчёты.

Обзор продукта: product. Технические детали UI: web-console.

Вход

URL консоли: all-in-one JAR — http://<host>:8080; Vite dev — http://<host>:5173. Подробнее: getting-started.

1. 1. Откройте Web Console по одному из URL выше.
2. 2. Войдите учётной записью оператора (демо: operator / operator).
3. 3. После входа откроется Operator HMI — полноэкранный режим без дерева объектов и редакторов.

Если у вас роль admin, но нужен режим оператора:

http://<host>:8080?mode=operator
# или (Vite dev):
http://<host>:5173?mode=operator

Для конкретного приложения:

http://<host>:8080?mode=operator&app=platform
# или (Vite dev):
http://<host>:5173?mode=operator&app=platform

Автозапуск приложения

Администратор может настроить auto-start для вашей учётной записи: после входа сразу откроется нужное operator app (например, platform или отраслевое приложение).

Operator HMI

Слева — дашборд (виджеты, графики, таблицы); справа — сайдбар Work Queue / журнал событий; внизу справа — ИИ-помощник смены (read-only).

Что доступно оператору

Работа с дашбордами

Навигация между экранами

Если в приложении несколько дашбордов, они отображаются как вкладки вверху экрана. Переключайте вкладки для перехода между экранами (например, «Обзор», «Детали», «Отчёты»).

Виджет dashboard-link на экране может открыть другой дашборд — в текущей вкладке или в модальном окне.

Виджеты на экране

Полный справочник виджетов: widgets.

На экранах с таблицей устройств (object-table с selectionKey) клик по строке обновляет связанные виджеты — графики и индикаторы показывают данные выбранного устройства.

Виджет spreadsheet

Виджет spreadsheet — таблица с адресацией ячеек в стиле Excel (A1, B2, …). Значения и формулы пересчитываются на экране без round-trip к серверу (кроме live-ячеек binding).

Подробная инструкция: spreadsheet-widget.

Кратко:

Выделение и ввод (free mode):

1. 1. Клик по ячейке — выделить; содержимое появляется в formula bar.
2. 2. Двойной клик или F2 — редактирование прямо в ячейке.
3. 3. Formula bar — число (10), текст или формула (=A1+B2); Enter — сохранить.
4. 4. Tab / Shift+Tab — следующая / предыдущая ячейка; стрелки — перемещение по сетке.

Горячие клавиши (free mode, фокус на сетке):

Сохранение: введённые значения и формулы сохраняются автоматически (сессия дашборда или переменная объекта — как настроено разработчиком). После F5 данные остаются, если виджет привязан к переменной (persistMode: variable).

Лабораторный пример: дашборд root.platform.dashboards.lab-calculator — шаблонный калькулятор (режим configured): редактируются только A2 и B2; суммы пересчитываются автоматически.

Динамический выбор объекта

На экранах с таблицей устройств (object-table с selectionKey) клик по строке обновляет связанные виджеты — графики и индикаторы показывают данные выбранного устройства.

Work Queue

Work Queue содержит BPMN user tasks, назначенные операторам.

Типичный поток

1. 1. Workflow запускается (вручную администратором или по событию).
2. 2. Процесс доходит до user task → задача появляется в Work Queue.
3. 3. Оператор нажимает Claim — задача закрепляется за ним.
4. 4. Оператор выполняет действие (например, подтверждение на дашборде).
5. 5. Нажимает Complete — workflow продолжается.

Где смотреть

• - Sidebar справа в Operator HMI — панель Work Queue.
• - Виджет work-queue на дашборде — встроенная очередь на экране.

Если задача недоступна

• - Задача уже claimed другим оператором — дождитесь завершения или обратитесь к администратору.
• - Статус workflow STOPPED — новые задачи не создаются.

Журнал событий

Sidebar Event Journal показывает недавние события платформы:

• - Превышение порога датчика
• - Срабатывание alert rule
• - Ручная публикация события
• - Системные уведомления

Уровни: DEBUG, INFO, WARNING, ERROR, CRITICAL.

Виджет event-log на дашборде может фильтровать события по конкретному объекту.

4. Развёртывание (prod / Docker)

Docker Compose

docker compose up -d

Volume: ispf_pg_data.

Profiles Compose не используются — все сервисы стартуют вместе.

Spring Boot Server

Артефакт: :packages:ispf-server:bootRun или JAR из build/libs/.

Переменные окружения

Профили

База данных

• - Flyway — миграции при старте (ddl-auto: validate); locations по RelationalDialect (см. 0037-relational-core-portability)
• - local: H2 ./data/ispf-local (PostgreSQL compatibility mode)
• - prod: PostgreSQL; TimescaleDB extension (docker image timescale/timescaledb) — hypertables variable_samples и event_history, retention 90d (0009-timescaledb-retention, 0015-event-history-timescale)

Режимы хранилища

Одна БД — штатный сценарий: конфигурация, объекты, event_history и variable_samples в одном PostgreSQL. ClickHouse/Cassandra — только при высокой нагрузке на time-series.

Опционально: ISPF_METADATA_DB_KIND (postgresql, h2, mssql, …) — см. storage-portability-inventory.

Смена движка metadata (greenfield, до v1.0): новая пустая БД, Flyway baseline выбранного dialect, конфигурация — импорт бандлов. In-place миграция PG→MSSQL не поддерживается.

Platform Data Sources (root.platform.data-sources.*): internal — схема в ISPF_DB; external — JDBC к внешней БД для отчётов и SQL bindings (не metadata).

Messaging

Production quick start (BL-127)

Одна команда поднимает lab / localhost стек на Linux-хосте с Docker (PostgreSQL + Redis + ispf-server + nginx для UI). Не привязан к VPS ispf.example.invalid.

Не для internet-facing production без hardening: порты привязаны к 127.0.0.1, demo-fixtures выключены, дефолтные пароли БД (ispf/ispf) нужно сменить перед выносом в сеть. Образы — pinned tags из deploy/air-gap-images.env. Полный чеклист prod: DEMOSTANDS.md § Production.

Требования: Docker Engine + Compose v2, JDK 25 (для сборки), Node.js 20+ (для UI).

bash deploy/prod-quickstart.sh

Скрипт:

1. 1. Собирает ispf-server JAR (bootJar, без тестов).
2. 2. Собирает apps/web-console (npm ci && npm run build).
3. 3. Копирует JAR в deploy/staging/ispf-server.jar.
4. 4. Запускает deploy/docker-compose.prod-stack.yml.
5. 5. Ждёт readiness через deploy/health-check.sh.

Остановка:

docker compose -f deploy/docker-compose.prod-stack.yml down

Volumes PostgreSQL сохраняются (ispf_prod_pg). Полная очистка: добавьте -v.

Файлы:

Prod VPS: для ispf.example.invalid по-прежнему используйте deploy/vps-deploy-direct.ps1 (direct SCP + staging), не этот quick start.

Kubernetes Helm chart (BL-186)

Chart: deploy/helm/ispf. Устанавливается Helm 3.14+; lint/template smoke без кластера.

# Статический smoke (локальный helm или Docker alpine/helm)
bash deploy/helm/ispf/validate.sh

# Install
helm upgrade --install ispf deploy/helm/ispf \
  --namespace ispf --create-namespace \
  --set secrets.dbPassword='change-me' \
  --set ispf.bootstrap.fixturesEnabled=false

# Runtime smoke
kubectl -n ispf rollout status deploy/ispf --timeout=180s
kubectl -n ispf port-forward svc/ispf 8080:80 &
curl -sf http://127.0.0.1:8080/actuator/health
curl -sf http://127.0.0.1:8080/api/v1/info

ARM edge в K8s: edge.enabled=true / edge.arm64=true (см. edge/arm64). Compose-профиль для Pi/шлюзов: BL-187.

5. Полная документация на GitVerse