Закупки — помощник закупщика

Веб-приложение команды BK Group для Hackalem: складской учёт и планирование закупок в одном рабочем пространстве. Оно помогает вести товары и документы, анализировать продажи и готовить проект заказа поставщику с объяснением расчёта.

Приложение запускается на компьютере и открывается в браузере. Для учёта и расчёта закупок API-ключи не нужны.

Что можно делать

Раздел	Возможности
Рабочее пространство	Каталог товаров, контрагенты, склады, закупки, продажи, денежные операции, задачи и журнал изменений.
План закупок	Загрузка Excel-архивов, проверка данных, прогноз спроса и расчёт количества к заказу.
Карточка товара	История продаж, ожидаемые поставки, прогноз остатка, объяснение рекомендации и ручное уточнение данных.
Проверка прогноза	Сравнение методов на завершённых месяцах и исторический прогон за выбранный период.
Выгрузка результатов	Excel с расчётом и источниками, ZIP с CSV-файлами заказов по поставщикам.

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

Запуск

Нужны Python 3.10+ и браузер. Команды выполняются из папки проекта.

Первый запуск на Windows

Создайте виртуальное окружение, установите зависимости и запустите сервер:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe app.py

Откройте http://127.0.0.1:8765. Оставьте терминал открытым; для остановки нажмите Ctrl+C.

Для следующих запусков достаточно последней команды. В уже настроенной среде также доступен ./start.ps1: он использует встроенный Python Codex, если тот установлен, иначе — python из системы. Скрипт не устанавливает зависимости и не выбирает .venv автоматически.

Другой порт и явные пути к архивам:

.\.venv\Scripts\python.exe app.py --port 8766 --archives "C:\data\IEK.zip" "C:\data\Systeme electric.zip"

Интерфейс написан на HTML, CSS и JavaScript; отдельная сборка не требуется. Экспорт Excel дополнительно требует Node.js и доступного пакета @oai/artifact-tool. В среде разработки они уже подключены; при переносе на другой компьютер их нужно обеспечить отдельно. ZIP/CSV работает без Node.js.

Как начать работу

Вести учёт

1. Откройте Рабочее пространство. Добавьте товары в разделе Товары, контрагентов — в Контрагенты, склад — в Склад → Склады.
2. Введите начальные остатки через Оприходование или оформите Приёмку от поставщика.
3. Сохраните документ как черновик, проверьте его и нажмите Провести. Остатки изменяются после проведения, а не после сохранения черновика.
4. Оформляйте отгрузки, возвраты, перемещения и денежные операции. Результат доступен в остатках, отчётах и журнале изменений.

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

Подготовить закупку

1. Откройте План закупок → Данные и загрузите ZIP-архивы Excel. Сейчас поддерживаются структуры выгрузок IEK и Systeme Electric.
2. Проверьте Паспорт качества: источники, пропуски и данные, которые нужно уточнить.
3. Во вкладке Параметры задайте срок поставки, период пересмотра и квантиль страхового запаса (80%, 90% или 95%). Сам запас рассчитывается автоматически. После сверки подтвердите единицы, кратность, ожидаемые поставки и порядок учёта резервов.
4. Вернитесь в План закупок. Найдите товар и откройте его карточку: проверьте графики, причины рекомендации и предупреждения. При необходимости уточните остаток, резерв или условия закупки, указав причину.
5. Нажмите Скачать Excel или Заказы по поставщикам. В отдельные проекты заказов попадают только проверенные позиции с положительным количеством.

При запуске программа ищет IEK.zip и Systeme electric.zip в папке Downloads пользователя. Если архивов нет, их можно загрузить через сайт. Первая обработка может занять несколько минут; повторные запуски используют локальный кэш.

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

Как рассчитывается закупка

Программа прогнозирует спрос по месячной истории продаж, учитывает доступный остаток, резерв, даты поступлений и страховой запас. Количество заказа округляется с учётом кратности и минимальной партии. Риск дефицита до прихода новой поставки показывается отдельно.

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

Расчёт привязан к дате среза загруженных данных. Историческая симуляция показывает поведение правил закупки при заданных условиях; она не доказывает фактическую экономию компании.

Данные и ограничения

• Это локальная версия для одного пользователя: сервер доступен на 127.0.0.1, учётных записей и разграничения доступа сотрудников пока нет.
• Поддерживаются конкретные форматы Excel. Прямого обмена с 1С, маркетплейсами и банками нет.
• Учёт включает базовые движения товаров и денег. Пока нет автоматических резервов, связанных оплат и частичных отгрузок, расчёта себестоимости, налоговой отчётности и фискальных чеков.
• Доступные архивы не содержат стабильного идентификатора покупателя. История отдельных клиентов по накладным не восстанавливается.
• AI-агент подключается только через OpenAI. Основные сценарии работают без него. При использовании AI сообщения и данные, отобранные инструментами для ответа, передаются OpenAI.

Операционные документы хранятся в data/operations.sqlite3; настройки расчёта, журнал и кэш — в каталоге data/. Для резервной копии остановите сервер и скопируйте этот каталог. Если запускали с --state-dir, сохраните указанный каталог состояния. Локальные данные исключены из Git.

AI-помощник на OpenAI

Нажмите Подключить OpenAI в шапке сайта. Введите API-ключ и ID модели (по умолчанию предлагается gpt-5.4-mini), сохраните настройки и нажмите Проверить подключение. Ключ можно использовать до остановки сервера или сохранить в зашифрованном хранилище Windows. Ключ не нужно отправлять в чат. Оплата API — отдельно по тарифам OpenAI.

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

Ручной режим доступен всегда. После настройки OpenAI появляется кнопка AI-помощника. Неподтверждённые предложения действуют 30 минут; перезапуск сервера завершает диалоги. Подробнее о возможностях, хранении ключа, передаваемых данных и ограничениях — в инструкции агента.

Для разработчика

Путь	Назначение
app.py	Локальный HTTP-сервер и API.
web/	Интерфейс учёта, планирования и помощника.
operations/	Документы, справочники, складские и денежные движения.
procurement/	Загрузка данных, прогноз, расчёт закупки, хранение и экспорт.
scripts/	Вспомогательные скрипты, включая экспорт Excel.
tests/	Автоматические проверки.

Запуск тестов в подготовленном окружении:

.\.venv\Scripts\python.exe -m unittest discover -s tests -v
.\.venv\Scripts\python.exe -m unittest discover -s analysis -p "test_*.py" -v

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