Microservice: Сервис Оркестрации для аналитики Process Mining

pm-analytics

Репозиторий сервиса

Исходный код (GitHub)

Published

October 20, 2026

WarningОграничение публичной документации

В открытом доступе представлена демонстрационная версия метода. В настоящей публичной документации отображены не все шаги, технические сценарии и приватные эндпоинты для системы цифровых симуляторов бизнес-процессов.

  • Полная спецификация метода: Будет доступна только во внутреннем контуре разработки (Confluence / Swagger Enterprise).

1 Общее назначение и архитектурная роль сервиса

Микросервис go-pm-backend выступает единым шлюзом аналитического контура (API Gateway & Orchestrator). Он управляет внешними HTTP/WebSocket-соединениями с Flutter-клиентами, верифицирует сессии через go-auth-service, извлекает эталонные .bpmn схемы из MinIO (S3) и маршрутизирует расчеты в изолированный воркер python-pm4py-worker по gRPC. Оркестратор реализует разделение ответственностей:

  • Авторизация и Сессии: проверка JWT/Bearer через межсервисный вызов.
  • Артефакты регламентов: кэширование и скачивание .bpmn файлов по scenario_id.
  • Агрегация и Маршрутизация: трансляция тяжелых расчетов из Python-воркера в легкий клиентский JSON.
  • Автоматический алертинг: при получении классификации CRITICAL_BACKEND_BUG отправляет нотификацию в Slack/Telegram-инженерный чат; при UNDOCUMENTED_API_FEATURE инициирует создание задачи для бизнес-аналитиков.

2 Основные бизнес-функции

  1. HandleProcessGraphRequest (HTTP/REST & WebSocket): прием запроса от мобильного клиента (scenario_id, фильтры по времени/роли).
  2. VerifyOperatorSession : синхронный gRPC/HTTP-запрос к go-auth-service для валидации токена и прав доступа (user_role).
  3. FetchBpmnSchemaFromMinIO : получение XML-содержимого диаграммы процесса из бакета S3 (bpmn-repository).
  4. DispatchToAnalyticsWorker: вызов gRPC-метода AnalyzeConformance к python-pm4py-worker с передачей XML-контента и порогов шума.
  5. EnrichAndRouteAnomalies: обработка поля classification из ответа воркера (генерация алертов или тикетов в Jira/Confluence API).

3 Структура базы данных и хранилищ (Реестр СУБД/S3)

Компонент / СУБД Логическая роль в сервисе Схема / Бакет Режим доступа из Go
MinIO (S3) Репозиторий эталонных регламентов s3://bpmn-repository/{scenario_id}.bpmn Чтение по S3 SDK (GetObject) с локальным TTL-кэшем (5 минут)
go-auth-service Сервис аутентификации и ролей gRPC :9000 / /auth.v1.AuthService/Verify Синхронный gRPC-клиент (таймаут 500мс)
python-pm4py-worker Аналитический вычислитель gRPC :9090 / analytics.ProcessMiningService Синхронный gRPC-клиент (таймаут 10сек)
ClickHouse (logs) Прямо из Go не читается logs.process_events Строго изолировано: доступ имеет только python-pm4py-worker

4 Сквозной gRPC Контракт (analytics.proto)

Listing 1: : gRPC-контракт взаимодействия оркестратора go-pm-backend и воркера python-pm4py-worker 

syntax = "proto3";

package analytics;
option go_package = "./pb";

service ProcessMiningService {
  // Выполняет мгновенный анализ соответствия реального лога эталону BPMN
  rpc AnalyzeConformance (ConformanceRequest) returns (ConformanceResponse);
}

message ConformanceRequest {
  string scenario_id = 1;      // Например: "fridge_cooking_flow"
  string user_role = 2;        // User, Bot_Simulator
  string bpmn_xml_content = 3; // Содержимое .bpmn файла, скачанное Go из MinIO
  float noise_threshold = 4;   // Калибровочный порог шума (по умолчанию 0.2)
}

message ConformanceResponse {
  SummaryStats summary = 1;
  repeated CaseDiagnostic detailed_cases = 2;
}

message SummaryStats {
  double global_fitness_score = 1; // Индекс прилегания от 0.0 до 1.0
  int32 total_cases_analyzed = 2;
  string health_status = 3;        // HEALTHY, ATTENTION_REQUIRED
}

message TokenMetrics {
  int32 consumed = 1;  // Потреблено позициями (c)
  int32 produced = 2;  // Сгенерировано (p)
  int32 missing = 3;   // Пропущено / Ошибка порядка (m)
  int32 remaining = 4; // Застряло в тупиках (r)
}

message AnomalyDetail {
  string type = 1;     // MISSING_TOKEN_STATE_MACHINE, HIDDEN_API_ROUTE
  string severity = 2; // CRITICAL, HIGH, LOW_WARNING
  string message = 3;  // Человекочитаемое описание для мобилки или Slack
}

message CaseDiagnostic {
  string case_id = 1;             // ID сессии трансформации сущностей
  double fitness_score = 2;       // Локальный Fitness Score трека
  bool is_compliant = 3;          // Идеально соответствует?
  TokenMetrics metrics = 4;       // Метрики c, p, m, r
  string classification = 5;      // CRITICAL_BACKEND_BUG, UNDOCUMENTED_API_FEATURE
  repeated AnomalyDetail anomalies = 6;
}

5 Пример клиентского JSON-ответа (Mobile API Payload)

Listing 2: : Формат ответа REST-эндопоинта /api/v1/process-graph для мобильного клиента Flutter 

{
  "summary": {
    "global_fitness_score": 0.845,
    "total_cases_analyzed": 1250,
    "status": "ATTENTION_REQUIRED"
  },
  "detailed_cases": [
    {
      "case_id": "cooking_session_xyz777",
      "fitness_score": 0.5,
      "is_compliant": false,
      "metrics": { "consumed": 4, "produced": 4, "missing": 2, "remaining": 2 },
      "classification": "CRITICAL_BACKEND_BUG",
      "anomalies": [
        {
          "type": "MISSING_TOKEN_STATE_MACHINE",
          "severity": "CRITICAL",
          "message": "Критический баг Go Core: сырье списано на шаге 'Готовка', но транзакция создания нового блюда не зафиксирована."
        }
      ]
    },
    {
      "case_id": "fast_consume_session_888",
      "fitness_score": 0.75,
      "is_compliant": false,
      "metrics": { "consumed": 3, "produced": 4, "missing": 0, "remaining": 1 },
      "classification": "UNDOCUMENTED_API_FEATURE",
      "anomalies": [
        {
          "type": "HIDDEN_API_ROUTE",
          "severity": "LOW_WARNING",
          "message": "Обнаружена скрытая фича API: Вызван метод быстрого списания в обход экрана инвентаря во Flutter. Требуется обновить BPMN."
        }
      ]
    }
  ]
}

6 Диаграмма последовательности (Sequence Diagram)

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'actorBkg': '#EBF8FF',
    'actorBorder': '#A3BFFA',
    'actorTextColor': '#000000',
    'rectBkg': '#FAF7F0',
    'rectBorder': '#E3DDCF',
    'noteBkgColor': '#E6F4EA',
    'noteBorderColor': '#34D399',
    'noteTextColor': '#064E3B',
    'signalColor': '#2D3748',
    'signalLineColor': '#4A5568'
  }
}}%%
sequenceDiagram
    autonumber
    actor Client as Мобильный Клиент (Flutter)
    participant Gateway as HTTPS/WS Handler (go-pm-backend)
    participant Auth as go-auth-service (gRPC)
    participant MinIO as MinIO S3 (BPMN Repo)
    participant Wkr as python-pm4py-worker (gRPC)
    participant Alert as Slack / Jira Webhook

    Client->>Gateway: GET /api/v1/process-graph?scenario=X [Authorization: Bearer]
    activate Gateway
    
    note over Gateway: Шаг 2: Валидация сессии и извлечение user_role
    Gateway->>Auth: gRPC Verify(token)
    activate Auth
    Auth-->>Gateway: UserValid (UserID, Role, Status=ACTIVE)
    deactivate Auth

    note over Gateway: Шаг 3: Проверка локального LRU-кэша BPMN XML
    Gateway->>MinIO: S3 GetObject(bpmn-repository/{scenario_id}.bpmn)
    activate MinIO
    MinIO-->>Gateway: BPMN XML Content string
    deactivate MinIO

    note over Gateway: Шаг 4: Формирование ConformanceRequest с noise_threshold=0.2
    Gateway->>Wkr: gRPC AnalyzeConformance(scenario_id, bpmn_xml, noise)
    activate Wkr
    
    note over Wkr: Выполнение SQL в ClickHouse и Alignment-расчет PM4Py
    Wkr-->>Gateway: ConformanceResponse (SummaryStats + CaseDiagnostics)
    deactivate Wkr

    note over Gateway: Шаг 8: Сериализация и отдача легкого JSON клиенту
    Gateway-->>Client: HTTPS 200 OK + JSON payload
    deactivate Gateway

    note over Gateway: Шаг 9: Асинхронный роутинг классификаций
    opt CRITICAL_BACKEND_BUG detected
        Gateway->>Alert: HTTP POST Webhook -> Slack #incident-alerts
    end
    opt UNDOCUMENTED_API_FEATURE detected
        Gateway->>Alert: HTTP POST Webhook -> Jira Create Ticket
    end
Figure 1: Сквозной конвейер обработки и маршрутизации запросов в go-pm-backend

7 Таблица расшифровки шагов сценария

Шаг Источник Получатель Протокол / Метод Полезная нагрузка (Payload) Обработка сбоев (Fallback)
1 Мобильный Flutter go-pm-backend HTTPS GET /api/v1/process-graph?scenario=X Header: Authorization: Bearer , Query params Возврат 401 Unauthorized или 400 Bad Request
2 go-pm-backend go-auth-service gRPC AuthService.Verify { token: “…” } При таймауте (>500ms) или сбое — 503 Service Unavailable
3 go-pm-backend MinIO (S3) S3 GetObject Bucket: bpmn-repository, Key: {scenario_id}.bpmn Использование локального in-memory кэша / fallback-шаблона
4 go-pm-backend python-pm4py-worker gRPC ProcessMiningService.AnalyzeConformance ConformanceRequest (scenario_id, bpmn_xml_content, noise_threshold) Circuit Breaker: при DEADLINE_EXCEEDED (>10s) возврат кэшированного графа
5 python-pm4py-worker ClickHouse TCP/HTTP SQL Query Чтение logs.process_events по case_id / timestamp Возврат пустого среза за период
6-7 python-pm4py-worker go-pm-backend gRPC Response ConformanceResponse (SummaryStats, repeated CaseDiagnostic) Логирование ошибки парсинга XML/Petri-сети
8 go-pm-backend Мобильный Flutter HTTPS 200 OK JSON Listing 2 Отправка частичного отчета с флагом degraded_mode: true
9 go-pm-backend Slack / Jira API HTTP POST Webhook Асинхронная отправка инцидента по classification Подавление дубликатов алертов через Redis-окно (1 час)

8 Справочник ошибок шлюза (go-pm-backend)

HTTP / gRPC Статус Каноничный код (canonical_code) Уровень Сообщение для клиента (message) Действие бэкенда
401 / UNAUTHENTICATED GATEWAY_AUTH_INVALID WARN Недействительный или просроченный токен авторизации. Сброс сессии на клиенте
404 / NOT_FOUND BPMN_SCENARIO_MISSING ERROR Сценарий процесса не найден в репозитории регламентов. Лог system_error_logs, алертинг аналитикам
504 / DEADLINE_EXCEEDED PM4PY_WORKER_TIMEOUT ERROR Аналитический движок перегружен, попробуйте позже. Возврат фоллбек-статистики, метрика pm4py_timeout_total
502 / INTERNAL BPMN_XML_PARSE_ERROR ERROR Ошибка структуры эталонной BPMN-диаграммы. Создание задачи в Jira для исправления XML в MinIO