ProcureAI — автоматический расчёт заказов поставщикам

ProcureAI готовит проверяемую рекомендацию по пополнению склада для менеджера отдела закупа.

Проблема

Менеджер отдела закупа считает потребность вручную в Excel. Расчёт трудоёмкий, поэтому выполняется редко. Две системные ошибки искажают результат:

• разовая крупная продажа одному клиенту завышает регулярный спрос и ведёт к избыточному запасу;
• период отсутствия товара занижает наблюдаемые продажи, и система повторно заказывает мало — дефицит воспроизводится.

Решение

Предусмотрен следующий процесс:

1. загрузить историю продаж, остатки и признаки отсутствия товара;
2. отделить регулярный спрос от разовых крупных заказов;
3. восстановить спрос за подтверждённые периоды отсутствия;
4. оценить тренд и сезонность;
5. рассчитать потребность на горизонт пополнения;
6. вычесть остаток и подходящие товары в пути;
7. сгруппировать рекомендации по поставщикам;
8. показать факты и обоснование менеджеру;
9. передать решение об утверждении человеку.

Репозиторий содержит воспроизводимый синтетический набор, детерминированный расчёт рекомендации и интерфейс для проверки результата менеджером. Система рекомендует количество, но не утверждает заказ вместо менеджера.

Быстрый старт

Требуется Python 3.12.

Команды, которые работают в текущем состоянии репозитория:

pip install -r requirements.txt
python -m procure.run              # расчёт по поставщикам
python -m streamlit run app.py     # интерфейс
python -m pytest                   # тесты

После установки зависимостей расчёт и тесты не требуют интернета. Загрузка пакетов командой pip install может требовать интернет или локальный кэш пакетов.

Данные

Все текущие входные данные синтетические. Клиенты обезличены идентификаторами вида CUST-XXX; персональных данных в наборе нет. Использование синтетики прямо разрешено техническим заданием для демонстрации метода.

Файл	Колонки	Тип	Смысл
data/sales.csv	date, sku, qty, price, customer_id, warehouse	CSV, месячные строки по клиентам	История продаж пяти SKU за 24 месяца
data/stock.csv	sku, name, supplier, lead_time_days, stock, in_transit, pack_size	CSV, одна строка на SKU	Текущий товарный справочник, остаток и параметры поставки
data/stockout.csv	sku, month, is_stockout	CSV, одна строка на SKU и месяц	Явный признак отсутствия товара в конкретном месяце

Период истории: с октября 2024 года по сентябрь 2026 года включительно. Склад один: WH-01. Генератор использует фиксированный seed 20260920; два запуска создают байт-в-байт одинаковые файлы.

Демонстрационные SKU:

SKU	Имя	Поставщик	Что заложено в данные
A-100	STABLE	SUP-01	Стабильные продажи от 90 до 110 единиц в месяц
A-200	SEASONAL	SUP-01	50–70 единиц обычно и 130–160 в ноябре–январе; профиль повторяется по годам
A-300	GROWTH	SUP-02	Плавный рост 40→65 в первый год и 65→100 во второй, без одиночного скачка
A-400	STOCKOUT	SUP-02	Около 90 единиц обычно; 10–20 в апреле и мае 2026 года, оба месяца отмечены как stockout
A-500	OUTLIER	SUP-03	Регулярные 40–55 единиц и одна дополнительная продажа 500 единиц клиенту CUST-017 в марте 2026 года

В каждом месяце регулярный объём распределён между несколькими клиентами, поэтому выброс A-500 виден как событие одного клиента, а не как общий рост спроса.

Методология расчёта

Порядок вычислений

Целевой порядок вычислений:

1. исходные данные;
2. валидация;
3. исключение выбросов;
4. маскирование stockout;
5. тренд;
6. сезонность;
7. восстановление спроса;
8. потребность на горизонт;
9. вычет остатка и товаров в пути;
10. округление до упаковки;
11. срочность;
12. обоснование.

Этот основной pipeline в разработке. Сейчас код выполняет только генерацию и отдельный наивный baseline без очистки.

Порядок важен по двум причинам: выбросы должны удаляться до оценки тренда, иначе одиночная продажа создаст ложный рост; stockout должен маскироваться до расчёта сезонности, иначе низкие продажи занизят коэффициент соответствующего месяца.

1. Базовый спрос

Основной устойчивый показатель базового спроса в разработке. Окно, минимальное число наблюдений и выбор между средним и медианой ещё не реализованы; до появления кода README не фиксирует эти параметры.

Реализован только наивный показатель для контрольного сравнения. Код сначала суммирует все клиентские строки по SKU и месяцу, затем берёт среднее месячных сумм по всем 24 месяцам:

naive_monthly_demand = mean(sum(qty) по каждому месяцу за 24 месяца)

Наивный показатель намеренно не очищает выбросы и не исправляет stockout. Он моделирует простой ручной расчёт и служит точкой сравнения, а не итоговой рекомендацией.

2. Исключение разовых крупных заказов

Алгоритм исключения разовых крупных заказов в разработке. Числовые пороги в коде отсутствуют и здесь не задаются. Критерий, окно сравнения и минимальное число наблюдений ещё должны быть реализованы и проверены тестами.

Планируемые признаки для проверки:

• размер клиентской продажи относительно обычного уровня SKU;
• единичность события для конкретного клиента;
• повторяемость сопоставимых заказов того же клиента;
• наличие аналогичного сезонного пика в другом году;
• согласованность роста между несколькими последовательными периодами.

Метод 3σ не принят и не реализован. На истории из 24 месячных точек одна крупная величина одновременно повышает среднее и стандартное отклонение, поэтому порог может стать практически недостижимым. Перед выбором другого критерия нужны измеримые тесты на синтетике и затем калибровка на разрешённых реальных данных.

Полное или частичное исключение объёма в разработке. Код пока не удаляет и не корректирует ни одну продажу. Исходное событие должно сохраняться для аудита независимо от будущего правила очистки.

Начало устойчивого роста нельзя определять по одной крупной продаже. Оно должно подтверждаться несколькими последовательными периодами и несколькими клиентами. Конкретное окно и доля подтверждающих периодов в разработке.

Главный риск ложноположительного решения — принять реальный новый регулярный заказ за разовый. Ограничители этого риска в разработке. До их реализации результат по A-500 существует только в наивном baseline и остаётся завышенным.

3. Восстановление спроса за периоды отсутствия

Восстановление спроса в разработке. Сейчас период отсутствия определяется только входным флагом is_stockout в data/stockout.csv. Для A-400 отмечены ровно два месяца: 2026-04 и 2026-05.

Замена наблюдаемого значения пока не реализована. Она не должна подставлять ноль, потому что низкая продажа при отсутствии товара не доказывает низкий спрос. Будущая оценка должна учитывать обычный уровень SKU и сезон месяца. Точная формула и минимальная история в разработке.

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

4. Сезонность

Сезонность рассчитывается на очищенном и восстановленном помесячном спросе. Требуются минимум 24 месяца истории; при более короткой истории для всех месяцев используется season_factor = 1.0.

residual_m = restored_demand_m / trend_factor^(index_m / 12)
season_factor(month) = mean(residual_m for calendar month) / mean(month factors)

Из расчёта исключаются явно отмеченные stockout-месяцы. Для календарного месяца с менее чем двумя пригодными наблюдениями используется фактор 1.0; остальные факторы ограничиваются диапазоном 0.5–2.0.

ARIMA и Prophet не используются. В текущем проекте нет ML-библиотек. Приоритет отдан прозрачному разложению, потому что каждое изменение заказа должно иметь проверяемое объяснение.

5. Устойчивый рост

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

g_i = demand_i / demand_(i-12) - 1
support = count(g_i > 0)
trend_pct = 100 × clamp(median(g_i), 0, 0.30), if support >= 5; otherwise 0
trend_factor = 1 + trend_pct / 100

Один скачок не считается устойчивым ростом: без как минимум пяти положительных сравнений trend_pct = 0. Верхняя граница — 30%, а отрицательная медиана не уменьшает спрос этим этапом.

6. Формула заказа

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

planning_horizon_days = lead_time_days + 14
expected_daily = restored_demand × season_factor × trend_factor / 30
horizon_need = expected_daily × planning_horizon_days
raw = max(0, horizon_need - stock - in_transit)
recommended_qty = ceil(raw), then rounded up to pack_size

Страховой запас на P0 равен нулю. Остаток и товары в пути вычитаются из потребности; физический остаток не включает товары в пути. Для сравнения с очищенным расчётом naive_qty использует ту же формулу, но raw demand до исключения разовой аномалии.

Реализованный наивный baseline использует более узкую формулу:

naive_qty = max(
    0,
    naive_monthly_demand × lead_time_days / 30 - stock - in_transit
)

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

7. Срочность

Срочность использует только физический остаток и ожидаемый суточный спрос:

days_of_cover = stock / expected_daily

При нулевом или ненадёжном спросе статус — unknown. Иначе: high при покрытии меньше срока поставки; medium от срока поставки включительно до lead_time_days + 14; low при покрытии не меньше lead_time_days + 14.

Что на выходе

Текущий --naive печатает таблицу:

Колонка	Тип	Смысл
sku	строка	Идентификатор товара
naive_monthly_demand	число	Среднее месячных сумм без очистки
naive_qty	число	Количество по наивной формуле

Итоговая таблица рекомендаций в разработке. Контракт ItemFacts уже фиксирует поля спроса, сезонности, тренда, горизонта, остатка, товаров в пути, покрытия, выброса, количества, срочности и флагов.

Группировка строк по поставщикам, CSV-экспорт и XLSX-экспорт в разработке.

Целевой формат короткого детерминированного обоснования:

На горизонт нужно 200; в наличии 60; в пути к сроку 40; рекомендуем 100.

Это пример формата, а не результат текущего набора. Фактическое обоснование должно строиться из фактов конкретной строки; реализация в разработке.

Роль AI

Все числа рекомендации вычисляет детерминированный Python-код. Рабочий режим объяснений — детерминированный русский шаблон: он подставляет только рассчитанные факты и не меняет количество, поставщика или срочность.

Языковая модель не требуется для работы продукта и остаётся опциональным будущим дополнением. Сетевые вызовы для объяснений сейчас отсутствуют; шаблон работает без API-ключа и доступа к интернету.

Как проверить

pip install -r requirements.txt
python -m procure.run              # расчёт по поставщикам
python -m streamlit run app.py     # интерфейс
python -m pytest                   # 52 теста

На Windows тесты запускаются именно через python -m pytest, чтобы корень проекта оставался доступен для импорта пакета procure.

Сценарий	Что проверяет	Результат
Разовая продажа	исключение выброса	A-500: 124 → 49 шт (−60.5%)
Дефицит	восстановление спроса	A-400: 84.5 → 90.3 шт/мес
Сезон	коэффициент месяца прихода	A-200: пик 1.74–1.86
Рост	устойчивый тренд	A-300: коэффициент 1.30
Стабильный	очистка не меняет результат	A-100: 89 = 89
Изменение входа	пересчёт без правки кода	В пути 0→20: 49 → 29 шт
Без модели	числа идентичны	AI_MODE=off, 12 SKU

Ограничения подхода

• На реальной базе из 145 товаров минимальный остаток задан только у 10 (7%). Расчёт от порога покрывает малую часть ассортимента — это обоснование подхода от прогноза спроса.
• 70% товаров не имеют продаж за последний месяц. На таких позициях система возвращает «Нет данных», а не ноль.
• Сезонность требует 24 месяцев истории. На коротких рядах коэффициент равен 1.0: выдуманная сезонность хуже её отсутствия.
• Порог выброса median + 4×MAD откалиброван на синтетических данных и требует проверки на реальном ряде продаж.
• Открытые заказы засчитываются без проверки ожидаемой даты. Зависший заказ бессрочно уменьшает потребность. Будущее правило: засчитывать только заказы с ожидаемой датой не позже следующего пересмотра.
• Кратность упаковки применяется только при подтверждённой связи товар—поставщик.
• Цены в демонстрационных данных синтетические.
• Восстановленный спрос является оценкой, а не фактом; текущий набор содержит один склад и не моделирует межскладские перемещения.
• Наивный baseline нельзя использовать как итоговую закупочную рекомендацию; совместимость с 1С не проверялась.

Масштабирование

Текущие CSV и обработка pandas достаточны для маленького демонстрационного набора. При сотнях тысяч SKU и многолетней истории месячная агрегация и расчёт факторов должны выполняться инкрементально и кэшироваться по каждому SKU; сами правила расчёта при этом не меняются.

Для такого объёма следует инкрементально считать месячные агрегаты, пересчитывать только SKU с новыми данными или изменённой политикой и хранить версию входа вместе с параметрами метода. Можно кэшировать проверенные месячные агрегаты, признаки доступности, сезонные профили и результаты по неизменившимся SKU.

Разбиение по SKU и складу допускает параллельную обработку независимых групп. Экспорт и объяснения можно строить после числового расчёта отдельным этапом. Переход от CSV к колоночному формату или базе данных потребуется только после измерения объёма и времени.

Смысл текущего подхода сохраняется: сначала формируется проверяемый регулярный спрос, затем прогноз на явный горизонт, после чего из потребности вычитаются доступные запасы и подходящие поставки. Меняется способ хранения и выполнения, а не причинная структура расчёта.

Реализация масштабирования не входит в текущий этап.

Структура проекта

procure/
├── __init__.py          пакет ProcureAI
├── contracts.py         замороженные dataclass-контракты строк и объяснений
├── audit.py             аудит расчёта — в разработке
├── export.py            экспорт результата — в разработке
├── run.py               CLI генерации, baseline и заглушки pipeline
├── data/
│   ├── __init__.py      пакет работы с данными
│   ├── generate.py      детерминированный генератор трёх CSV
│   └── load.py          загрузка и валидация входа — в разработке
├── calc/
│   ├── __init__.py      пакет расчётов
│   ├── naive.py         реализованный наивный baseline
│   ├── outliers.py      исключение выбросов — в разработке
│   ├── stockout.py      маскирование stockout — в разработке
│   ├── trend.py         устойчивый тренд — в разработке
│   ├── season.py        сезонные коэффициенты — в разработке
│   ├── restore.py       восстановление спроса — в разработке
│   └── order.py         итоговая рекомендация — в разработке
└── ai/
    ├── __init__.py      пакет объяснений
    ├── template.py      шаблонный fallback — в разработке
    ├── prompt.py        безопасный промпт — в разработке
    ├── render.py        подстановка фактов — в разработке
    ├── validate.py      валидация ответа — в разработке
    └── explain.py       оркестрация объяснения — в разработке

data/
├── sales.csv            синтетическая история продаж
├── stock.csv            остатки и параметры пяти SKU
└── stockout.csv         месячные признаки отсутствия

tests/
├── test_contracts.py    неизменяемость контрактов
└── test_data.py         воспроизводимость набора и свойства fixture

requirements.txt         pandas, numpy, openpyxl и pytest
README.md                состояние, методология и ограничения проекта