Запуск за минуту

Нужен Python 3.12 или новее; Node.js и API-ключ не нужны. Из корня проекта:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m app

Через 10–15 секунд, после строки Application startup complete, откройте http://localhost:8000. Windows, Docker и запуск на другом порту описаны в разделе «Быстрый старт», сценарий для проверки — в разделе «Проверка работы».

Содержание

• Запуск за минуту
• Назначение
• Возможности
• Сценарий работы
• Архитектура
• Методология расчёта
• Технологии
• Данные и интеграции
• Быстрый старт
• Проверка работы
• Основные команды
• API и ошибки
• Качество прогноза
• Известные ограничения
• Внешние материалы и AI-инструменты
• Развёртывание

Назначение

Сейчас количество к заказу считают Excel-методом — по среднему сырых продаж за последние 12 месяцев. Такой расчёт не учитывает месяцы без товара, разовые крупные заказы, сезонность и тренд. GrimStack помогает менеджеру закупок подготовить заказы IEK и Systeme Electric по выгрузкам 1С. Сервис рассчитывает количество для каждого SKU с учётом спроса, остатка, товара в пути и кратности поставки. Менеджер проверяет рекомендацию, при необходимости меняет количество и утверждает заказ.

Возможности

Приложение покрывает путь от загрузки выгрузок до утверждения и экспорта заказа.

Возможность	Что получает менеджер
Данные	Встроенные XLSX-выгрузки IEK и SE или загрузка собственных файлов; для нового поставщика — ввод названия и выбор формата IEK/SE
Расчёт	Прогноз с обработкой разовых продаж, месяцев без товара, сезонности и тренда; сравнение с Excel-методом
Работа с заказом	История SKU, объяснение рекомендации, правка количества с проверкой кратности, утверждение и экспорт XLSX
Сводка	Запрос к OpenAI-совместимому API или подготовленный образец из samples/cache/
Проверка метода	Бэктест прогноза на шести контрольных точках в data/backtest/report.json
Сценарий «что если»	«Аналитика» → блок «Задержка поставщика»: второй расчёт с увеличенным сроком поставки и изменения количества, срочности и суммы (POST /api/runs/compare)

Сценарий работы

От входных выгрузок до результата менеджер проходит четыре шага:

1. Выбирает встроенные данные поставщика или загружает собственные XLSX-файлы. Для нового поставщика вводит название и выбирает формат выгрузок 1С — как у IEK или SE.
2. Запускает расчёт и сравнивает рекомендацию с базовым Excel-методом.
3. Проверяет историю и объяснение по SKU, при необходимости меняет итоговое количество с учётом кратности.
4. Утверждает заказ и скачивает XLSX для 1С. Сервис не отправляет заказ поставщику автоматически.

Архитектура

Один процесс FastAPI обслуживает API и собранный React-интерфейс. Данные проходят через нормализацию, расчёт и проверку заказа:

flowchart LR
    XLSX["Выгрузки 1С · XLSX"] --> Ingest["app/ingest · нормализация"]
    Ingest --> Engine["app/engine · прогноз и заказ"]
    Engine --> API["app/api · FastAPI"]
    UI["frontend/dist · React"] <--> API
    API --> Store["app/store · прогоны и утверждения"]
    API --> AI["app/ai · кэш или LLM"]

app/ingest/ приводит выгрузки 1С к единому Dataset. app/engine/ очищает спрос, восстанавливает спрос в месяцы без товара, прогнозирует и рассчитывает заказ. app/api/ вызывает ядро, проверяет изменения менеджера и отдаёт JSON/XLSX. app/store.py держит наборы и прогоны в памяти. frontend/ показывает параметры, строки заказа и историю SKU.

analyze учитывает очистку, stockout, сезонность и тренд. baseline использует среднее сырых продаж за последние 12 закрытых месяцев без этих поправок при той же политике остатка, товара в пути и кратности.

Формы данных заданы в app/contracts.py и повторены в frontend/src/api/types.ts. Подробности алгоритма находятся в docs/design.md, структура проекта — в docs/structure.md.

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

Расчёт идёт по каждому SKU на месячной сетке, дата данных — 22.09.2026 (app/engine/, полное описание — docs/design.md §4).

1. Исключение разовых крупных заказов (cleaning.py). По строкам расходных накладных 2025+ для SKU считаются медиана, квартили и вторая по величине строка. Нужно не меньше 5 строк у IEK и 20 у SE. Строка считается разовой, если выполнено одно из правил:

   • B — все условия сразу: q > 5 × медиана, q > Q3 + 3·IQR, q ≥ типичного месяца SKU, и такие строки были не больше чем в 3 месяцах (у SE — в 4). Иначе это регулярный опт;
   • U — «беспрецедентная» строка: q ≥ 2 × вторая по величине и q > 5 × медиана.

   Разовая строка заменяется медианной, излишек вычитается из месяца. Документ с тремя и более такими строками помечается как проектный заказ одного клиента. Паллетный поток SE (кратные партии) в статистику не входит.

2. Упущенный спрос при дефиците (stockout.py). Месяц с нулевым или низким остатком получает добавку база × (1 − доля дней в наличии). База — медиана 6 предыдущих месяцев, когда товар был в наличии; добавка не больше 2 × база.

3. Прогноз (forecast.py): база × сезонность(месяц) × тренд × (1 + прирост %). База — среднее очищенного и восстановленного спроса за 12 закрытых месяцев без сезонности. Сезонность считается по товарной группе, а при длинной устойчивой истории подмешивается собственный профиль SKU. Тренд — последние 6 месяцев к тем же месяцам год назад, ограничен ×0,67…×1,5 и сжат при короткой истории. Редкий спрос (Syntetos–Boylan: intermittent/lumpy) заказывается не меньше медианной продажи.

4. Заказ (policy.py): S = прогноз на (L + R) + z·σ·√((L + R)/30), где уровень сервиса z зависит от категории SKU. заказ = ⌈(S − остаток − в пути с ETA в горизонте) / кратность⌉ × кратность. Срочность — по дням покрытия: меньше L — срочно, меньше L + R — скоро.

5. Обоснование (explain.py). У каждой строки есть главная причина текстом и разложение количества по шагам: прогноз, страховой запас, минус остаток, минус в пути, округление. Сумма шагов равна рекомендации.

Технологии

Стек подтверждён requirements.txt, frontend/package-lock.json и Dockerfile.

Область	Технологии	Назначение
Сервер и API	Python 3.12+, FastAPI, Pydantic, Uvicorn	HTTP-контракт, валидация и выдача интерфейса
Расчёт и файлы	pandas, NumPy, openpyxl	Обработка выгрузок, прогноз и экспорт XLSX
Интерфейс	React, TypeScript, Vite, TanStack Query, ApexCharts	Работа с расчётом, заказами и графиками
Запуск	Docker или локальный Python	Один серверный процесс с готовым frontend/dist
AI	Laya (офлайн), OpenAI-совместимый API (gpt-4o-mini по умолчанию; NVIDIA NIM через OPENAI_BASE_URL)	Товарные группы по наименованиям; текстовая сводка по готовым цифрам заказа

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

В репозитории есть выгрузки 1С IEK и Systeme Electric в data/raw/iek/ и data/raw/se/. Через интерфейс можно загрузить собственный набор XLSX-файлов для одного из них или добавить нового поставщика: указать название, выбрать формат файлов IEK/SE и загрузить выгрузки тех же ролей. Это два поддерживаемых формата, а не универсальный импорт произвольной таблицы 1С. После загрузки интерфейс выбирает созданный набор и поставщика для следующего расчёта. Профиль данных описан в docs/data-profile.md, состав файлов и API — в docs/API.md.

Товарные группы читаются из data/categories/sku_categories.csv. Для подготовки этого справочника отдельно применялась модель Laya; при запуске сервиса она не нужна. Сводка заказа использует OpenAI-совместимый API с необязательными OPENAI_API_KEY, OPENAI_BASE_URL и MODEL. Без ключа основные расчёты, правка и экспорт работают; для исходных расчётов доступны образцы из samples/cache/. Если подходящего образца нет, сводка возвращает 503.

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

Для запуска готового приложения достаточно Docker или Python 3.12 и новее (проверено на 3.12 и 3.14). Node.js не нужен: собранный интерфейс frontend/dist уже находится в репозитории. Все команды выполняются из корня проекта; остановка сервера — Ctrl+C.

Docker: macOS, Linux и Windows

Установите и запустите Docker Desktop (macOS/Windows) или Docker Engine (Linux). В macOS используйте терминал zsh/bash, в Linux и Windows WSL — bash, в Windows без WSL — CMD. Команды одинаковы во всех этих терминалах:

docker build -t grimstack .
docker run --rm -p 8000:8000 -v grimstack-var:/srv/var grimstack

Docker выбирает поддерживаемый вариант базового образа для своей платформы. Именованный том grimstack-var сохраняет базу утверждений SQLite var/app.db между запусками контейнера. При повторном запуске достаточно второй команды.

Python: macOS, Linux и Windows WSL

Установите Python 3.12 или новее с модулями venv и pip; версию покажет python3 --version. В macOS в терминале zsh/bash, а в Linux и Windows WSL в bash выполните из корня проекта:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m app

Окружение .venv создаётся для текущей ОС. Если проект используется и из Windows, и из WSL, держите отдельную копию проекта с собственным .venv для каждой среды.

Python: Windows CMD

Установите Python 3.12 или новее с Python Launcher (py) и pip. В CMD из корня проекта выполните:

py -3 -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt
.venv\Scripts\python.exe -m app

После сообщения Uvicorn о старте откройте http://localhost:8000. Адрес http://localhost:8000/health должен вернуть {"status":"ok"}. Первая загрузка встроенных XLSX может занять время; дождитесь сообщения о старте перед проверкой.

Если порт 8000 занят (в логе address already in use), запустите сервис на другом порту и откройте http://localhost:8001:

PORT=8001 .venv/bin/python -m app

В Windows CMD сначала выполните set PORT=8001, затем .venv\Scripts\python.exe -m app.

Настройка окружения

Необязательные настройки задаются переменными окружения или файлом .env в корне проекта. Для локального Python можно скопировать .env.example и заполнить нужные значения. Для Docker в macOS zsh/bash, Linux/WSL bash или Windows CMD добавьте --env-file .env перед именем образа:

docker run --rm -p 8000:8000 -v grimstack-var:/srv/var --env-file .env grimstack

Переменная	Назначение
OPENAI_API_KEY	Ключ LLM для новых сводок
OPENAI_BASE_URL	Адрес OpenAI-совместимого провайдера, в том числе NVIDIA NIM
MODEL	Идентификатор модели у выбранного провайдера
PORT	Порт сервиса; по умолчанию 8000

Если меняете PORT при запуске Docker, укажите тот же порт с обеих сторон аргумента -p.

Проверка работы

Дождитесь запуска Uvicorn и откройте http://localhost:8000/health: ответ {"status":"ok"} подтверждает, что встроенные данные загружены. Основной сценарий проверяется без API-ключа:

1. Запустите приложение по инструкции для своей ОС в разделе «Быстрый старт» и откройте http://localhost:8000.
2. Откройте раздел «Данные и расчёт», выберите Systeme Electric из встроенных данных data/raw/se/, оставьте метод «Наш расчёт» и параметры по умолчанию, нажмите «Рассчитать». Затем перейдите в «Заказы».
3. В поиске введите 030200193_ и откройте строку IMT35150. Видно 37 800 шт. в пути, рекомендацию 22 680 шт. и сравнение с Excel-методом 0 шт.
4. Нажмите «Сводка» у поставщика: появится сохранённый текст с пометкой «Из кэша». Нажмите «Excel для 1С»: скачается order_SE_<дата>.xlsx.
5. Для проверки управляемости измените итоговое количество IMT35150 на 26 460 (семь упаковок по 3 780) и сохраните: в строке появится 26 460. Затем утвердите заказ. После утверждения правка блокируется; автоматической отправки поставщику нет.

Основные команды

После первой установки запускайте сервис и тесты из корня проекта командами для своей среды.

Задача	macOS zsh/bash, Linux и WSL bash	Windows CMD
Повторный запуск	.venv/bin/python -m app	.venv\Scripts\python.exe -m app
Тесты	.venv/bin/python -m pytest -q	.venv\Scripts\python.exe -m pytest -q

Для повторной сборки интерфейса нужны Node.js 24 или новее и npm. В macOS zsh/bash, Linux/WSL bash или Windows CMD выполните из корня проекта:

npm ci --prefix frontend
npm run build --prefix frontend

Сборка обновляет frontend/dist; обычный запуск готового приложения Node.js не требует.

API и ошибки

Маршруты API имеют префикс /api. Ошибки возвращаются в едином JSON-формате {"detail": "...", "code": "...", "meta": {}}.

HTTP	code	Ситуация
404	not_found	Нет прогона, SKU, поставщика, набора данных или маршрута API; неверный метод у маршрута /api/*
404	backtest_not_found	Файл отчёта бэктеста отсутствует
405 и другие HTTP-ошибки	http_error	Неподдерживаемый запрос вне /api, например неверный метод у /health
409	conflict	Заказ уже утверждён
422	validation_error	Запрос не прошёл проверку схемы
422	invalid_input	Некорректное количество или форма загрузки, файл больше 30 МБ
422	unknown_role, missing_file, empty_file, not_xlsx, bad_format	Ошибка XLSX; роль файла в meta.file_role, когда известна
503	unavailable	Сводка недоступна через провайдера и в кэше нет подходящего ответа
500	internal_error	Неожиданная ошибка; детали пишутся в серверный лог

Качество прогноза

Отчёт бэктеста хранится в data/backtest/report.json и доступен по GET /api/backtest; методика описана в docs/backtest.md. На шести контрольных точках с марта по август 2026 года WAPE по очищенным продажам составил 0,3972 у IEK против 0,4055 у базового метода; у SE — 0,230 против 0,275. Это оценка прогноза спроса, а не экономического эффекта или качества итогового заказа.

Известные ограничения

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

• Прогоны и загруженные наборы хранятся в памяти одного процесса и пропадают после перезапуска. База утверждений и их истории хранится в SQLite var/app.db; учётных записей и авторизации нет.
• Новый поставщик добавляется только в загруженный набор данных. Его выгрузки должны соответствовать выбранному формату IEK или SE; отдельной постоянной регистрации поставщиков нет.
• Текущий остаток IEK является нижней оценкой из-за неизвестных приходов сентября. Цен IEK в данных нет, поэтому сумма заказа для него не показывается.
• Срочность во многом держится на этой оценке: из 382 срочных позиций 377 рассчитаны по оценочному остатку (в интерфейсе — подпись под показателем и значок ≈ у остатка). Перед утверждением остаток стоит сверить с 1С.
• Склад: в выгрузках один склад (Алматы); у SE текущий остаток — сумма складских остатков (свободный, витрина, ТЗ, РЦ, розница), поэтому расчёт ведётся по складу целиком. Выбор «по категории» работает по товарным группам и по классам поставщика.
• У SKU, где накладных меньше 5 (IEK) или 20 (SE), разовые заказы не распознаются: статистики строк недостаточно, и крупная продажа такого редкого товара поднимет рекомендацию. Клиента в выгрузках нет, поэтому «одного клиента» заменяет документ-накладная.
• Транзакции доступны только с 2025 года. Разовые продажи 2024 года нельзя проверить по документам; без необязательного sales_tx анализ разовых заказов и дней наличия ограничен. Паллетный поток SE не входит в базовый спрос.
• Срок поставки SE основан на допущении в 40 дней; параметры расчёта можно изменить в интерфейсе. Новые LLM-сводки требуют проверки по числовым строкам заказа.
• Готовые сводки в samples/cache/ есть только для исходных расчётов с параметрами по умолчанию. После правки количества или смены параметров без OPENAI_API_KEY кнопка «Сводка» показывает объяснение вместо текста (код 503); расчёт, правка и экспорт от этого не зависят.
• Бэктест использует исторические срезы с текущими справочниками SKU; внешняя проверка на других наборах данных не проводилась.

Внешние материалы и AI-инструменты

Раскрытие по п. 6.4 Положения.

• Данные: выгрузки 1С IEK и Systeme Electric, предоставленные партнёром кейса (ТОО «Электрокомплект»), в data/raw/. Других внешних датасетов в расчёте нет.
• Библиотеки: сервер — FastAPI, Uvicorn, Pydantic, pandas, NumPy, openpyxl, python-dotenv, OpenAI Python SDK (requirements.txt); интерфейс — React, TypeScript, Vite, TanStack Query, ApexCharts, Radix UI и др. (frontend/package.json).
• Модель Laya (convaiinnovations/laya, мультиязычный чекпойнт, Convai Innovations, Apache 2.0) — офлайн-классификация наименований по товарным группам (scripts/classify_laya.py), в сервис не входит. Правила по ключевым словам определили 3 037 из 3 667 SKU (83 %); ответ модели принимался только при уверенности ≥ 0,9 — на размеченных правилами SKU она совпадает с ними в 81 % случаев. Моделью размечено 11 SKU, 619 неуверенных ответов отнесены к «Прочее». Замер — data/categories/laya_eval.json, сырые ответы — data/categories/laya_raw.csv.
• LLM gpt-4o-mini через OpenAI-совместимый API — текст сводки по заказу поставщику (app/ai/llm.py). Модель получает уже посчитанные цифры и ничего не пересчитывает. 8 ответов сохранены в samples/cache/ для запуска без ключа.
• AI-инструменты разработки: Claude Code (Anthropic) — ядро расчёта, AI-слой, бэктест, тесты, документация и правки интерфейса; Codex (OpenAI) — API и интерфейс. Сгенерированный код проверен автотестами (pytest) и вручную в браузере.
• Готовые шаблоны интерфейса не использовались.

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

Публичной развёрнутой версии нет. Рабочее приложение запускается локально по разделу «Быстрый старт»: FastAPI раздаёт API и собранный интерфейс на http://localhost:8000. Для публичного доступа текущей реализации необходимы авторизация и постоянное хранилище прогонов.