Tirek — рекомендации по пополнению склада

Проект команды Tirek Systems and Solutions для HackAlem AI. Кейс ТОО «Электрокомплект»: автоматический расчёт заказов поставщикам.

Tirek помогает закупщику перейти от ручного сведения Excel к списку закупок с объяснением каждой позиции. Система учитывает прогноз продаж, остатки, поступления и ограничения партии. Менеджер проверяет рекомендации, меняет количество с указанием причины, утверждает снимок заказа и скачивает CSV. Цель — уменьшить дефицит, излишки и время подготовки заказа; экономический эффект в эксплуатации пока не измерен.

Жюри: запуск · проверка за 5 минут · метрики · подробный сценарий · анализ соответствия условиям.

Что можно проверить

• Регистрацию, вход, восстановление сессии, выход и смену пароля. Каждый аккаунт получает отдельное рабочее пространство: файлы, расчёты и решения не видны другим аккаунтам.
• Встроенного помощника: локальная справка доступна без ключа; внешний ИИ подключается администратором через серверные переменные окружения.
• Обзор склада, поиск и группировку рекомендаций по поставщику, карточку товара, историю спроса, причины решения и отсутствующие данные.
• Полный демонстрационный цикл: корректировка → утверждение → экспорт → повторное скачивание сохранённого снимка.
• Импорт совместимых XLSX Systeme Electric и IEK, нормализацию, прогноз v2 и расчёт потребности при наличии подтверждённого текущего остатка и условий партии.
• Скачивание учебного ZIP в «Источниках данных»: синтетические Excel проходят настоящий расчёт, отдельно от встроенного демо с заранее подготовленными числами.
• Сохранённые веса, протокол временной проверки, сравнение с baseline и тесты бизнес-правил.

Два режима проверки: встроенное демо содержит 12 синтетических товаров и работает без партнёрских файлов и API-ключей. Его числа подготовлены заранее, forecast.method=contract_example. Реальный адаптер запускает сохранённую модель на локальных XLSX; исходные данные партнёра в Git не включены. При переданных точных интервалах stockout и обезличенных клиентских метках адаптер применяет модуль регулярного спроса к затронутым товарам; метод и поправки видны в обосновании и требуют ручной проверки. Без этого контекста используется сохранённый прогноз v2, а отсутствие данных явно указывается. В исходных партнёрских XLSX таких меток нет: это не доказательство качества коррекции на реальном бизнесе. Проверка MVP.

Быстрый запуск

Нужны Git, Python 3.12, Node.js 20.19+ и npm. Команды выполняются из корня проекта. Для первой установки зависимостей нужен интернет. Docker, внешняя база, обучение модели и ключ LLM не требуются.

git clone https://github.com/BAITC-Hacks/hack-e1c6f154-tirek-systems-and-solutions.git
cd hack-e1c6f154-tirek-systems-and-solutions

Windows / PowerShell

py -3.12 -m venv .venv-ml
.\.venv-ml\Scripts\python.exe -m pip install -r backend/requirements-ml.txt
npm --prefix frontend ci

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

.\.venv-ml\Scripts\python.exe -m uvicorn backend.app.main:app --host 127.0.0.1 --port 8000

Во втором терминале из того же корня:

npm --prefix frontend run dev

Также доступен общий скрипт ./scripts/dev.ps1: он запускает оба сервера, проверяет доступность API через Vite и сохраняет логи в .logs/. Если PowerShell запрещает выполнение скрипта, используйте две команды выше.

Linux / macOS

python3.12 -m venv .venv-ml
.venv-ml/bin/python -m pip install -r backend/requirements-ml.txt
npm --prefix frontend ci
.venv-ml/bin/python -m uvicorn backend.app.main:app --host 127.0.0.1 --port 8000

Во втором терминале: npm --prefix frontend run dev. Локальная проверка сдачи выполнялась на Windows.

Адрес	Назначение
http://127.0.0.1:5173	Приложение для жюри
http://127.0.0.1:8000/docs	Интерактивная документация API
http://127.0.0.1:8000/api/v1/health	Проверка работы API

Первый запуск автоматически создаёт SQLite. Создайте аккаунт в форме регистрации: имя, название рабочего пространства, email и пароль от 12 символов. В личном пространстве появится явно помеченный демонстрационный набор. Данные сохраняются в data/; другой каталог задаётся переменной DATA_DIR. Остановка — Ctrl+C в каждом терминале. Настройки.

Проверка за 5 минут

1. Откройте приложение, зарегистрируйтесь или войдите. Если раньше использовались другие данные, нажмите «Новый расчёт», выберите синтетический набор и стандартные параметры: 28 дней = 7 дней поставки + 21 день пересмотра.
2. В «Рекомендациях» найдите EZ9F34116 и откройте карточку: доступны история, прогноз, остаток, партия и обоснование.
3. В «Корректировке» введите 13 и причину: приложение должно отклонить количество, не кратное 12. Введите 156 и причину «Уточнён план монтажа», сохраните.
4. Отметьте позицию, нажмите «Утвердить (1)», затем «Утвердить и скачать CSV». Проверьте в файле final_quantity=156 и причину. Заказ поставщику не отправляется.
5. В «Истории решений» повторно скачайте снимок. Найдите A9R41240 в рекомендациях: неизвестный остаток показан как —, указана причина отсутствия количества.

Полный сценарий, формат CSV и проверка реальных XLSX.

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

Часть	Технологии и назначение
Интерфейс	React 19, TypeScript, Vite 7, React Router, Recharts, Radix Dialog
API и хранение	Python, FastAPI, Pydantic / JSON Schema, SQLite, фоновые задачи
Данные и прогноз	openpyxl, pandas, NumPy, SciPy, CatBoost; baseline и смеси моделей
Расчёт заказа	Python, дневные траектории, поступления, экономика, MOQ и кратность
Проверки	pytest, unittest, Playwright, OpenAPI 3.1

flowchart LR
    XLSX[Локальные XLSX] --> N[Проверка и нормализация]
    N --> F[Прогноз v2 на 28 дней]
    F --> D[Расчёт потребности]
    D --> API[FastAPI и SQLite]
    DEMO[Синтетический набор] --> API
    API <--> UI[React: проверка менеджером]
    UI --> A[Утверждённый снимок]
    A --> CSV[Экспорт CSV]

Методология

1. Источники проверяются и получают SHA-256 и версию набора. Помесячные продажи и детализация сверяются, а не складываются. Неизвестные значения остаются null.
2. Прогноз v2 оценивает положительные наблюдаемые продажи на следующие 28 дней. Методы выбирались по трём временным validation-окнам; признаки используют только прошлое, финальные веса нельзя применять к более ранним датам.
3. Расчёт учитывает свободный запас, даты поступлений, обязательства, внешний прирост и экономический профиль либо явно заданную политику категории. Неизвестные ограничения партии требуют проверки, недостаточные данные блокируют окончательное количество. Бюджет проверяется при утверждении.
4. Подключённый модуль регулярного спроса оценивает спрос по доступным дням и группирует крупные клиентские покупки в семидневные окна. Повторяемые покупки сохраняются, разовый избыток помечается и исключается из регулярной оценки без удаления исходных событий. Это эвристика; в реальной выгрузке нет точных интервалов stockout и клиентских ID для подтверждения её качества.

Проверка модели на учебных Excel

.\.venv-ml\Scripts\python.exe scripts/generate_sample_data.py --output .local-data/samples

Генератор создаёт синтетические данные с сезонностью, stockout и разовой покупкой. Это функциональный пример, а не данные партнёра или доказательство точности. Во вкладке «Источники данных» выберите Systeme Electric, загрузите шесть XLSX из .local-data/samples, вставьте содержимое additional-context.SYNTHETIC.json в дополнительный контекст и нажмите «Проверить и загрузить». Затем «Перейти к расчёту»:

• дата 22.09.2026, срок 7 дней, сценарный режим;
• категория политики: Учебная категория, квантиль 90%, явное обоснование;
• нажмите «Применить политику к расчёту», затем «Подготовить рекомендации».

Появятся четыре товара. Их числа рассчитываются моделью и правилами при запуске; готовые числа встроенного демо не используются. Откройте SYN-ONE-003: в обосновании показан исключённый разовый объём 300 шт. У SYN-OUT-002 учтён интервал отсутствия. Выберите позиции, изучите предупреждения и утвердите CSV. В снимке есть явные поля «Минимальная партия» и «Склад»; если их убрать, система запросит подтверждённые ограничения вместо скрытой подстановки.

Качество прогноза

Результаты сохранённой v2 на двух ретроспективных 28-дневных окнах:

Поставщик / единица	WAPE v2	MAE на товар × окно
Systeme Electric / шт.	33,92%	212,00
IEK / м	56,64%	257,26
IEK / упаковки	26,89%	13,77
IEK / шт.	33,30%	24,81

WAPE = Σ|прогноз − продажи| / Σпродажи; меньше — лучше. Для SE baseline v1: 37,73%, улучшение v2: 3,82 процентного пункта по неокруглённым значениям. Это ошибка объёма продаж, а не доля верных решений. Последние два окна уже использовались при разработке v1 и не являются новым независимым тестом. Цель WAPE ≤10% не достигнута. Разные единицы не суммируются.

Полный отчёт · сохранённые метрики · воспроизведение и веса.

Автоматические проверки

Из корня после установки зависимостей (Windows; на Linux/macOS замените .\.venv-ml\Scripts\python.exe на .venv-ml/bin/python):

.\.venv-ml\Scripts\python.exe scripts/validate_contract.py
.\.venv-ml\Scripts\python.exe -m pytest backend/tests model -q
npm --prefix frontend run build

При запущенных API и frontend, из каталога frontend/:

npx playwright install chromium --no-shell
npm run test:e2e:service

Playwright создаёт аккаунты, расчёты и утверждения: перед запуском API задайте отдельный DATA_DIR=./.local-data/browser-service. Для ML-сценария сначала создайте учебные файлы командой выше. Старый набор npm run test:e2e:legacy запускается отдельно с другим DATA_DIR и TIREK_AUTH_DISABLED=1; не используйте этот режим на рабочей базе. Подтверждено после объединения с обновлениями команды: 162 backend-теста / 10 подтестов, 181 модельный тест / 966 подтестов, 17 браузерных сценариев, включая SE и IEK XLSX → ML → CSV. Ещё два браузерных прогона прошли на готовой сборке без Vite. Подробности и границы: отчёт проверки MVP. Дополнительно прошли 12 проверок складского шаблона IEK: дубли SKU, склад, единицы, противоречивые остатки, ETA и неизвестный шаг единицы. Метрики прогноза и успешность функциональных тестов оценивают разные свойства.

Ограничения и навигация

• Реальный веб-адаптер поддерживает расчёт SE, Алматы, штуки и IEK, Алматы, штуки/метры/упаковки. Старый импорт и прогноз IEK ранее проверены на 2 149 товарах. Новый текущий снимок IEK проверяется на учебных данных; без свободного остатка IEK заказ остаётся неопределённым. Образец снимка доступен в учебном ZIP IEK. Запуск на своих файлах и настройка ИИ. Универсального импорта Excel нет.
• «Настройки» содержат синтетическую симуляцию уровней остатка 40/30/20%. Состояния и события сохраняются отдельно для каждого аккаунта; намерение пересчёта фиксируется, но worker автоматического пересчёта ещё не подключён.
• При неизвестном MOQ и неподтверждённом складском снимке количество предварительное; утверждение неполных условий блокируется сервером.
• В реальном адаптере используется одна дневная траектория; вероятностная гарантия уровня обслуживания не подтверждена.
• LLM-проверка подключается настройками backend/.env; без провайдера и модели она честно недоступна. Реальной отправки поставщикам, живой интеграции с 1С и подтверждённого импорта в конкретную конфигурацию 1С нет.
• Сервис MVP рассчитан на один сервер и один процесс API. Есть cookie-сессии, защита CSRF, хеширование паролей, изоляция аккаунтов и журнал действий. Приглашения коллег, роли внутри компании, подтверждение email и восстановление забытого пароля по почте пока не реализованы. Партнёрские файлы и секреты не публикуются.

Аккаунты и помощник

Регистрация создаёт личное пространство, вход восстанавливает доступ к сохранённым расчётам. «Настройки» позволяют изменить пароль; при этом прежние сессии отзываются. Утверждение и ручные изменения записывают автора в журнал /api/v1/audit. Cookie недоступна JavaScript, сессия действует 12 часов; запросы изменения данных требуют CSRF-токен. TIREK_AUTH_DISABLED=1 предназначен только для изолированных старых тестов. Не используйте его при общем развёртывании.

Помощник работает только на чтение. Без ключа он показывает локальную справку по навигации и фактам выбранного расчёта, помеченную «Локальная справка». Для внешнего диалога задайте в локальном backend/.env:

OPENAI_API_KEY=<новый ключ, не публикуйте его>
TIREK_ASSISTANT_MODEL=<доступная вашему проекту модель>

Перезапустите API. Текст вопроса передаётся OpenAI; выбранные факты расчёта — только при включённом согласии в панели. Исходные Excel и клиентские события помощник не отправляет. Используется Responses API с store=false; это не равнозначно соглашению Zero Data Retention. Ошибка провайдера отображается как ошибка, а не как успешный ответ ИИ. Опциональная проверка одной позиции использует отдельные TIREK_LLM_* настройки.

Развёртывание одного экземпляра

Для запуска готового интерфейса без Vite:

npm --prefix frontend run build
.\.venv-ml\Scripts\python.exe -m uvicorn backend.app.main:app --host 127.0.0.1 --port 8000 --workers 1

Откройте http://127.0.0.1:8000: API и собранный интерфейс работают на одном адресе. Также подготовлены Dockerfile и compose.yaml: docker compose up --build -d, адрес http://127.0.0.1:8080, данные — в именованном томе tirek-data. Контейнерная сборка требует Docker; факт её проверки отдельно указан в отчёте.

Для внешнего сервера задайте HTTPS, TIREK_COOKIE_SECURE=1 и точный адрес фронтенда в TIREK_ALLOWED_ORIGINS. Обязательно сохраняйте том с базой и загрузками. SQLite и фоновые задачи рассчитаны на один процесс: после перезапуска незавершённая задача получает ошибку и требует повторного запуска. Несколько воркеров и автоматическое восстановление очереди в этот MVP не входят.

Где смотреть	Содержание
Сценарий жюри	Проверки, XLSX и CSV
Анализ сдачи	Условия, готовность и оставшиеся задачи
Аудит интеграции	Проверки платформы и технические ограничения
Матрица кейса	Пять обязательных бизнес-требований
Backend, frontend	Запуск и устройство приложения
ML-интеграция	Реальный адаптер и расширение
Прогноз v2	Текущая модель; v1 — предыдущий эксперимент
Расчёт заказа	Математика и ограничения
Синтетический testbed	Отдельная среда и её результаты
OpenAPI	API-контракт и типы
Спецификация, дизайн	Целевой продукт и интерфейс

Планы в docs/ описывают целевой объём. Фактическое состояние реализации и границы доказательств приведены в README и анализе сдачи.