SupplyMind — пополнение склада

HackAlem AI, задача «Электрокомплекта»: рекомендации заказов поставщикам с учётом регулярного спроса, сезонности, роста, остатков, транзита и периодов отсутствия товара.

Команда: Uitech.

Для работы в интерфейсе: краткое руководство пользователя. Процесс закупки: business_process.md; текущие алгоритмы и планы развития: algorithms.md.

Текущее состояние

Работают Java backend и отдельный frontend: импорт шести файлов Systeme Electric или IEK, расчёт потребности, журнал исключённых продаж, прогноз дефицита, группировка по поставщикам, ручная корректировка, утверждение версии и CSV-экспорт. В интерфейсе есть графики, поиск, фильтры, отчёт качества и семь демо-сценариев. Основное хранилище — PostgreSQL с миграциями Flyway; исходные XLSX сохраняются через локальный FileStorage.

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

Редактор Уточнить данные сохраняет исправления товара с автором, причиной и историей значений, затем открывает параметры нового расчёта. Проверка 23.09.2026: 43 backend-теста с PostgreSQL и обоими архивами прошли; 7 браузерных сценариев прошли на отдельной нативной тестовой базе и production build frontend (20,5 секунды). Обновлённая сборка Docker на этом ноутбуке прервана сбоем Docker Engine после исчерпания системной памяти; для этой версии контейнерный запуск пока не подтверждён. Ранее описанные успешные проверки полного Docker-стека относятся к версии до редактора.

Быстрый запуск для проверки — Docker

Нужны только Git и работающий Docker Desktop с Linux containers (либо Docker Engine с Compose v2). Из корня репозитория на Windows:

./tools/start_docker.ps1

или

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\tools\start_docker.ps1

Скрипт сам создаст .local/postgres.env со случайным паролем, если файла ещё нет, соберёт исходники и дождётся готовности трёх сервисов. Существующие настройки и данные сохраняются. Откройте http://127.0.0.1:5173 и выберите Демо-сценарии → Заказы двум поставщикам. Для этого не нужны реальные архивы, личные аккаунты, Java, Maven или Node.js на компьютере проверяющего. На новой установке список импортов пустой; демо создаёт синтетический набор через обычный API.

Эквивалентный запуск вручную на любой ОС: скопируйте .env.example в .env, задайте свой POSTGRES_PASSWORD и выполните:

docker compose up --build -d --wait

Если настройки созданы Windows-скриптом, используйте docker compose --env-file .local/postgres.env up --build -d --wait. Первая сборка требует сети для образов и зависимостей и нескольких гигабайт свободного места. Образы собираются из исходников: Maven выполняет тесты и создаёт JAR; Node собирает статический frontend, который обслуживает Nginx. В образы входят только код и синтетические fixtures — .local, секреты и реальные файлы исключены через .dockerignore.

Сервисы: frontend на 5173 → /api в backend:8080 → postgres:5432 внутри сети Compose. Снаружи backend доступен на 8080, PostgreSQL на 5433; все порты привязаны к 127.0.0.1. Изменить их можно через UI_PORT, BACKEND_PORT, POSTGRES_PORT. Compose ждёт healthcheck базы перед backend и backend перед frontend. Nginx допускает multipart до 40 МБ и ожидание ответа до 180 секунд.

Постоянные тома: uitech_postgres-data для БД и uitech_source-files для оригиналов XLSX. Они переживают пересборку и обычный down. Команда down -v удаляет данные. Для остановки Windows-варианта: docker compose --env-file .local/postgres.env stop; для просмотра ошибок: docker compose --env-file .local/postgres.env logs --tail 100. Не запускайте одновременно локальные dev-серверы и контейнеры на тех же портах.

Историческая проверка 23.09.2026, до добавления редактора исходных данных: оба образа были собраны из исходников; внутри Docker-сборки backend прошли 34 теста, 7 проверок внешних архивов/БД пропущены. Полный стек прошёл 6 браузерных сценариев, включая оба реальных импорта (31,2 секунды). Отдельный проект с пустыми томами автоматически создал схему и прошёл 4 демо-сценария (8,2 секунды; 2 реальных импорта без архивов пропущены). После пересоздания контейнеров сохранены прежние расчёты и все 12 XLSX, контрольные суммы файлов совпали. Это проверка чистых томов на текущем Docker, запуск на втором физическом ноутбуке ещё не проверен.

Основы конфигурации: порядок запуска Compose, сборка в несколько этапов, проксирование Nginx. Базовые образы: Maven 3.9 / Eclipse Temurin 17 (Apache-2.0 / GPLv2 с Classpath Exception), Node 22.15.1 (MIT), Nginx stable (BSD-2-Clause), PostgreSQL 17.11 (PostgreSQL License); точные загруженные версии и digest показывает docker image inspect.

Локальная разработка без контейнеров приложений

Нужны PostgreSQL 17, JDK 17, Maven 3.9+ и Node.js 22.12+ (проверено на 22.15.1). Для вспомогательных скриптов — Python 3.11+. Первая сборка скачивает зависимости из Maven Central и npm; последующие расчёты не требуют внешней сети.

Если полный Compose уже работает, сначала остановите контейнеры приложений: docker compose --env-file .local/postgres.env stop frontend backend. Для работы с загруженными в Docker оригиналами скопируйте их в локальное хранилище: docker compose --env-file .local/postgres.env cp backend:/data/files/. .local/files/. При обратном переключении новые локальные файлы нужно перенести в том backend; база для обоих режимов одна, а каталоги файлов разные.

Создайте каталог .local и файл .local/postgres.env по образцу .env.example, задав собственный пароль. Файл с паролем исключён из Git. Для базы и переноса архивов оставьте не менее 2 ГБ свободного места.

Из корня этого репозитория, при работающем Docker:

docker compose --env-file .local/postgres.env up -d --wait postgres
mvn -f backend/pom.xml clean verify
./tools/start_backend.ps1

Compose запускает PostgreSQL 17.11 в контейнере uitech-postgres-1, с постоянным томом uitech_postgres-data и адресом 127.0.0.1:5433. При первоначальном переключении на Docker запуск был проверен: контейнер был healthy, backend подключался к нему. Это результат прежней проверки, не текущий статус после сбоя Engine, указанного выше. Данные были перенесены из нативного PostgreSQL через pg_dump/pg_restore: совпали количества строк и контрольные суммы содержимого всех 22 таблиц, включая 9 наборов, 22 расчёта и 12 ссылок на оригиналы. Перед переносом создана резервная копия .local/uitech-before-docker.dump.

После переключения на Docker повторно прошли все шесть браузерных сценариев (33,1 секунды), проверены скачивание 12 оригиналов по SHA-256 и неизменность ранее утверждённого расчёта и CSV.

Прежний нативный PostgreSQL остановлен; его данные в .local/postgres-data сохранены как снимок до переключения и больше не обновляются. Для отдельного запуска без Docker предусмотрен ./tools/start_postgres_native.ps1; порт 5433 должен быть свободен. На другом Windows-компьютере можно передать -BinDirectory 'C:\Program Files\PostgreSQL\17\bin'; скрипт создаёт отдельный кластер, существующие базы не меняет. Нативная проверка использовала бинарники Zonky embedded-postgres-binaries-windows-amd64:17.11.0 из Maven Central, они не включены в Git.

Для существующего внешнего PostgreSQL задайте UITECH_DB_URL, UITECH_DB_USER, UITECH_DB_PASSWORD и запустите backend. По умолчанию активен профиль postgres; ошибка подключения останавливает запуск, автоматического отката на JSON нет. Без БД доступен явно выбранный режим: ./tools/start_backend.ps1 -Storage file.

API: http://127.0.0.1:8080/api/v1, проверка — GET /health. Перед пересборкой JAR остановите запущенный backend через Ctrl+C.

В другом терминале, из корня репозитория:

cd frontend
npm ci
npm run dev

Откройте http://127.0.0.1:5173. Vite проксирует /api на backend. Если backend работает на другом порту, перед запуском frontend задайте $env:BACKEND_URL = 'http://127.0.0.1:8090'. Продакшен-сборка: npm run build; её локальная проверка: npm run preview, адрес http://127.0.0.1:4173 (backend должен работать). Это локальный preview, не production hosting.

Проверка через интерфейс

1. Нажмите Демо-сценарии → Заказы двум поставщикам. Синтетические данные явно помечены; числа рассчитывает backend.
2. Откройте товар: видны формула, MOQ/кратность, графики спроса и наличия. В сценарии «Разовая крупная продажа» дополнительно виден журнал исключённого всплеска.
3. Измените количество и укажите причину. Например, 150 → 160 шт. при кратности 10.
4. Утвердите заказ, указав имя проверившего и подтвердив предупреждения, если они есть. Скачайте CSV выбранного поставщика.
5. Повторная правка снимает утверждение. При неизвестном остатке утверждение и экспорт недоступны.

Уже сохранённые наборы доступны через выбор Набор данных; оригиналы и замечания — в Качество данных. Кнопка Загрузить данные принимает шесть XLSX выбранного поставщика (Systeme Electric / IEK) либо нормализованный JSON/контрольный пример. В интерфейсе ZIP сначала нужно распаковать. Реальный набор не получает вымышленных сроков поставки, MOQ, коэффициентов единиц и календаря наличия: данные нужно уточнить перед утверждением. Кнопка Уточнить данные (также в карточке товара) открывает редактор остатка, правил закупки, категории и сроков поставщика. Автор и причина обязательны. Исправление создаёт новый набор с историей значений до/после и сохраняет ссылки на XLSX; исходный набор и утверждённые заказы не меняются. После сохранения открываются параметры нового расчёта. Пустые MOQ/коэффициент/кратность остаются неизвестными. Транзит, наличие и полнота продаж этим действием не подтверждаются; для остальных исходных полей по-прежнему нужен нормализованный JSON.

В браузере сохраняется только ID последнего открытого расчёта, чтобы восстановить его после обновления страницы. Наборы и расчёты хранятся в PostgreSQL; исходные файлы — в томе uitech_source-files для Docker или .local/files при локальном запуске. Реальные данные в frontend bundle не включаются.

В другом терминале, из корня репозитория:

python tools/demo_backend.py --approve

Команда загружает синтетический пример, рассчитывает заказ 150 шт., утверждает его от имени тестового пользователя и сохраняет JSON/CSV в .local/demo/. Без --approve результат остаётся черновиком. Другой сценарий: python tools/demo_backend.py --fixture 08_one_off_order.

Переменные окружения: PORT (8080), UITECH_BIND_ADDRESS (127.0.0.1), UITECH_DATA_DIR (../.local/backend-data относительно каталога запуска). При прямом запуске java -jar из других каталогов задайте UITECH_DATA_DIR абсолютным путём. Скрипт start_backend.ps1 сам задаёт абсолютные .local/backend-data и .local/files внутри проекта, переопределяя эти две переменные; порт задаётся его параметром -Port. В профиле postgres этот каталог нужен для переноса старых JSON; в профиле file — для локального хранения. UITECH_FILES_DIR задаёт каталог исходных файлов. Полноценные пользователи и роли пока не реализованы. Изменение расчёта и утверждение защищены транзакцией и блокировкой строки PostgreSQL; устаревшая revision получает 409.

Хранение и перенос данных

• Товары, поставщики, продажи, остатки, поставки и месячные ряды — отдельные таблицы и строки. Количества доступны как numeric, даты как date, внешние ключи и индексы сохраняют связи. JSONB каждой строки хранит полный контракт и ссылки на источники; один JSONB на весь архив не используется.
• Исправленные наборы в PostgreSQL хранят свои товары, остатки, источники и замечания; через datasets.history_dataset_id используют прежние продажи, транзит и исторические ряды. Исправление одного товара не дублирует историю всего архива. API /data по-прежнему возвращает полный набор. В резервном профиле file сохраняется полная JSON-копия.
• datasets хранит метаданные и сводку; calculations и calculation_items — расчёт и его позиции. calculation_events фиксирует новые правки и утверждения. Исходные наборы после импорта неизменяемы.
• Исходные XLSX — объекты по SHA-256 в /data/files контейнера (постоянный том uitech_source-files) или .local/files при локальном запуске; таблица source_files хранит имена, размеры и связи с наборами. MinIO/S3 пока не подключён, замена выполняется через интерфейс FileStorage. CSV создаётся из утверждённой версии по запросу; отдельный архив экспортов пока не ведётся.
• Flyway применяет SQL из backend/src/main/resources/db/migration/ при старте: V1 создаёт схему, V2 — журнал переноса старых файлов, V3 — ссылки исправленных наборов на неизменяемую историю исходного импорта. Применённые миграции не редактируют — добавляют новые.

Один раз перенести старые .local/backend-data/*.json:

./tools/start_backend.ps1 -MigrateLocal

Перенос сохраняет ID, даты наборов, актуальные состояния расчётов, версии и утверждения. Контрольная сумма исходного JSON записывается в migration_sources. У старого JSON-хранилища формат чисел мог измениться после вычисления ID: такой ID сохраняется, а текущий hash сериализации фиксируется отдельно. Каждая запись набора переносится транзакционно; прерванный перенос можно повторить. Существующие записи БД не перезаписываются; новые правки после переноса не теряются при повторном запуске. Старые JSON остаются резервной копией и больше не обновляются в режиме PostgreSQL. Для расчётов из старого хранилища создаётся событие MIGRATED: прошлые отдельные правки, которых не было в JSON, не восстанавливаются. После переноса запускайте без -MigrateLocal.

Старые импорты не содержали бинарных оригиналов на backend. Повторная загрузка тех же шести XLSX привязывает оригиналы к существующему набору без дублирования продаж. Оригинальные архивы в Downloads не изменяются.

При первоначальном переносе из JSON были сверены 9 наборов и 17 прежних расчётов; позднее к переносу в Docker их стало 22. Эти числа относятся к разным этапам и не описывают текущий счётчик БД. Прямой SQL подтвердил 3 909 товаров и 248 467 строк продаж двух реальных поставщиков; повторный импорт сохранил 12 оригинальных XLSX, скачивание проверено по SHA-256 исходных файлов. После перезапуска backend утверждённый синтетический расчёт сохранился без изменений, экспортированный CSV совпал побайтово. Проверить прежние расчёты сразу после переноса: python tools/verify_migration.py (после дальнейших правок расчётов полное совпадение со старыми JSON уже не ожидается).

Импорт Systeme Electric и IEK

При работающем сервере, из корня репозитория:

python tools/import_supplier.py "C:\Users\User\Downloads\Systeme electric.zip" --supplier SYSTEME
python tools/import_supplier.py "C:\Users\User\Downloads\IEK.zip" --supplier IEK

Скрипт читает архив в памяти и отправляет шесть XLSX через multipart API. Исходные файлы не меняются. API принимает XLSX: до 15 МБ на файл и 40 МБ на запрос. Серверный ZIP-импорт не реализован.

На предоставленном архиве получены: 724 товара, 76 997 принятых строк продаж, 497 снимков остатка, 7 ненулевых поставок, 18 282 месячных значения продаж и 23 133 значения остатков. Объединение справочников включает товары, отсутствующие в отдельных источниках. 315 операций детализации вынесены в сообщения карантина; количество не меняется через модуль. Полный нормализованный набор и все замечания доступны через GET /datasets/{id}/data; краткий отчёт ограничен первыми 200 замечаниями.

IEK: 3 185 товаров, 171 470 принятых строк продаж, 81 279 месячных значений продаж, 94 149 значений начальных остатков. Отдельно сохранены 306 записей партий (reported_inbound) и 1 938 строк ограничений отгрузки (reported_purchase_rules). 133 операции — в карантине; 15 ошибок MOQ и дубликаты сохранены с замечаниями. Актуальных остатков IEK нет; начальные остатки месяца их не заменяют. Сроки «поступление до» остаются предельными датами, количества партий не вычитаются из заказа до подтверждения единиц и склада. Нормализованный транзит пока пустой — это не утверждение об отсутствии товара в пути. В отчёте качества можно раскрыть исходные партии и правила.

После уточнений можно получить нормализованный JSON, исправить подтверждённые поля с указанием ручного источника и создать новый dataset через POST /datasets. Старый набор сохраняется. Допущения, поддерживаемые расчётом, описаны в контракте. Неизвестный остаток, MOQ или коэффициент единиц не заменяются нулём/единицей. Помесячные остатки сохраняются для сверки и не превращаются в вымышленные даты stockout. Для интерфейса GET /datasets/{id}/review возвращает справочники и качество без полной истории продаж; /data сохраняет полный набор.

Метод расчёта

Продажи агрегируются по документу и по клиенту за день. Детектор использует медиану/MAD, сезонную нормализацию и повторяемость крупных покупок по неделям. Исключения видны в результате; при отсутствии ID клиента проверяются только документы.

Сначала снимается сезонность, затем очищенный спрос усредняется по дням наличия. Дни с явным ASSUME_AVAILABLE также входят в знаменатель и помечаются как допущение. Упущенный спрос при stockout оценивается отдельно. Используется предоставленная сезонность либо её оценка при наличии минимум двух полных наблюдений каждого месяца года с достаточными днями наличия, затем ручной прирост либо линейный тренд минимум по трём полным месяцам. Потребность: прогноз на срок поставки и период пересмотра + страховой запас − свободный остаток − подтверждённый транзит внутри горизонта. Поставка после раннего дефицита, но до конца горизонта, уменьшает количество заказа, сохраняя предупреждение о раннем дефиците. Итог переводится в единицы закупки и округляется по MOQ/кратности.

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

Проверки и зависимости

mvn clean verify запускает автоматические тесты: 17 контрольных сценариев, обработка неполных данных, API, версии, экспорт, чтение XLSX. Тесты реальных архивов по умолчанию пропускаются; включить их из backend:

mvn verify "-DargLine=-Xmx512m" "-Duitech.systemeZip=C:\Users\User\Downloads\Systeme electric.zip" "-Duitech.iekZip=C:\Users\User\Downloads\IEK.zip"

На 23.09.2026 verify с обоими реальными архивами и -DargLine="-Xmx384m -XX:ReservedCodeCacheSize=48m": 43 теста, 0 ошибок, 0 пропусков при заданном UITECH_TEST_DB_URL и обоих архивах. Без PostgreSQL шесть интеграционных проверок пропускаются; без архивов — ещё две. Ограничение heap сдерживает потребление памяти JVM, но не гарантирует отсутствие исчерпания памяти всей системы. Проверены сборка JAR, HTTP-сценарий расчёт → утверждение → CSV, multipart-импорт и повторное сохранение без дублирования. Это проверка реализации, а не доказательство точности прогноза или экономии компании. Исторический backtest и сравнение с работой менеджера ещё не выполнены.

Для интеграционных проверок БД задайте UITECH_TEST_DB_URL (например, jdbc:postgresql://127.0.0.1:5433/uitech), UITECH_DB_USER и UITECH_DB_PASSWORD. Тесты создают уникальную временную схему, применяют Flyway и удаляют только эту схему. Проверяют round-trip без дубликатов, полный rollback при ошибке, конфликт двух параллельных правок, сохранение утверждения и повторный перенос без перезаписи новых правок. Обычные API-тесты явно используют профиль file; они также проверяют побайтовое скачивание оригинала XLSX.

Frontend проверяется командами npm run build и npm run test:e2e из frontend. Для E2E должны работать backend и frontend; по умолчанию используется установленный Microsoft Edge. Другой браузер: $env:PLAYWRIGHT_CHANNEL = 'chrome'. Если frontend открыт на другом порту, задайте UI_URL, например $env:UI_URL = 'http://127.0.0.1:5174'; это адрес для тестов, а BACKEND_URL задаёт backend для Vite. Тест реального XLSX-импорта включается переменной UITECH_XLSX_DIR, указывающей на каталог с шестью распакованными файлами Systeme. Для IEK задайте UITECH_IEK_XLSX_DIR с его шестью файлами. Без архивов запускаются пять проверок, две пропускаются. Набор E2E включает семь сценариев, в том числе настоящий multipart-импорт обоих поставщиков. Артефакты — frontend/test-results/, в Git не попадают.

Основные зависимости: Java 17, PostgreSQL 17.11 (PostgreSQL License), JDBC PostgreSQL 42.7.11 (BSD-2-Clause), Flyway 11.7.2 (Apache-2.0), Spring Boot 3.5.16 (Apache-2.0), Apache POI 5.5.1 (Apache-2.0), Jackson через Spring Boot (Apache-2.0), JUnit Jupiter для тестов (EPL-2.0); React 19.3.0 (MIT), Vite 8.3.0 (MIT), TypeScript 7.0.2 (Apache-2.0), Playwright 1.63.0 для E2E (Apache-2.0), Prettier для форматирования (MIT). Версии зафиксированы в backend/pom.xml, BOM Spring Boot и frontend/package-lock.json; транзитивный состав показывает mvn dependency:tree и npm ls. Документация: React, Vite. LLM/API модели в текущем расчёте не используются. Реальные материалы предоставлены организатором; в Git их нет. Контрольные примеры созданы командой и полностью синтетические.

В исторической проверке до редактора исходных данных после переноса на PostgreSQL шесть E2E прошли в Edge за 34,5 секунды, включая повторный импорт обоих поставщиков без дублирования; backend запущен с -Xmx512m. XLSX читается SAX из временного файла в режиме READ, чтобы POI не распаковывал весь архив в heap; временный файл удаляется после чтения. Сериализация локального dataset и подсчёт hash выполняются потоково. Для IEK до переноса измерен размер /review 3 893 719 байт против 96 877 642 байт полного JSON; контракт и исходные данные сохранены полностью.

• Руководство пользователя
• Бизнес-процесс
• Алгоритмы
• Анализ и первоначальный план
• Аудит исходных Excel-файлов
• Контракт данных и API v1
• Контрольные сценарии
• Синтетические входные данные

Контрольные примеры проверяются backend-тестами; они не измеряют эффект на данных компании.

Для повторного создания контрольных файлов нужен Python 3 без дополнительных библиотек:

python tools/generate_contract_fixtures.py