Электрокомплект · HackAlem AI

Рабочий локальный MVP помощника планирования закупок для кейса ТОО «Электрокомплект». Менеджер импортирует шесть Excel-источников SystemElectric и/или ИЭК, загружает демонстрационный JSON или выбирает встроенный демо-набор. Затем выбирает разрез и допущения, рассчитывает рекомендации, корректирует количество, утверждает план и скачивает CSV.

Демонстрационные данные вымышлены. Реальный режим читает только выбранные локальные папки; исходные Excel не изменяются. Внешняя передача данных выполняется только при отдельном запуске AI-анализа и подтверждении для реальных данных.

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

Нужен Node.js 20 или новее и современный браузер. Зависимостей npm и сборки нет: используется встроенный в Node.js сетевой клиент. Устанавливать пакеты через npm install не требуется. AI-аналитик необязателен: без ключа расчёт, утверждение и CSV продолжают работать.

Из корня репозитория:

node server.js

Откройте http://127.0.0.1:3000. Эквивалентная команда при доступном npm — npm start. Сервер слушает только 127.0.0.1. Остановка — Ctrl+C. HTML нужно открывать через сервер: запуск файла двойным щелчком не поддерживается из-за ES-модулей.

На Windows можно использовать .\start.cmd: он ищет Node в PATH, затем в стандартном пути Visual Studio 2022 Community. На машине разработки Node.js найден в поставке Visual Studio, но отсутствует в PATH. Прямая команда PowerShell для этой машины:

& 'C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Microsoft\VisualStudio\NodeJs\node.exe' server.js

Необязательная настройка AI-аналитика

Скопируйте пример настроек и добавьте ключ OpenAI локально:

Copy-Item .env.example .env
notepad .env

Укажите OPENAI_API_KEY=... и при необходимости измените OPENAI_MODEL. В примере уже задана модель gpt-6-luna. Сохраните .env, остановите старый сервер Ctrl+C и снова запустите .\start.cmd. Сервер загружает .env при старте; существующие системные переменные окружения имеют приоритет. Устанавливать SDK или другие пакеты не нужно. Ключ передаётся только в заголовке серверного запроса к OpenAI, не выдаётся браузеру и исключён из Git. Никогда не вставляйте ключ в чат, README или файл .env.example.

При занятом порте задайте другой, например в PowerShell:

$env:PORT = '3001'
node server.js

Если сервер уже работал до обновления проекта, остановите его Ctrl+C, снова выполните .\start.cmd и обновите страницу браузера. Новый импорт требует обновлённого локального сервера.

Как открыть реальные данные на Windows

1. Из корня проекта выполните .\start.cmd, откройте http://127.0.0.1:3000.
2. В блоке Excel проверьте две папки. По умолчанию это Downloads\Systeme electric\Systeme electric и Downloads\IEK\IEK текущего пользователя. Путь можно изменить в интерфейсе; пустой путь исключает поставщика из импорта. В выбранной папке должны быть все шесть типов файлов.
3. Нажмите кнопку импорта. Просмотрите отчёт: все файлы и листы, число товаров, периоды, пропуски, несопоставленные позиции и кандидаты для сверки продаж. Названия файлов используются для выбора профиля, а периоды продаж — из содержимого ячеек.
4. Для совокупного плана выберите общий разрез без распределения по складам и источник «Ежемесячные продажи». Подтвердите фактическую дату недатированного снимка SystemElectric. Срок нового заказа, страховые дни, период пересмотра, отсутствующие MOQ/кратность и год сокращённой ETA — видимые допущения, которые нужно проверить перед подтверждением.
5. Для ИЭК месячный остаток — начальный остаток на первое число. Если решили использовать этот старый снимок, явно разрешите это в настройках. Пустая ячейка останется неизвестной даже после разрешения старого снимка. Вариант «неизвестный остаток = 0» — отдельное допущение, а не подтверждённый ноль.
6. Запустите расчёт. Все товары сохраняются; таблица показывает страницы по 100 строк и поиск по всему результату. «Почему столько?» показывает исходные значения, даты, источники и расчёт.
7. Исправьте количество с учётом MOQ и кратности. Строку без достаточных данных можно явно исключить из заказа или принять самостоятельное решение вручную. Неопределённые строки нельзя незаметно утвердить как нулевые. Для отмеченных различий закупочной и складской единиц положительный заказ запрещён: коэффициент пересчёта не подтверждён, такие строки рассчитываются отдельно.
8. Утвердите весь подготовленный план и скачайте CSV. Фильтр поиска/страница не ограничивают утверждение и экспорт. Исключённые строки остаются в CSV с явным статусом и пустым количеством к заказу.

Для отдельного склада доступна подробная динамика продаж. Общие остатки и партии в пути на этот склад автоматически не распределяются. Разрез месячного отчёта не доказан: числовую сверку следует трактовать как сопоставимую только после подтверждения одинакового охвата. Подробные и месячные продажи никогда не складываются.

Подробное описание форматов и допущений: docs/excel-import.md.

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

• Загрузка JSON с проверкой схемы, ссылок, дат, количеств и полноты истории наличия; скачиваемый пример JSON.
• Детерминированные демонстрационные данные: 8 товаров, 2 склада, 3 категории, 3 поставщика, 996 дней истории.
• Локальное чтение всех XLSX-файлов двух поставщиков: MOQ/кратность, подробная динамика, месячные остатки, месячные продажи, сезонность, путь. Сопоставление по коду 1С и уникальному артикулу внутри поставщика, отчёт конфликтов.
• Отдельное помесячное ядро реальных данных: без искусственного ежедневного наличия, с неизвестными остатками, незавершёнными месяцами, датами/источниками, отдельными возвратами и корректировками.
• Расчёт по продажам, остаткам, партиям в пути и их ETA, сроку поставки товара, периоду пересмотра и страховому запасу категории.
• В демо/JSON — сезонность по 12 индексам категории; в Excel — нормированные годовые профили поставщиков. Устойчивый исторический тренд и ручной годовой прогноз, заменяющий тренд.
• В демо/JSON — оценка упущенного спроса в дни подтверждённого отсутствия товара, без повторного добавления к прогнозу. В реальных Excel показатель недоступен без ежедневного наличия.
• В демо/JSON — исключение разовых крупных клиентских заказов после агрегации строк одного клиента за день; сохранение регулярных крупных покупок. В реальных Excel без ID клиента автоматическое исключение отключено.
• Фильтрация по складу/категории, группировка по поставщикам, срочность и числовое объяснение каждой рекомендации.
• Корректировка целого количества с проверкой кратности упаковке, утверждение текущей версии и экспорт CSV.
• Любое изменение количества снимает утверждение; изменение источника или параметров требует нового расчёта. Экспорт неутверждённого или изменённого снимка блокируется.

Заказы поставщикам не отправляются. CSV — универсальный файл, не документ заказа конкретной учётной системы. Совместимость с каким-либо форматом 1С без образца не заявляется.

AI-аналитик закупок

Для первой проверки нажмите «Демонстрационный набор», выполните расчёт и откройте AI-аналитик закупок. При желании выберите товар и задайте вопрос, затем нажмите «Анализировать текущий план». Вызов использует настроенный OpenAI API и может тарифицироваться согласно вашему проекту; автоматический запрос при загрузке, импорте или расчёте не выполняется.

Перед запросом показывается точное содержимое JSON: итоги плана, сводка по поставщикам, до пяти приоритетных строк, выбранная строка и вопрос. Для реальных данных обязательна отдельная галочка согласия; при изменении вопроса, позиции, параметров или количества согласие снимается. Передаются только коды/названия выбранных позиций, значения расчёта и статусы, до пяти ссылок на их исходные ячейки и короткие объяснения. Полные Excel, история продаж и полный список товаров не отправляются. Демо искусственное, но AI-вызов для него тоже обращается к API.

AI отвечает по-русски, различает факты, допущения и отсутствующие сведения и считает текст Excel недоверенными данными. Модель объясняет готовый расчёт, но не меняет количество, не утверждает план и не отправляет заказ. Ответ остаётся в браузере; после изменения плана или настроек помечается устаревшим. Без ключа и при ошибке OpenAI расчёт и экспорт доступны.

По умолчанию используется gpt-6-luna; укажите модель, доступную вашему API-проекту, в OPENAI_MODEL. Описание моделей и Responses API: официальное руководство по выбору модели и справочник Responses API.

Запрос идёт с локального сервера на https://api.openai.com/v1/responses, с store: false, тайм-аутом 60 секунд и ограничением размера запроса/ответа. Лимит генерации — 6 000 токенов, включая внутренние рассуждения; для модели gpt-6-luna явно задано reasoning.effort: low. Модель получает инструкцию отвечать до 300 слов. JSON-ответ ограничен 64 КиБ, текст анализа — 12 000 байт. Незавершённый ответ не показывается как готовый анализ: отдельно объясняются исчерпание лимита генерации, ограничение содержимого и неизвестная причина. Автоматических повторных платных запросов нет. store: false отключает сохранение объекта ответа через API, но не является обещанием нулевого хранения или обработки внешним сервисом. Учитывайте настройки и условия хранения данных OpenAI; не включайте персональные или лишние сведения. AI-вывод проверяйте по источникам: модель может ошибиться или неверно истолковать показатель.

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

Vanilla JavaScript (ES-модули), HTML, CSS; Node.js http для локальной раздачи разрешённых статических файлов и API Responses; встроенные fetch, node:test и node:assert/strict.

index.html / src/styles.css     русский адаптивный интерфейс
src/app.js                     загрузка, фильтры, таблицы, действия менеджера
src/validation.js              строгая проверка входного JSON
src/demo.js                    синтетический набор с фиксированным seed
src/engine.js                  чистое расчётное ядро, без сетевых вызовов
src/workflow.js                черновик, коррекции, утверждение, CSV
src/analyst-payload.js         компактная сводка и allow-list полей AI-запроса
src/openai-client.js           серверный клиент Responses API, лимиты и тайм-аут
src/env.js                     загрузка локального .env при старте
server.js                      локальный статический сервер
scripts/generate-demo.js       создание data/demo.json
tests/                         расчёт, данные, импорт, workflow и HTTP

Демо/JSON, импорт и расчёт выполняются локально в памяти. Для Excel браузер передаёт только пути локальному серверу на 127.0.0.1; сервер читает XLSX, нормализует записи и возвращает набор браузеру. Исходные книги сами по себе во внешние сервисы не загружаются. Только по кнопке и с согласием для реального набора сервер передаёт ограниченную AI-сводку OpenAI. Сервер не сохраняет планы; после перезагрузки страницы импорт, утверждение и ответ аналитика теряются. Утверждение — локальный шаг менеджера, не электронная подпись и не многопользовательское согласование.

Новые модули: src/xlsx-reader.js — чтение ZIP/XML и кэшированных значений формул; src/excel-import.js — проверенные профили поставщиков и сопоставление; src/local-import.js — локальные папки; src/real-engine.js — месячный расчёт. API: GET /api/sources, POST /api/import, GET /api/ai/status, POST /api/ai/analyze. API ограничен локальным host и тем же origin; статические файлы выдаются только из явного списка, .env не раздаётся. Зависимостей npm по-прежнему нет.

Методология расчёта

Ниже описано ежедневное ядро демонстрационного JSON v1. Реальный Excel v2 использует отдельную месячную методологию: по месячным снимкам не восстанавливаются точные дни отсутствия, а без ID клиента не исключаются автоматически его разовые заказы. Эти показатели в реальном режиме обозначены как недоступные.

Расчёт независим для каждой пары товар–склад. asOf — начало дня снимка; история заканчивается предыдущим днём. Поступления доступны в начале дня ETA. Категория задаёт месячные сезонные индексы, период пересмотра и число страховых дней. Индексы предоставляются во входных данных, автоматически из истории не оцениваются.

1. Суммируем продажи одного клиента за день и исключаем редкие крупные события. Порог использует медиану клиентских заказов, медианное абсолютное отклонение и типичный дневной объём. Устойчивые повторные покупки сохраняются; подробное правило и ограничения описаны в методологии.
2. Делим очищенные продажи на сезонный индекс. Для обучения используем дни подтверждённого наличия, включая нулевые продажи. Дни отсутствия не превращаются в нулевой спрос.
3. Оцениваем устойчивый логарифмический тренд по недельным средним. Автоматический годовой прирост ограничен диапазоном −80%…+200%; при недостатке истории используется 0% с предупреждением. Ручной прирост от −90% до +200% полностью заменяет автоматический.
4. Приводим наблюдения последних 180 календарных дней к дате снимка выбранным трендом и усредняем; при недостатке наблюдений используем всю историю. Прогноз дня = база × (1 + прирост)^(дни / 365) × сезонный индекс. Один тренд используется при приведении истории и при прогнозировании; повторного роста нет.
5. Оцениваем спрос в исторические дни отсутствия той же моделью. Оценка показывается отдельно и второй раз к прогнозу не прибавляется.
6. Строим календарь на срок поставки + период пересмотра. Буфер равен прогнозу на страховые дни после горизонта. С даты новой поставки находим максимальную дневную потребность с учётом всех поступлений к соответствующему дню и округляем вверх до упаковки.

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

Пример: спрос 10 шт./день, срок 2 дня, пересмотр 3 дня, буфер на 1 день, остаток 30, нет пути, упаковка 10. Спрос на горизонт — 50, буфер — 10; заказ = 50 + 10 − 30 = 30. Если остаток 0, первые 20 единиц спроса будут потеряны до поступления; обычный заказ составит 40, а строка получит критическую срочность и отдельное предупреждение о 20 единицах раннего дефицита.

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

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

Этот раздел относится к демонстрационному JSON. Реальные источники XLSX читаются отдельной кнопкой; преобразовывать их в ежедневный JSON не нужно. Исходные XLSX и производные данные (private-data/, data/, exports/, import-reports/) исключены из Git. Не добавляйте их с git add -f.

Полная спецификация — docs/data-format.md. Один JSON содержит справочники товаров, складов, категорий и поставщиков, продажи с обезличенным customerId, ежедневное наличие, текущие остатки и партии в пути. Даты — YYYY-MM-DD, числа — JSON-числа. availability обязательна на каждый день каждой пары товар–склад: по отсутствию продаж нельзя достоверно отличить отсутствие спроса от отсутствия товара.

Самый простой пример — кнопка «Скачать пример JSON». Для создания файла командой:

node scripts/generate-demo.js

Результат — data/demo.json (исключён из Git). Демонстрационный seed 20260923, история 2024-01-01…2026-09-22, снимок 2026-09-23. Заложены сезонность, базовый рост 14% в год, дефицит, разовые заказы 625 (350+275 одному клиенту) и 800 единиц, регулярные недельные/месячные оптовые покупки и разные ETA. Наблюдаемый тренд отдельных товаров может отличаться от 14% из-за шума и регулярных фиксированных объёмов.

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

CSV содержит поставщика, склад, товар, рекомендованное и утверждённое количество, показатели расчёта, объяснение, демо-маркировку, дату и ID утверждённого плана. Экспортируются все рассчитанные строки, включая нулевые: при дальнейшей обработке отберите положительные утверждённые количества. Кодировка UTF-8 с BOM, разделитель ;, переносы CRLF. Текстовые формулы экранируются от исполнения в табличных редакторах.

Для реальных рекомендаций добавлены код 1С, артикул, MOQ, кратность, решение менеджера, ограничения, источники/числовые факты и настройки. Пустое количество/остаток означает неизвестность; статус исключения нельзя трактовать как заказ. Свободный остаток не уменьшается на резерв повторно.

Проверки

node --test

На машине разработки без Node в PATH:

& 'C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Microsoft\VisualStudio\NodeJs\node.exe' --test

Обязательное требование	Автоматические проверки
Продажи, остатки, категории, путь, ETA, сроки и прогноз	tests/engine.test.js: формула, упаковка, календарный дефицит, границы ETA, просрочка
Сезонность и рост без двойного учёта	tests/engine.test.js: сезонный постоянный спрос, восстановление тренда, замена ручным ростом
Упущенный спрос	tests/engine.test.js: дефицит, нулевые продажи при наличии, отсутствие наблюдений
Разовые и регулярные крупные продажи	tests/engine.test.js, tests/integration.test.js: split-строки, постоянный оптовик, сезонный демо-набор
Поставщики, срочность, объяснения	tests/engine.test.js, tests/integration.test.js: группировка, фильтры, числовые поля
Полный сценарий	tests/integration.test.js: сериализация/импорт JSON → расчёт → коррекция → утверждение → CSV
AI, серверный ключ, allow-list, размер/тайм-аут и имитации Responses API	tests/ai-analyst.test.js, tests/env.test.js, tests/server.test.js
Валидация и локальная безопасность	tests/validation.test.js, tests/workflow.test.js, tests/server.test.js

Пример ручной проверки интерфейса:

1. Откройте приложение, нажмите «Демонстрационный набор». Должна появиться явная демо-маркировка.
2. Выберите «Демо-склад „Север“» и «Электроустановочные изделия», запустите расчёт. Должны быть 4 строки одного поставщика.
3. Раскройте «Почему столько?» для автомата 16 А: исключён один заказ на 625, есть оценка исторического упущенного спроса и числовая формула.
4. Измените количество на число, кратное упаковке. До утверждения CSV недоступен. Отрицательное, дробное и некратное значение должны блокировать утверждение.
5. Нажмите «Утвердить план», затем «Скачать CSV»; проверьте изменённое количество и демо-маркировку. Повторное изменение должно снять утверждение.
6. Скачайте пример JSON, загрузите его кнопкой «Загрузить JSON», повторите расчёт. Попробуйте некорректный JSON: должна появиться ошибка без подмены файла демонстрационным набором.
7. Измените склад, категорию или прогноз: предыдущий результат должен исчезнуть до нового расчёта.

Проверено на предоставленных наборах: 12 файлов, 3 907 товаров (SystemElectric — 724, ИЭК — 3 183), без ограничения числа строк расчёта. Все 101 синтетический тест прошли, включая прежние проверки демо. Независимый аудит через openpyxl проверил 6 товаров и 93 исходных значения/месячных агрегата. SHA-256 всех 12 исходников совпал до и после работы.

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

Новые синтетические тесты: tests/xlsx-reader.test.js, tests/excel-import.test.js, tests/real-engine.test.js, расширенные проверки workflow и локального API. Они не содержат реальных кодов, продаж или клиентов. Полный объём локальных Excel проверяется отдельно явной командой:

& 'C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Microsoft\VisualStudio\NodeJs\node.exe' scripts/verify-local-import.js

Команда импортирует выбранные папки целиком, проверяет влияние запасов/поставок/роста/сезонности/партий и цикл утверждения, сравнивает SHA-256 исходников до/после. Она записывает производные результаты только в private-data/, исключённую из Git. Для других папок можно задать SYSTEME_DATA_DIR и IEK_DATA_DIR. Независимая сверка нескольких товаров через Python/openpyxl доступна в scripts/crosscheck-local.py; Python нужен только для этого дополнительного аудита, не для приложения.

Внешние сервисы, безопасность и ограничения

OpenAI Responses API — единственный внешний сервис, используемый только для явно запрошенного AI-анализа. Автоматической аналитики, CDN и удалённых шрифтов нет. Без нажатия кнопки анализа запросов OpenAI нет. Ключ хранится в локальном .env, не попадает в код браузера, журналы или ответы ошибок; сервер раздаёт файлы по явному списку и не отдаёт .env. .env, Excel, CSV и производные данные исключены из Git. CSP браузера подключается только к локальному приложению: OpenAI вызывает сервер. Аутентификации нет; MVP предназначен для локальной работы одного менеджера.

• Поддержаны JSON v1 и конкретные изученные XLSX-профили SystemElectric/ИЭК. XLS, CSV-импорт и универсальная интеграция с 1С не реализованы. Пределы JSON v1 (30 МиБ, 28…1830 дней, 200 000 записей наличия, 300 000 продаж) не применяются к числу товаров Excel v2. XLSX не усекается; защитные пределы архива вызывают явную ошибку (128 МиБ на исходный файл, 256 МиБ на ZIP-запись, 768 МиБ распакованного содержимого).
• В демо сезонность задаётся категорией. В Excel индексы строятся из полных завершённых годовых агрегатов поставщика, с нормировкой масштаба и продолжительности месяцев. Единицы агрегата не подписаны, поэтому перенос его сезонности на SKU — явное допущение. Нет моделирования праздников, акций, замен, внутридневного дефицита и рабочего календаря. Сроки — календарные дни.
• Определение выбросов — эвристика, не доказательство разового характера. Недостаток наблюдений, редкие контракты и смена поведения требуют проверки менеджером. Включение исключённого события выполняется изменением входных данных/правил, отдельной кнопки отмены выброса нет.
• Упущенный спрос — оценка на основе доступных наблюдений, без гарантии точности. Нет обучения на данных компании, исторического бэктеста, оценки финансового эффекта или обещания уровня сервиса.
• На товар назначен один поставщик. Нет сравнения цен, альтернативных поставщиков, бюджетов, моделирования будущих резервов и обязательных клиентских заказов, минимальной суммы закупки и оптимизации перемещений. Готовый свободный остаток используется без повторного вычитания уже учтённого резерва.
• AI-аналитик зависит от доступности и ограничений настроенного OpenAI API. Он может ошибиться, не является основанием для утверждения, а его ответ не сохраняется на сервере. Реальные бизнес-данные уходят внешнему сервису только после отдельного согласия менеджера.
• Нет сохранения сессий, истории согласования, ролей или подписей; экспорт сохраняет результат. Заказы не отправляются автоматически.