StockPilot AI

Hackathon-ready веб-продукт для кейса «Автоматический расчёт заказов поставщикам для пополнения склада» компании «Электрокомплект».

Hackathon team repository for Miras and Dastan.

Что решает

StockPilot AI превращает историю продаж, остатки, товар в пути и условия поставщиков в объяснимые рекомендации по пополнению. Разовые крупные продажи выявляются как выбросы и не раздувают регулярный прогноз.

Главное

• Детерминированные TypeScript-расчёты: IQR + modified Z-score, взвешенное скользящее среднее, safety stock, reorder point, MOQ и pack size.
• Воспроизводимый демонабор: 32 SKU, до 36 недель истории, поставщики, товары в пути и кейс CAB-NYM-3X2.5 с продажей 176 шт. У SOCKET-FLOOR 8 недель; у SURGE-3P нет поставщика.
• Семь рабочих разделов: «Обзор», «Рекомендации», «ИИ-агент», «Проверка на истории», «Сценарии», «Черновики заказов», «Данные». Раздел отражается в URL; набор данных, поиск и параметры сохраняются при переходах.
• Полная таблица с поиском, фильтрами, сортировкой, пагинацией и выбором допустимых строк. Карточка товара показывает график исходных/очищенных продаж и объяснение количества.
• Импорт продаж .xlsx, .xls, UTF-8 .csv: файл → колонки → проверка → подтверждение. Предпросмотр таблицей, реальные счётчики ошибок и явное подтверждение исключения некорректных строк.
• Черновик из выбранных допустимых позиций с группировкой по поставщику, безопасным CSV и копированием текста письма. Изменение расчёта требует пересмотра черновика; заказ автоматически не отправляется.
• Историческое сравнение обычного среднего и основного прогноза StockPilot через существующий модуль stockpilot-backtest.
• Demo Mode работает без API key. С настроенными ключом и моделью «ИИ-агент» использует OpenAI Responses API с function calling: выбирает серверные инструменты для сводки, объяснения SKU, плана и сценария. Количества вычисляет детерминированный движок, не модель. В карточке товара также сохранено AI-объяснение.

Архитектура

React UI → /api/agent + /api/agent/stream → OpenAI Responses API → разрешённые tools → deterministic analytics in lib/analytics.

LLM не видит исходный Excel и не производит количественные расчёты. Внешнему API передаются вопрос и результаты инструментов; нормализованный набор для расчёта хранится в памяти сервера в изолированной сессии. API key остаётся на сервере; store: false включён.

Запуск

В корне используется существующий pnpm-lock.yaml:

pnpm install --frozen-lockfile
pnpm dev

Для необязательного AI-объяснения скопируйте .env.example в .env.local и задайте ключ. Без ключа демонстрация и расчёты работают полностью. Не добавляйте .env.local в git.

Проверки:

pnpm run typecheck
pnpm run lint
pnpm test
pnpm run build

Переменные окружения

• OPENAI_API_KEY — необязательный ключ. При его отсутствии включается Demo Mode.
• OPENAI_MODEL — имя доступной text-модели (для агента обязательно вместе с ключом).

Режим объяснения не меняет источник данных: интерфейс отдельно обозначает демонабор или импортированный файл. При ошибке внешнего сервиса показывается ошибка; расчётное объяснение остаётся доступно.

Формулы и ограничения

• Выбросы: IQR и modified Z-score. Они заменяются средней регулярной продажей в cleaned series.
• Прогноз: weighted moving average по последним 8 неделям.
• Safety stock: z × σ спроса × √lead time.
• Reorder point: спрос на lead time + safety stock.
• Рекомендация: target stock − stock position, после чего применяется MOQ и кратность упаковки.

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

Сценарий демонстрации

1. Нажмите «Открыть демо». В «Обзоре» показаны вычисленные приоритеты и первые рабочие строки.
2. В «Рекомендациях» найдите CAB-NYM-3X2.5 и нажмите название товара. В базовом сценарии рекомендовано 50 шт.; разовая продажа 176 шт. отмечена на графике. Покажите цепочку от целевого запаса и позиции до итогового количества.
3. Закройте карточку. В «Сценариях» установите «Дополнительная задержка, дней» = 7, нажмите «Применить сценарий». Рекомендация для кабеля становится 70 шт., исходные продажи не меняются.
4. Вернитесь в «Рекомендации», выберите checkbox только у CAB-NYM-3X2.5 и нажмите «Создать черновик». В «Черновиках заказов» проверьте единственную выбранную позицию, поставщика, количество и сумму.
5. Нажмите «Скачать CSV» либо скопируйте текст письма. Это подготовка к согласованию, не отправка заказа.
6. Измените задержку на 14 дней и примените сценарий. Прежний черновик помечается как требующий пересмотра; экспорт заблокирован до действия «Пересобрать по текущему расчёту». Его состав не подменяется незаметно.
7. Откройте «Проверка на истории», выберите товар, проверьте период, начальный запас и условия, затем нажмите «Запустить сравнение». Покажите линии запаса, проигрывание по неделям и фактические итоги обеих стратегий.

50/70 шт. — результаты закреплённого демонабора и сценариев, а не числа, встроенные в UI.

Импорт и хранение данных

Импорт открывается с начального экрана («Импортировать Excel / CSV») и из «Данных» («Импортировать данные»). Используется первый лист; заголовки должны быть в первой строке. Обязательны дата, SKU и количество; без названия отображается SKU.

Поддерживаются даты ГГГГ-ММ-ДД, ДД.ММ.ГГГГ и числовые даты Excel. Невозможная дата, пустое количество или отрицательное значение не принимаются. Явный 0 допускается. CSV должен быть UTF-8 с BOM или без него. Ограничение — 10 МБ и 100 000 строк.

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

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

Тестовый файл: tests/fixtures/sales-import.csv. В нём 9 строк: 8 корректных недель и 1 ошибочная дата. Ожидаемая проверка — 8 принятых и 1 отклонённая строка.

Данные и один активный черновик находятся в памяти вкладки. Перезагрузка очищает их. При открытии ИИ-агента набор передаётся в серверную сессию в памяти с ограниченным временем жизни. Постоянное серверное сохранение, автоматический localStorage, отправка писем и ERP-интеграция не реализованы.

Что проверяется на истории

В основном приложении createStockPilotStrategy использует настоящие detectOutliers, weightedForecast, stdDev, mean из lib/analytics.ts. Стратегии называются «Обычное среднее» и «StockPilot · основной прогноз». Они получают только завершённую историю до недели решения и используют общую политику пополнения.

Это сравнение прогнозов при одинаковых правилах закупки, а не проверка всей системы с бюджетным отбором и выбором поставщика. Начальный запас — допущение эксперимента; коммерческие условия — текущие допущения, а не восстановленные исторические договоры. Параметры раздела «Сценарии» не переносятся в отдельный исторический эксперимент.

Если цена неизвестна, стоимости не вычисляются. Итоги всего периода отделены от текущей недели проигрывания, изменение доли обслуживания выражается в процентных пунктах. Скрытый спрос при историческом отсутствии товара неизвестен: продажи используются как его приближение.

Независимый модуль сохраняет собственный запуск и существующий package-lock.json:

cd stockpilot-backtest
npm ci
npm run dev

Там доступны шесть отдельных демонаборов и встроенная демонстрационная стратегия; основной прогноз подключается через публичные интерфейсы. Источники имеют отдельные метки. Подробнее: INTEGRATION.md.

Проверки из директории модуля:

npm run typecheck
npm run lint
npm test
npm run build

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

Редизайн сохраняет генератор демоданных и ядро симуляции. Интеграция агента дополнительно запрещает закупку при неизвестных остатках и трактует явный бюджет 0 как отсутствие бюджета, а не безлимит. Полный результат трёх фиксированных сценариев сравнивается с исходным коммитом 09ff771 в регрессионных тестах.

Существующие ограничения также сохранены: очистка может не найти всплеск в плоском ряду с нулевыми IQR/MAD, а некоторые комбинации MOQ и упаковки дают несовместимое количество. Интерфейс блокирует оформление количества, не соответствующего условиям; исправление модели должно быть отдельной задачей.

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

Подробности проверок: REDESIGN_VERIFICATION.md.

Проверка реального ИИ

1. Настройте .env.local: OPENAI_API_KEY и OPENAI_MODEL (например, gpt-4.1-mini). Перезапустите сервер.
2. Откройте демо → «ИИ-агент» → «Что требует внимания?».
3. Дождитесь ответа и метки OpenAI · <модель>. В журнале видны фактически вызванные инструменты. Без настройки отображается локальный тестовый режим.

Данные агентной сессии не переживают перезапуск сервера. NVIDIA-review пока недоступен без подключения отдельного адаптера; агент честно сообщает об этом. Agent drafts пока не связаны с экспортом UI: для CSV используйте «Рекомендации» → «Черновики заказов». Подробнее: OPENAI_INTEGRATION.md.