Контур закупок · HACKALEM AI

Демонстрационный сервис для закупщика ТОО «Электрокомплект»: продажи и остатки → объяснимый прогноз → рекомендации по поставщикам → корректировка менеджером → утверждённый CSV. Автоматической отправки поставщику нет.

Запуск

Windows: нужен стандартный CPython 3.11+ и Node.js 22+. Из корня проекта:

.\setup.ps1
.\start.ps1

setup.ps1 устанавливает зависимости и собирает интерфейс. Если всё уже установлено, нужен только start.ps1. Открыть http://127.0.0.1:8000/. Backend отдаёт собранный React-интерфейс: отдельный frontend-сервер для демо не нужен.

Скрипт выбирает рабочее окружение .venv или .venv-win. Если PowerShell запрещает выполнение скриптов, можно выполнить команды вручную:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -c requirements-dev.lock.txt -e ".[dev]"
npm.cmd --prefix frontend ci
npm.cmd --prefix frontend run build
.\.venv\Scripts\python.exe -m backend.run

На этой машине также доступно .venv-win\Scripts\python.exe. Не используйте MSYS2 Python: его платформенные пакеты несовместимы с обычными Windows wheels. Дождитесь успешного завершения pip; отменённая установка не создаёт готовое окружение.

Повторный запуск обнаруживает работающий API и не создаёт вторую копию. Если порт занят чужим сервисом: .\start.ps1 -Port 8001. Остановка — Ctrl+C. После изменения backend-кода остановите старый процесс и запустите заново. После изменения frontend выполните npm.cmd --prefix frontend run build.

Linux/macOS: обычный venv, pip install -e '.[dev]', npm --prefix frontend ci, npm --prefix frontend run build, python -m backend.run.

Что демонстрировать

1. Открыть обзор: активный набор явно подписан как синтетический.
2. Выбрать склад/категорию и выполнить расчёт. Первый запуск подготавливает историю; прогресс отображается. Следующие сценарии используют кеш подготовки.
3. Просмотреть рекомендации по поставщику и раскрыть SKU: история, сезонность, тренд, stockout, клиентские события, формула и календарь остатка.
4. Изменить настройки коррекций и сравнить количество с предыдущим сценарием.
5. Создать черновик для поставщика, скорректировать количество с причиной, утвердить и скачать CSV.
6. Во вкладке данных можно проверить источник, скачать 9 CSV и импортировать другой набор того же контракта.

Полный сценарий на 4 минуты: docs/DEMO.md. Проверка MUST HAVE: docs/ACCEPTANCE.md.

Данные и алгоритм

По умолчанию: 120 SKU, 2 склада, 6 категорий, 8 поставщиков, 300 обезличенных клиентов, 24 месяца (2024-09-01…2026-08-31), 72 370 строк продаж при seed=42. Все уровни, профили и клиенты вымышлены; они не являются сведениями о бизнесе партнёра.

.\.venv\Scripts\python.exe -m backend.generate_synthetic --output data/synthetic --seed 42
.\.venv\Scripts\python.exe -m backend.validate_data --input data/synthetic --as-of-date 2026-09-01 --history-start 2024-09-01 --history-end 2026-08-31
.\.venv\Scripts\python.exe -m backend.preprocess_sales --input data/synthetic --output data/preprocessed

Первый запуск API создаёт стандартную синтетику, если её ещё нет. Скрытый спрос и scenario_type находятся отдельно и не читаются расчётным ядром. Реальные Excel в IEK/ и Systeme electric/ сохранены: прямые адаптеры сложных партнёрских Excel пока не реализованы. Реальные данные подключаются через согласованный CSV-контракт; отсутствующие поля нельзя подменять выдуманными значениями.

Метод статистический, без ML/LLM-сервисов: причинная очистка клиентских событий, оценка спроса при отсутствии, сезонный профиль SKU/категории, ограниченный устойчивый тренд, дневной прогноз и проекция запаса. Количество учитывает свободный остаток, даты и неполученную часть поставок, срок поставщика, период пересмотра, резерв, MOQ и кратность.

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

Проверки

.\.venv\Scripts\python.exe -m pytest -q
npm.cmd --prefix frontend run build

Тесты используют отдельные .test-runs/run-*, чтобы не конфликтовать с правами старого Windows TEMP. Каталоги исключены из Git. /health проверяет доступность API; /docs содержит его актуальный контракт.

Хранение и границы демо

• data/runtime/workspace.sqlite3 — набор данных, результаты расчётов, заказы и аудит.
• data/runtime/runs/ — неизменяемые CSV-снимки входов каждого расчёта.
• data/synthetic/, data/preprocessed/, data/runtime/ — локальные генерируемые данные, исключены из Git.
• Утверждённый заказ не редактируется. Проверка версии защищает от одновременных правок. CSV содержит утверждённые количества, UTF-8 BOM и стабильные коды товаров/складов/поставщиков.
• Демонстрация предназначена для localhost и одного локального рабочего пространства. Полноценной аутентификации и промышленного развёртывания нет.
• Совместимость CSV с конкретной обработкой загрузки 1С требует согласования шаблона. При открытии CSV в Excel задавайте артикулу тип «текст», чтобы сохранить ведущие нули.
• Страховой запас в днях — явная политика, не обещание уровня сервиса; оценки спроса не являются гарантией будущих продаж.

Документация

• Архитектура, API, проверки.
• CSV-контракт, особенности Excel партнёра.
• Синтетика, подготовка продаж, прогноз и заказ.