EKT: объяснимое пополнение склада

Проект команды Furia для кейса ТОО «Электрокомплект» на HackAlem AI. Приложение помогает менеджеру закупок рассчитать заказ поставщикам, проверить обоснование по каждому товару, изменить количество, утвердить результат и выгрузить CSV/XLSX.

Эксперту для проверки: клонируйте репозиторий, установите зависимости и запустите встроенное демо по инструкции ниже. Приватные архивы, API-ключи, платные сервисы, Docker, Node.js, GPU и отдельная база данных не нужны. Основной расчёт работает локально.

Это MVP: состояние хранится в памяти сессии, внешней отправки заказа нет, совместимость с конкретным импортом 1С ещё не подтверждена. Синтетическое демо явно отделено от данных партнёра и ручных допущений.

1. Назначение и принцип работы

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

1. Импорт и нормализация таблиц, проверка типов, связей и происхождения.
2. Выделение регулярного спроса, исключение разовых крупных событий.
3. Компенсация упущенного спроса по подтверждённым периодам отсутствия товара.
4. Прогноз с сезонностью, устойчивым трендом и отдельным планом роста.
5. Расчёт потребности с учётом запаса, пути, минимальной партии и кратности.
6. Проверка менеджером, ручная корректировка, утверждение и экспорт.

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

Горизонт задают срок поставки и период пересмотра. Доступный запас берётся напрямую либо как on_hand минус reserved; резерв повторно не вычитается. При нулевой потребности MOQ не создаёт заказ. Месячная история и её детализация не суммируются повторно.

Детектор выбросов группирует продажи по обезличенному клиенту и дате, учитывает повторяемость крупных покупок и массовые пики. Без клиента используется документ, но документ не выдаётся за клиента. При менее 12 положительных событиях эвристика неприменима. При наличии не менее двух полных годовых циклов используется сезонность самого SKU; внешний prior применяется при недостатке такой истории, затем — нейтральный профиль. Нулевые продажи не доказывают stockout. Формулы, пороги и допущения описаны в методологии.

2. Архитектура

Один Python-процесс Streamlit. Frontend, Backend и Logic разделены по модулям, взаимодействуют через Python-функции и pandas DataFrame, не через HTTP API.

Браузер -> Streamlit -> app.py -> ekt_ui.app
                                  |
              Frontend: формы, таблицы, фильтры, session_state
                                  |
              Backend: application -> ingest / partner -> schema
                                  |
              Logic: demand -> forecast -> engine -> review
                                  |
              Backend: export -> CSV/XLSX -> скачивание

Путь	Назначение
app.py	Точка запуска, подключает локальный src
src/ekt_ui/	Импорт в UI, таблицы, аналитика, темы, правки и состояние сессии
src/ekt/application.py, ingest.py, partner.py	Операции над наборами, канонический импорт и адаптеры IEK/Systeme
src/ekt/schema.py	Единый Bundle, схема, нормализация, валидация и fingerprint
src/ekt/demand.py, forecast.py, engine.py	Спрос, прогноз и расчёт заказа
src/ekt/review.py, export.py	Утверждение, состав выгрузки и сериализация
src/ekt/demo.py	Воспроизводимый синтетический набор
tests/, scripts/	Автотесты, smoke и оценка прогноза
.streamlit/config.toml	Адрес, порт, лимит загрузки и темы

Backend и Logic не импортируют UI. БД, очереди задач, внешний AI API и промышленная авторизация не используются. Данные, правки и утверждения могут исчезнуть при перезагрузке страницы или перезапуске процесса. Подробности: DEVELOPMENT, действующий API: INTERFACES.

3. Технологии и зависимости

Для воспроизведения используйте Python 3.12, 64-разрядную ОС, Git и современный браузер. Нужны Python-модули venv и pip, права записи в каталог проекта и свободный локальный порт. Интернет требуется для клонирования и первоначальной установки.

Компонент	Версия в lock-файле	Назначение
Streamlit	1.64.0	Интерфейс и локальный сервер
pandas	3.0.6	Таблицы и временные ряды
NumPy	2.5.3	Числовые операции
openpyxl	3.1.5	Чтение и запись XLSX
Altair	6.3.0	Графики
pytest	9.1.1	Автотесты

Все прямые и транзитивные зависимости закреплены в requirements.lock. Устанавливайте весь файл. pyproject.toml допускает более широкий диапазон Python, но проверенное окружение и setup.ps1 ориентированы на 3.12. Командой проверялись Windows и Linux; отдельная приёмка macOS не заявляется.

Универсальные минимальные требования RAM и максимальный каталог не установлены. В синтетическом профиле ядра до интеграции UI-02 на 1000 SKU / 365000 продаж расчёт занял 40.14 с, fingerprint — 1.24 с, пик процесса с прежним UI — 541 МиБ. Замер выполнен на Windows/Python 3.12.14, история 365 дней, лимиты профилировщика 180 с / 800 МиБ. Время и память нового UI отдельно не измерялись; это единичный синтетический замер, не SLA и не замер реальных данных. Условия и остальные размеры: handoff Logic.

4. Установка

Клонируйте свежий main в новый каталог. Если GitHub запросит авторизацию, используйте учётную запись с доступом; не сохраняйте токены в репозитории.

git clone --branch main https://github.com/BAITC-Hacks/hack-2f144651-furia.git
cd hack-2f144651-furia
git rev-parse HEAD

Последняя команда фиксирует проверяемую версию. Все последующие команды выполняются из корня репозитория, где находятся app.py и requirements.lock.

Windows PowerShell

py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.lock
.\.venv\Scripts\python.exe -m pip check

Альтернатива первым двум командам: ./setup.ps1. Скрипт ищет Python 3.12 через Windows launcher, затем через окружение Codex, если оно установлено. Codex не обязателен. Явный путь: ./setup.ps1 -PythonExe 'C:\Python312\python.exe'. Если PowerShell запрещает скрипты, используйте команды выше, не меняя системную политику. Активация .venv не требуется.

Linux и macOS

python3.12 -m venv .venv
.venv/bin/python -m pip install -r requirements.lock
.venv/bin/python -m pip check

При отсутствии Python 3.12, venv или pip установите их средствами своей ОС. macOS-команды предназначены для стандартной Python-среды, но не являются заявлением о выполненном тесте на macOS.

5. Запуск и остановка

Windows:

.\.venv\Scripts\python.exe -m streamlit run app.py

Linux / macOS:

.venv/bin/python -m streamlit run app.py

Откройте http://127.0.0.1:8501. Оставьте терминал открытым. Остановка сервера: Ctrl+C в этом терминале. Не используйте python app.py: UI нужен Streamlit runner.

Если порт занят, выберите другой, не останавливая чужой процесс:

.\.venv\Scripts\python.exe -m streamlit run app.py --server.port 8502

В Linux/macOS замените путь интерпретатора на .venv/bin/python. Адрес станет http://127.0.0.1:8502. Проверка готовности процесса в другом терминале PowerShell:

(Invoke-WebRequest http://127.0.0.1:8501/_stcore/health).Content

Linux/macOS: curl -fsS http://127.0.0.1:8501/_stcore/health. Ожидается ok. Health подтверждает готовность процесса, не корректность бизнес-расчётов.

6. Параметры окружения

Обязательных переменных окружения нет. .env, secrets.toml, токен OpenAI, Google API, параметры БД и облачные учётные данные для основного запуска не нужны.

Параметр	Значение / назначение
.streamlit/config.toml: server.address	127.0.0.1, только та же машина
server.port	8501, переопределяется --server.port
server.headless	true, браузер открывается вручную
server.maxUploadSize	80 МБ на файл; не гарантия обработки любого такого набора
Бюджет импорта	До 100 МиБ входа суммарно на вызов, 200 МиБ распакованных данных, 100 файлов, 500 000 строк и 5 000 000 ячеек
browser.gatherUsageStats	false, телеметрия Streamlit отключена
Тема	Light / Dark / System через меню Streamlit; палитры в конфигурации
EKT_PARTNER_ARCHIVE_DIR	Необязательная папка только для opt-in тестов оригиналов
Дата расчёта	Задаётся в UI, совпадает с датой текущего остатка; для демо 22.09.2026

Сервер предназначен для локальной экспертной проверки. Не публикуйте его с приватными данными в интернет: промышленная аутентификация, разграничение доступа, постоянное хранение и аудит действий не реализованы. Сетевой деплой требует отдельного решения.

7. Основной сценарий проверки экспертом

Начните с новой сессии браузера. Демо полностью синтетическое, архивы не нужны.

1. Нажмите «Попробовать на демо» на первом экране или «Загрузить демо» в боковой панели.
2. В «Параметры расчёта» оставьте дату 22.09.2026, включённые исключение разовых заказов и компенсацию stockout.
3. Нажмите «Рассчитать предложения». Ожидаются 4 позиции двух поставщиков: IEK и Systeme, маркировка синтетики и рассчитанные рекомендации.
4. Выберите товар, откройте «Почему столько?». Проверьте прогноз, запас, путь, MOQ/кратность и объяснение. Просмотрите вкладки «Контроль данных», «Поставки», «Входные таблицы».
5. В таблице «Заказ» у одной позиции задайте 0 в поле «Заказать», добавьте причину, например «Проверка ручного решения», и подтвердите ввод ячейки. Ноль должен сохраниться; позиция должна оставаться выбранной.
6. Нажмите «Утвердить выбранные позиции». Ожидается локальное утверждение без отправки поставщику.
7. Установите фильтр IEK. Видны 2 строки, но при исходном выборе всех позиций «Экспорт» сохраняет 4 строки, включая скрытые. Скачайте CSV/XLSX: ручной ноль сохранён, approval_status равен approved.
8. Измените количество или причину после утверждения. Прежнее утверждение должно отмениться. Изменение входов или параметров расчёта также требует нового расчёта/утверждения.
9. Дополнительно проверьте темы, поиск, плотность таблицы и «Мои представления». Представления сохраняют фильтры только в текущей сессии, не заказы в БД.

Любое отличие ручного количества от рекомендации требует причины; пустое поле количества означает оставить рассчитанную рекомендацию, ручной ноль — отдельное решение. Даже небольшое изменение считается ручной правкой. Выбранная позиция с нечисловой, бесконечной или отрицательной рекомендацией не утверждается даже после ручной замены. Изменение входов, параметров расчёта, результата, количества или причины отменяет прежнее утверждение. Для кратности заказа поддерживается точность до 8 знаков после запятой; меньшая кратность или большее число знаков даёт локальную ошибку расчёта, а переполнение не подменяется нулевым заказом.

CSV/XLSX скачиваются через браузер. При открытии CSV в Excel задайте текстовый тип столбца кода; XLSX записывает коды текстом. Недопустимые для XML управляющие знаки видимо кодируются только в копии XLSX; заголовки и ячейки сверх лимита Excel либо непредставимые XML символы дают ошибку экспорта с координатой без обрезания данных. Размер XLSX может немного меняться. «Общая сумма заказа: Нет цен» отражает отсутствие согласованного контракта закупочных цен.

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

Windows, отдельный терминал из корня проекта:

.\.venv\Scripts\python.exe scripts/smoke.py
.\.venv\Scripts\python.exe -m pytest tests/test_acceptance.py -q -p no:cacheprovider
.\.venv\Scripts\python.exe -m pytest -q -p no:cacheprovider
.\.venv\Scripts\python.exe -m pip check

Linux/macOS: замените .\.venv\Scripts\python.exe на .venv/bin/python. Smoke проверяет импорт демо, расчёт, ручной ноль, утверждение и оба формата экспорта. Ожидаемый JSON: mode: synthetic, positions: 4, suppliers: 2, manual_zero: 0.0, approval: approved, положительные csv_bytes и xlsx_bytes. Успешный exit code: 0. Pytest должен завершиться без failed/errors. Skipped без приватных оригиналов ожидаемы, но не означают успешной проверки этих данных.

Must have	Проверки tests/test_acceptance.py
M1	Влияние истории, срока, роста, категории, остатка и пути
M2	Сезонность и устойчивый рост, отличимые от единичного всплеска
M3	Компенсация подтверждённого stockout без двойного учёта
M4	Разовый заказ, несколько документов клиента, сохранение регулярных крупных покупок
M5	Разные поставщики, позиции, объяснения и срочность

Последний полный прогон после интеграции AUD-LOG-01/AUD-BE-01 с UI-02 (продуктовый код cf2b7e8): 424 passed, 20 skipped, Windows/Python 3.12.14, 139.86 с. Smoke успешен; 20 пропусков относятся к приватным оригиналам. Последующее слияние README-01 меняет только документацию. Команды и ограничения: STATUS, handoff Logic.

Дополнительная синтетическая оценка прогноза:

.\.venv\Scripts\python.exe scripts/evaluate_forecast.py --demo --output work/evaluation.json

Она сохраняет локальный JSON с walk-forward метриками, не доказывает точность реальных закупок. Приватные исходники и диагностические выгрузки не публикуйте.

9. Собственные данные

Выберите «Мои данные». Канонический импорт: ZIP с CSV, XLSX с именованными листами или отдельные CSV. Шаблон доступен через «Скачать демо для импорта». Таблицы: products, sales, monthly_sales, stock_snapshots, inbound, stockouts, policies, growth_plan, seasonal_prior. Поля, единицы и обязательность: INPUT_GUIDE, точная схема: schema.py. Происхождение задаётся явно: synthetic, partner или manual.

«Дополнить текущий набор» заменяет загруженную таблицу целиком, а не добавляет строки. Для IEK/Systeme выберите формат отчётов, поставщика, дату выгрузки и только действительно подтверждённые область склада, семантику MOQ и единицы. Ошибка импорта сохраняет прежний набор. Не включайте подтверждения ради получения числа. Помимо лимита Streamlit 80 МиБ на файл действует бюджет одного вызова импорта: 100 МиБ входных данных, 200 МиБ после распаковки ZIP/XLSX, 100 файлов, 500 000 строк и 5 000 000 ячеек. Отдельный файл или архив ограничен 100 МиБ. Проверяется прямоугольный размер всех листов XLSX до загрузки книги; превышение явно отклоняется. Подробности: INPUT_GUIDE.

Opt-in проверка оригиналов на Windows:

$env:EKT_PARTNER_ARCHIVE_DIR = 'C:\private\ekt'
.\.venv\Scripts\python.exe -m pytest tests/backend/test_partner_originals.py -q -rs -p no:cacheprovider
Remove-Item Env:EKT_PARTNER_ARCHIVE_DIR

Папка должна содержать IEK.zip и Systeme.zip; второй может быть копией выданного Systeme electric.zip с новым именем и неизменными байтами. Файлы в Git не входят. Linux/macOS: EKT_PARTNER_ARCHIVE_DIR=/private/ekt .venv/bin/python -m pytest tests/backend/test_partner_originals.py -q -rs -p no:cacheprovider.

10. Ограничения и диагностика

• Оригиналы на 2377769: 2 passed, 18 skipped. Подтверждён корректный отказ: 15 ошибок Excel в MOQ IEK и 26 конфликтующих правил количества Systeme. Это не успешный полный импорт. Требуются исправленные и согласованные исходники.
• Недостающие customer_id, stockout, сроки, единицы и текущие остатки не выдумываются. IEK month_start не является текущим остатком. Неизвестное не заменяется нулём. Формулы исходного Excel не пересчитываются.
• Исправлены ошибки строковых кодов XLSX и сериализации, составных ключей, точности подписей и числовых крайних случаев; добавлен общий бюджет импорта. Остаются интерфейсные задачи AUD-FE-01: подключение общего правила подсветки/фильтра ручных правок, перехват отказа при подготовке XLSX, выбор аналитики по складу и другие пункты промпта. Актуальные результаты: STATUS; исходная сверка до исправлений — AUD-02.
• Постоянной БД, многопользовательского журнала, проверенной загрузки в 1С и внешней отправки заказа нет. Скачайте результаты до закрытия сессии. Экономия и точность на реальных закупках не измерены.
• CI временно запускается только вручную: GitHub Actions → EKT checks → Run workflow. Последний известный внешний блокер: billing lock. Отсутствие автоматического статуса не означает зелёный CI; выполняйте локальные проверки.

После разблокировки аккаунта владельцем запустите workflow вручную на актуальном main. После успешной проверки интегратор может вернуть триггеры push для main и pull_request в .github/workflows/checks.yml. До этого удалённый CI не считается подтверждённым.

Симптом	Действие
Python/Streamlit не найден	Используйте Python 3.12 и интерпретатор созданной .venv, установите lock-файл
Нет UI или ModuleNotFoundError для ekt	Перейдите в корень проекта, запускайте -m streamlit run app.py, не модуль из src напрямую
Порт занят / браузер не открылся	Выберите другой --server.port, откройте localhost вручную
В демо нет текущего остатка	Верните дату 22.09.2026, не подставляйте сегодня к старому снимку
Импорт отклонён	Прочитайте ошибку и контроль данных, исправьте источник; не отключайте проверку и не подставляйте нули
Утверждение отклонено	Проверьте причины правок, выбранные строки и доступность расчёта
Длительный расчёт	Начните с демо; большие наборы обрабатываются синхронно, гарантии времени нет

11. Дополнительная документация

• Методология, входы, API.
• Сверка с ТЗ, нагрузка, история проверок.
• Текущий интерфейс, демонстрация, сторонние компоненты.
• START_HERE, владение файлами, задачи, правила Git.

Разработка продолжается в существующем Python/Streamlit проекте. Перед изменениями проверяется свежий main; проверенные изменения публикуются без переписывания истории. Сырые архивы, клиентские данные и секреты не коммитятся. Push, локальная готовность и официальная сдача Организатору являются разными результатами; README не подтверждает факт или срок официальной сдачи.