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

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

Открыть опубликованное демо · Запустить локально · Инструкция закупщика

Данные → Прогноз спроса → План закупки → Проверка и правки → Утверждение → CSV
                              ↓
                    Сравнение вариантов → Новый план

Решение о закупке принимает человек. Приложение сохраняет расчёты, причины правок и утверждения; отправка поставщикам и в ERP не выполняется.

Содержание

1. О проекте и опубликованном демо
2. Возможности
3. Локальный запуск
4. Как пользоваться
5. Подключение данных компании
6. Архитектура и API
7. Проверки и решение проблем
8. Ограничения
9. Документация и работа команды

1. О проекте и опубликованном демо

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

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

Публичное демо и текущий main могут различаться: последняя зафиксированная облачная сборка — 19596be, а новые возможности подготовки реальных данных и сохранённых планов появились позже. Инструкции ниже относятся к текущей локальной версии репозитория. Доступность публичного UI и ответ HTTP 200 от health повторно проверены 23.09.2026; версия облачной сборки этой проверкой не обновлялась.

2. Возможности

Возможность	Что получает закупщик
Подготовка данных	Учебный набор или подключённая история IEK/Systeme Electric; проверка качества и видимые причины исключения товаров.
Остатки и условия закупки	Ввод свободного остатка, закупочных единиц, конверсии, минимальной партии, упаковки и сроков для выбранных товаров.
Прогноз спроса	Ежедневный прогноз с базовой, сезонной и ростовой составляющими; спорные разовые продажи доступны для проверки.
Расчёт пополнения	Страховой запас, порог пополнения, учёт датированных поступлений, раннего дефицита, минимальной партии и кратности упаковки.
Объяснение рекомендации	Состав количества до и после округления, запас и условия закупки, допущения и предупреждения.
Ручной контроль	Правка количества с причиной, новая версия после изменения, утверждение точной версии и выгрузка CSV.
Сравнение вариантов	Цель 95%/99%, задержка 0/7/14 дней и бюджет при наличии сопоставимых цен; выбранные условия можно применить к новому плану.
Проверка продаж	Подтверждение спорной продажи как регулярной или разовой проектной с обоснованием и отдельным пересчётом.
Сохранённая работа	Возврат к предыдущим планам, правкам, подготовленным условиям и утверждениям после перезапуска.

3. Локальный запуск

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

Понадобится Git. Выполните в терминале:

git clone https://github.com/BAITC-Hacks/hack-20ebc90b-codex-monsters.git
cd hack-20ebc90b-codex-monsters

Далее выберите один способ: Docker Compose либо Python с uv. Команды выполняются из корня репозитория. Для первой установки зависимостей или сборки образа нужен интернет.

3.2. Вариант A — Docker Compose

Требования: Docker и Compose v2. На macOS/Windows запустите Docker Desktop.

docker compose up --build -d
docker compose ps

Дождитесь готовности контейнера и откройте http://localhost:8501. Образ содержит синтетический набор; корпоративные книги в него не копируются.

Проверка готовности и логи:

docker compose exec -T app python scripts/check_health.py
docker compose logs --tail=100 app

Остановка с сохранением данных:

docker compose down

Состояние хранится в именованном volume ekt-data. Не добавляйте -v к down, если хотите сохранить планы и утверждения. Наружу опубликован только интерфейс на порту 8501; API доступен внутри контейнера.

3.3. Вариант B — Python и uv

Требования: установленный uv. Проект поддерживает Python 3.11–3.12; для воспроизводимого запуска используйте 3.12. При необходимости uv установит эту версию Python.

uv sync --frozen --python 3.12
uv run python scripts/run_app.py

После сообщения Application ready откройте http://localhost:8501.

Адрес	Назначение
localhost:8501	Интерфейс закупщика
127.0.0.1:8000/docs	Swagger: запросы API и схемы
127.0.0.1:8000/openapi.json	OpenAPI JSON
127.0.0.1:8000/v1/health	Проверка API

Launcher запускает FastAPI и Streamlit вместе. Ctrl+C останавливает оба процесса. Секреты и корпоративные файлы для учебного сценария не нужны. Локальное состояние хранится в var/; повторный запуск использует сохранённые данные.

Если нужны другие порты или отдельное хранилище:

uv run python scripts/run_app.py --port 8502 --api-port 8001 --state-dir ./var-local

В этом случае интерфейс будет доступен на http://localhost:8502, API — на http://127.0.0.1:8001.

3.4. Настройки и сохранение данных

Настройка	Назначение
--state-dir / EKT_DATA_DIR	Каталог SQLite, снимков, планов и истории решений
--port / UI_PORT	Порт интерфейса; по умолчанию 8501
--api-port / API_PORT	Порт API; по умолчанию 8000
--source-root / EKT_SOURCE_ROOT	Каталог локальных исходных книг
EKT_UI_PORT	Опубликованный порт UI в Docker Compose

Полный пример переменных — .env.example. Python launcher не читает .env автоматически: передайте переменные в окружение либо используйте аргументы запуска. Compose читает .env для подстановки опубликованного адреса и порта.

Локальная папка var/ и Docker volume — независимые хранилища. Для резервной копии сохраняйте SQLite вместе со связанными Parquet-артефактами.

4. Как пользоваться

Шаг 1. Подготовить первый план

В разделе «Данные» откройте «Подготовить новый план»:

1. В поле «Источник для расчёта» выберите «Демонстрационный набор» для первого знакомства.
2. Укажите «Цель: цикл без дефицита» — 95% или 99%.
3. Нажмите «Подготовить план закупки» и дождитесь завершения подготовки и расчёта.
4. Перейдите в «План закупки»: появятся предложения по поставщикам.

Учебный набор использует фиксированную дату 2026-09-23T00:00:00Z. Цель 95%/99% — вероятность пройти цикл поставки без дефицита в модели, а не гарантия наличия или измеренный результат компании.

Для подключённых реальных данных вместо учебного набора выберите IEK или Systeme Electric. Доступны первые 20, первые 100 или все поддерживаемые товары. Если обязательных сведений не хватает, заполните условия на следующем шаге.

Шаг 2. Заполнить остатки и условия для реальной истории

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

Поле	Что указать
Доступный остаток	Свободное количество на дату расчёта в базовой единице склада, уже за вычетом резервов и блокировок.
Ед. закупки и базовых единиц в закупочной	Закупочную единицу и явную конверсию: например, бухты при складском учёте в метрах.
Шаг базовой единицы	Допустимую точность складского количества.
Минимальная партия	MOQ в единицах закупки; 0 означает подтверждённое отсутствие минимума.
Кратность упаковки	Допустимый шаг закупочного количества.
Срок поставки и период проверки	Количество календарных дней до поступления и между проверками потребности.
Цена и валюта — необязательно	Цену за базовую единицу. Для суммы и бюджета нужны известные цены всех товаров в одной валюте.
Товар в пути — необязательно	Количество в базовых единицах и дату ожидаемого поступления.

Укажите «Источник данных и обоснование», явно примите допущение об истории продаж и нажмите «Сохранить условия и рассчитать заказ». Создаётся отдельный снимок и план; исходные данные и прошлые решения сохраняются.

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

Шаг 3. Проверить рекомендацию и изменить количество

В «Плане закупки» выберите «Поставщик и склад». Используйте поиск товара и фильтр срочности, проверьте ожидаемый дефицит и исключённые позиции.

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

Количество должно соблюдать минимальную партию и кратность. Ноль исключает позицию из CSV. Сохранение правки создаёт новую черновую версию и снимает предыдущее утверждение.

Шаг 4. Сравнить варианты

В «Сравнении вариантов» задайте цель 95%/99%, задержку поставки 0/7/14 дней и, если доступны цены, лимит закупки. Нажмите «Сравнить варианты» и проверьте изменения количества, стоимости и страхового запаса.

База сравнения — исходный успешный расчёт; ручные правки заказа в неё не входят. Сценарий не изменяет базовый заказ. Кнопка «Применить условия к новому плану» создаёт новый расчёт, который нужно проверить и утвердить отдельно.

Шаг 5. Утвердить и скачать CSV

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

Нажмите «Утвердить и подготовить CSV», затем «Скачать CSV». Выгрузка содержит товары, количества, единицы, доступные цены, объяснения и допущения. Экспорт разрешён только для утверждённой версии; после любой правки требуется новое утверждение.

Учебная выгрузка помечена «ДЕМОНСТРАЦИЯ — НЕ ЗАКАЗ ПОСТАВЩИКУ». Ни учебный, ни реальный CSV приложение не отправляет поставщику автоматически.

Дополнительно: проверить разовые продажи

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

Укажите «Обоснование решения» и нажмите «Подтвердить и пересчитать новый план». Старые планы и утверждения сохранятся. Разовая продажа в прошлом сама по себе не создаёт будущую проектную потребность.

Вернуться к предыдущей работе

Откройте «Сохранённые планы закупки», выберите план и нажмите «Открыть выбранный план». Решения загружаются с сервера; несохранённый ввод при смене плана очищается.

5. Подключение данных компании

Для работы с локальными книгами используйте запуск через Python. Интерфейс выбирает уже подключённые источники; загрузки произвольного Excel через браузер нет.

Подготовьте каталог с поддерживаемыми книгами в исходной структуре:

/path/to/sources/
├── IEK/
│   └── *.xlsx
└── Systeme electric/
    └── *.xlsx

Сохраните исходные названия и структуру книг: распознавание использует конкретные префиксы и схемы. Для каждого поставщика нужен полный поддерживаемый комплект; неоднозначные файлы автоматически не выбираются. Охват исходных книг и причины исключений описаны в проверке готовности данных.

uv run python scripts/run_app.py --source-root /path/to/sources

Альтернативы: EKT_SOURCE_ROOT или каталог data/sources/ в корне проекта. Если оба исходных архива IEK.zip и Systeme electric.zip уже присутствуют в корне, launcher автоматически распакует книги в игнорируемую Git папку состояния. Для явной регистрации локальных путей предусмотрен EKT_SOURCE_CONFIG.

После подключения выберите поставщика в «Данных» и заполните остатки и условия. Реальная история с пользовательскими допущениями сохраняет режим real_preview: это не подтверждение текущего состояния ERP. Не добавляйте новые корпоративные выгрузки, локальные БД, экспорты и секреты в Git или публичное демо.

6. Архитектура и API

Компонент	Технология и ответственность
Интерфейс	Streamlit; рабочий процесс закупщика через HTTP API
API и контракты	FastAPI, Pydantic; валидация, фоновые задания, версии и утверждения
Данные и прогноз	pandas, NumPy, DuckDB/Parquet; импорт, классификация, подготовка спроса и ежедневный прогноз
Планирование	Страховой запас, потребность, даты поступлений, закупочные ограничения, бюджет и объяснение
Хранение	SQLite для рабочего состояния и истории; Parquet для табличных артефактов

apps/buyer_ui/    Интерфейс закупщика
src/ekt/
├── api/          HTTP API и координация заданий
├── contracts/    Общие модели и форматы артефактов
├── data/         Подготовка снимков и адаптеры источников
├── forecast/     Классификация спроса и прогноз
├── planning/     Расчёт предложений и объяснений
└── storage/      Состояние, версии и аудит
scripts/         Запуск и проверки
tests/           Проверки модулей, UI и интеграции
docs/            Контракты, инструкции и доказательства приёмки

Раздельный запуск для разработки

После uv sync --frozen --python 3.12 запустите в первом терминале:

uv run uvicorn ekt.api.app:app --host 127.0.0.1 --port 8000

Во втором терминале (пример для bash/zsh):

BUYER_UI_MODE=http BUYER_API_URL=http://127.0.0.1:8000 uv run streamlit run apps/buyer_ui/app.py --server.address 127.0.0.1 --server.port 8501

По умолчанию UI работает с настоящим API. Изолированный mock включается явно через BUYER_UI_MODE=mock, технические настройки — через BUYER_DEVELOPER_MODE=true.

Основные маршруты

Задача	HTTP API
Готовность, источники, сохранённая работа	GET /v1/health, GET /v1/sources, GET /v1/workspace
Подготовка данных	POST /v1/snapshots, GET /v1/jobs/{job_id}
Остатки и закупочные условия	GET / POST /v1/snapshots/{snapshot_id}/buyer-inputs
Расчёт плана	POST /v1/planning-runs, GET /v1/planning-runs/{run_id}
Просмотр и правка заказа	GET /v1/proposals, GET / PATCH /v1/proposals/{proposal_id}
Утверждение	POST /v1/proposals/{proposal_id}/approve
Выгрузка CSV	POST /v1/proposals/{proposal_id}/export
Сценарии	POST /v1/scenarios, GET /v1/scenarios/{scenario_id}
Проверка продаж	GET /v1/planning-runs/{run_id}/demand-events, POST /v1/planning-runs/{run_id}/review-events

Подготовка и расчёты возвращают 202 и status_url; результат нужно дождаться до succeeded или failed. Правка использует expected_version, утверждение — точную версию и content_hash. Количества и деньги типа Decimal передаются JSON-строками; null означает неизвестное значение.

Актуальные схемы доступны в локальном Swagger. Дополнительно: контракты и сквозной API-пример.

7. Проверки и решение проблем

Сквозная проверка локального приложения

При работающем приложении выполните во втором терминале:

uv run python scripts/check_health.py
uv run python scripts/smoke_api.py

Smoke создаёт собственный синтетический план, проверяет запрет выгрузки черновика, правит количество, утверждает версию 2, сохраняет var/demo-approved.csv и сравнивает 95%/99% без изменения базового заказа. Успех отмечен "status": "passed". Команда добавляет демонстрационные записи в состояние выбранного экземпляра и не отправляет заказ.

Для Docker:

docker compose exec -T app python scripts/smoke_api.py

При нестандартных портах передайте API_PORT и UI_PORT health-скрипту; smoke принимает --url http://127.0.0.1:8001 и --output /path/to/demo.csv.

Проверки кода

uv run pytest -q
uv run ruff check src apps tests scripts

Протокол интегрированной приёмки: product-acceptance.md. Он отделяет проверенные функции, синтетические примеры и реальные данные с тестовыми допущениями. Локальные результаты не подтверждают успешный запуск облачного CI.

Частые проблемы

Симптом	Что сделать
uv не найден	Установить uv по ссылке выше; при установке через pip можно использовать python3 -m uv вместо uv.
Порт занят	Остановить свой предыдущий запуск или выбрать другие --port и --api-port. Для Compose изменить EKT_UI_PORT.
UI не соединяется с API	При едином запуске проверить терминал и health; при раздельном — процесс API и BUYER_API_URL.
IEK/Systeme нет в выборе	Проверить --source-root, названия папок, исходные имена книг и полный поддерживаемый комплект.
Расчёт или утверждение недоступны	Прочитать причины в качестве данных и исключённых позициях; заполнить обязательные условия и подтвердить допущения.
Бюджет недоступен	Проверить цены всех участвующих товаров и единую валюту.
CSV недоступен после правки	Проверить и заново утвердить текущую версию.
После обновления кода остался старый интерфейс	Перезапустить оба процесса приложения, сохранив каталог состояния.

8. Ограничения

• Данные. Поддерживаются определённые форматы IEK/Systeme. Непонятные движения и возвраты остаются исключёнными; дни без записей принимаются за нулевые продажи только с явным согласием закупщика.
• Прогноз. Восстановление потерянного спроса требует подтверждённых интервалов отсутствия товара. Без них потерянный спрос неизвестен. Обнаруженный всплеск — повод для проверки, а не доказанный проектный заказ.
• Результаты. Точность на будущем периоде, достигнутый уровень сервиса, экономия и сокращение времени работы компании здесь не заявляются. Синтетические расчёты подтверждают работу сценария, а не бизнес-эффект.
• Расчёт. Используются календарные дни UTC. Бюджет распределяется допустимым жадным алгоритмом без гарантии математического оптимума; многоскладовой оптимизации нет.
• Эксплуатация. Один worker и одна реплика; нет корпоративного SSO, разделения организаций и производственного SLA. Демонстрационная серверная роль не заменяет аутентификацию.
• Интеграции. Нет автоматической отправки поставщику, в 1С или другую ERP. Следующий пилот требует проверенных остатков, условий закупки и согласованного способа измерять результат.

9. Документация и работа команды

Документ	Когда читать
Приёмка продукта	Что проверено и в каких условиях
Готовность исходных данных	Поддержка книг, охват и ограничения истории
Сценарий демонстрации	Подготовка и проведение показа
API-контракты	Интеграция модулей и форматы запросов
Статус интеграции A	Текущий handoff и история checkpoints
Планы команды	Области ответственности A/B/C
Критерии хакатона	Польза, качество и доказательства для презентации
Git workflow	Синхронизация и публикация изменений

Разработка ведётся непосредственно в main, без новых веток, worktree и PR. A отвечает за платформу, контракты и интеграцию; B — за данные и прогноз; C — за интерфейс и демо. Перед работой прочитайте AGENTS.md и план своей роли; сохраняйте изменения коллег и публикуйте только проверенные файлы своей области.