Astrea — расчёт заказов поставщикам

Команда Astrea · хакатон HACKALEM AI · кейс ТОО «Электрокомплект» (ekt.kz)

Демо: https://astrea.one — зарегистрируйтесь (имя, email, пароль) и войдите.

1. Название проекта

Astrea — сервис, который по выгрузкам из 1С рассчитывает рекомендованные заказы поставщикам для пополнения склада и объясняет каждую цифру.

2. Краткое описание

Проблема. Менеджер отдела закупа «Электрокомплекта» считает потребность в пополнении склада вручную в Excel. Это трудоёмко, поэтому расчёт делают редко. В итоге одних позиций на складе слишком много, других не хватает, а разовые крупные продажи одному клиенту искажают оценку регулярного спроса. Постановка задачи — RULE.md.

Для кого. Для менеджера отдела закупа. Он открывает список рекомендованных заказов по поставщикам (IEK, Systeme Electric), по каждой позиции видит, почему предложено именно такое количество, при необходимости правит его и утверждает заказ. Заказ поставщику автоматически не отправляется.

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

Расчёт (все 5 пунктов must have из RULE.md п.7, у каждого есть автотест):

Требование кейса	Как сделано
Потребность с учётом всех источников: продажи, остатки, товар в пути, категории, прогноз прироста	Расчёт использует все источники. Изменение товара в пути или планового прироста меняет результат (тесты test_r1_*)
Сезонность и устойчивый рост	Сезонный индекс SKU и поставщика, рост год к году. Прогноз в пиковый месяц выше простого среднего (test_r2_*)
Упущенный спрос в периоды отсутствия товара	Месяцы с нулевым остатком и просевшими продажами восстанавливаются вверх (test_r3_*)
Исключение разовых крупных заказов	Робастная проверка строк накладных. Добавленный крупный заказ меняет рекомендацию не больше чем на 10% (test_r4_*)
Список по поставщикам с обоснованием	Каждая строка содержит обоснование, список сгруппирован по поставщикам (test_r5_*)

Дополнительно:

• Округление до кратности отгрузки (MOQ) поставщика.
• Срочность по каждой позиции: «Срочно», «Скоро» или «Позже», в зависимости от того, на сколько дней хватит остатка и товара в пути относительно срока поставки.
• Отдельная пометка «Сверить остаток» для позиций, у которых текущий остаток по данным определить нельзя.
• Сегментация спроса: регулярный, редкий и без продаж за 12 месяцев. Позиции без продаж не заказываются и выносятся на отдельную вкладку.
• Корректировка количества с комментарием и утверждение заказа (сценарий RULE.md п.3). Утверждённые заказы хранятся в PostgreSQL вместе с тем, кто их утвердил и когда.
• Выгрузка в xlsx для загрузки в 1С: отдельный лист на поставщика (Код 1С, артикул, наименование, ед., количество), лист «Проверить остаток» и лист «Обоснование».
• Загрузка своих выгрузок из 1С: пользователь загружает свежий комплект файлов по поставщику. Система определяет тип каждого файла по содержимому, проверяет формат и делает набор текущим для всех пользователей. Можно откатиться к прошлому набору или вернуть демо-данные.
• Страница «Точность»: сравнение нашего метода, Excel-методики партнёра и ML-модели на истории продаж.
• Вход и регистрация по email и паролю, пароли хранятся хэшем (scrypt). Без входа данные не загружаются и не показываются; вход сохраняется до явного выхода.
• ML-модель (градиентный бустинг), обученная на реальных данных, в роли соперника формулы. Почему она не выбрана по умолчанию — в разделе 4.

4. Как работает решение

Сценарий пользователя

1. Вход. Регистрация (имя, email, пароль), дальше — вход по email и паролю. Сессия сохраняется при обновлении страницы и завершается только по кнопке «Выйти».
2. Данные. По умолчанию — выгрузки партнёра на 22.09.2026. На странице «Данные» можно загрузить свежий комплект из 1С.
3. Заказ. Сводка (позиций, штук, срочно, сверить остаток) и таблица рекомендаций по поставщикам. Клик по строке открывает панель «Почему N шт.» с разбором расчёта.
4. Корректировка. Количество и комментарий правятся в панели деталей.
5. Утверждение и выгрузка. «Утвердить заказ» сохраняет его в истории, «Скачать xlsx» даёт файл для загрузки в 1С.

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

Для каждого SKU, по месяцам до последнего полного месяца (неполный месяц среза в прогноз не входит):

1. Сегментация по числу месяцев с продажами за последние 12: ≥ 4 — регулярный спрос (модель), 1–3 — редкий (правило max-уровня), 0 — без продаж (не заказывается).
2. Исключение разовых крупных заказов — см. отдельный раздел ниже.
3. Восстановление упущенного спроса. Месяц считается месяцем дефицита, если остаток на начало месяца равен 0, а продажи меньше половины медианы продаж SKU в месяцы без дефицита. Для такого месяца спрос = max(факт, медиана × сезонный индекс месяца). Корректировка только вверх.
4. Сезонность. Индекс месяца считается по полным 2024 и 2025 годам: 50% — индекс самого SKU, 50% — индекс поставщика (сжатие к общему профилю, потому что у SKU всего 2 года истории). Ограничение — [0,3; 3].
5. Уровень спроса — среднее очищенного от сезонности спроса за 12 месяцев. У новых SKU считается с первого месяца продаж, но не меньше чем по 4 месяцам.
6. Рост — последние 3 полных месяца к тем же месяцам год назад, ограничение [0,5; 2]. Сравнение год к году нужно, чтобы сезонный пик не выглядел как рост.
7. Прогноз на месяц = уровень × рост × сезонный индекс × (1 + плановый прирост).
8. Заказ:
   • потребность = сумма прогноза по дням окна «срок поставки + период покрытия» + страховой запас − свободный остаток − товар в пути;
   • страховой запас = 1,65 × σ(месячного спроса) × √(срок поставки / 30), что соответствует уровню сервиса ~95%;
   • потребность округляется вверх до кратности отгрузки.

Параметры по умолчанию:

• Срок поставки IEK — 24 дня. Это медиана по объёму, рассчитанная по датам заказа и поступления в документах «в пути».
• Срок поставки SE — 35 дней. Это допущение: у Systeme Electric дат поставки в данных нет.
• Период покрытия — 30 дней.

Все три параметра меняются в настройках расчёта.

Алгоритм исключения разовых крупных заказов

ID клиента в данных нет, поэтому «разовая крупная продажа одному клиенту» ищется по строкам накладных:

• по каждому SKU считаются медиана и MAD (медианное абсолютное отклонение) количества в строке накладной, при этом MAD не меньше 1. Иначе SKU, который всегда продаётся по 1 шт., дал бы деление на ноль;
• строка — выброс, если робастный z = (x − медиана) / (1,4826 × MAD) > 10 и её доля в объёме SKU > 20%;
• объём выбросов вычитается из продаж соответствующего месяца. Флаг и даты исключённых заказов попадают в обоснование;
• до начала подробных данных по накладным (почти весь 2024 год) месячные продажи ограничиваются сверху: медиана + 5 × 1,4826 × MAD по месячному ряду SKU.

Пример. SKU обычно продаётся по 10–20 шт. в строке (медиана 15, MAD 5). Строка на 900 шт. даёт z = (900 − 15) / (1,4826 × 5) ≈ 119 > 10. Если при этом её доля в объёме SKU больше 20%, она исключается из регулярного спроса.

Проверка на истории (страница «Точность», scripts/backtest.py)

Обучение на данных до 06.2026, прогноз на 07–08.2026, сравнение с фактом. Проверяются SKU с продажами в ≥ 9 из 12 месяцев: 818 SKU IEK и 258 SKU SE. Методика партнёра восстановлена из формул в его Excel-файле: среднее за 12 месяцев × (1 + коэффициент роста) × (1 + коэффициент сезонности).

	Метод	WAPE	MdAPE	Смещение
IEK	Astrea (по умолчанию)	39,1%	58,1%	+6,6%
	Excel-методика партнёра	1193,7%	80,8%	+1156,7%
	ML (эксперимент)	34,5%	44,5%	−22,9%
SE	Astrea (по умолчанию)	25,3%	48,9%	−3,8%
	Excel-методика партнёра	71,1%	73,3%	+20,7%
	ML (эксперимент)	31,5%	36,3%	−26,3%

• WAPE — суммарная абсолютная ошибка к суммарному факту. MdAPE — медианная ошибка по SKU, она устойчива к выбросам. Смещение — Σ прогноз / Σ факт − 1.
• Методика партнёра даёт огромный WAPE по IEK из-за 42 SKU, у которых прогноз превышает 10× среднемесячных продаж. Коэффициенты роста и сезонности у неё делятся на один и тот же квартал год назад, и если в нём был провал продаж, оба коэффициента взлетают. Эти 42 SKU дают 94,6% всей ошибки. Даже по медианной ошибке, устойчивой к таким выбросам, наш метод точнее.
• ML-модель точнее по WAPE и MdAPE, но занижает общий спрос на 23–26%: она оптимизирует абсолютную ошибку и поэтому предсказывает медиану. Для заказа важен общий объём, поэтому по умолчанию используется формула, а ML доступна как экспериментальный режим. Условие |смещение| ≤ 10% добавлено в правило выбора метода уже после того, как были получены результаты: мы пишем это прямо.

5. Технологии

• Язык: Python 3.12 в Docker (локально — Python 3.9+).
• Библиотеки (версии в requirements.txt): pandas, numpy, openpyxl (чтение xlsx), streamlit (веб-интерфейс), scikit-learn (ML-модель HistGradientBoostingRegressor), psycopg (PostgreSQL), pytest.
• База данных: PostgreSQL 16 — пользователи, утверждённые заказы, загруженные наборы данных.
• Инфраструктура: Docker, Docker Compose. На сервере — Caddy (HTTPS, сертификат Let's Encrypt).
• Внешние AI-сервисы и API: не используются. Расчёт и обучение модели выполняются на своём сервере.

6. Архитектура проекта

data/raw/                   демо-выгрузки 1С от партнёра (IEK, Systeme Electric)
app/
  loaders/                  чтение xlsx 1С → единая модель данных (свой адаптер на поставщика)
  datasets.py               проверка и хранение загруженных пользователем выгрузок
  engine/                   расчёт — без интерфейса
    segmentation.py         регулярный / редкий / без продаж
    cleaning.py             исключение разовых крупных заказов
    stockout.py             восстановление упущенного спроса
    forecast.py             уровень × рост × сезонность
    order.py                окно потребности, страховой запас, остаток, в пути, кратность, срочность
    explain.py              обоснование
    ml.py                   ML-модель-соперник
    backtest.py, metrics.py проверка на истории (WAPE, MdAPE, смещение)
    pipeline.py             build_recommendations() — весь расчёт одним вызовом
  auth.py                   регистрация и вход, пароли — scrypt
  orders.py                 корректировки и подготовка к утверждению
  db.py                     PostgreSQL: схема, заказы, пользователи, наборы данных
  export.py                 xlsx для 1С
  ui/                       Streamlit: вход, навигация, страницы «Заказ», «Данные»,
                            «История заказов», «Точность»
db/migrations/              SQL-схема
scripts/backtest.py         бэктест из командной строки
tests/                      автотесты на синтетических данных + проверки на реальных файлах

Слои разделены. app/engine, app/loaders, app/auth.py, app/orders.py и app/db.py не зависят от Streamlit: интерфейс только вызывает их. Поэтому API или другой фронтенд можно добавить, не переписывая расчёт.

7. Установка и запуск

Вариант 1 — Docker (рекомендуется: приложение и база одной командой)

Нужны Docker и Docker Compose.

git clone https://github.com/BAITC-Hacks/hack-3cf19ef3-astrea.git
cd hack-3cf19ef3-astrea
cp .env.example .env

docker compose -f docker-compose.yml up --build      # → http://localhost:8501

Данные партнёра уже лежат в репозитории (data/raw/), докладывать ничего не нужно.

Вариант 2 — без Docker для приложения

База данных нужна для входа, поэтому поднимается в контейнере:

docker compose -f docker-compose.yml up -d db
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
export DATABASE_URL=postgresql://astrea:change-me@localhost:5432/astrea
streamlit run app/ui/streamlit_app.py

Тесты

docker compose -f docker-compose.yml run --rm app pytest -q   # внутри контейнера, вместе с тестами базы
pytest -q                                                      # локально: тесты базы пропускаются без DATABASE_URL

Без DATABASE_URL интеграционные тесты PostgreSQL пропускаются; полный набор с базой запускается командой Docker выше.

8. Как проверить решение

1. Откройте https://astrea.one (или http://localhost:8501) → Регистрация → имя, email, пароль.
2. Страница «Заказ»: сводка и таблица по IEK и SE. Позиции «Срочно» — те, у которых остатка и товара в пути хватит меньше чем на срок поставки.
3. Кликните по строке. Откроется панель «Почему N шт.»: спрос в месяц, рост, сезонность, исключённые разовые заказы, восстановленный дефицит, остаток, товар в пути, кратность.
4. Поменяйте количество, добавьте комментарий и нажмите «Утвердить заказ». Заказ появится на странице «История заказов». «Скачать xlsx» даёт файл для 1С.
5. Страница «Точность»: сравнение с Excel-методикой партнёра и ML-моделью.
6. Страница «Данные»: загрузите комплект файлов из data/raw/IEK как новую выгрузку, и расчёт пересчитается. Загрузите посторонний xlsx, и система отклонит его с объяснением. Кнопка «Вернуть демо-данные» откатывает изменения.
7. Бэктест из консоли: python scripts/backtest.py.

9. Данные и интеграции

Источник — выгрузки из 1С, переданные партнёром. Склад — Алматы, дата среза — 22.09.2026 (сентябрь 2026 неполный).

Данные	IEK	Systeme Electric
Продажи по накладным	Динамика продаж_2025-2026.xlsx	Динамика продаж_Syseme Electric_2025-2026.xlsx
Продажи по месяцам (01.2024–09.2026)	Ежемесячные продажи…xlsx	Ежемесячные продажи…SystemElectric 2024-2026.xlsx
Остатки на начало месяца	Ежемесячные остатки…ИЭК.xlsx	Ежемесячные остатки SystemElectric 2024-2026.xlsx
Товар в пути на 22.09.2026	Путь ИЭК 22.09.2026.xlsx	Товар в пути_SystemElectric на 22.09.2026.xlsx (также категории и текущий свободный остаток)
Кратность (MOQ)	MOQ ИЭК.xlsx	MOQ SystemElectric.xlsx

Объём: ~249 тыс. строк продаж по накладным, ~2 460 SKU IEK и ~550 SKU SE.

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

Интеграции. Внешних API нет. С 1С сервис связан через файлы: на входе стандартные выгрузки xlsx, на выходе xlsx для загрузки заказа поставщику.

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

• ID клиента в данных нет, поэтому разовые крупные заказы определяются по накладной, а не по клиенту.
• Сроков поставки в выгрузках нет. У IEK они восстановлены из дат в документах «в пути», у SE это допущение (35 дней). Оба значения меняются в настройках.
• Текущий остаток IEK оценивается как остаток на начало месяца минус продажи с начала месяца, потому что приходы внутри месяца в данных не видны. Позиции, где такая оценка ненадёжна (продали больше, чем было на начало месяца), помечаются «Сверить остаток». В файле для 1С они вынесены на отдельный лист.
• Категории есть только у Systeme Electric. У IEK их в данных нет.
• Не используются: материальная ведомость из 1С (партнёр её не передал), цены (их нет в выгрузках) и файлы «Сезонность» (там суммы в деньгах по всей компании, их искажают цены). Сезонность считается по количеству из продаж.
• Совместимость с 1С: xlsx с кодом 1С и количеством. Импорт в конкретную конфигурацию 1С партнёра не проверялся.
• Заказ поставщику автоматически не отправляется (RULE.md п.9): только утверждение и выгрузка файла.
• Опциональные пункты RULE.md п.8 реализованы частично: кратность и приоритет по срочности есть, а графиков трендов по категориям и отправки заказа поставщику пока нет.
• Вход сохраняется до явного выхода: для этого в PostgreSQL хранится хэш случайного токена сессии, а не пароль.
• Первый расчёт после перезапуска сервера занимает ~10 секунд: данные 1С берутся из кэша на диске меньше чем за секунду, а сам расчёт выполняется заново. Ход загрузки показывается на экране.

11. Deployed-версия

https://astrea.one — сервер с Docker Compose (приложение, PostgreSQL, Caddy с HTTPS). Доступ после регистрации. Инструкция по развёртыванию — docs/deploy.md.