HACKALEM AI · Планирование закупок ИЭК

Из Excel-выгрузок — в объяснимый прогноз спроса и план закупок.

Локальное приложение для менеджера отдела закупа ТОО «Электрокомплект». Менеджер загружает таблицы, изучает расчёт по товарам и, при наличии необходимых фактических данных, корректирует и подтверждает заказ.

Первый рабочий охват: ассортимент ИЭК, склад Алматы. В интерфейсе проект обозначен как EKT. Регистрация, аккаунты и внешние AI-ключи не нужны. Расчёты выполняются локальным сервером, не языковой моделью.

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

Содержание

• Что умеет приложение
• Быстрый запуск
• Какие файлы загружать
• Работа с приложением: по шагам
• Прогноз, предварительный план и заказ
• Как устроен расчёт
• Предупреждения и ошибки
• Где хранятся данные
• Запуск для разработки
• Проверки и тесты
• Устройство проекта и API
• Ограничения

Что умеет приложение

• Принимать XLSX и ZIP с книгами Excel.
• Объединять отдельные файлы, листы и поддерживаемые общие таблицы по коду товара, а не по названию.
• Рассчитывать прогноз спроса, сезонность, тренд и страховой запас.
• Выделять аномально крупные операции и объяснять их исключение.
• Учитывать даты поставок в пути и минимальные партии MOQ.
• Показывать прогноз даже при неизвестном текущем остатке.
• По явному выбору менеджера строить предварительный план с оценкой остатка.
• Показывать формулу и исходные компоненты для каждого товара.
• Для фактического заказа сохранять ручную корректировку с причиной, подтверждение и экспорт CSV/XLSX.

Три раздела интерфейса: «Данные» → «Закупки» → «Заказы». Демо-кнопок и автоматически подставляемых тестовых товаров на сайте нет. Синтетические сценарии в репозитории предназначены для тестов разработчика.

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

1. Подготовьте компьютер

Понадобятся Git, работающий Docker с командой docker compose, браузер и свободные порты 8080 и 8000. На Windows/macOS можно использовать Docker Desktop. Интернет нужен для первого скачивания образов и зависимостей.

При запуске через Docker отдельно устанавливать Python, Node.js и базу данных не требуется.

2. Получите проект

Откройте терминал:

git clone https://github.com/BAITC-Hacks/hack-d46eb454-alias.git
cd hack-d46eb454-alias

Если проект уже скачан, откройте его корневую папку — ту, где лежит compose.yaml. Повторно клонировать его не нужно.

3. Запустите приложение

Убедитесь, что Docker запущен. Выполните из корня проекта:

docker compose up --build -d

Первая сборка может занять несколько минут. Проверьте состояние:

docker compose ps

У backend должен появиться статус healthy, у frontend — Up.

4. Откройте сайт

Назначение	Адрес
Приложение менеджера	127.0.0.1:8080/#/data
Документация API	127.0.0.1:8000/docs
Проверка сервера	127.0.0.1:8000/api/health

Работающая проверка API возвращает {"status":"ok","version":"0.1.0"}.

127.0.0.1 — компьютер, на котором запущен Docker. Открытие этого адреса на другом компьютере не подключит его к вашему серверу. Текущая конфигурация рассчитана на локальную работу.

Остановка, повторный запуск и обновление

Остановить приложение, сохранив данные:

docker compose down

Запустить снова:

docker compose up -d

После изменения кода пересобрать:

docker compose up --build -d

Для получения изменений из GitHub сначала проверьте git status. Если локальных изменений нет, выполните git pull --ff-only, затем пересборку. Если изменения есть, сначала сохраните и согласуйте их — не удаляйте рабочую папку и не делайте принудительный сброс.

Не добавляйте --volumes к остановке, если хотите сохранить наборы и расчёты: удаление тома уничтожает рабочие данные.

Какие файлы загружать

Основной поддерживаемый набор — шесть файлов ИЭК:

Файл	Содержимое	Использование
input table	Детальные продажи: дата, документ, код, товар, единица, склад, количество	Основная история спроса, анализ операций и аномалий
input table	Месячные продажи в количестве	Сверка с детализацией; не прибавляются к тем же продажам повторно
input table	Остатки на начало месяца	Исторические остатки; основа опциональной оценки, но не текущий факт
input table	Поставки в пути, документы и ожидаемые даты	Учёт будущих поступлений внутри горизонта
input table	Нормированные коэффициенты сезонности	Общий месячный сезонный профиль
input table	MOQ и артикулы поставщика	Минимальная партия и реквизиты товара

Имена файлов можно менять: назначение определяется по структуре листов и заголовкам. Исходные длинные названия и ф1.xlsx принимаются одинаково, если содержимое совпадает.

Подготовка к загрузке

1. Соберите все шесть файлов в одной папке.
2. Выбирайте настоящие .xlsx, а не временные файлы Excel с префиксом ~$.
3. Не преобразовывайте коды товаров в числа: ведущие нули и суффиксы имеют значение.
4. Для проверки исходного набора используйте склад Алматы и дату 23.09.2026: детализация содержит продажи до 22.09.2026. Это воспроизводимый пример, не обязательная дата для новых выгрузок.
5. Новые выгрузки рассчитывайте на соответствующую им дату. Старые файлы не становятся актуальными от выбора сегодняшнего дня.

Ограничения формы: до 12 файлов, 25 МиБ на файл, 64 МиБ суммарно. Принимаются XLSX и ZIP с XLSX; CSV и старый XLS этим импортом не поддерживаются.

Нужны ли все столбцы в каждом файле?

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

Поддерживаются перестановка колонок и явно перечисленные варианты заголовков, например «Код товара» / «Код 1С», «Количество» / «Кол-во». Произвольные таблицы не угадываются. Неизвестный формат или два заголовка с одинаковым смыслом попадут в отчёт.

Подробные требования: форматы импорта.

Работа с приложением: по шагам

Шаг 1. Загрузите и проверьте файлы

На странице «Данные»:

1. Нажмите «Выбрать файлы» или перетащите файлы в область загрузки.
2. Выберите все шесть таблиц либо ZIP с этими книгами.
3. Проверьте поле «Склад».
4. Нажмите «Проверить файлы» и дождитесь обработки.

Появятся количество проверенных файлов и число распознанных записей по источникам. Это ещё не расчёт закупки. Большая детализация может обрабатываться десятки секунд — повторно нажимать кнопку не нужно.

Шаг 2. Укажите параметры

Поле	Значение
Дата расчёта	Дата, относительно которой берутся история, остатки и будущие поставки
Пересмотр, дней	Через сколько дней планируется следующий пересмотр заказа
Поставка, дней	Срок новой закупки; вводится менеджером, не выводится автоматически из файлов
Коэффициент z	Множитель страхового запаса; большее значение увеличивает запас при прочих равных
Плановый прирост, %	Дополнительная корректировка прогноза: 10 означает +10%, а не множитель 10

Стартовые значения: 7 дней пересмотра, 21 день поставки, z = 1,65, прирост 0%. Это редактируемые параметры, а не подтверждённые условия поставщика. Горизонт в этом примере: 21 + 7 = 28 дней.

Шаг 3. Выберите режим остатка

По умолчанию опция «Предварительный план по оценке месячного остатка» выключена. Прогноз рассчитывается и без фактического остатка; количество заказа в таком случае остаётся неизвестным.

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

Шаг 4. Выполните расчёт

Нажмите «Сохранить набор и рассчитать». Сервер сохранит снимок импорта и выполнит расчёт. На «Данных» появятся число рассчитанных позиций, замечания, ограничения и кнопка «Посмотреть рекомендации», если есть рассчитанные товары.

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

Шаг 5. Изучите прогноз и план

Нажмите «Посмотреть рекомендации» или перейдите в «Закупки».

В таблице доступны товар и код, остаток, учитываемые поступления, прогноз спроса на горизонт, количество к заказу и приоритет. Поиск работает по названию и коду; фильтры — по поставщику, срочности и статусу.

Список разбит на страницы: по умолчанию 20 товаров, можно выбрать 10, 20 или 50. Кнопки страниц находятся сверху и снизу таблицы. Поиск и фильтры работают по всему расчёту, а не только по текущей странице; изменение фильтров или размера страницы возвращает на первую страницу.

• «Нет данных об остатке» вместо количества — прогноз есть, но заказ не определён.
• «Оценка» / «предварительно» — использован оценочный, не фактический остаток.
• Нулевой заказ при известном остатке — потребность закрыта запасом и учитываемыми поступлениями.

Нажмите на товар или кнопку обоснования: откроются компоненты, формула, дата снимка, горизонт, сезонность, тренд и исключённые объёмы.

После изменения входных файлов, склада или параметров нужно заново выполнить расчёт. Старый результат автоматически не пересчитывается.

Шаг 6. Подготовьте фактический заказ, если данные позволяют

Для подтверждённого операционного заказа дополнительно нужен фактический остаток. Пример структуры отдельного листа:

Код 1С	Остаток	Дата	Склад
<код товара из ваших файлов>	<фактическое количество>	<дата снимка>	Алматы

Это описание структуры, не данные для загрузки. Введите реальные значения. В общей таблице продаж используйте отдельную «Дату остатка», не дату продажи.

Загрузите снимок вместе с исходными файлами, пересчитайте результат и откройте «Заказы»:

Позиции выбранного заказа также показываются страницами по 10, 20 или 50 строк (по умолчанию 20). Пока строка изменена, но не сохранена, переход между страницами и смена размера недоступны: сначала сохраните правку. Подтверждение и экспорт включают все позиции расчёта, не только видимую страницу.

1. Проверьте позиции и количества.
2. При необходимости измените количество, введите причину и нажмите «Сохранить строку».
3. Нажмите «Подтвердить весь расчёт» и подтвердите действие в диалоге.
4. Скачайте CSV или XLSX появившимися кнопками.

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

После изменения подтверждённого количества появляется статус «Нужно повторное подтверждение»; экспорт недоступен до повторного подтверждения. Ручная правка не превращает неизвестный/оценочный остаток в факт.

Автоматической отправки заказа поставщику нет. Совместимость CSV/XLSX с конкретной конфигурацией 1С не заявляется без проверки её формата.

Прогноз, предварительный план и заказ

Результат	Что получает менеджер	Утверждение и итоговый экспорт
Прогноз спроса	Прогноз, страховой запас, объяснение; без остатка количество заказа неизвестно	Нет, если фактического остатка нет
Предварительный план	Прогноз и оценочное количество с явной пометкой и допущениями	Нет: это не фактический заказ
Фактический заказ	Расчёт на подтверждённых данных, корректировка и подтверждение	После явного подтверждения менеджером и проверки данных

Как получается оценочный остаток

Оценка остатка = max(0, остаток на начало месяца − продажи с начала месяца до даты расчёта)

Используется только снимок того же календарного месяца, что и дата расчёта, с совместимой единицей. Более старый или будущий месячный снимок не подставляется. Если подходящего значения нет, сохраняется только прогноз. Фактический снимок имеет приоритет над оценкой.

Допущения: месячная таблица относится к выбранному складу; неизвестные приходы, возвраты, резервы, списания и перемещения в оценке не учтены. Поставки «в пути» не означают, что товар уже получен. Оценка может существенно отличаться от склада и не является восстановленным фактом.

В API фактическое поле available_stock при оценке остаётся null; оценочное значение, метод и источник хранятся отдельно в stock_estimate.

Как устроен расчёт

Расчёт воспроизводим и выполняется Python-сервером. Фронтенд показывает ответ API, а не придумывает числа.

1. Импорт. Источники нормализуются и связываются по строковому коду 1С. Сохраняются ссылки на файл, лист и строку.
2. История. Для текущего прогноза используются положительные расходные операции выбранного склада за последние 90 дней относительно даты расчёта. Месячные итоги сверяются с детализацией, но не прибавляются к ней.
3. Аномалии. Крупные операции оцениваются через медиану и MAD — устойчивую меру разброса. При наличии обезличенного ID клиента учитывается повторяемость покупок. В исходных шести файлах такого ID нет.
4. Сезонность и тренд. Используется нормированный месячный профиль из файла сезонности. Тренд сравнивает два соседних 28-дневных окна очищенного спроса. Плановый прирост применяется отдельно.
5. Отсутствие товара. Компенсация упущенного спроса применяется только при подтверждённых интервалах stockout. Пустые остатки и дни без продаж не доказывают отсутствие товара.
6. Страховой запас. Рассчитывается как z × σ спроса за срок поставки.
7. Потребность. Из прогноза и страхового запаса вычитаются известный остаток и учитываемые будущие поставки. Без остатка сохраняется прогноз, но не выдумывается количество заказа.
8. Ограничения закупки. К положительной потребности применяется MOQ и, если отдельно подтверждена, кратность. MOQ не равен кратности упаковки.

Горизонт = срок поставки + период пересмотра

Потребность = max(0, прогноз на горизонт + страховой запас
                     − остаток − поставки внутри горизонта)

Учебный пример, не реальные данные: прогноз 100 + страховой запас 20 − остаток 30 − своевременная поставка 40 = потребность 50 единиц до MOQ/кратности.

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

Методика: backend/README.md, решения проекта.

Предупреждения и ошибки

Не каждое сообщение означает, что импорт не работает. Программа различает пропуски отдельных строк, ограничения прогноза и ошибки, не позволяющие подтвердить заказ.

Сообщение или ситуация	Что означает и что делать
Нет кода, даты или количества	Строка не годится для истории. Проверить указанные файл, лист и номера строк.
Другой тип документа / неположительное количество	Операция не включена в обычный положительный спрос. Проверить смысл возвратов и корректировок; не менять знак автоматически.
MOQ пустой или отрицательный	Условие не принято. Исправить источник; не считать пустоту нулём.
Код отсутствует в детализации	У источников разный ассортимент/охват. Сверить коды; не объединять товары только по похожему имени.
Месячные суммы расходятся	Проверить склады, период, возвраты и охват. Не складывать источники повторно.
Текущий остаток не предоставлен	Прогноз доступен; фактический заказ неизвестен. Можно явно включить предварительную оценку.
Нет категорий / stockout / ID клиента	Часть методов недоступна; используются общие параметры, недостающие факты не генерируются.
Разные единицы или конфликтующие остатки	Нельзя однозначно объединить данные. Уточнить источник и пересчёт единиц.
Неизвестная структура листа	Свериться с форматами импорта; новый формат требует адаптера и теста.

Сайт не открывается или сервер недоступен

Из корня проекта выполните:

docker compose ps
docker compose logs --tail=100 backend frontend

Проверьте, что Docker работает, сборка завершена и порты свободны. Backend должен быть healthy; проверка /api/health должна отвечать. После изменения кода пересоберите приложение и обновите страницу.

В dev-режиме FastAPI работает на 8000, Vite — на 5173. Docker и отдельный dev-backend не могут одновременно занимать один порт.

Рассчитано 0 позиций

Проверьте дату, склад, распознанную детализацию и критические конфликты. Для исходных ф1–ф6 контрольная дата — 2026-09-23, склад — Алматы. В текущей реализации само отсутствие остатка не должно обнулять число прогнозов.

Прогноз есть, но заказ или экспорт недоступны

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

После обновления исчезли файлы и замечания

Это нормально: экранный отчёт не хранится постоянно. Последний реальный расчёт восстанавливается в текущей сессии браузера по сохранённому run_id; истории всех запусков отдельным экраном пока нет. Для нового отчёта выберите файлы и выполните расчёт заново.

Где хранятся данные

• Docker: SQLite, снимки импортов и расчёты находятся в именованном томе Compose hackalem_data. Фактическое имя тома обычно содержит префикс проекта.
• Без Docker: по умолчанию используется каталог data/ в корне. Путь задаётся серверной переменной HACKALEM_DATA_DIR.
• Браузер: в sessionStorage хранится идентификатор последнего расчёта, не весь Excel.
• Исходные книги пользователя не изменяются. Сервер сохраняет нормализованный снимок; оригиналы храните отдельно.

Рабочие данные, базы и артефакты тестирования исключены из Git. Не добавляйте реальные выгрузки вручную в коммиты. Для публичных примеров используйте только явно синтетические данные.

Приложение не отправляет таблицы в облачную LLM и не требует внешних AI-ключей. Загрузка выполняется на локальный backend. Развёртывание в интернете без доработки защиты не предусмотрено.

Для резервной копии сохраните весь каталог данных/том, не только SQLite: база ссылается на JSON-снимки. Делайте копию при остановленном backend. docker compose down без удаления томов сохраняет данные, но само по себе не является резервной копией.

Запуск для разработки

Основной способ для менеджера и демонстрации — Docker. Режим ниже нужен для изменения кода.

Требования

• Python 3.14 — версия текущего Docker-образа.
• Node.js 24 — версия сборочного образа; frontend/package.json допускает Node.js от 22.12.
• npm и два терминала.

Backend — терминал 1

Команды для macOS/Linux, из корня проекта:

python3 -m venv .venv
.venv/bin/python -m pip install -r backend/requirements-dev.txt
.venv/bin/python -m uvicorn backend.main:app --host 127.0.0.1 --port 8000

На Windows вместо .venv/bin/python используйте .venv\Scripts\python.exe; создать окружение можно командой py -3.14 -m venv .venv.

Frontend — терминал 2

cd frontend
npm ci
npm run dev

Откройте 127.0.0.1:5173/#/data. Vite проксирует /api на 127.0.0.1:8000.

Для другого backend задайте переменную окружения API_PROXY_TARGET перед запуском Vite. Пример значения находится в frontend/.env.example. Для остановки dev-серверов нажмите Ctrl+C в обоих терминалах.

Проверки и тесты

После установки dev-зависимостей из корня проекта:

.venv/bin/python -m pytest -q tests/backend

Из каталога frontend:

npm test
npm run build
npm run test:e2e

Проверка	Что проверяет
pytest	Расчёт, импорт, конфликты, API и ограничения утверждения
npm test	Преобразование серверных данных и клиентскую логику
npm run build	TypeScript и production-сборку
test:e2e	Пользовательские сценарии в браузере с настоящим backend

Playwright запускает FastAPI и Vite либо использует уже работающие серверы на 8000 и 5173. Требуется .venv с dev-зависимостями в корне. По умолчанию используется установленный Chrome. Альтернатива для macOS/Linux:

npx playwright install chromium
PLAYWRIGHT_CHANNEL=chromium npm run test:e2e

Для проверки реальных шести файлов из frontend укажите папку с файлами именно ф1.xlsx … ф6.xlsx:

IEK_FILES_DIR="/абсолютный/путь/к/IEK" npm run test:e2e

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

Актуальные результаты и границы приёмки: docs/status.md. Наличие тестов не доказывает бизнес-точность прогноза.

Устройство проекта и API

backend/                 FastAPI, импорт, расчёт, хранение и экспорт
frontend/                React + TypeScript, три экрана менеджера
contracts/               OpenAPI и пример ответа
tests/backend/           Серверные регрессионные тесты
tests/fixtures/          Синтетические расчётные сценарии
frontend/tests/          Браузерные сценарии Playwright
docs/                    Форматы, статус и проектная документация
compose.yaml             Совместный запуск frontend и backend
PROJECT_CONTEXT.md       Текущие решения и допущения
PROJECT_BRIEF.md         Исходное задание и критерии готовности

Стек: React, TypeScript, Vite → Nginx → FastAPI / Python → SQLite и локальные JSON-снимки. Excel читается через openpyxl.

Метод и путь	Назначение
GET /api/health	Состояние сервера
POST /api/import/preview	Проверить файлы; получить preview_id
POST /api/import/commit	Сохранить снимок; получить dataset_id
POST /api/recommendations/calculate	Рассчитать набор; получить run_id и результат
GET /api/recommendations/runs/{run_id}	Прочитать сохранённый расчёт
PATCH /api/recommendations/runs/{run_id}/items/{item_id}/adjust	Сохранить ручное количество с причиной
POST /api/orders/{run_id}/approve	Подтвердить весь расчёт
GET /api/orders/{run_id}/export?format=csv	Скачать подтверждённый заказ; также доступен format=xlsx

Пример тела запроса расчёта — замените dataset_id на результат своего импорта:

{
  "dataset_id": "<dataset_id из import/commit>",
  "calculation_date": "2026-09-23",
  "warehouse_scope": "Алматы",
  "review_period_days": 7,
  "default_lead_time_days": 21,
  "service_level_z": 1.65,
  "growth_override_percent": 0,
  "stock_mode": "actual_only"
}

Для явно выбранного предварительного плана используйте stock_mode: "monthly_estimate". null в количестве заказа означает «не определено», не 0.

Подробнее: контракт API, backend, frontend, инструкции для участников разработки.

Ограничения

• Поддерживаются конкретные структуры и синонимы заголовков; универсального распознавания любых Excel нет.
• Основной расчёт использует детализацию. Месячные продажи служат сверке, не самостоятельной полной заменой истории операций.
• В шести исходных файлах нет текущего фактического остатка, подтверждённых интервалов stockout, категорий и обезличенного ID клиента.
• Месячная таблица остатков не содержит отдельной колонки склада; её охват — допущение предварительного режима, не установленный факт.
• Готовая сезонность рассчитана по агрегированной выручке; её применимость к количеству конкретного товара требует проверки.
• MOQ не подтверждает кратность упаковки. Метры и бухты нельзя переводить без подтверждённого коэффициента.
• Нет цен и валюты: приложение не рассчитывает стоимость заказа и денежную экономию.
• Нет автоматического подбора поставщика, полноценной интеграции с 1С, отправки заказов, авторизации и многопользовательской работы.
• Нет отдельного экрана истории всех импортов и расчётов. Аудит сохраняется на сервере, но не все его поля показаны в UI.
• Это локальный MVP. Точность прогноза, бизнес-эффект и пригодность оценки остатков не подтверждаются одним успешным запуском.

---

Первое знакомство: запустите Docker → откройте «Данные» → загрузите ф1–ф6 → проверьте файлы → задайте дату и параметры → рассчитайте → откройте «Закупки» и обоснование товара. Предварительную оценку включайте осознанно; фактический заказ подтверждайте только при подтверждённых данных.