Метод 5: compile_analytical_metrics()

Домен: SIMULATION | Контур: Аналитическая свертка и расчет голода

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

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

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

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

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

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

Этот метод принимает на вход сырой пакет данных (RawExtractionPacket), собранный на предыдущем шаге из внешнего приложения и внутренних таблиц. Задача метода — перевести эти разрозненные физические параметры в абстрактные математические показатели состояния человека.

Поскольку из симулятора полностью удален расчет порчи продуктов, фокус метода направлен исключительно на биологические часы голода. Метод считает, сколько виртуальных часов назад пользователь ел в последний раз. На основе этой дельты времени вычисляется показатель голода. Если данных в базе не оказалось (первый старт), система применяет защитный дефолт, чтобы симуляция не остановилась.

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

Проверка истории: Из пакета данных извлекается номер такта последней еды (last_tick_updated). Если запись пустая (первый запуск нового пользователя), симулятор искусственно считает, что пользователь ел 12 часов назад от текущего момента времени.
Расчет интервала: Вычисляется дельта времени: текущий такт симуляции минус такт последней еды.
Нормирование голода: Показатель голода (\(x_0\)) рассчитывается по линейной формуле. Каждые 24 часа без еды приравниваются к 100% голоду (\(1.0000\)). Значение жестко удерживается в границах от 0.0 до 1.0.
Слияние весов: Извлекается карта личных весов пользователя. Если для каких-то категорий продуктов (DAIRY, FRUITS, READY_MEALS, GROCERIES) веса в базе отсутствуют, им автоматически присваивается стартовое базовое значение 1.0000.
Интеграция характера: Из профиля извлекается коэффициент лени, который без изменений упаковывается в финальный объект.

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

Диаграмма наглядно показывает, как метод принимает сырой пакет данных от контура сбора (Метод 4), проводит математический расчет голода в памяти и выдает готовый скомпилированный контекст пользователя для сохранения в оперативной памяти (Метод 6).

sequenceDiagram
    autonumber
    participant Reg as Метод 4 (TickRegistryImpl)
    participant Sub as compile_analytical_metrics()
    participant Math as Математический Движок (JVM Heap)
    participant Commit as Метод 6 (put_if_absent_commit)

    %% ВХОД МЕТОДА
    Reg->>Sub: Вызов compileAnalyticalMetrics(twin_id, current_tick, packet)
    activate Sub
    Note over Sub: Вход метода: twin_id, текущий такт и сырой пакет данных из 4-х источников
    
    %% ВНУТРЕННИЕ МАТЕМАТИЧЕСКИЕ РАСЧЕТЫ
    alt Ситуация 1: Данные снапшота еды существуют
        Sub->>Math: delta_t = current_tick - last_tick_updated
    else Ситуация 2: Первый запуск (Снапшота еды нет в базе)
        Sub->>Math: Принудительный дефолт: delta_t = 12 часов
    end
    activate Math
    Math-->>Sub: Результат: Количество часов без еды
    deactivate Math
    
    Sub->>Math: Нормирование: hunger_x0 = delta_t / 24.0
    activate Math
    Math-->>Sub: Скаляр голода в диапазоне от 0.0 до 1.0
    deactivate Math

    alt Карта личных весов K пуста
        Sub->>Sub: Заполнение дефолтами (Все категории = 1.0000)
    end

    Note over Sub: Сборка всех параметров в иммутабельный TwinContext
    Note over Sub: Выход метода: Полный готовый объект TwinContext (Вектор X)

    %% ПЕРЕДАЧА УПРАВЛЕНИЯ СЛЕДУЮЩЕМУ МЕТОДУ
    Sub->>Commit: Вызов putIfAbsentCommit(twin_id, twinContext)
    activate Commit
    Note over Commit: Управление передано в Метод 6 (Засев оперативной памяти)
    deactivate Commit
    
    deactivate Sub

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

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

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

Данные передаются между внутренними методами класса внутри оперативной памяти сервера.

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

{
  "twin_id": "d3b07384-d113-4956-bf8a-e421cd7bf777",
  "current_tick": 105,
  "packet_data": {
    "db_snapshot": {
      "hunger_x0": 0.1000,
      "last_tick_updated": 81
    },
    "db_profile": {
      "chronotype": "DAILY_LUNCH",
      "laziness_coefficient": 0.8500
    },
    "db_weights": {
      "FRUITS": 1.4500,
      "DAIRY": 0.9000
    }
  }
}

4.2. Структура скомплектованного контекста пользователя (Выходные параметры для Метода 6)

{
  "twin_id": "d3b07384-d113-4956-bf8a-e421cd7bf777",
  "current_tick": 105,
  "compiled_metrics": {
    "hunger_x0": 1.0000,
    "laziness_coefficient": 0.8500
  },
  "preference_vector_k": {
    "FRUITS": 1.4500,
    "DAIRY": 0.9000,
    "READY_MEALS": 1.0000,
    "GROCERIES": 1.0000
  }
}

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

Заголовок: Реализация метода аналитической свертки параметров compile_analytical_metrics и нормирования голода

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

Написать приватный метод compileAnalyticalMetrics внутри существующего класса TickRegistryImpl.
Извлечь lastTickUpdated из снапшота. Реализовать логику ветвления: если объект снапшота равен null, выставить дефолтную дельту времени в 12 часов.
Рассчитать скаляр голода по формуле deltaTicks / 24.0000. Применить защитное ограничение диапазона с помощью Math.min(1.0, Math.max(0.0, value)), чтобы гарантировать попадание в интервал от 0.0 до 1.0.
Инициализировать базовую карту весов со значениями 1.0000 для всех четырех категорий (DAIRY, FRUITS, READY_MEALS, GROCERIES). Наложить на неё сверху те веса, которые пришли из базы данных, через метод .putAll().
Собрать все обработанные параметры в иммутабельный объект Java Record TwinContext и вернуть его для последующего сохранения в оперативной памяти.

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

Заголовок: Наложение проверочного ограничения CHECK на колонку голода в таблице снапшотов

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

Чтобы данные внутри базы данных симулятора PostgreSQL гарантированно соответствовали математическому правилу нормирования, необходимо наложить проверочный констреинт на таблицу историй. Это защитит систему от случайной записи некорректных дробных значений (меньше нуля или больше единицы).

ALTER TABLE simulation.twin_state_snapshots 
ADD CONSTRAINT chk_hunger_x0_range 
CHECK (hunger_x0 >= 0.0000 AND hunger_x0 <= 1.0000);