Подробное описание скриптов приложения ibp¶

В этом разделе приведены подробные описания ключевых скриптов приложения ibp: назначение, логика работы, параметры и бизнес-сценарии использования.

Актуальная версия расчёта плана поставок (supply2.py)¶

Общая архитектура¶

Расчёт плана поставок в ibp реализован в модуле supply2.py (старая версия — supply.py — больше не используется). Новый модуль поддерживает: - Многоуровневое планирование поставок по всей цепочке (от поставщика до склада/клиента) - Учёт альтернативных маршрутов (альтернативные процессы) - Интеграцию с параметрами остатков, транзита, корректировок - Расчёт целевых запасов (страховых и регулярных) через модуль stock_target.py - Учёт ограничений транспорта (лот, машина), вместимости складов - Параллельную обработку логистических плеч - Гибкую настройку горизонта и частоты планирования (день/неделя)

Ключевые функции¶

calc_plan — основной алгоритм расчёта плана поставок для заданного горизонта, набора товаров, локаций и процессов.
calc_plan_main — обёртка с декоратором @pq_script, используется для запуска из интерфейса/скриптов.
Вспомогательные функции: подготовка календаря поставок, обработка альтернативных маршрутов, логирование ошибок, очистка параметров плана.

Основные параметры и входные данные¶

req_df — DataFrame с потребностями (требованиями) по товарам и локациям
proc_df — DataFrame с маршрутами/процессами (логистические цепочки)
target_stock_params_df — параметры целевых запасов (уровень сервиса, ошибка прогноза и др.)
vehicle_params_df — параметры транспорта (типы машин, вместимость)
supply_calendar — календарь допустимых дней поставки (для дневного горизонта)
data_freq — частота планирования (daily/weekly)
periods_num — количество периодов для расчёта
Флаги: use_lots, use_vehicles, use_stock_prebuild, calc_stock_target и др.

Ключевые этапы расчёта¶

Подготовка данных: загрузка потребностей, остатков, транзита, корректировок, маршрутов, параметров транспорта и запасов.
Расчёт целевых запасов: автоматический вызов calc_target_stock из stock_target.py для расчёта страховых и регулярных запасов.
Планирование по основным и альтернативным маршрутам: последовательный расчёт плана с учётом приоритетов маршрутов.
Учёт ограничений: лоты, транспорт, вместимость складов, календарь поставок.
Параллельная обработка: для ускорения расчёта по разным логистическим плечам.
Сохранение результатов: запись плана, остатков, транзита и других параметров в соответствующие сущности (supply2__plan_*, supply2__stock_plan_open_* и др.).

Пример запуска (из интерфейса или скрипта)¶

from planiqum.apps.ibp.scripts.supply2 import calc_plan_main
calc_plan_main(periods_num=8, data_freq="weekly", filter_={...})

Бизнес-сценарии использования¶

Автоматизация расчёта плана поставок по всей цепочке (от поставщика до склада/клиента)
Учёт ограничений транспорта, лотов, складских остатков
Интеграция с расчётом целевых запасов (страховых и регулярных)
Поддержка сценариев S&OP, supply planning, demand planning

Важно¶

Для всех новых расчётов и параметров используется префикс supply2__*
Модуль supply.py считается устаревшим и не должен использоваться в новых сценариях
Для расчёта целевых запасов используется только stock_target.py

Агрегация данных¶

aggregate_data¶

Агрегирует данные из одного параметра в другой с учётом измерений и мер. Поддерживает функции агрегации (sum, max, min, avg, count).

Параметры:
from_param — исходный параметр
to_param — целевой параметр
agg_func — функция агрегации
filter — фильтр по данным
revision — ревизия для отслеживания изменений
Логика:
Определяет общие и отличающиеся измерения между параметрами.
Строит SQL-запрос с нужными join и группировками.
Выполняет агрегацию по совпадающим мерам.
Сохраняет результат в целевой параметр, при необходимости фиксирует изменения в таблице ревизий.
Бизнес-сценарии:
Перенос агрегированных данных между уровнями иерархий (например, из SKU в категорию).
Суммирование, усреднение или подсчёт значений по выбранным измерениям.

aggregate_data¶

Агрегирует данные между параметрами по совпадающим именам мер.

Параметры:
from_param, to_param, dim_pairs, filter, revision, agg_func
Логика:
Находит соответствия между мерами исходного и целевого параметра по именам.
Определяет общие и агрегируемые измерения.
Выполняет агрегацию по заданной функции.
Сохраняет результат в целевой параметр с отслеживанием изменений.

disaggregate_data¶

Дизагрегирует данные с одного параметра на другой с использованием весов или коэффициентов.

Параметры:
from_param, to_param, param_ratios, filter_from_param, filter_to_param, dim_pairs, static_dims, revision, measures
Логика:
Определяет, как распределить значения исходного параметра по целевому.
Использует веса или коэффициенты для пропорционального распределения.
Сохраняет результат в целевой параметр.

Построение прогноза¶

build_forecast¶

Строит статистический прогноз временных рядов по историческим данным.

Параметры:
param_hist — параметр с историческими данными
param_fcst — параметр для записи прогноза
min_periods_for_fcst, fcst_periods, use_testing, test_periods, models, err_func_key, filter_, revision и др.
Логика:
Выбирает и обучает статистические модели (например, Exponential Smoothing, ARIMA).
Оценивает качество моделей на тестовой выборке (MAE, MAPE и др.).
Выбирает лучшую модель по заданной метрике ошибки.
Строит прогноз на заданный горизонт и сохраняет результат.
Бизнес-сценарии:
Автоматизация построения прогноза спроса/продаж.
Сравнение различных моделей прогнозирования.

build_forecast_full¶

Расширенная версия построения прогноза с поддержкой различных частот данных, тестирования, обработки отрицательных значений и др.

Параметры:
data_type, data_freq, min_periods_for_fcst, fcst_periods, test_periods, models, err_func_key, filter_, revision и др.
Логика:
Позволяет гибко настраивать параметры прогноза.
Поддерживает обработку сезонности, тестирование на разных горизонтах, автоматический выбор модели.

Расчёт целевых и страховых запасов (stock_target.py)¶

Общая архитектура¶

Расчёт целевых запасов (страховых и регулярных) реализован в модуле stock_target.py (старая версия — stock.py — больше не используется). Новый модуль поддерживает: - Расчёт страхового запаса (safety stock) с учётом статистических параметров: ошибка прогноза, уровень сервиса, отклонения lead time - Расчёт регулярного запаса (regular stock) по среднесуточной потребности и нормативу дней - Гибкую логику расчёта: можно получить максимум, сумму или отдельные типы запасов - Учёт ограничений по вместимости склада (product-location capacity) - Интеграцию с расчётом плана поставок (вызывается из supply2.py)

Ключевые функции¶

calc_target_stock — основной алгоритм расчёта целевых запасов (страховой, регулярный, max, sum)
calc_stock_level — расчёт конкретного типа запаса (safety_stock или regular_stock)
prepare_target_stock — подготовка и ограничение целевых запасов по вместимости склада

Основные параметры и входные данные¶

req_df — DataFrame с потребностями (требованиями) по товарам и локациям
proc_df — DataFrame с маршрутами/процессами (логистические цепочки, для lead time)
target_stock_params_df — параметры целевых запасов (уровень сервиса, ошибка прогноза, норматив дней)
data_freq — частота расчёта (daily/weekly)
periods_for_daily_stock_basis — окно для усреднения потребности
target_stock_logic — тип расчёта: safety_stock, regular_stock, max, sum
req_err, service_level, reg_stock_in_days — параметры по умолчанию

Ключевые этапы расчёта¶

Расчёт среднесуточной потребности: усреднение потребности за заданное окно (rolling window)
Расчёт страхового запаса: статистическая формула с учётом ошибки прогноза, уровня сервиса, отклонения lead time
Расчёт регулярного запаса: среднесуточная потребность × норматив дней
Ограничение по вместимости склада: если включено, запас не превышает максимальную вместимость product-location
Сохранение результатов: запись в параметры типа supply2__stock_target_*, supply2__unconstrained_stock_target_*

Пример запуска (из кода или через supply2.py)¶

from planiqum.apps.ibp.scripts.stock_target import calc_target_stock
calc_target_stock(req_df, filter_req, proc_df, target_stock_params_df, data_freq="weekly")

Бизнес-сценарии использования¶

Автоматизация расчёта страхового запаса для снижения out-of-stock и избыточных запасов
Учёт вариабельности спроса, lead time, уровня сервиса
Интеграция с расчётом supply plan (вызывается автоматически из supply2.py)
Поддержка сценариев S&OP, supply planning

Важно¶

Для всех новых расчётов и параметров используется префикс supply2__*
Модуль stock.py считается устаревшим и не должен использоваться
Все расчёты страховых запасов должны выполняться только через stock_target.py

Интеграция данных¶

Подробная информация о CSV-интерфейсах, функциях импорта, универсальном скрипте import_master_data и best practices вынесена в отдельный раздел: Интеграция ibp