evaluate_next_step()

Домен: SIMULATION | Контур: Инициация транзакции шага и оркестрация

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

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

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

1. Бизнес-спецификация метода

Идентификатор метода: BPDS-SIM-M03
Системное имя: evaluate_next_step()
Микросервис: simulation-core-engine
Домен: SIMULATION
Класс / Компонент: simulation.engine.core.CoreSimulationEngineImpl

1.1. Описание логики работы

Этот метод является главным диспетчером и регулировщиком бизнес-логики. Сюда передаются только те пользователи, которые успешно прошли проверку активности на Шаге 2.

Метод работает как изолированный конвейер: он открывает шаг симуляции для конкретного пользователя, привязывает к нему сквозной номер сессии (X-Request-ID), запускает по очереди сбор данных (Часть 2) и математический расчет желаний. В самом конце он направляет пользователя в один из четырех сценариев действий (Покупка, Готовка, Потребление или Выброс).

1.2. Пошаговое выполнение

Привязка сессии (MDC Логирование): Метод принимает входящий X-Request-ID и жестко привязывает его к текущему виртуальному потоку. Все последующие записи в логах от этого пользователя будут помечены этим номером.
Запуск сбора данных: Метод вызывает Метод 4 (fetch_twin_metrics) для загрузки состава холодильника из приложения и привычек из базы данных симулятора.
Запуск математического ядра: Полученные данные (утвержденный кэшем профиль) передаются в математический блок (Метод 9), который считает итоговое желание пользователя.
Маршрутизация (Роутинг): На основе ответа математического блока метод определяет, какой сценарий выпал, извлекает нужный прикладной компонент из карты сценариев и передает ему управление.

2. Диаграмма последовательности метода (Вход и Выход флоу)

Диаграмма наглядно показывает, как Метод 3 принимает управление от Диспетчера (Метод 2), фиксирует сквозной номер сессии, управляет вызовами сбора данных и перенаправляет поток в конкретный сценарий Части 3.

sequenceDiagram
    autonumber
    participant Disp as Метод 2 (ActivationDispatcher)
    participant Core as CoreSimulationEngineImpl
    participant Reg as Метод 4 (TickRegistryImpl)
    participant Gen as Метод 9 (StochasticRouter)
    participant Part3 as Сценарии Части 3 (BUY/COOK/...)

    %% ВХОД МЕТОДА И ИНИЦИАЛИЗАЦИЯ
    Disp->>Core: Вызов evaluateNextStep(twin_id, tick, request_id)
    activate Core
    Note over Core: Вход метода: twin_id, номер такта, сквозной request_id
    
    Core->>Core: Фиксация в памяти потока: MDC.put("X-Request-ID", request_id)
    
    %% ШАГ 2: ВЫЗОВ СБОРА ДАННЫХ (ЧАСТЬ 2)
    Core->>Reg: Вызов fetchTwinMetrics(twin_id, tick)
    activate Reg
    Note over Reg: Если в RAM пусто, здесь сработает каскад сбора из 3-х источников
    Reg-->>Core: Возврат: Полностью готовый TwinContext объект
    deactivate Reg

    %% ШАГ 3: ВЫЗОВ МАТЕМАТИЧЕСКОГО ЯДРА
    Core->>Gen: Вызов projectStochasticSeed(TwinContext)
    activate Gen
    Note over Gen: Расчет плотностей желаний и процентов через Softmax
    Gen-->>Core: Возврат: Тип выбранного сценария (Пример: SCENARIO_B2B_BUY_RECEIPT)
    deactivate Gen

    %% ВЫХОД МЕТОДА И ПЕРЕДАЧА УПРАВЛЕНИЯ
    Note over Core: Выход метода: Вызов прикладного кода сценария покупки/готовки/потребления
    
    Core->>Part3: Вызов сценария execute(TwinContext)
    activate Part3
    Note over Part3: Управление передано в соответствующий qmd-документ Части 3
    deactivate Part3
    
    Core->>Core: Очистка памяти потока: MDC.remove("X-Request-ID")
    deactivate Core

3. Схемы данных и SQL-взаимодействие

Этот метод является чистым логическим оркестратором в памяти и напрямую с базой данных PostgreSQL не общается — он координирует вызовы других компонентов, у которых есть доступ к СУБД.

4. Спецификация обмена данными (Вход / Выход)

Обмен данными происходит внутри оперативной памяти виртуального потока микросервиса.

4.1. Структура входящих параметров оркестрации (Входные параметры от Метода 2)

{
  "active_twin_id": "d3b07384-d113-4956-bf8a-e421cd7bf777",
  "current_tick": 105,
  "x_request_id": "req-t105-active-d3b07384"
}

4.2. Структура выходного управляющего сигнала роутинга (Выходные параметры для Части 3)

{
  "dispatched_twin_id": "d3b07384-d113-4956-bf8a-e421cd7bf777",
  "activated_scenario_route": "SCENARIO_B2B_BUY_RECEIPT",
  "trace_status": "ROUTED_SUCCESSFULLY"
}

5. ЗАДАЧА ДЛЯ РАЗРАБОТЧИКА: BACKEND

Заголовок: Реализация главного оркестратора шага симуляции evaluate_next_step с поддержкой сквозного MDC-логирования

5.1. Что нужно сделать

Написать Java-класс CoreSimulationEngineImpl в пакете simulation.engine.core, реализовав интерфейс CoreSimulationEngine. Пометить аннотацией @Service.
Внедрить через конструктор зависимости: TickRegistry (RAM-реестр), StochasticGenerator (Математическое ядро) и карту зарегистрированных сценариев Map<ScenarioEnum, ExecutableScenario>.
В самом начале метода прописывать входящую строку requestId в контекст логирования MDC.put("X-Request-ID", requestId).
Последовательно вызвать: сначала tickRegistry.fetchTwinMetrics(), затем передать полученный результат в stochasticGenerator.projectStochasticSeed().
По полученному названию сценария извлечь из карты нужный обработчик и вызвать его метод .execute(context).
Обернуть всю логику в блок try-catch, ловить любые исключения и записывать их в лог. В блоке finally обязательно очищать контекст потока через MDC.remove("X-Request-ID").

6. ЗАДАЧА ДЛЯ РАЗРАБОТЧИКА: МИГРАЦИЯ

Заголовок: Настройка конфигурации вывода логов Logback для поддержки сквозного X-Request-ID

6.1. Что нужно сделать

Чтобы разработчик или аналитик логов мог отследить всю цепочку шагов конкретного пользователя в условиях, когда 1500 потоков пишут логи одновременно, стандартный шаблон вывода логов в файле src/main/resources/logback-spring.xml должен быть физически настроен на вывод переменной MDC.

<configuration>
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <!-- Добавление паттерна %X{X-Request-ID} для автоматического вывода номера сессии твина -->
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} [%X{X-Request-ID}] - %msg%n</pattern>
        </encoder>
    </appender>
    <root level="INFO">
        <appender-ref ref="STDOUT" />
    </root>
</configuration>