hack-baba2015-sis

Hackathon team repository for SiS

HACKALEM AI — автоматизация заказов поставщикам

Сервис поддержки закупочных решений для кейса ТОО «Электрокомплект» (ekt.kz). Проект разработан для олимпиады HACKALEM AI и помогает менеджеру закупа рассчитывать пополнение склада на основе истории продаж, сезонности, динамики спроса, остатков и ожидаемых поставок.

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

Технологии: Python · Pandas · NumPy · Streamlit · Plotly · OpenPyXL · XlsxWriter.

Содержание

• Проблема и задача
• Возможности
• Архитектура
• Структура проекта
• Быстрый запуск
• Пользовательский сценарий
• Входные данные
• Методология
• Результат и экспорт
• Проверка требований ТЗ
• Тестирование
• Ограничения прототипа
• Приватность
• Дальнейшее развитие

Проблема и задача

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

Ошибки возникают, когда:

• разовая крупная продажа принимается за устойчивый рост спроса;
• нулевые продажи во время отсутствия товара считаются отсутствием спроса;
• при заказе не учитываются свободный остаток и товар в пути;
• сезонные изменения заменяются средним значением за всю историю;
• рекомендуемое количество не соответствует условиям поставщика.

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

Возможности

• Импорт архивов IEK и Systeme Electric с Excel-выгрузками партнёра.
• Объединение источников по поставщику и коду товара в 1С.
• Проверка структуры данных, ключей и числовых значений.
• Выявление крупных разовых операций по документам, а при наличии обезличенной детализации — по клиентам.
• Прогноз с учётом сезонности и устойчивой динамики спроса.
• Компенсация упущенного спроса по подтверждённым периодам stockout.
• Учёт свободного остатка и дат ожидаемых поступлений.
• Настройка дополнительного прироста спроса и политики запаса по категориям.
• Раздельный учёт MOQ и кратности заказа.
• Приоритизация по риску дефицита.
• Объяснение каждой рекомендации.
• Фильтры поставщика и категории, графики истории и прогноза.
• Экспорт рекомендаций в Excel.
• Ручная корректировка количества и выгрузка подтверждённого заказа в CSV.
• Учебный режим с синтетическими дневными данными.

Архитектура

Excel-отчёты в ZIP + дополнительные CSV
                    ↓
           Импорт и проверка данных
                    ↓
      Объединение по поставщику и коду 1С
                    ↓
          Исключение разовых операций
                    ↓
       Сезонность + stockout + тренд спроса
                    ↓
       Прогноз на горизонт пополнения
                    ↓
       Страховой запас − склад − путь
                    ↓
              MOQ и кратность
                    ↓
       Рекомендации с объяснениями
                    ↓
     Проверка менеджером → экспорт заказа

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

Структура проекта

.
├── app.py                       # Точка входа Streamlit
├── src/
│   ├── __init__.py
│   ├── partner_import.py        # Импорт Excel-книг из архивов
│   ├── forecast.py              # Сезонный прогноз и исключение крупных операций
│   ├── partner_ui.py            # Интерфейс кейса, дополнения и проверка заказа
│   └── planning.py              # Дневной учебный расчёт и экспорт Excel
├── data/
│   ├── products.csv             # Синтетический справочник
│   └── sales.csv                # Синтетическая история
├── tests/
│   ├── test_forecast.py
│   ├── test_import.py
│   └── test_planning.py
├── .github/
│   └── workflows/
│       └── tests.yml            # Автоматические проверки
├── .streamlit/
│   └── config.toml              # Настройки локального сервера и оформления
├── .gitignore
├── requirements.txt
└── README.md

Реальные выгрузки компании не должны входить в публичный репозиторий. Для демонстрации без исходных архивов используются синтетические данные из data/.

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

Требования

• Python 3.11 или 3.12.
• Интернет для первоначальной установки зависимостей.
• Браузер для работы с интерфейсом.

Скачайте репозиторий или распакуйте архив проекта. Откройте терминал в папке, где находится app.py.

Windows PowerShell

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

Linux / macOS

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m streamlit run app.py

Откройте адрес, который появится в терминале. При стандартной конфигурации:

http://localhost:8501

Чтобы остановить сервер, нажмите Ctrl+C в терминале.

Если приложение не запускается

• Убедитесь, что команда выполняется из папки проекта.
• Устанавливайте зависимости и запускайте приложение одним и тем же интерпретатором из .venv.
• Если команда python недоступна, установите Python или используйте доступный в вашей системе Python Launcher.
• Если Windows блокирует нативную библиотеку, например PyArrow, используйте разрешённое Python-окружение или обратитесь к администратору. Приложение не требует отключения системной защиты.

Пользовательский сценарий

1. Выберите режим кейса Электрокомплект.
2. Загрузите IEK.zip и Systeme electric.zip.
3. Проверьте список распознанных источников и предупреждения.
4. При необходимости загрузите дополнения: актуальные остатки, сроки поставки, ограничения заказа, календарь stockout или обезличенную клиентскую детализацию.
5. Укажите дату расчёта, период пересмотра и параметры страхового запаса.
6. Настройте политику запаса по категориям.
7. Нажмите «Рассчитать заказы по архивам».
8. Отфильтруйте результат по поставщику или категории.
9. Изучите объяснение и графики выбранного товара.
10. Подготовьте и скачайте Excel с рекомендациями.
11. В разделе проверки скорректируйте количества, подтвердите их и скачайте CSV заказа.

Первый импорт больших Excel-файлов может занять несколько минут. Повторные действия используют данные текущей сессии. Изменение входных данных или параметров требует пересчёта рекомендаций.

Для знакомства без реальных архивов выберите «Дневной учебный пример» и нажмите «Рассчитать заказы».

Входные данные

Архивы партнёра

Источник	Назначение
Ежемесячные продажи	История суммарного спроса по товарам
Динамика продаж	Поиск крупных разовых операций по документам
Ежемесячные остатки	Диагностика возможного дефицита и покрытия данных
Файлы сезонности	Профиль сезонности поставщика
MOQ / кратность	Ограничения количества заказа
Товар в пути	Ожидаемые поступления и даты
Ведомость Systeme Electric	Свободный остаток, категория, коэффициент роста и связанные поля

Основной ключ объединения — поставщик + код 1С. Артикул поставщика сохраняется отдельным полем. Объединение по похожим названиям не используется.

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

Дополнения к справочнику

CSV содержит обязательные ключи supplier,sku и любое подмножество поддерживаемых полей:

Поле	Значение
supplier	IEK или Systeme Electric
sku	Код товара в 1С, строка
stock	Актуальный свободный остаток, за вычетом резервов
moq	Минимальное ненулевое количество заказа
pack_size	Кратность заказа, не меньше 1
lead_time_days	Срок поставки в днях
growth_pct	Дополнительный прирост: 0.10 означает +10%
category	Категория для выбора политики запаса
unit	Согласованная единица учёта
safety_multiplier	Индивидуальный множитель страхового запаса

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

Календарь stockout

supplier,sku,month,stockout_days

• month — первый день соответствующего месяца, например 2026-08-01.
• stockout_days — подтверждённое целое количество дней отсутствия товара.
• Значение 0 означает проверенный месяц без stockout.
• Непереданный месяц означает отсутствие информации, а не подтверждённое наличие товара.

Обезличенная клиентская детализация

supplier,sku,date,document,quantity,customer_id

Допускаются только указанные поля. Пользователь должен подтвердить обезличивание. Файл заменяет детализацию документов для выявления выбросов; месячный отчёт остаётся источником суммарных объёмов.

Номер документа не считается идентификатором клиента. В исходных архивах ID клиента отсутствует, поэтому без дополнения используется анализ документов.

CSV следует сохранять в UTF-8 с разделителем-запятой. Коды товаров необходимо хранить как строки, сохраняя ведущие нули.

Методология

1. Подготовка истории

Из месячного прогноза исключается текущий неполный месяц. Например, при расчёте на 22 сентября сентябрьские продажи не сравниваются с полными месяцами.

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

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

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

2. Исключение крупных разовых операций

При наличии обезличенного ID клиента продажи агрегируются по клиенту, товару и месяцу. Это позволяет обнаружить крупную покупку, разбитую на несколько документов.

При отсутствии ID клиента анализируются группы «документ + дата + товар».

Для товара с минимум восемью группами рассчитывается робастный порог:

threshold = max(
    5 × median,
    median + 6 × 1.4826 × MAD,
    1
)

MAD = median(|quantity − median(quantity)|)

Операции выше порога исключаются из регулярного спроса, если их количество не превышает max(1, floor(10% числа групп)). Клиент с крупными отклонениями более чем в двух месяцах не считается разовым автоматически.

Исключаемый объём ограничивается положительным фактическим объёмом соответствующего месяца. Это защищает от отрицательного регулярного спроса при несовпадении источников.

Алгоритм является эвристикой. Для короткой истории, проектных продаж и регулярно крупных покупателей требуется проверка менеджера.

3. Сезонность

Файлы сезонности дают нормализованный профиль поставщика по полным 2024–2025 годам. Поскольку эти таблицы содержат денежные показатели, их профиль используется как приближение сезонности натурального спроса.

Если у товара есть два полных года истории и достаточно ненулевых месяцев, рассчитывается собственный профиль:

1. Объём месяца переводится в средний дневной спрос.
2. Дневной спрос нормируется на среднее значение соответствующего года.
3. Для каждого календарного месяца берётся медиана нормированных значений.
4. Итоговый профиль объединяет 80% сезонности товара и 20% сезонности поставщика.

При недостаточной истории используется профиль поставщика. Если и он отсутствует, сезонные коэффициенты равны 1.

4. Компенсация упущенного спроса

Для подтверждённого stockout применяется корректировка по числу дней доступности:

recovered_demand = regular_sales × D / (D − d)

Здесь D — число дней месяца, d — число дней отсутствия товара.

Для месяца, когда товар отсутствовал полностью, используется медианная дневная база остальных месяцев с сезонной корректировкой. Если такой базы нет, спрос признаётся неизвестным.

Компенсация включается в восстановленную историю. Отдельно прибавлять её ещё раз к будущему заказу нельзя: это привело бы к двойному учёту.

Нулевой остаток в месячном снимке не означает отсутствие товара весь месяц. Без календаря stockout модель не выдумывает длительность дефицита.

5. Устойчивый рост и дополнительный прирост

База прогноза — средняя восстановленная дневная потребность последних шести полных месяцев после удаления сезонного эффекта.

Исторический тренд рассчитывается по изменениям к тем же месяцам предыдущего года:

• требуется минимум шесть сравнений;
• используются последние двенадцать доступных сравнений;
• изменение считается устойчивым, когда минимум 2/3 сравнений имеют тот же знак, что и медиана;
• годовой темп ограничивается диапазоном от −50% до +100%.

По настройке интерфейса «Кэф. Роста» из ведомости заменяет историческую оценку. Он трактуется как годовой темп с ограничением от −90% до +200%. Период этого коэффициента необходимо подтвердить у партнёра; допущение отражается в объяснении.

Для будущего дня t:

daily_forecast = base_daily_demand
                 × seasonal_factor
                 × (1 + annual_trend)^(t / 365.25)
                 × (1 + growth_pct)

growth_pct — отдельно заданный бизнес-прогноз прироста. Исторический тренд и коэффициент роста ведомости не применяются одновременно как два независимых эффекта.

6. Горизонт и страховой запас

H = lead_time_days + review_days

Страховой запас для месячной модели:

safety_stock = ceil(
    z × σ × sqrt(H × 30)
      × category_multiplier
      × safety_multiplier
)

σ — стандартное отклонение десезонализированной дневной базы за последние двенадцать месяцев. z — настраиваемый коэффициент запаса.

Политика категорий редактируется в интерфейсе. По умолчанию множители равны 1. Числовые категории источника не интерпретируются как ABC-классы без правил партнёра.

Формула запаса — приближение по месячным данным. Она не гарантирует заданный уровень обслуживания и требует калибровки на исторических результатах.

7. Остаток, путь и срочность

Из потребности вычитается свободный остаток и подтверждённый путь с датой поступления после снимка остатков и не позже конца горизонта.

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

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

8. MOQ и кратность

net_need = max(0, forecast + safety_stock − stock − in_transit)

order_qty = 0, если net_need = 0

order_qty = ceil(max(ceil(net_need), MOQ) / pack_size) × pack_size,
            если net_need > 0

MOQ — минимальный допустимый ненулевой заказ. Кратность — шаг количества. Эти ограничения различаются.

Ситуация	Результат
Нужно 100, на складе 40, в пути 30, без дополнительных ограничений	30
Чистая потребность 37, MOQ 50, кратность 1	50
Чистая потребность 110, MOQ 50, кратность 1	110
Чистая потребность 110, MOQ 50, кратность 50	150
Чистая потребность 0, MOQ 50	0

Таким образом, пример 120 + 40 − 30 − 20 даёт 110 единиц до округления. Рекомендация 150 корректна при кратности 50, а не только при MOQ 50.

Результат и экспорт

Рекомендации содержат идентификаторы товара, поставщика, прогноз, запас, остаток, путь, ограничения и объяснение.

Поле	Смысл
supplier, sku, article	Поставщик, код 1С, артикул поставщика
name, category, unit	Описание, категория, единица учёта
forecast, safety_stock	Прогноз на горизонт и страховой запас
stock, in_transit	Свободный остаток и учтённые поступления
net_need	Потребность до ограничений поставщика
moq, pack_size, order_qty	MOQ, кратность, рекомендуемое количество
lost_sales, excluded_qty	Компенсация дефицита и исключённый разовый объём в истории
urgency, deficit_date	Срочность и ожидаемая дата дефицита
status, explanation	Качество исходных данных, допущения и обоснование

Пустое количество заказа означает, что данных недостаточно. Оно не равно нулевой потребности.

Excel содержит отфильтрованные рекомендации и историю расчёта. После проверки менеджером доступна выгрузка подтверждённых количеств в CSV с кодами 1С и артикулами поставщика.

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

Проверка требований ТЗ

Must Have	Реализация	Условие проверки
Базовая потребность с учётом источников	История, склад, путь, категории и прирост участвуют в расчёте или диагностике	Изменение значимых входов меняет результат либо статус
Сезонность и устойчивый рост	Сезонный профиль и годовой тренд	Сезонный ряд даёт различающийся прогноз по месяцам
Упущенный спрос	Восстановление по подтверждённым дням отсутствия	При stockout восстановленный спрос выше сырого
Исключение крупных разовых продаж	Анализ документов или клиента за месяц	Искусственный разовый всплеск не увеличивает регулярный прогноз пропорционально объёму
Объяснение и поставщики	Объяснение каждой строки, сортировка и фильтрация	Каждая позиция проверяется отдельно и в разрезе поставщика

Проверка на реальных клиентах и реальных периодах отсутствия требует дополнительных данных: в предоставленных архивах этих полей нет.

Тестирование

Windows:

.\.venv\Scripts\python.exe -m unittest discover -s tests -v

Linux / macOS:

.venv/bin/python -m unittest discover -s tests -v

Тесты покрывают сезонность, рост, компенсацию дефицита, настоящий нулевой спрос, неизвестный спрос, крупные документы, раздробленный заказ одного клиента, склад, даты пути, категорийную политику, MOQ, кратность, валидацию и экспорт.

Автоматические тесты проверяют бизнес-правила. Они не доказывают точность прогноза или экономический эффект. Для этого требуется backtest на отложенной истории с сопоставлением с базовыми прогнозами и фактическими складскими результатами.

Ограничения прототипа

1. Текущие остатки IEK. В месячной выгрузке указаны начальные остатки. Они не заменяют актуальный свободный остаток на дату расчёта; до его загрузки количество заказа не определяется.
2. Календарь stockout. Месячные снимки не позволяют восстановить точную длительность отсутствия. Компенсация по реальным периодам требует отдельного источника.
3. Клиенты. В исходной динамике нет ID клиента. Без дополнения доступен только анализ документов.
4. Сроки поставки. При отсутствии подтверждённого срока применяется явно обозначенный сценарный параметр.
5. Единицы измерения. Метры, штуки и бухты нельзя смешивать. Позиции с несогласованным переводом единиц требуют проверки до заказа.
6. Склады. Расчёт по архивам консолидирован: источники не дают согласованной детализации месячных продаж и актуальных остатков по каждому складу. Реализован выбор категории.
7. Сезонность. Денежный профиль поставщика — приближение натурального спроса. Собственная сезонность SKU оценивается до восстановления stockout и может быть смещена длительными дефицитами.
8. Выбросы. Автоматический порог не заменяет знания менеджера о проектах, акциях и повторяющихся крупных заказах.
9. Дата снимка. Исходные сведения привязаны к сентябрю 2026 года. Изменение даты в интерфейсе не обновляет источники автоматически.
10. Производственная эксплуатация. Постоянный журнал утверждений, аутентификация, разграничение прав, плановые загрузки и интеграция с 1С не входят в текущий локальный прототип.

Приватность

• Реальные данные компании не публикуются в GitHub.
• Обработка выполняется локально без передачи продаж в облачные LLM или внешние API.
• Импортированные таблицы хранятся в памяти текущей сессии, без общего глобального кэша.
• Клиентская детализация допускается только с обезличенными ID. Подтверждение в интерфейсе не заменяет предварительное обезличивание владельцем данных.
• Исходные архивы не изменяются при импорте.
• Сервис не отправляет заказ поставщику автоматически.
• Перед публикацией репозитория необходимо проверить, что в Git не попали реальные выгрузки, промежуточные файлы и секреты.

Дальнейшее развитие

• Загрузка актуальных остатков, резервов и подтверждённых дат поступления из 1С.
• Учёт ежедневной доступности товара и точных интервалов stockout.
• Расчёт по складам и рекомендации по перемещениям между ними.
• Согласование единиц закупки, MOQ и кратности по каждому поставщику.
• Проверка качества прогноза на отложенной истории и сравнение с сезонным наивным прогнозом.
• Учёт промоакций, проектных заказов и товарных замен.
• Калибровка страхового запаса под целевой уровень обслуживания.
• Постоянный журнал изменений и утверждений, роли пользователей.
• Подготовка адаптера экспорта для конкретной конфигурации 1С.

Контекст проекта

Мероприятие: HACKALEM AI.
Кейс: автоматизация формирования заказов поставщикам.
Партнёр: ТОО «Электрокомплект» (ekt.kz).
Основной пользователь: менеджер отдела закупа.

Рекомендации предназначены для проверки ответственным сотрудником перед оформлением закупки.