StockPilot AI — автоматизация пополнения склада

1. О проекте

StockPilot AI — веб-приложение для менеджера отдела закупа ТОО «Электрокомплект».

Проект решает задачу автоматизации расчёта заказов поставщикам для пополнения склада. Вместо ручной консолидации нескольких Excel-выгрузок менеджер получает готовый список позиций к закупке с рекомендуемым количеством, срочностью и объяснением расчёта.

Система предназначена для поддержки решения закупщика, а не для полностью автономной закупки: итоговое количество можно скорректировать вручную, после чего менеджер подтверждает план и экспортирует его в CSV. Автоматической отправки заказа поставщику в проекте нет.

---

2. Что реализовано

В текущей версии проекта реализованы

• расчёт рекомендаций по пополнению на уровне SKU;
• учёт истории продаж по месяцам;
• календарная сезонность;
• оценка устойчивого изменения спроса;
• робастное ограничение аномальных месячных всплесков;
• исключение отмеченных разовых крупных продаж из регулярного спроса;
• корректировка спроса при переданных периодах stockout;
• учёт текущего остатка;
• учёт товара в пути;
• страховой буфер;
• MOQ / кратность заказа в текущей модели;
• приоритизация рекомендаций по срочности;
• группировка результата по поставщикам;
• фильтры по поставщику, категории и срочности;
• поиск по SKU, артикулу поставщика и наименованию;
• подробное объяснение выбранной позиции;
• сценарий «Что если?» с изменением:
  • горизонта расчёта;
  • спроса;
  • остатка;
  • товара в пути;
  • числа stockout-дней;
• загрузка stockout-периодов из CSV;
• ручная корректировка количества к заказу прямо в таблице;
• подтверждение плана менеджером;
• экспорт чернового или подтверждённого плана в CSV;
• AI-агент для сводки плана, объяснения SKU, анализа аномалий, проверки качества данных и сравнения сценариев;
• локальный demo-режим AI-агента без API-ключа;
• публичный health-check endpoint;
• Docker-конфигурация и конфигурация Railway для развёртывания.

---

3. Как работает решение

Основной пользовательский сценарий:

1. Приложение загружает подготовленный локальный каталог, построенный из предоставленных выгрузок поставщиков.
2. Расчётный модуль анализирует историю спроса по SKU.
3. Из регулярного спроса удаляются отмеченные разовые операции и ограничиваются экстремальные месячные пики.
4. При наличии stockout-периодов спрос корректируется вверх.
5. Для горизонта планирования рассчитывается прогноз с сезонностью и трендом.
6. К прогнозу добавляется страховой буфер.
7. Из потребности вычитаются доступный остаток и товар в пути.
8. Итоговое количество округляется с учётом MOQ текущей модели.
9. Рекомендации группируются по поставщикам и получают срочность.
10. Менеджер открывает любую строку и видит обоснование расчёта.
11. При необходимости менеджер вручную меняет количество в колонке «Заказать».
12. Менеджер нажимает «Утвердить план».
13. После подтверждения можно выгрузить CSV со статусом согласования.

AI-агент не выполняет арифметику самостоятельно. Он вызывает функции расчётного модуля и объясняет уже проверенные результаты.

---

4. Технологии

Backend

• Python 3.11 в Docker-образе;
• стандартная библиотека Python:
  • http.server;
  • json;
  • gzip;
  • urllib;
  • datetime;
• openpyxl — используется при построении подготовленного каталога из исходных Excel-файлов.

Frontend

• HTML5;
• CSS3;
• vanilla JavaScript;
• без фронтенд-фреймворков.

AI

• OpenAI Responses API;
• модель по умолчанию задаётся переменной окружения: OPENAI_MODEL=gpt-5.6-luna;
• при отсутствии OPENAI_API_KEY работает локальный demo-agent с теми же детерминированными инструментами расчёта.

Развёртывание

• Docker;
• Railway;
• публичный health-check: /api/health.

---

5. Архитектура проекта

Браузер
  │
  ▼
frontend/
  ├── index.html
  ├── styles.css
  └── app.js
  │
  │ HTTP / JSON
  ▼
app.py
  ├── GET  /api/health
  ├── GET  /api/products
  ├── POST /api/recommendations
  └── POST /api/agent
  │
  ├──────────────► replenishment.py
  │                 ├── прогноз спроса
  │                 ├── сезонность
  │                 ├── тренд
  │                 ├── stockout
  │                 ├── выбросы
  │                 ├── остатки
  │                 ├── товар в пути
  │                 └── расчёт заказа
  │
  └──────────────► agent.py
                    ├── выбор инструмента
                    ├── OpenAI Responses API
                    └── локальный demo-agent

data/demo_catalog.json.gz
  ▲
  │
scripts/build_demo_data.py
  ▲
  │
Excel / ZIP выгрузки поставщиков

Расчётное ядро отделено от LLM: количество заказа формируется обычным кодом, а AI используется для выбора инструмента и объяснения результата.

---

6. Структура репозитория

.
├── app.py
├── agent.py
├── replenishment.py
├── frontend/
│   ├── index.html
│   ├── styles.css
│   └── app.js
├── data/
│   └── demo_catalog.json.gz
├── scripts/
│   └── build_demo_data.py
├── tests/
├── Dockerfile
├── railway.json
├── requirements.txt
├── .env.example
├── START_LOCAL.bat
├── DEPLOY_RAILWAY.bat
└── README.md

---

7. Установка и запуск

Локальный запуск

Требуется Python.

Из корня проекта:

python app.py

По умолчанию сайт будет доступен по адресу:

http://127.0.0.1:8000

Проверка API:

http://127.0.0.1:8000/api/health

На Windows также присутствует файл:

START_LOCAL.bat

Подключение OpenAI

Создайте локальный файл .env на основе .env.example:

OPENAI_API_KEY=...
OPENAI_MODEL=gpt-5.6-luna

API-ключ не должен попадать в Git.

При отсутствии ключа приложение продолжает работать, а AI-панель использует локальный demo-режим.

Docker

docker build -t stockpilot-ai .
docker run -p 8000:8000 stockpilot-ai

Railway

В проекте есть Dockerfile и railway.json.

При установленном Railway CLI:

railway.cmd login
railway.cmd init
railway.cmd up
railway.cmd domain

---

8. Как жюри может проверить решение

Публичная версия:

https://stockpilot-ai-production-4f94.up.railway.app

Для использования не требуется GitHub, Python, VS Code или Railway.

Рекомендуемый сценарий проверки:

1. Открыть deployed-версию в браузере.
2. Дождаться автоматического расчёта плана пополнения.
3. Выбрать поставщика IEK или Systeme Electric.
4. При необходимости выбрать категорию и срочность.
5. Открыть любую строку таблицы.
6. Проверить:
   • прогноз спроса;
   • остаток;
   • товар в пути;
   • MOQ;
   • срочность;
   • текстовое обоснование.
7. Изменить значение в колонке «Заказать».
8. Нажать «Утвердить план».
9. Нажать «Экспорт CSV» и проверить статус согласования в файле.
10. Открыть блок «Что если?»:
    • изменить спрос, например на +15%;
    • изменить горизонт;
    • пересчитать сценарий.
11. В AI-панели попробовать запрос:
    • Покажи срочные позиции IEK на 30 дней;
    • Какие выбросы алгоритм исключил?;
    • Объясни SKU 010400432;
    • Что изменилось после сценария?.
12. Открыть раздел источников данных и посмотреть ограничения входного набора.

Health-check deployed-версии:

https://stockpilot-ai-production-4f94.up.railway.app/api/health

---

9. Данные и интеграции

Подготовленный каталог проекта построен из предоставленных выгрузок по поставщикам:

• IEK;
• Systeme Electric.

В репозитории используется агрегированный локальный каталог data/demo_catalog.json.gz.

В обработке используются доступные поля и представления:

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

Для stockout предусмотрен отдельный CSV:

sku,month,days_out

Пример:

200400085,2026-08,10

Внешняя интеграция текущей версии:

• OpenAI Responses API — опционально;
• Railway — хостинг deployed-версии.

---

10. Ограничения текущей версии

Ограничения отражены в интерфейсе и не скрываются:

• в предоставленных выгрузках нет обезличенного client_id, поэтому нельзя достоверно объединять несколько документов как покупки одного клиента;
• крупные разовые операции выявляются на уровне доступных документов / SKU и месячных аномалий;
• в исходном наборе нет полноценной истории stockout — её можно передать отдельным CSV или задать в сценарии;
• нет автоматически обновляемого подключения к 1С;
• входные данные используются из подготовленного локального снимка, а не обновляются в реальном времени;
• фактические сроки новых поставок не представлены полноценным справочником, поэтому горизонт расчёта задаётся как параметр сценария;
• для части данных свежесть снимка ограничена исходными отчётами;
• совместимость экспортируемого CSV с конкретной конфигурацией импорта 1С не подтверждена;
• точность прогноза не заявлена как подтверждённая отдельным backtesting-набором;
• подтверждение менеджера в текущем веб-интерфейсе сохраняется локально в браузере, а не в общей корпоративной БД;
• нет пользовательской авторизации и серверного журнала утверждений;
• автоматической отправки заказа поставщику нет;
• публичная deployed-версия не предназначена для размещения новых конфиденциальных данных через интерфейс.

---

11. Deployed-версия

StockPilot AI:
https://stockpilot-ai-production-4f94.up.railway.app

Health-check:
https://stockpilot-ai-production-4f94.up.railway.app/api/health

---

Безопасность и принцип принятия решения

StockPilot AI является системой поддержки закупщика.

AI / алгоритм рекомендует
        ↓
менеджер проверяет
        ↓
при необходимости корректирует
        ↓
менеджер утверждает
        ↓
формируется CSV

Система не отправляет заказ поставщику автоматически.

---

Быстро открыть проект

Способ 1 — готовая онлайн-версия

Самый простой способ для жюри и пользователей — открыть уже развёрнутый StockPilot AI:

https://stockpilot-ai-production-4f94.up.railway.app

Ничего скачивать или устанавливать не требуется. Ссылка открывается в обычном браузере.

Способ 2 — запуск на Windows через BAT

Если проект скачан из GitHub как ZIP:

1. Распакуйте ZIP в отдельную папку.
2. Убедитесь, что на компьютере установлен Python и команда python доступна из терминала.
3. В корне распакованного проекта дважды нажмите:

START_LOCAL.bat

4. После запуска сервера откройте в браузере:

http://127.0.0.1:8000

5. Для остановки локального сервера закройте окно терминала или нажмите Ctrl+C.

Если локальный запуск недоступен, используйте готовую онлайн-версию:

https://stockpilot-ai-production-4f94.up.railway.app