HackAlem AI — объяснимые рекомендации к заказу поставщикам

HackAlem AI — demo-MVP для менеджера по закупкам. Сервис помогает подготовить пополнение ассортимента у поставщиков IEK и Systeme Electric: показывает рекомендованное количество по SKU, срочность и понятную расшифровку расчёта.

Какую проблему решает

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

Целевая аудитория — закупщик или менеджер по ассортименту, который готовит заказ поставщику и отвечает за его проверку.

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

• Расчёт рекомендаций для двух поставщиков: IEK и Systeme Electric.
• Параметры расчёта: дата, горизонт планирования, срок поставки, ожидаемый рост спроса и переключатель коррекции дефицита.
• Рекомендации, сгруппированные по поставщику: SKU, наименование, количество к заказу и уровень срочности.
• Расшифровка каждой рекомендации: базовый спрос, сезонность, тренд, корректировка дефицита, остаток, товар в пути, целевой спрос и кратность заказа.
• Ручная правка целого неотрицательного количества и CSV-экспорт после явного подтверждения пользователя. Любая новая правка требует повторного подтверждения; заказ поставщику автоматически не отправляется.
• Версионированный HTTP API и Swagger UI.
• Автоматические backend-тесты и production-сборка frontend.

Как работает решение

1. Менеджер выбирает поставщика и задаёт параметры расчёта.
2. Frontend отправляет запрос в POST /api/v1/replenishment/calculate.
3. Backend загружает синтетический fixture MVP и для каждого SKU рассчитывает средний спрос, применяет сезонный и трендовый коэффициенты, явно заданную коррекцию дефицита и ожидаемый рост.
4. Потребность на большем из горизонта планирования и срока поставки уменьшается на остаток и товар в пути, затем округляется вверх до кратности.
5. Пользователь видит результат и его факторы, при необходимости меняет количество, подтверждает подготовку заказа и выгружает CSV.

Дата расчёта в текущем MVP выбирает месяц для сезонного коэффициента и возвращается в ответе. Она пока не выбирает исторический снимок остатков или товара в пути.

Технологии

Область	Используется
Backend	Python 3.14, FastAPI, Uvicorn, Pydantic Settings
Frontend	React 19, TypeScript, Vite 7
Контракт API	OpenAPI 3.0.3 (api/openapi.yaml)
Работа с Excel	openpyxl подключён для будущего импорта; runtime-MVP Excel пока не импортирует
Контейнеризация	Docker Compose, Python slim, Node.js 24, Nginx
Тестирование	pytest, FastAPI TestClient
AI-модели, внешние API, база данных	В текущем MVP не используются

Архитектура

Браузер
   │ http://localhost:5173
   ▼
React / Vite frontend ── POST /api/v1/replenishment/calculate ──► FastAPI backend
                                                                     │
                                                                     ▼
                                              data/demo/replenishment_demo.json
                                              (синтетический fixture MVP)

• frontend/ — пользовательский интерфейс и CSV-экспорт в браузере.
• backend/ — API и детерминированный расчёт рекомендаций.
• api/openapi.yaml — единственный публичный контракт между frontend и backend.
• data/demo/ — versioned synthetic данные для демонстрации и тестов.
• IEK/ и Systeme electric/ — read-only исходные Excel-книги партнёров.
• docs/ — методика, сценарий демо, приемочные проверки и описание данных.

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

Вариант 1. Docker Compose — рекомендуемый

Требуется Docker Desktop с запущенным Docker Engine.

# Выполняйте из корня клонированного репозитория
Copy-Item .env.example .env
docker compose up --build

Если .env уже создан, повторно копировать его не нужно. После запуска:

• приложение: http://localhost:5173
• Swagger UI: http://localhost:8000/docs
• healthcheck: http://localhost:8000/health

Для запуска в фоне используйте docker compose up --build -d; остановка — docker compose down.

Вариант 2. Запуск без Docker

Требуются Python 3.14+ и Node.js 24+ с npm. Команды backend запускайте из корня репозитория, а не из каталога frontend/.

Терминал 1:

# Выполняйте из корня клонированного репозитория
Copy-Item .env.example .env
py -m venv backend/.venv
backend/.venv/Scripts/python.exe -m pip install -r backend/requirements.txt
backend/.venv/Scripts/python.exe -m uvicorn app.main:app --app-dir backend --reload --port 8000

Терминал 2:

Set-Location frontend
npm.cmd install
npm.cmd run dev

На Windows используйте npm.cmd, если PowerShell блокирует npm.ps1 политикой выполнения.

Как проверить решение

1. Откройте http://localhost:5173.
2. Выберите IEK, укажите дату 2026-09-22 и оставьте остальные параметры по умолчанию. Нажмите «Рассчитать заказ».
3. Откройте расчёт IEK-001: в нём видны сезонный коэффициент, коррекция дефицита, текущий остаток, товар в пути и кратность.
4. Измените дату на январь и пересчитайте: для IEK-001 изменятся сезонный коэффициент и целевой спрос.
5. Переключитесь на Systeme Electric: отобразится отдельная группа SKU с другой кратностью заказа.
6. Измените количество в карточке, отметьте подтверждение и нажмите «Экспортировать CSV». Экспорт допускает только целое неотрицательное количество; без подтверждения или после новой правки он блокируется.

Дополнительно можно проверить API через Swagger UI или командами:

backend/.venv/Scripts/python.exe -m pytest backend/tests -q
Set-Location frontend
npm.cmd run build

Полный сценарий доступен в docs/demo-script.md, а критерии готовности — в docs/acceptance-tests.md.

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

Работающее приложение читает только data/demo/replenishment_demo.json — синтетический набор с датой и отметкой происхождения. В нём есть продажи, сезонные коэффициенты, остаток, товар в пути, кратность и synthetic коэффициент коррекции дефицита.

Excel-книги в IEK/ и Systeme electric/ сохранены как исходный материал и не изменяются. Они содержат кандидаты на продажи, остатки, движения, MOQ/кратность, товар в пути и сезонность; их структура описана в docs/data-contract.md. В runtime-MVP эти файлы ещё не загружаются.

Внешних API, облачных сервисов, AI/LLM-моделей и базы данных нет.

Ограничения MVP

• Нет импорта и нормализации реальных Excel-данных, хранения снимков и пользовательских правок.
• Нет автоматической отправки или интеграции с поставщиками: CSV — только подготовленная выгрузка для ручного процесса.
• Периоды дефицита, срок поставки и трактовка MOQ в демо имеют явные допущения: коррекция дефицита задана в synthetic fixture, срок поставки вводит пользователь, MOQ используется как кратность округления до бизнес-подтверждения.
• В доступных исходниках отсутствуют customer ID и подтверждённые периоды дефицита. Synthetic customer-транзакция отображается в объяснении как демонстрационное допущение, но не является результатом обработки реальных клиентских данных.
• В репозитории нет deployed-версии и ссылки на публичное окружение.

Полезные материалы

• OpenAPI-контракт
• Архитектура
• Методика расчёта
• Контракт исходных данных