ProofFlow — объяснимые заказы на пополнение склада

Конкурсный проект команды ProofFlow для задачи Электрокомплект: расчёт черновиков заказов поставщикам по SKU и складам. Сервис показывает не только количество, но и причины рекомендации, происхождение данных и риск дефицита. Заказ не отправляется автоматически: сотрудник проверяет, при необходимости правит объём, утверждает и скачивает CSV/XLSX.

Для менеджера: меньше ручной сверки в Excel, видимые риски дефицита и понятная причина каждой закупки. Экономический эффект требует пилота; проценты экономии на предприятии не заявлены.

Быстрый запуск

Нужен Python 3.12+; проверка во время конкурса проводилась в локальном окружении Python 3.14. Интернет нужен только для первоначальной установки пакетов. Runtime не вызывает OpenAI/NVIDIA или другие внешние API и не требует личной подписки участника.

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.lock
.\.venv\Scripts\python.exe server.py

Откройте http://127.0.0.1:8000. На Linux/macOS после создания окружения: ./.venv/bin/python -m pip install -r requirements.lock, затем ./.venv/bin/python server.py. Все приведённые ниже команды запускайте через это же окружение: системный Python может не содержать openpyxl.

Проверка без партнёрских данных: нажмите «Загрузить демо», изучите пометку «Синтетические данные», измените остаток или срок поставки одного товара, запустите расчёт, откройте объяснение позиции, скорректируйте заказ, утвердите и выгрузите файл. Шаблон данных можно скачать из интерфейса или GET /api/template и затем загрузить обратно. API-документация: http://127.0.0.1:8000/docs. Это полностью автономная демонстрация без партнёрских файлов и ключей.

Что проверить жюри

Требование кейса	Проверка
История, остатки, товары в пути, категории и прирост влияют на потребность	Раскройте «Данные и параметры товаров», измените остаток или рост товара и пересчитайте. Тест требования 1 меняет источники по отдельности.
Сезонность и устойчивый рост	Кнопкой i откройте DEMO-SEASON-01 и DEMO-GROW-02: история, прогноз и коэффициенты объясняют рекомендацию. Тест требования 2 проверяет календарную сезонность и тренд.
Компенсация спроса при stockout	DEMO-STOCKOUT-03 показывает восстановленный спрос за заданный период отсутствия товара; тест требования 3 сравнивает с сырыми продажами.
Исключение разового крупного заказа	DEMO-SPIKE-04 показывает исключённый объём; повторяющийся спрос сохраняется. Тест требования 4 добавляет крупный заказ.
Поставщики и обоснование каждой позиции	Проверьте группы, измените количество, утвердите, скачайте CSV/XLSX. Тест требования 5 проходит сценарий через API.

Все пять проверок находятся в tests/test_workflow_acceptance.py. Демонстрационные stockout-интервалы и клиентские пики заданы в синтетике; они не выдаются за реальные сведения партнёра.

Возможности рабочего места

• Русский, қазақша и English; светлая и тёмная темы. Выбор сохраняется в браузере. После смены языка пересчитайте данные для новых серверных пояснений и языка экспорта.
• Фильтры склада, категории и поставщика; редактируемые параметры товаров, политики категорий, MOQ и кратность упаковки.
• История, прогноз, срочность и объяснение позиции. Покрытие данных показывает подтверждённость исходных полей, а не точность прогноза.
• CSV/XLSX на языке расчёта. Неизвестные цены остаются пустыми; неполная сумма отмечается.
• «Паспорт расчёта» — JSON с первоначальными и утверждёнными количествами, сверкой сумм и SHA-256 отпечатком. Это проверка изменений, не цифровая подпись или неизменяемый реестр. Описание отчёта.

Входные данные и метод

Канонический JSON состоит из as_of, products, sales, stockouts, inbound, category_policies, settings, metadata. Точная структура — docs/CONTRACT.md; происхождение и неполнота материалов партнёра — docs/DATA_MAPPING.md. JSON-шаблон из демо содержит только синтетические строки. Поддерживаемые форматы загрузки: JSON, CSV, XLSX и ZIP с известной структурой. Адаптер партнёрских книг работает только с распознанными листами и показывает предупреждения о пропущенных полях/файлах; неизвестную схему нельзя молча считать достоверной.

Расчёт выполняется локально, детерминированно и без LLM. Для каждой пары SKU/склад он очищает исторический спрос от обоснованно выделенных разовых всплесков, оценивает спрос, скрытый подтверждёнными периодами отсутствия товара, учитывает сезонность, устойчивый тренд и настроенный рост, затем прогнозирует потребность на срок поставки, период обзора и страховой горизонт. Текущий остаток и датированные ожидаемые поступления вычитаются в порядке их доступности; черновой заказ доводится до MOQ/кратности упаковки. Параметры алгоритма — инженерные настройки, не нормативы организатора. Подробности и формулы: docs/METHODOLOGY.md.

Если в исходных материалах нет реального остатка, периода отсутствия товара, ETA поставки, клиентского идентификатора или срока поставки, приложение не должно объявлять эти величины измеренными: предупреждения видны до расчёта, а менеджер может ввести недостающие параметры. Без подтверждённых stockout- интервалов компенсация lost sales не рассчитывается по реальным данным; демо отдельно показывает этот механизм на синтетическом примере.

Архитектура и безопасность

Технологии: Python, FastAPI/Uvicorn, SQLite, openpyxl, HTML/CSS/JavaScript, pytest. Расчёт и интерфейс работают локально без LLM-запросов и CDN.

• importer.py — разбор и нормализация; исходные архивы не помещаются в Git.
• engine.py — чистый расчёт и пояснения, без сети и записи в базу.
• server.py — локальный FastAPI, предпросмотр, запуск, проверка/утверждение.
• storage.py — SQLite в игнорируемой private_data/; детальные ряды SKU загружаются по запросу, чтобы не пересылать весь архив продаж в браузер.
• exports.py — CSV/XLSX с защитой от формул в недоверенных текстовых полях.
• evidence.py — сверка рекомендаций и утверждённых количеств, паспорт расчёта.
• frontend/ — автономный интерфейс без CDN.

Поток данных и границы ответственности модулей — в docs/ARCHITECTURE.md. Матрица правил и ограничений — в docs/COMPLIANCE.md.

Путь к локальной базе можно задать перед запуском сервера. Например:

$env:PROOFFLOW_DATA_DIR = "C:\ProofFlowData"
.\.venv\Scripts\python.exe server.py

По умолчанию используется игнорируемая Git папка private_data/.

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

Проверка и ограничения

.\.venv\Scripts\python.exe scripts/preflight.py
.\.venv\Scripts\python.exe scripts/verify_live_flow.py
.\.venv\Scripts\python.exe scripts/benchmark.py

preflight.py запускает весь локальный тестовый набор и проверку синтаксиса JS (если установлен Node.js). verify_live_flow.py сам поднимает сервер на свободном localhost-порту, проверяет загрузку, расчёт, детали, утверждение, CSV/XLSX и паспорт расчёта, затем останавливает его. Временная база изолирована от ваших рабочих данных. Параметры --locale kk и --locale en выбирают язык проверки. benchmark.py печатает только агрегированные количества и время работы; для проверки предоставленных партнёром файлов передайте пути к ним аргументами. Ни один из этих сценариев не делает push, не отправляет заказ и не заменяет форму сдачи на платформе.

Опциональный локальный контейнер (Docker не обязателен для оценки и не был проверен на конкурсной машине):

docker build -t proofflow .
docker run --rm -p 127.0.0.1:8000:8000 proofflow

Запускайте контейнер только через localhost: публичная публикация этого однопользовательского сервиса без аутентификации небезопасна. Данные в контейнере без тома не сохраняются между запусками.

Ограничения: прогноз статистический, не гарантия спроса; качество зависит от истории и достоверности остатков. Клиентский выброс определяется уверенно только при доступном обезличенном ID; при его отсутствии возможен отдельный анализ аномального документа с явной оговоркой. Цена нужна лишь для ориентировочной суммы: она не влияет на количество, а отсутствующая цена не выдумывается. Рекомендация — черновик для человека, а не автоматический заказ поставщику. Файловый экспорт не является проверенным коннектором 1С: см. docs/1C_COMPATIBILITY.md.

Происхождение и ход разработки

Основная функция написана во время соревновательной части в официальном репозитории команды. Ранее созданный TransClaim — отдельный железнодорожный продукт; его код и готовая функциональность сюда не переносились. Используются общедоступные Python-библиотеки FastAPI, Uvicorn, openpyxl, Pydantic, Pytest с лицензиями их авторов. Рабочие решения и ограничения фиксируются в docs/TEAM_MEMORY.md; факты о часовом прогрессе — в docs/SPRINT.md.

Локальные иконки Phosphor распространяются по MIT с сохранённым уведомлением: происхождение и лицензия визуальных ресурсов. Короткий сценарий демо помогает воспроизвести основной поток.

После финального push необходимо отдельно нажать «Сдать решение» для выбранной задачи на платформе организатора до объявленного freeze. История Git сама по себе не заменяет сдачу.