calculate_intents_density()

Домен: SIMULATION | Контур: Оценка плотности желаний пользователя

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

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

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

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

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

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

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

Математика шага учитывает три фактора:

  1. Физиология (Голод): Чем сильнее пользователь голоден (показатель \(x_0 \rightarrow 1.0\)), тем сильнее искусственно раздувается его желание пойти в магазин за покупками (BUY).
  2. Характер (Лень): Если пользователь от природы ленив, его базовое желание готовить (COOK) жестко штрафуется и падает практически до нуля.
  3. Физическое ограничение (Холодильник): Симулятор проверяет список продуктов, полученный из приложения. Если холодильник на бэкенде пуст, пользователь физически не может готовить (COOK), есть (CONSUME) или выбрасывать испорченное (WASTE). Эти три желания принудительно обнуляются, оставляя пользователю единственный выход — идти в магазин.

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

  1. Загрузка базовых шансов: Метод извлекает из памяти зашитые в настройки базовые веса сценариев розничной сети.
  2. Личное перемножение: Каждое базовое значение перемножается на личный коэффициент предпочтения (\(K\)) пользователя для соответствующей категории продуктов.
  3. Накачка голодом: Желание сценария Покупки (BUY) умножается на величину \((1 + hunger\_x_0)\), увеличивая приоритет закупа при истощении.
  4. Штраф за лень: Желание сценария Готовки (COOK) умножается на инвертированный коэффициент лени: \((1 - laziness\_coefficient)\).
  5. Проверка холодильника: Если массив продуктов из приложения пуст, показатели желаний для Готовки, Потребления и Выброса принудительно выставляются в 0.0000.
  6. Передача на нормализацию: Сформированный вектор сырых плотностей желаний передается следующему методу (Метод 8) для перевода в проценты.

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

Диаграмма наглядно показывает, как метод принимает утвержденный кэшем контекст пользователя, подтягивает константные веса Алматы из файла ресурсов и выдает скорректированную карту желаний.

sequenceDiagram
    autonumber
    participant Core as Метод 3 (CoreSimulationEngine)
    participant Gen as StochasticGeneratorImpl
    participant Res as Ресурсы (regional_weights_almaty.json)
    participant Math as Математический Процессор (RAM Heap)
    participant M8 as Метод 8 (logistic_normalization)

    %% ВХОД МЕТОДА
    Core->>Gen: Вызов projectStochasticSeed(TwinContext)
    activate Gen
    Note over Gen: Вход метода: Утвержденный TwinContext (Голод, Лень, Продукты, Веса K)
    
    alt Если константы Алматы еще не загружены в RAM
        Gen->>Res: Чтение конфигурационного JSON из ресурсов JAR
        Res-->>Gen: Данные: Базовые шансы розницы Алматы (W_base)
    end

    %% МАТЕМАТИЧЕСКАЯ КОРРЕКЦИЯ
    Gen->>Math: Перенос параметров: W_base * K_user
    activate Math
    Note over Math: Коррекция BUY: умножение на (1 + голод)<br/>Коррекция COOK: умножение на (1 - лень)
    
    alt Ситуация: Список продуктов из приложения пуст
        Note over Math: Принудительное обнуление параметров:<br/>COOK = 0.0, CONSUME = 0.0, WASTE = 0.0
    end
    
    Math-->>Gen: Возврат: Карта сырых плотностей желаний
    deactivate Math

    Note over Gen: Выход метода: Сформированная карта плотностей (Map)

    %% ПЕРЕДАЧА УПРАВЛЕНИЯ СЛЕДУЮЩЕМУ МЕТОДУ
    Gen->>M8: Вызов logisticNormalization(rawDensities)
    activate M8
    Note over M8: Управление передано в Метод 8 (Выравнивание шансов через Softmax)
    deactivate M8
    
    deactivate Gen

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

Этот метод является чистым математическим калькулятором внутри оперативной памяти и напрямую к PostgreSQL запросы не отправляет — все данные (веса \(K\), продукты) уже извлечены из баз методами Части 2 и находятся внутри переданного объекта TwinContext.

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

Метод оперирует статическим конфигурационным файлом, зашитым внутрь сборки симулятора.

4.1. Константная матрица Алматы (Файл src/main/resources/regional_weights_almaty.json)

Файл отражает базовую структуру поведения усредненного жителя Алматы:

{
  "region": "Almaty_Retail_Network",
  "base_scenario_weights": {
    "SCENARIO_B2B_BUY_RECEIPT": 0.3500,
    "SCENARIO_COOKING_MEAL": 0.2500,
    "SCENARIO_CONSUMING_FOOD": 0.3000,
    "SCENARIO_WASTE_DISPOSAL": 0.1000
  }
}

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

{
  "twin_id": "d3b07384-d113-4956-bf8a-e421cd7bf777",
  "hunger_x0": 1.0000,
  "laziness_coefficient": 0.8500,
  "preference_vector_k": {
    "FRUITS": 1.4500,
    "DAIRY": 0.9000,
    "READY_MEALS": 1.1000,
    "GROCERIES": 1.0000
  },
  "raw_fridge_snapshot_is_empty": true
}

4.3. Выходной вектор сырых плотностей (Выходные параметры для Метода 8)

{
  "raw_intents_density": {
    "SCENARIO_B2B_BUY_RECEIPT": 1.0150,
    "SCENARIO_COOKING_MEAL": 0.0000,
    "SCENARIO_CONSUMING_FOOD": 0.0000,
    "SCENARIO_WASTE_DISPOSAL": 0.0000
  }
}

Пояснение расчета: Покупка = 0.35 (базовый) 1.45 (K) * (1 + 1.0 голод) = 1.015. Готовка обнулена из-за пустого холодильника, несмотря на то, что расчет с учетом лени дал бы 0.0375.*

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

Заголовок: Реализация математического контура перемножения матриц и штрафования интентов calculate_intents_density

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

  1. Создать Java-класс StochasticGeneratorImpl в пакете simulation.engine.generator, реализовав интерфейс StochasticGenerator. Пометить аннотацией @Service.
  2. Внутри метода @PostConstruct реализовать чтение статического файла regional_weights_almaty.json из ресурсов classpath и распарсить его в карту Map<ScenarioEnum, Double> baseWeights.
  3. Написать метод calculateIntentsDensity, принимающий TwinContext.
  4. Реализовать формулы перемножения базовых весов на личные веса \(K\) твина: для покупки брать категорию FRUITS, для готовки — GROCERIES, для еды — READY_MEALS.
  5. Применить модификаторы: умножить покупку на (1.0 + context.hungerX0()), умножить готовку на (1.0 - context.lazinessCoefficient()).
  6. Добавить жесткую инспекцию холодильника: если список продуктов пуст или равен null, принудительно перезаписать значения для готовки, еды и выброса в 0.0000. Передать полученную карту плотностей на шаг нормализации.

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

Заголовок: Поставка статического конфигурационного файла regional_weights_almaty.json в ресурсы сборки

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

Поскольку базовая региональная матрица Алматы является неизменяемой константой модели поведения, она поставляется как кодовый ресурс приложения (Code Asset). Задача миграции контура настроек — создать и закомитить файл regional_weights_almaty.json в папку src/main/resources/ со строго валидной структурой JSON-схемы розничной сети.