Электрокомплект — планирование закупок

Сервис помогает менеджеру определить, что, сколько и у какого поставщика заказать. Он объединяет продажи, остатки и товары в пути, корректирует разовые всплески спроса и рассчитывает пополнение с учётом сезонности, сроков поставки и правил заказа.

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

Стек: Go · HTML/CSS/JavaScript · JSON-хранилище · Docker. Интерфейс и подготовленный набор Excel-данных встроены в бинарник. Для обычного запуска не нужны Node.js, Python или отдельная база данных.

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

Требуется Go 1.23+. Из корня проекта:

go run .

Откройте http://127.0.0.1:8080. При первом запуске новый склад автоматически заполняется подготовленными данными IEK и Systeme Electric:

Товаров	Месячных записей	Строк поставок	Коэффициентов сезонности
3 907	99 561	313	24

Данные сохраняются в data/warehouse.json. Если склад уже существует, его содержимое сохраняется; перейти со старого демо на исходные данные можно кнопкой «Данные Excel», подтвердив замену.

Остановка — Ctrl+C. После изменения кода или интерфейса перезапустите go run .: статические файлы включаются в приложение при сборке.

Что посмотреть на сайте

1. Нажмите «Пример расчёта» — в карточке показано «Нужно → Есть → Приедет → Заказать». Продажи, сезонность и корректировки доступны в «Подробном расчёте».
2. В «Параметрах расчёта» настройте дату, период анализа, сроки поставщиков и страховой запас. Для встроенного набора используются дата 23.09.2026 и история 365 дней.
3. Проверьте рекомендации, поиск по названию, артикулу или коду 1С и фильтры поставщиков. Откройте товар, чтобы увидеть обоснование и помесячные корректировки.
4. В «Рекомендациях» доступны «Все товары» и «Требуют внимания»: блокировки заказа, риск дефицита и уточнение данных. Карточки подскажут следующий шаг; общие предупреждения раскрываются через «Подробнее». Поступления — в «Товарах в пути».
5. Нажмите «Экспорт CSV». Выгружаются все готовые строки заказа, независимо от фильтров таблицы, с обоснованием и BOM для Excel.

В контрольном примере IVR21-1-25 целевой запас равен 7, доступный остаток — 0, в пути — 5, рекомендация — 2 единицы. Подробный сценарий показа: демо на 3 минуты.

Формирование рекомендаций и экспорт не отправляют заказ поставщику и не создают новую поставку. Решение принимает менеджер.

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

Приложение поддерживает два вида истории:

Данные	Метод
Встроенный набор, кнопка «Данные Excel»	Месячные продажи, корректировки всплесков, компенсация возможного отсутствия товара, тренд и сезонность
Прямой импорт XLSX и JSON с дневными продажами	Полные календарные дни до даты расчёта, исключения и возвраты, коррекция всплесков и сезонность

Для месячного расчёта:

1. Берутся завершённые месяцы, пересекающие выбранный период. Неполный сентябрь 2026 исключается. Месяцы учитываются целиком.

2. Аномальная часть документных продаж уменьшает соответствующий месячный итог пропорционально. Месячные и дневные источники не суммируются.

3. Спрос приводится к дневному значению без сезонности. Всплески корректируются по медиане и MAD — медиане абсолютных отклонений. При четырёх и более положительных наблюдениях порог равен max(3 × медиана, медиана + 3 × 1,4826 × MAD).

4. Если известный начальный остаток нулевой, а спрос не превышает 20% медианы нормальных периодов с запасом, он восстанавливается до этой медианы. При неизвестном остатке такая компенсация не применяется.

5. При наличии шести месяцев сравниваются медианы последних и предыдущих трёх. Коэффициент тренда ограничен диапазоном 0,75–1,25. Затем применяются месячные коэффициенты будущего периода.

6. Рассчитываются запас и заказ:

   горизонт = срок поставки + период закупки + страховой запас, дней
   целевой запас = округление вверх прогнозного спроса и страхового запаса
   доступный остаток = остаток − резерв
   потребность = max(0, целевой запас − доступный остаток − поставки в горизонте)
   заказ = положительная потребность с учётом минимума и кратности
   

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

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

Данные и импорт

Для знакомства достаточно встроенного набора — вручную загружать исходные книги не требуется. Он подготовлен из выгрузок на 22.09.2026. Состав источников и результаты преобразования доступны в отчёте импорта.

Чтобы загрузить свои данные, нажмите «Загрузить данные»:

• Excel: выберите полный комплект из шести .xlsx для одного поставщика или 12 для обоих. Проверяются только обнаруженные поставщики; полный комплект второго не требуется. Для каждого неполного комплекта выводится отдельный русский список недостающих отчётов. Для предоставленных выгрузок укажите дату 2026-09-22 и начало истории 2025-01-01.
• JSON: выберите один набор данных или ранее скачанную резервную копию.
• Проверьте результат и подтвердите «Заменить данные». Импорт заменяет весь склад; перед заменой можно скачать текущие данные.

В IEK/ и systemElectric/ находятся дневные продажи, месячные продажи, месячные остатки, сезонность, MOQ и товары в пути. MOQ ИЭК теперь находится в папке IEK/: MOQ ИЭК.xlsx. Файлы можно добавлять по очереди через «Добавить файлы», сохраняя уже выбранные.

Тип отчёта и поставщик определяются по структуре листов и колонок; имя файла служит дополнительным признаком. Для общих структур динамики продаж и сезонности учитывается обнаруженный комплект. Если поставщика нельзя определить однозначно или имя противоречит структуре, проверка просит уточнить поставщика в имени файла. Файл без имени поставщика не считается IEK автоматически.

Поддерживается структура предоставленных выгрузок; произвольные Excel-таблицы и старый формат .xls не поддерживаются. Лимит загрузки — 12 файлов и 64 МиБ; сервер читает сохранённые значения формул без их выполнения. Не добавляйте повторно копии уже выбранных книг; одного MOQ ИЭК.xlsx достаточно.

Полный комплект Systeme Electric в systemElectric/ содержит шесть файлов (написание Syseme сохранено из исходной выгрузки):

• MOQ SystemElectric.xlsx
• Динамика продаж_Syseme Electric_2025-2026.xlsx
• Ежемесячные остатки SystemElectric 2024-2026.xlsx
• Ежемесячные продажи в кол-м выражении SystemElectric 2024-2026.xlsx
• Сезонность SystemElectric 2024-2026.xlsx
• Товар в пути_SystemElectric на 22.09.2026.xlsx

Для JSON обязательны массивы suppliers, products, sales, stock, shipments; пустые коллекции задаются как []. Месячный формат дополнительно использует monthly, seasonality, source_date. Каждый товар должен иметь остаток и ссылку на существующего поставщика. Даты — YYYY-MM-DD, количества — в одной базовой единице товара. Пример: dataset.json; полная модель: model.go.

Допущения и качество данных

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

Прямой импорт XLSX сохраняет дробные количества и применяет более строгие проверки: неподтверждённые сроки, непроверенные или явно устаревшие остатки и нерешённые проблемы товара блокируют заказ. Предварительное количество видно в suggested_quantity, но строка не попадает в заказы и CSV. Поэтому результаты двух способов загрузки могут различаться.

В исходниках IEK остатки — начальное сальдо на 01.09.2026. У части товаров Systeme Electric есть текущие остатки на 22.09.2026. Перед реальной закупкой нужны актуальные остатки, подтверждённые сроки и проверка единиц, особенно для бухт и метров. Месячная компенсация дефицита — эвристика: точные дни отсутствия товара по этим данным неизвестны.

Обновление встроенного набора

После изменения исходных книг выполните из корня проекта:

python3 scripts/import_excel.py
go run .

Python-конвертер использует стандартную библиотеку и обновляет internal/realdata/dataset.json.gz и отчёт импорта. Перезапустите приложение, затем нажмите «Данные Excel», чтобы заменить уже сохранённый склад новым набором.

Для отдельной дневной выгрузки и подробной сверки источников доступен python3 scripts/import_supplier_workbooks.py: результат записывается в data/supplier-import.json и data/supplier-import-report.json. Описание этого преобразования — в проверке исходных книг.

API

Метод	Маршрут	Назначение
GET	/healthz, /readyz	Доступность и готовность сервиса
GET	/api/v1/dataset	Текущий снимок, ревизия и ETag
PUT	/api/v1/dataset	Полная замена набора с If-Match
GET	/api/v1/excel-dataset	Встроенный набор без изменения склада
POST	/api/v1/import/xlsx	Предпросмотр Excel: multipart/form-data, поля files, as_of, history_start
POST	/api/v1/recommendations	Рекомендации и объяснения по товарам
POST	/api/v1/recommendations.csv	Экспорт готовых заказов

Пример расчёта для запущенного локального сервера:

curl --fail-with-body http://127.0.0.1:8080/api/v1/recommendations \
  -H 'Content-Type: application/json' \
  -d '{"as_of":"2026-09-23","lookback_days":365,"review_period_days":14,"safety_stock_days":7}'

История допускает 7–730 дней, период закупки — 1–365, страховой запас — 0–365. Пустой запрос {} для встроенного набора использует дату после source_date и 365 дней истории; без source_date — сегодня по UTC и 90 дней. Период закупки и страховой запас по умолчанию равны 14 и 7 дням.

Для PUT отправляйте сам набор, без оболочки ответа GET, и текущий ETag в If-Match, включая кавычки. При конфликте ревизий возвращается 412: перечитайте данные перед повторной записью. Отсутствующий If-Match даёт 428. Ответы расчёта содержат X-Dataset-Revision; интерфейс проверяет его перед экспортом.

Настройки и Docker

Переменная	По умолчанию	Назначение
HTTP_ADDR	127.0.0.1:8080	Адрес сервера
DATA_FILE	data/warehouse.json	Файл хранилища
SEED_EXCEL	Не задана	1 включает автозаполнение нового склада при явном DATA_FILE; без явного DATA_FILE оно включено автоматически
API_KEY	Пусто	Общий ключ доступа, минимум 24 символа, без пробелов по краям
CORS_ORIGIN	Пусто	Разрешённый origin отдельного веб-клиента

Для работы вне loopback-адреса нужен API_KEY. Передавайте его как Authorization: Bearer <ключ> или введите в настройках подключения сайта. Интерфейс хранит ключ только в памяти вкладки.

Запуск через Docker Compose:

export API_KEY="$(openssl rand -hex 32)"
docker compose up --build -d

Откройте http://127.0.0.1:8080 и введите ключ. Контейнер запускается от непривилегированного пользователя, автоматически заполняет новый склад и хранит данные в томе warehouse-data. docker compose down останавливает сервис с сохранением тома.

Для отдельного пустого склада задайте новый путь явно: DATA_FILE=data/empty-warehouse.json SEED_EXCEL=0 go run .. Существующий файл при этом не очищается.

Разработка и проверки

go test -race ./...
go vet ./...
go build -o bin/backend .
python3 -m unittest discover -s scripts -p 'test_*.py'

Браузерные тесты требуют Node.js 20+ и Chromium. Они запускают отдельный сервер с временным складом:

npm ci
npx playwright install chromium
npm run test:syntax
npm run test:browser

Для сценариев только IEK, только Systeme Electric и обоих поставщиков с исходными книгами:

SUPPLIER_WORKBOOK_DIR="$PWD" go test ./internal/workbook -v
SUPPLIER_WORKBOOK_DIR="$PWD" npm run test:browser

Перед ними соберите bin/backend командой выше. Для установленного Chrome можно задать CHROME_BIN=/path/to/chrome. Сценарий реального товара проверяется командой go test ./internal/realdata -run TestLiveDemoSKUTrace -v.

Каталог	Содержимое
internal/planning/	Дневной и месячный расчёт, модель данных
internal/workbook/	Чтение XLSX и прямой импорт
internal/realdata/	Встроенный набор и аудит источников
internal/httpapi/, internal/storage/	API, CSV и атомарное сохранение снимков
internal/webui/	Интерфейс, встроенный через go:embed
scripts/, tests/	Конвертеры и браузерные тесты

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