Метод 16: verify_state_mutation()

Домен: SIMULATION | Контур: Верификация изменений в базе данных бэкенда

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

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

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

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

Идентификатор метода: BPDS-SIM-M016
Системное имя: verify_state_mutation(twin_id: UUID, expected_change: ScenarioEnum): Boolean
Микросервис: simulation-core-engine
Домен: SIMULATION
Класс / Компонент: simulation.engine.net.StateMutationValidator

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

Этот метод выполняет роль контролера качества и аудитора данных. Он запускается сразу после того, как Метод 15 получил успешный ответ 200 OK от API-шлюза бэкенда.

В микросервисной архитектуре бывает ситуация, когда шлюз принял запрос и ответил «Успешно», но внутренняя очередь сообщений или база данных бэкенда зависла, и реальные данные в PostgreSQL бэкенда не изменились. Чтобы исключить рассинхронизацию (расхождение состояния), симулятор делает независимый контрольный GET-запрос к бэкенду. Он запрашивает актуальный состав холодильника и проверяет: действительно ли продукты добавились (после покупки), удалились (после поедания/выброса) или трансформировались (после готовки). Если проверка пройдена, такт признается успешным.

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

Контрольный вызов: Метод инициирует повторный HTTP GET запрос к эндпоинту холодильника бэкенда для проверяемого пользователя twin_id.
Получение факта: Бэкенд возвращает из своей PostgreSQL актуальный срез продуктов.
Логическая сверка (Инспекция мутаций): Программа сопоставляет факт с ожиданиями текущего сценария:
- После Покупки: Симулятор проверяет, появились ли в массиве новые UUID купленных товаров.
- После Готовки: Симулятор проверяет, исчезли ли UUID списанных ингредиентов и появилась ли строка готового блюда.
- После Потребления/Выброса: Симулятор проверяет, что съеденный или выброшенный UUID полностью отсутствует в списке.
Выход: Если база данных бэкенда изменилась корректно, метод возвращает статус true, открывая дорогу финальной фиксации привычек. Если обнаружено расхождение (база бэкенда старая), метод выбрасывает контролируемое исключение StateDriftException.

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

Диаграмма наглядно показывает, как валидатор симулятора делает независимый проверочный GET-запрос к API бэкенда, сверяет реальное состояние его PostgreSQL со своими ожиданиями и дает зеленый свет финальному шагу.

sequenceDiagram
    autonumber
    participant Core as Метод 3 (Orchestrator)
    participant Val as StateMutationValidator
    participant Client as RestClient (JVM Network)
    participant Gateway as API Шлюз Бэкенда (Magnum/Small)

    %% ВХОД МЕТОДА
    Core->>Val: Вызов verifyStateMutation(twin_id, scenario)
    activate Val
    Note over Val: Вход метода: twin_id пользователя и тип выполненного сценария
    
    %% КОНТРОЛЬНЫЙ ЗАПРОС GET
    Val->>Client: Инициация проверочного GET запроса
    activate Client
    Client->>Gateway: HTTP GET /api/v1/fridge/products (X-Twin-ID)
    activate Gateway
    Note over Gateway: Бэкенд вычитывает текущие строки из своей PostgreSQL
    Gateway-->>Client: Возврат: HTTP 200 OK + Актуальный JSON холодильника
    deactivate Gateway
    Client-->>Val: Передача массива продуктов List (RawProductDto)
    deactivate Client
    
    %% ВНУТРЕННЯЯ ВЕРИФИКАЦИЯ МУТАЦИИ
    Val->>Val: Сверка факта СУБД бэкенда с ожиданиями сценария
    
    alt Ситуация 1: Данные бэкенда сошлись с логикой шага
        Note over Val: Выход метода: Статус успешного подтверждения консистентности (true)
        Val-->>Core: Возврат: true
    else Ситуация 2: Обнаружено расхождение (база бэкенда не обновилась)
        Note over Val: Прерывание: Выброс исключения StateDriftException
    end
    deactivate Val
    Note over Core: Оркестратор принимает сигнал true и переходит к Методу 17 (Фиксация весов)

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

Этот метод обращается к прикладному API бэкенда по сети. Прямых SQL-запросов к своей PostgreSQL он не делает, однако под капотом он верифицирует результат транзакций, которые бэкенд выполнил в своей СУБД public.fridge_products.

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

Пример проверки состояния холодильника после того, как Твин успешно выполнил сценарий потребления готового йогурта.

4.1. Исходящий контрольный HTTP GET запрос к бэкенду (Входные параметры в сеть)

GET /api/v1/fridge/products HTTP/1.1
Host: almaty-backend-gateway:8080
X-Shop-Token: almaty_retail_secret_hash_2026
X-Twin-ID: d3b07384-d113-4956-bf8a-e421cd7bf777
X-Request-ID: req-t105-active-d3b07384
Accept: application/json

4.2. Входящий ответ бэкенда для верификации (Выходные параметры из сети для проверки)

База данных бэкенда вернула пустой массив [] — это означает, что йогурт успешно удален из public-таблицы бэкенда. Мутация подтверждена:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2

[]

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

Заголовок: Реализация компонента верификации мутаций данных бэкенда verify_state_mutation

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

Написать Java-класс StateMutationValidator в пакете simulation.engine.net и пометить его аннотацией @Component.
Внедрить Spring RestClient для вызова прикладного эндпоинта холодильника бэкенда.
Написать метод verifyStateMutation, принимающий twinId и тип сценария ScenarioEnum.
Выполнить сетевой вызов GET /api/v1/fridge/products, обязательно прокинув в заголовках X-Twin-ID и текущий X-Request-ID из MDC-контекста. Распарсить ответ в List<RawProductDto>.
Реализовать логику сверки. Если сценарий был CONSUME или WASTE — проверить, что целевых списанных ID продуктов больше нет в полученном списке. Если сценарий BUY — проверить, что в списке появились новые строки.
Если проверка условий провалена (база данных бэкенда не зафиксировала изменения), выбрасывать исключение StateDriftException("Обнаружено расхождение данных с бэкендом приложения"). Если все верно — возвращать true.

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

Заголовок: Настройка параметров пула соединений СУБД бэкенда для поддержки мгновенных проверок READ COMMITTED

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

Чтобы контрольные GET-запросы симулятора мгновенно видели изменения, сделанные параллельными POST-запросами на Шаге 15, уровень изоляции транзакций в PostgreSQL бэкенда должен быть жестко зафиксирован как READ COMMITTED (стандартный для Postgres, позволяющий видеть только зафиксированные транзакции). Нам необходимо убедиться, что пул соединений бэкенда розничной сети настроен на моментальную отдачу коммитов во избежание фантомных ошибок расхождения. Данная задача относится к категории миграции настроек базы данных бэкенда (Database Configuration Migration).

Проверить и зафиксировать параметры пула HikariCP в файле application.yml тестируемого бэкенда:

spring:
  datasource:
    hikari:
      # Гарантия того, что проверочные SELECT-запросы симулятора не будут зависать в очередях блокировок
      transaction-isolation: TRANSACTION_READ_COMMITTED
      maximum-pool-size: 50