Nexus Автозаказ

Автоматический расчёт заказов поставщикам для пополнения склада. Кейс ТОО «Электрокомплект» (ekt.kz), хакатон HackAlem AI, трек «Логистика».

Живой деплой: https://nexus-electrokomplekt.vercel.app/replenishment

1. Проблема

Менеджер отдела закупа ТОО «Электрокомплект» сегодня вручную считает пополнение склада в Excel: сводит историю продаж, остатки и товар в пути по каждому артикулу. Это трудоёмко, поэтому расчёт проводится нечасто и не в реальном времени — отсюда избыточные запасы по одним позициям и дефицит по другим. Разовые крупные заказы (в том числе продажа большого объёма одному клиенту) искажают расчёт регулярной потребности и дополнительно портят картину.

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

Сервис читает исходные книги обоих поставщиков (IEK и Systeme Electric), считает по каждому SKU регулярный спрос очищенным от аномалий способом и выдаёт конкретную рекомендацию — сколько и у какого поставщика заказать, с числовым обоснованием и меткой срочности.

Все пять официальных обязательных требований кейса реализованы и покрыты отдельными тестами:

1. Расчёт использует все источники данных — историю продаж, остатки, товар в пути, категорию, внешний прогноз прироста; изменение любого из них меняет результат (проверено тестами по каждому источнику отдельно).
2. Сезонность и устойчивый рост — сезонный индекс считается отдельно для каждого будущего календарного месяца горизонта поставки и периода пересмотра, плюс ограниченный (±50%) исторический тренд, комбинированный с внешним прогнозом.
3. Компенсация упущенного спроса при дефиците — месяцы с околонулевым остатком, ненулевым спросом в соседних периодах и действительно подавленными текущими продажами исключаются из знаменателя среднего, а не считаются нулевым спросом.
4. Исключение разовых крупных заказов — на уровне накладной/SKU (строки одной накладной агрегируются), устойчивой статистикой (медиана + MAD/IQR, не среднее и стандартное отклонение, которые сами чувствительны к выбросам).
5. Итоговый список по поставщикам с обоснованием и срочностью — каждая строка сопровождается числовым разбором (спрос, сезонность, рост, поправка на дефицит, исключённые всплески, остаток, резерв, товар в пути, страховой запас) и меткой high/medium/low.

Дополнительно, по итогам сверки с партнёром реализовано сверх изначального минимума:

• Страховой запас от статистической волатильности спроса, а не фиксированная доля от среднего: z(уровень_сервиса) × σ(спрос) × √(срок_поставки + период_пересмотра), с уровнем сервиса по категории (98% / 95% / 90%).
• Резервы под клиентов вычитаются из доступного остатка там, где эти данные есть (Остаток − Резерв).
• Повторные крупные заказы отличаются от разовых всплесков: если аномально крупные продажи повторяются минимум в двух разных месяцах за последние 3 месяца — это устойчивый сдвиг спроса, а не выброс, и такие продажи остаются в расчёте (а не исключаются). Одиночный крупный заказ по-прежнему исключается как и раньше.
• Классификация типа спроса — стабильный / волатильный / прерывистый (по доле ненулевых периодов и коэффициенту вариации). Для прерывистого спроса отключены сезонный коэффициент и краткосрочный тренд — на малой выборке ненулевых периодов они дают ложные скачки, а не реальный сигнал.
• Консервативный учёт неизвестного ETA: товар в пути без даты показывается менеджеру отдельным риском, но не уменьшает заказ и не снижает срочность, пока дата прихода не подтверждена.
• Актуализация остатка: для Systeme Electric используется фактический снимок Остаток из dashboard; для IEK, где такого снимка нет, последний начальный остаток прозрачно переносится на расчётную дату вычитанием продаж с начала периода.
• Проверка и подтверждение менеджером — по каждой позиции можно изменить количество и подтвердить его (MOQ применяется в момент подтверждения); рассчитанная системой рекомендация при этом не перезаписывается и остаётся видна отдельно. Подтверждённые позиции выгружаются в консолидированный CSV Purchase Order по поставщикам; отправки заказа поставщику без человека нет.
• Редактируемые допущения — срок поставки, период пересмотра, внешний прогноз прироста и уровни сервиса категорий доступны непосредственно перед запуском расчёта.
• Фильтры по срочным заказам, аномалиям спроса, рискам поставки и избытку остатков.
• Опциональное LLM-обоснование поверх уже посчитанных чисел (кнопка «Получить объяснение от ИИ» на каждой строке) — LLM только формулирует текст на русском, не пересчитывает и не изменяет ни одного числа.

3. Как это работает

Загрузка 10 XLSX-файлов (5 на поставщика) → парсинг в браузере
  → нормализация в общую структуру (lib/nexus/replenishment/assemble.ts)
  → детерминированный расчёт (lib/nexus/replenishment/calculation.ts)
  → таблица рекомендаций по поставщикам
  → (опционально, по клику) LLM-обоснование через серверный API-роут

Весь расчёт выполняется в браузере пользователя — файлы не отправляются ни на какой сервер, парсинг и вычисления идут локально в JavaScript. Единственный сетевой запрос — опциональный вызов /api/replenishment/narrate, и только когда пользователь явно нажимает кнопку «Получить объяснение от ИИ» по конкретной строке; это осознанное архитектурное решение: секретный OPENAI_API_KEY не может присутствовать в клиентском коде, поэтому эта единственная функция реализована как серверный маршрут, а не как прямой вызов из браузера.

Формула пополнения:

target_position = сумма прогноза по будущим сезонным месяцам горизонта × рост + страховой_запас
current_position = max(0, остаток − резерв) + товар_в_пути_в_горизонте
рекомендуемый_заказ = max(0, target_position − current_position), округлено до кратности MOQ

4. Технологии и архитектура

• Стек: Next.js 15 / React 19 / TypeScript, без внешних UI-библиотек.
• Парсинг XLSX: библиотека xlsx, весь разбор — в браузере (lib/nexus/replenishment/xlsxParsers.ts).
• Расчёт: чистые детерминированные функции без побочных эффектов (lib/nexus/replenishment/calculation.ts), 0 зависимостей от LLM — воспроизводимо и тестируемо байт в байт.
• LLM-обоснование (опционально): OpenAI Responses API (gpt-5-mini по умолчанию, OPENAI_MODEL переопределяемо), серверный маршрут app/api/replenishment/narrate, со строгой JSON-схемой ответа и явным fallback (никогда не 500-я ошибка) при отсутствии ключа/таймауте/некорректном ответе модели.
• Границы клиент/сервер: components/replenishment/ReplenishmentWorkspace.tsx — весь клиентский код (парсинг, расчёт, UI); app/api/replenishment/narrate/route.ts + lib/nexus/replenishment/narration.ts — единственное место, где на сервере используется API-ключ.

Этот кейс построен поверх переиспользуемой инфраструктуры (харнесс) — что именно унаследовано и что написано заново для этого кейса, см. раздел «Disclosure» ниже и приложение в конце файла.

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

Требуется Node.js (проверено на Node 24).

npm install
npm run dev

Открыть http://localhost:3000/replenishment.

Продакшен-сборка (именно так собирается деплой на Vercel):

npm run build
npm run start

6. Как проверить сценарий

1. Открыть /replenishment (локально или на живом деплое выше).
2. Для каждого из двух поставщиков загрузить соответствующие 5 файлов из demo/data/replenishment/iek/ и demo/data/replenishment/systeme-electric/ в поля с такими подписями: «Динамика продаж» → sales_transactions.xlsx, «Продажи по месяцам» → monthly_sales.xlsx, «Остатки по месяцам» → monthly_stock.xlsx, «Товар в пути» → inbound_shipments.xlsx (у IEK) / inbound_dashboard.xlsx (у Systeme Electric), «MOQ / кратность» → moq.xlsx.
3. Нажать «Рассчитать заказы →».
4. При необходимости изменить срок поставки, период пересмотра, внешний прогноз или целевые уровни сервиса в блоке «Плановые допущения».
5. Появится таблица по каждому поставщику: артикул, рекомендуемое количество, срочность, покрытие в месяцах. Раскрыть «Показать расчёт» у любой строки — видно полное числовое обоснование.
6. После проверки скорректировать и подтвердить нужные позиции, затем скачать консолидированный PO CSV. Опционально нажать «Получить объяснение от ИИ» — требуется OPENAI_API_KEY.

Это реальные данные партнёра (не синтетика) — с ними легко напрямую проверить каждый из 5 обязательных критериев (см. раздел 2).

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

• Данные: реальные выгрузки партнёра (ТОО «Электрокомплект») по двум поставщикам — IEK и Systeme Electric, включены в репозиторий в demo/data/replenishment/ (это официальные материалы кейса, не синтетика; персональных данных клиентов в них нет — история продаж не содержит поля с идентификатором клиента вообще).
• Внешние сервисы: OpenAI Responses API — опционально, только для текстового обоснования; сам расчёт не зависит от него ни в каком виде.

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

Честно, без приукрашивания:

• Нет поля «клиент» в истории продаж — вопреки исходному ТЗ, в реальных данных партнёра такого поля нет вообще. Детекция разовых крупных заказов работает по аномальному размеру отдельной транзакции, а не по привязке к конкретному клиенту.
• Нет явного индикатора дефицита (stockout) — ни в одном исходном файле такой отметки нет. Период дефицита выводится эвристически: месяц с остатком около нуля при ненулевом спросе в соседних месяцах.
• Нет источника срока поставки по SKU/поставщику в предоставленных файлах — используется явно показанное и редактируемое перед расчётом допущение (по умолчанию 2 месяца).
• Резервы под клиентов и категория товара есть только у Systeme Electric (в файле «Товар в пути») — у IEK такого источника нет, резерв по умолчанию 0, категория — UNCLASSIFIED с нейтральным уровнем сервиса 95%.
• Внешний прогноз прироста спроса («прогноз по приросту» из ТЗ) не имеет отдельного источника данных от партнёра — по умолчанию 0 (полагаемся только на историческую сезонность и тренд), значение редактируется перед расчётом.
• Бюджет закупки и загрузка транспорта — не реализованы (не входили в обязательные требования кейса; в требованиях упоминались только MOQ/условия поставщика, что реализовано).
• LLM-обоснование — опциональное улучшение поверх уже вычисленного результата; при недоступности модели интерфейс молча остаётся на детерминированном тексте, который уже полностью удовлетворяет требованию «каждая строка сопровождается обоснованием» сам по себе.

9. Disclosure: что подготовлено до соревновательной части

Согласно Положению §6.4 (обязательное раскрытие использования ранее созданного кода) — этот проект построен поверх переиспользуемой, доменно-нейтральной инфраструктуры («харнесс»), подготовленной командой заранее с помощью Claude Code (AI-агент для разработки; разрешено согласно §6.9):

• Next.js-каркас приложения и конфигурация деплоя.
• Слой приёма данных: разбор CSV/XLSX (устойчивый к кавычкам, многолистовой, с учётом русских форматов дат, разделителей тысяч и локализованных заголовков) — общие утилиты, на которых также построен новый парсер XLSX-книг Электрокомплекта.
• Агентный паттерн (LLM выбирает/формулирует, никогда не вычисляет) и транспортный слой вызова LLM с таймаутами/ретраями/аудитом (lib/nexus/agentic/llmRequest.ts) — переиспользован для опционального LLM-обоснования в этом кейсе.
• Универсальный статистический движок и Domain Registry — не используются напрямую в расчёте этого кейса (задача не инвестигационная, а расчётная), но их код остаётся в репозитории как часть заявленного харнесса.

Никакой доменной бизнес-логики, датасета или решённого кейса в этой базе не было. Всё, что относится непосредственно к решению — парсинг реальных книг Электрокомплекта, нормализация данных, формула пополнения, сезонность, компенсация дефицита, исключение всплесков, страховой запас от волатильности, учёт резервов, страница /replenishment, LLM-обоснование — построено во время соревновательной части. Коммиты в этом репозитории с официального старта отражают эту работу.

10. Команда

Один участник.

---

Приложение: базовый харнесс (подготовлен заранее, раскрыт выше)

Ниже — краткое описание переиспользуемой инфраструктуры, на которой построен этот кейс. Она была спроектирована как доменно-нейтральный движок для расследования аномалий (LLM Investigator/Skeptic поверх детерминированной статистики) — терминология «risk investigation» ниже относится именно к этому базовому слою, а не к текущему кейсу пополнения склада, который является отдельным детерминированным расчётным модулем.

• Назначение движка: загруженный табличный датасет профилируется, маршрутизируется по форме данных (TIME_SERIES/CROSS_SECTIONAL/EVENT_TRANSACTION/AMBIGUOUS_TABULAR), и по нему проводится ограниченное объяснимое расследование: LLM-Investigator выбирает, какой детерминированный инструмент запустить, каждый вызов возвращает EvidenceRecord, LLM-Skeptic оспаривает гипотезу, отдельный валидатор независимо пересчитывает весь артефакт из сырых данных и сверяет хэш. Причинность никогда не устанавливается — только заявляется как гипотеза.
• Инвариант: LLM решает, что проверить и как сформулировать вывод; детерминированный код считает каждое число. Валидатор никогда не доверяет заявленному агентом числу — только собственному пересчёту.
• Domain Registry (lib/nexus/domains/) — словарные записи (без бизнес-логики) для RETAIL, LOGISTICS, MANUFACTURING, MINING.
• Живой маршрут расследования: /investigate — доступен в этом репозитории как часть заявленного харнесса, но не является решением текущего кейса.

Полная документация базового харнесса: docs/methodology.md (статистика), docs/task-adaptation-harness.md (процедура адаптации под новую задачу).

Переменные окружения

OPENAI_API_KEY=      # опционально; включает LLM-обоснование в /replenishment и живой агентный цикл в /investigate
OPENAI_MODEL=        # опционально; по умолчанию gpt-5-mini

Без OPENAI_API_KEY приложение полностью работает — расчёт пополнения детерминирован и не зависит от LLM ни в каком виде; /investigate переходит на явно помеченный детерминированный fallback. .env.local никогда не коммитится (исключён через .gitignore).

Тесты и проверка

npm test          # node --test lib/**/*.test.ts
npm run typecheck # tsc --noEmit
npm run lint      # eslint .
npm run build     # next build

Docker

Приложение запускается одним контейнером: Next.js одновременно раздаёт frontend и обслуживает API routes. База данных и дополнительные сервисы не требуются.

1. При необходимости скопируйте .env.example в .env и задайте OPENAI_API_KEY. Ключ опционален: без него расчёт и детерминированные объяснения продолжают работать.
2. Соберите и запустите приложение:

docker compose up --build

Интерфейс будет доступен на http://localhost:3000, healthcheck — на http://localhost:3000/api/health. Для другого порта задайте NEXUS_PORT, например NEXUS_PORT=8080 docker compose up --build.

Переменные окружения:

OPENAI_API_KEY=  # опционально, только для LLM-обоснования
OPENAI_MODEL=    # опционально, по умолчанию gpt-5-mini
NEXUS_PORT=      # опционально, внешний порт Docker Compose; по умолчанию 3000

Остановка:

docker compose down

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

Vercel

Живой деплой уже развёрнут по ссылке в начале файла. Чтобы развернуть свою копию:

Вариант A — через Vercel CLI (не требует прав на этот GitHub-репозиторий):

npm install -g vercel
vercel login
vercel --prod --yes

Команда собирает и разворачивает текущую папку напрямую, без привязки к GitHub. После первого запуска добавьте переменную окружения (если нужен LLM):

vercel env add OPENAI_API_KEY production

и выполните vercel --prod --yes повторно, чтобы переменная подхватилась.

Вариант B — импорт репозитория через vercel.com: New Project → Import Git Repository → выбрать этот репозиторий → Deploy. Next.js определяется автоматически, дополнительная настройка не требуется. OPENAI_API_KEY/OPENAI_MODEL — опционально, в Project Settings → Environment Variables.

Оба варианта разворачивают идентичное приложение — то же самое, что запускается локально (npm run dev) или в Docker.

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

app/replenishment/            Страница кейса: загрузка файлов, таблица рекомендаций
app/investigate/              Живой маршрут базового харнесса (не относится к текущему кейсу)
app/api/replenishment/narrate/ Серверный маршрут LLM-обоснования (единственное место с API-ключом)
components/replenishment/     UI кейса
lib/nexus/replenishment/      Парсинг, сборка входа, детерминированный расчёт, LLM-обоснование
demo/data/replenishment/      Реальные данные партнёра (IEK, Systeme Electric) для воспроизводимости
lib/engine/, lib/nexus/agentic/, lib/nexus/domains/, ...  Базовый харнесс (см. приложение выше)
docs/                         Методология и документация адаптации харнесса