Pairadox

Краткое описание

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

Проект решает проблему непрозрачных закупочных рекомендаций: вместо одного итогового числа пользователь видит прогноз спроса, текущий остаток, товары в пути, страховой запас, кратность заказа, приоритет и риск.

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

• загрузка рекомендаций из FastAPI backend;
• таблица рекомендаций с постраничным просмотром по 50 товаров;
• поиск по SKU и доступным полям ответа API;
• отображение прогноза, остатка, товаров в пути, страхового запаса и рекомендуемого заказа;
• приоритеты critical, high, medium и low;
• категории риска backend;
• панель с объяснением расчёта выбранного товара;
• сравнение сценариев с включением и отключением исключения аномалий, коррекции stockout, сезонности и тренда роста;
• отдельный график прогнозируемого спроса;
• раздел контроля качества данных и ограничений расчёта;
• экспорт отфильтрованных рекомендаций в CSV;
• состояния загрузки, ошибки backend и повторная попытка подключения.

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

1. Backend загружает предоставленные Excel-файлы IEK и нормализует продажи, остатки, товары в пути, кратность заказа и сезонность.
2. Аналитический pipeline рассчитывает прогноз спроса, потребность на срок поставки, страховой запас и рекомендуемое количество заказа.
3. Frontend запрашивает рекомендации страницами через GET /recommendations и показывает их в закупочном рабочем пространстве.
4. Пользователь выбирает SKU и проверяет составляющие базового расчёта.
5. При необходимости пользователь меняет параметры сценария. Frontend отправляет их в POST /counterfactual, после чего показывает сравнение с базовой рекомендацией.
6. Пользователь может скачать текущий отфильтрованный список в CSV.

Технологии

• Python;
• FastAPI;
• Uvicorn;
• pandas;
• NumPy;
• SciPy;
• scikit-learn;
• statsmodels;
• openpyxl;
• React 19;
• TypeScript;
• Vite;
• CSS и SVG-графика;
• Git и GitHub.

Внешние AI API, API-ключи и база данных для запуска проекта не требуются.

Архитектура проекта

hackathon_alemai/
├── backend/
│   ├── main.py                 # FastAPI-приложение и API-маршруты
│   ├── config.py               # пути к файлам и параметры расчёта
│   ├── models/schemas.py       # схемы API
│   └── services/               # загрузка данных и аналитический pipeline
├── data/IEK/                  # исходные Excel-файлы IEK
├── frontend/
│   ├── src/App.tsx             # интерфейс рабочего пространства
│   ├── src/App.css             # стили интерфейса
│   ├── src/services/api.ts     # frontend-адаптер API
│   └── vite.config.ts          # локальный proxy /api → backend
├── requirements.txt
└── README.md

Frontend и backend запускаются как два процесса. В режиме разработки Vite перенаправляет запросы /api на http://127.0.0.1:8000.

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

Требования: macOS или Linux, Python 3.10+, Node.js 20.19+ или 22.12+, npm и Git.

Скачайте репозиторий и перейдите в его корень:

git clone https://github.com/BAITC-Hacks/hack-866564aa-pairadox.git
cd hack-866564aa-pairadox

Создайте окружение Python, установите зависимости и запустите backend в первом терминале:

python3 -m venv .venv/mac
source .venv/mac/bin/activate
python -m pip install -r requirements.txt
python -m uvicorn backend.main:app --reload --port 8000

Дождитесь сообщения Application startup complete.. Первый запуск читает Excel-файлы и может занять несколько минут. Терминал backend должен оставаться запущенным.

Во втором терминале установите frontend-зависимости и запустите Vite:

cd frontend
npm install
npm run dev

Откройте адрес, который напечатает Vite, обычно http://localhost:5173.

Для production-проверки frontend:

npm run build

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

1. Убедитесь, что backend сообщает Application startup complete..
2. Откройте адрес Vite и дождитесь статуса Backend connected.
3. Откройте раздел Recommendations и выберите строку товара.
4. Сверьте в правой панели месячный прогноз, потребность на срок поставки, страховой запас, остаток, товары в пути и рекомендуемый заказ.
5. В блоке Compare a scenario отключите один параметр, например Exclude one-off anomalies, и нажмите Calculate scenario.
6. Сравните новый результат с базовой рекомендацией. Базовая цифра в таблице сохраняется отдельно от сценарного результата.
7. Выполните поиск по SKU и нажмите Export CSV, чтобы проверить экспорт отфильтрованных строк.
8. Откройте раздел Forecasts, выберите другой SKU и проверьте прогнозные точки.
9. Откройте раздел Data quality, чтобы увидеть допущения и ограничения исходных данных.

Данные и API

Backend использует файлы из data/IEK/:

• динамика продаж с датами документов;
• ежемесячные продажи;
• ежемесячные остатки;
• MOQ и кратность отгрузки;
• товары в пути;
• коэффициенты сезонности.

Основные маршруты:

• GET /health — состояние API и количество рассчитанных рекомендаций;
• GET /recommendations — рекомендации с фильтрами и пагинацией;
• GET /recommendations/{sku} — детали товара и прогнозы;
• POST /counterfactual — сравнение сценария по query-параметрам;
• GET /suppliers — сводка по поставщикам;
• GET /export?format=csv или GET /export?format=xlsx — экспорт backend-данных.

Frontend использует локальный proxy /api, поэтому в обычной локальной установке отдельный адрес API указывать не нужно.

Ограничения

• Backend в текущей конфигурации обрабатывает набор IEK.
• Исходные данные — снимки Excel, а не подключение к системе склада в реальном времени.
• Срок поставки по умолчанию задан как один месяц; уровень обслуживания — 95%. Это параметры планирования, а не измеренная статистика поставщика.
• Количество товаров в пути суммируется; frontend отдельно не проверяет, успеет ли каждая поставка прибыть в срок заказа.
• Месячные пустые значения нормализуются backend в ноль; последний доступный период может быть неполным.
• Отрицательные месячные значения сохраняются, а транзакционные количества для прогнозирования приводятся к модулю.
• Категория риска является эвристической оценкой, а не калиброванной вероятностью дефицита.
• Исторические продажи не вынесены в отдельный frontend endpoint; раздел Forecasts показывает прогнозные точки backend.
• Точность прогноза и экономический эффект не оцениваются на отдельном контрольном наборе.
• Внешняя deployed-версия проекта не используется; запуск выполняется локально.