KAZ-AI — рекомендации для заказов поставщикам

Прототип для кейса ТОО «Электрокомплект» на HackAlem AI. Закупщик получает объяснимый прогноз спроса и рекомендуемое количество по артикулу, проверяет его, при необходимости корректирует и утверждает. Основное демо работает только с вымышленными товарами, продажами и ID клиентов. Дополнительный публичный стенд показывает производные рекомендации по 497 SKU без клиентских ID, сырой истории продаж, цен и исходных файлов. Сервис не отправляет заказы поставщикам.

Начать за 3 минуты

1. Откройте публичное демо KAZ-AI. Регистрация не нужна. На «Обзоре» блок «Контроль расчёта» показывает риск до поставки, исключённый разовый спрос, восстановление спроса при дефиците и наличие остатков. Все числа вычисляются из текущих синтетических рекомендаций.
2. В разделе «Рекомендации» найдите DEMO-A202: разовая покупка 900 единиц клиентом DEMO-C017 исключена из обычного спроса. У DEMO-B310 показано восстановление спроса за период дефицита. Для срочных позиций видна величина ожидаемого дефицита до поставки. Измените горизонт покрытия с 30 на 45 дней и сравните количество.
3. В разделе «Поставщики» откройте позиции одного поставщика. Вернитесь к рекомендациям, отметьте позицию, при необходимости измените количество и нажмите «Утвердить выбранные». После этого проверьте «Историю» и скачайте CSV заказа. В «Истории» действия пользователя показаны отдельно от помеченных синтетических примеров; примеры не влияют на утверждения и CSV.
4. Для сценария неполных данных снимите фильтр «Только к заказу» и найдите DEMO-B840: без актуального остатка количество заблокировано до его ввода. В «Настройках» доступны русский и казахский языки, горизонт, поставщик и фильтр по умолчанию.

Чистый запуск основного демо (Python 3.11+, для синтетического режима установка пакетов не требуется):

git clone https://github.com/BAITC-Hacks/hack-37ae610f-kaz-ai.git
cd hack-37ae610f-kaz-ai
python3 -m kaz_ai

Откройте http://127.0.0.1:8765/. Автоматическая проверка пяти обязательных требований ТЗ: python3 -m unittest discover -s tests -v. Короткое видео показывает тот же сценарий.

Технологии

• Расчёт и локальный API: Python 3.11+, детерминированный прогноз с поправками на сезонность, рост, дефицит и разовые заказы; стандартная библиотека Python обслуживает HTTP. В числовом расчёте нет внешнего LLM или платного API.
• Импорт и аналитическая проверка: openpyxl читает архивы Excel партнёра без изменения исходников; модуль supply_control/ использует Python, pandas и openpyxl для аудита и бэктеста.
• Интерфейс: HTML, CSS и JavaScript без фронтенд-фреймворка. Публичная статическая сборка размещена на Vercel; действия демо сохраняются в localStorage браузера.

Единая конкурсная версия

kaz_ai в корне — канонический расчётный контур: импорт двух поставщиков, очистка спроса, исключение разовых заказов, stockout, сезонность, рост, подтверждение и CSV. Основной публичный интерфейс — пять страниц в site/; он собирается из kaz_ai и содержит только синтетические данные. Каталог supply_control/ добавляет проверку прогноза на данных партнёра, строгий аудит параметров и отдельный аналитический стенд. Синтетический режим этого стенда также строится из kaz_ai; его результаты не являются отдельным источником производственных заказов.

• Основная публичная версия содержит 12 синтетических товаров и доказывает 5/5 must-have.
• Дополнительный публичный стенд содержит производные рекомендации по 497 SKU Systeme Electric; клиентские ID, сырая история, цены и исходные файлы исключены.
• Все строки партнёра требуют ручной проверки из-за неподтверждённых параметров заказа.
• Локальный сервис показывает предварительный прогноз по архивам партнёра, но не разрешает утверждать или выгружать заказ до завершения проверки параметров.

Основное публичное демо для жюри: https://kaz-ai-hackalem.vercel.app/

Дополнительные стенды команды: расширенный публичный режим и проверка 5/5, приватная аналитика партнёра (требует отдельного доступа). Для проверки основного решения достаточно публичного демо и этого репозитория.

Лист приёмки и недостающие данные фиксирует обязательные проверки, требуемые подтверждения от заказчика и открытый вопрос формата импорта в 1С.

Техническое задание

Запуск

Нужен Python 3.11+. Для синтетического режима внешние пакеты не нужны.

python3 -m kaz_ai

Откройте http://127.0.0.1:8765/. Без аргументов запускается синтетический набор: 12 товаров, 1 537 операций, 5 вымышленных ID клиентов, 32 месяца истории. Продажи с ID клиентов можно скачать из интерфейса или по адресу /api/synthetic-sales.csv.

В наборе есть проверяемые сценарии: сезонность, рост, 22 дня дефицита в сентябре 2025 года, товары в пути и заказ 900 единиц клиента DEMO-C017 в мае 2025 года. Последний исключается из регулярного спроса по товару DEMO-A202; это видно в объяснении рекомендации. Один товар специально оставлен без текущего остатка, чтобы показать блокировку количества заказа до ручного ввода.

Для локальной проверки отдельных архивов предусмотрен приватный режим. Архивы должны оставаться вне репозитория; он требует pip install -r requirements.txt:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m kaz_ai \
  --iek "/путь/к/первому.zip" \
  --systeme "/путь/к/второму.zip" \
  --as-of 2026-09-22

Можно передать один архив. --as-of — дата среза остатков, а не сегодняшняя дата. Если дата среза отличается от даты остатка, сервис не выдаёт утверждаемое количество до ввода актуального остатка. Интерфейс слушает только 127.0.0.1; порт меняется через --port.

Методика расчёта

1. История содержит месячные продажи и детальные операции с ID клиента. В синтетическом наборе сумма операций за месяц совпадает с месячными продажами. В базовую историю входят только закрытые месяцы.
2. Разовый крупный заказ ищется по ID клиента; если ID отсутствует, используется номер документа. Событие исключается, только когда его доля велика, месяц выглядит аномальным и сумма деталей согласуется с месячной историей. Дополнительная проверка ограничивает изолированный месячный всплеск; повторяющийся сезонный пик не исключается. В рекомендации указывается ID клиента и исключённое количество.
3. Для месяца с подтверждёнными днями отсутствия товара продажи пересчитываются на доступные дни с ограничением величины оценки. Если точных дней нет, нулевой начальный остаток и низкие продажи дают лишь помеченную оценку упущенного спроса.
4. База — среднее скорректированных продаж за последние 12 закрытых месяцев. Сезонный коэффициент рассчитывается из помесячных количеств товара; для разреженной истории он смешивается с профилем категории или поставщика. Устойчивый рост оценивается сравнением последних двух полугодий; при наличии коэффициента роста в источнике оба сигнала смешиваются с ограничением экстремальных значений.
5. Прогноз складывается по дням с сезонным коэффициентом каждого месяца. Целевой период равен выбранному покрытию + сроку поставки + страховому запасу в днях. Потребность = прогноз на целевой период − свободный остаток − товары в пути, прибывающие до конца периода. Положительная потребность округляется вверх до кратности заказа.
6. Срочность показывает риск нехватки товара до ближайшей поставки: прогноз спроса за срок поставки сравнивается с остатком и поступлениями в этот срок.

Каждая строка показывает прогноз, свободный остаток, ожидаемые поступления, рост, кратность и величину исключённых всплесков или восстановленного спроса. Для позиций с риском показана оценка дефицита до поставки в штуках. Горизонт 30 дней — пользовательский сценарий. В публичном демо сроки поставки (12 и 21 день) и страховой запас (4–7 дней) вымышлены. Для архивов партнёра срок по умолчанию отсутствует и это явно отмечается в рекомендации.

Контроль расчёта на обзоре

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

Происхождение параметров

Срок поставки, страховой запас, MOQ и закупочная цена имеют отдельные статусы: confirmed, user_input, assumption или missing. API возвращает их в parameter_trace, а terms_readiness показывает, можно ли вынести количество на ручное утверждение. Сценарные цены дают оценочную стоимость, но не становятся подтверждёнными коммерческими условиями. Статус user_input поддерживается расчётным ядром, однако форма ввода этих параметров в текущем интерфейсе ещё не реализована. Подробное описание модели.

Ограничения данных

Поле	Состояние	Поведение прототипа
ID клиента	Синтетический набор содержит ID у каждой операции	Крупный заказ DEMO-C017 явно исключён из регулярного спроса.
Дни дефицита	В синтетическом наборе для одного месяца задано число дней без товара	Спрос за недоступные дни оценивается с ограничением величины.
Сроки поставки и страховой запас	Значения партнёра не предоставлены	В синтетическом примере используются вымышленные сроки и запас. При импорте архивов невыданный срок помечается; даты партий в пути учитываются отдельно.
Свободный остаток	Для одного демонстрационного товара отсутствует	Количество заказа скрыто до ручного ввода остатка на дату среза.
Формат импорта в 1С	Не предоставлен	CSV содержит код товара и поля заказа; совместимость с конкретным импортом 1С пока не подтверждена.

Если используются архивы партнёра, их детальные продажи могут не содержать ID клиента и точных периодов дефицита. В этом режиме интерфейс показывает предупреждения, а оценки по неполным данным следует проверять вручную. Денежные агрегаты из вкладок «Сезонность» не подставляются в прогноз количества.

Утверждение и экспорт

На синтетическом наборе выберите позиции, измените количество с соблюдением кратности и нажмите «Утвердить выбранные». После этого доступен общий CSV или CSV отдельного поставщика в UTF-8 с BOM и разделителем ;. Карточки поставщиков показывают рекомендованные и утверждённые позиции. Действия закупщика записываются в журнал. В локальном Python-сервисе утверждения, вручную введённые остатки и журнал хранятся в .local/, которое исключено из Git. Они привязаны к версии синтетического набора или к конкретным архивам и дате среза. Изменение остатка сбрасывает прежнее утверждение для этого артикула. Для архивов партнёра интерфейс оставляет предварительный прогноз доступным для проверки, но в текущем UI нет ввода недостающих условий закупки, поэтому такие строки нельзя утвердить или выгрузить. Расчётное ядро и серверная проверка допускают разблокировку только после явного подтверждения срока поставки, страхового запаса и MOQ; сервис ничего не отправляет поставщику.

Публичное демо

Открыть KAZ-AI — статическая версия только с вымышленными товарами, операциями и ID клиентов. Утверждения, введённые остатки и журнал действий сохраняются в localStorage этого браузера. Они не передаются на сервер и не синхронизируются между устройствами. CSV формируется в браузере.

Интерфейс разделён на пять страниц: «Обзор», «Рекомендации», «Поставщики», «История» и «Настройки». Аналитический блок добавлен в наш существующий дизайн; расширенный стенд команды остаётся отдельным. На странице «Настройки» можно выбрать русский или казахский язык, горизонт покрытия, поставщика и фильтр «только к заказу». Выбор сохраняется в браузере и применяется при следующем открытии рекомендаций. На телефоне позиции показаны карточками. Утверждённые решения доступны после перехода между страницами. Цвета и текстовое название заказчика в шапке отсылают к сайту ГК «Электрокомплект». Исходные названия и коды товаров в CSV сохраняются для совместимости с учётными данными.

План ЛК сотрудников и мобильного приложения описывает приглашения, роли, серверный API, будущую PWA и черновик схемы базы. Это проект следующего этапа; в конкурсном демо настоящей авторизации и общей базы нет.

План интеграции с 1С описывает возможный REST обмен и сервисный API ключ. Реального подключения к 1С пока нет; формат обмена должен подтвердить заказчик.

Вариант Telegram-бота описывает уведомления и просмотр срочных позиций с привязкой к ЛК. Бот и Mini App пока не созданы: публичное демо не имеет общей серверной БД и авторизации.

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

Собрать и проверить статическую версию локально:

python3 -m scripts.build_static_demo
python3 -m scripts.check_public_bundle
python3 -m http.server 8767 --directory site

Публикация текущего содержимого site/ вручную: cd site && npx vercel deploy --prod. Автоматическая публикация изменений из Git пока не настроена.

Проверка прогноза

python3 -m kaz_ai.backtest

Отчёт содержит воспроизводимый помесячный бэктест за январь 2025 — август 2026: 240 прогнозов, WAPE 9,1% против 19,9% у простого среднего сырых продаж за последние 12 месяцев. Для каждого прогноза используются только месяцы, завершённые к дате расчёта. Проверка выполнена исключительно на сконструированных синтетических сценариях; она не показывает ожидаемую точность на данных партнёра.

Проверка требований

python3 -m unittest discover -s tests -v

Тесты проверяют влияние входных факторов на результат, сезонность и рост, восстановление спроса при дефиците, исключение крупной покупки одного клиента, согласованность синтетических операций с месячными продажами, группировку по поставщику, срок и страховой запас, MOQ, происхождение параметров, оценочную стоимость, блокировку неподтверждённых условий, утверждение и журнал действий.

Дополнительный аналитический стенд можно собрать из файлов этого репозитория без исходных Excel. Первая команда обновляет локальный supply_control/site/dist/, вторая готовит отдельный очищенный каталог supply_control/site/public-dist/ для публичного просмотра:

python3 supply_control/scripts/build_integrated_site.py
python3 supply_control/site/scripts/build_public_demo.py
python3 -m http.server 8768 --directory supply_control/site/public-dist

Откройте http://127.0.0.1:8768/. Для тестов модуля supply_control/ дополнительно установите его зависимости (python3 -m pip install -e ./supply_control) и запустите python3 -m unittest discover -s supply_control/tests -t supply_control -v. Исходные Excel и ZIP в репозиторий не добавляются. Проверка импорта исходных файлов без них пропускается. Для развёртывания с реальными данными потребуется отдельная проверка защиты данных, пользователей и формата интеграции с 1С.