Запуск

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
cp .env.example .env          # ключи AI — по желанию
.venv/bin/uvicorn api:app --port 8000      # HTTP API (/docs) и интерфейс QadamSupply из web/ на http://127.0.0.1:8000
.venv/bin/streamlit run app.py              # запасной интерфейс для аналитика
.venv/bin/python -m pytest -q               # тесты

Данные. Каждый архив партнёра распаковывается в свою подпапку data/raw/: IEK.zip → data/raw/IEK/, Systeme electric.zip → data/raw/SE/ (папку __MACOSX не нужно). Другая корневая папка — переменная DATA_DIR. Файлы ищутся по началу имени, а если имя не подошло (в архиве SE имена искажены) — по заголовкам колонок, так что переименовывать ничего не нужно. Первый разбор xlsx ~15 с, дальше данные читаются из кэша data/cache/ (~0,3 с) и перечитываются сами, когда меняются файлы. Данные партнёра в git не попадают.

Ключи (необязательно): OPENAI_API_KEY + OPENAI_MODEL — чат; NVIDIA_API_KEY + NVIDIA_MODEL — критик. Ключи только в .env, в коде и конфиге их нет.

Какие данные используются

Источником спроса выбраны накладные: месячный отчёт с ними расходится (у SE — примерно вдвое, «Петли LOOP» на 210 000 шт. в месячном отчёте нет вовсе), а найти конкретную разовую сделку можно только по накладным. Изменение любого источника меняет итог — это проверяется тестами (см. ниже).

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

Один пакет по всем товарам обоих поставщиков, ~1,5 с на 3 561 SKU (engine/calc.py). Для каждого товара по месяцам:

1. Ряд спроса. 2024 — из месячного отчёта, 2025+ — сумма строк накладных; возвраты спросом не считаются. Текущий месяц неполный (данные до 22.09): в прогноз не входит, используется только для оценки текущего остатка ИЭК.
2. Разовые крупные продажи исключаются — см. следующий раздел.
3. Упущенный спрос (stockout). Месяц дефицитный, если остаток на его начало ≤ 0 и продажи ниже половины ожидаемых. Ожидаемый спрос = медиана спроса без сезонности по месяцам с товаром × сезонность месяца; до него месяц и досчитывается. Если товар пришёл в середине месяца и нормально продавался, месяц не трогаем.
4. Сезонность — своя у товара, если у него ≥ 18 месяцев продаж и заметный объём (смешивается с сезонностью группы 60/40), иначе — группы товаров (префикс кода 1С) внутри поставщика, смешанная с сезонностью поставщика. Коэффициент сентября 2026 в файлах партнёра посчитан по 22 дням — досчитываем ×30/22.
5. Уровень и тренд. Уровень — взвешенное среднее спроса без сезонности за 6 последних месяцев (свежие весят больше). Тренд — последние 6 месяцев к предыдущим 6, ограничен 0,67…1,5, применяется, только если изменение ≥ 10% и совпадает по знаку с годом к году. Прогноз месяца = уровень × тренд × (1 + прирост %) × сезонность месяца.
6. Горизонт = срок поставки + период до следующего заказа (30 дн.), по календарным дням. Срок: ИЭК — из дат заказов в пути (по товару, иначе медиана по поставщику, взвешенная по количеству, = 24 дн.); SE — 45 дн., допущение (дат заказа нет). Меняется в интерфейсе и API.
7. Заказ.

   страховой запас = z(категории) × σ(спроса без сезонности, 12 мес.) × √(горизонт / 30)
   потребность     = прогноз на горизонт + страховой запас − остаток − в пути (приход в горизонте)
   заказ           = 0, если потребность ≤ 0 или спроса почти нет, иначе вверх до кратности
   

   Категория → уровень сервиса: 1/A — 98%, 2/B/5 — 95%, 3/C — 90%; категория 7 (новинка или выведен) — без автозаказа. SE — категории из файла менеджера; у ИЭК категорий нет → ABC по числу строк накладных за 12 мес. (80/15/5%): число строк не зависит от единиц шт/м/упак.
8. Остаток. SE — как в модели менеджера: свободный + витрина + ТЗ + розничный. ИЭК — оценка: остаток на 01.09 минус продажи 01–22.09 (поступления сентября не видны).
9. Срочность. «Критично» — запаса не хватит до прихода новой поставки; «высокая» — хватит меньше чем на срок поставки + половину периода; «плановая» — заказ нужен; «не нужно».
10. Обоснование собирается кодом из тех же чисел для каждой строки: спрос, тренд, сезонность по месяцам горизонта, исключённые накладные, досчитанные месяцы, категория и сервис, остаток и его источник, путь, кратность. LLM для него не нужен, поэтому текст всегда совпадает с цифрой.

Алгоритм исключения выбросов (разовые крупные продажи)

В данных нет клиента, поэтому «крупная продажа одному клиенту» определяется по строке накладной: строка намного больше обычной строки этого товара и в одиночку делает месяц.

1. Для каждого товара по его строкам накладных: типичная = медиана, разброс — MAD (медианное абсолютное отклонение × 1,4826). Обе величины устойчивы к самим выбросам.
2. Строка — разовая, если одновременно: количество > max(медиана + 6 × MAD, 5 × медиана) и строка даёт ≥ 50% продаж товара за месяц. Строгость (6) — параметр «строгость отсечения» в интерфейсе.
3. Регулярный крупный покупатель — не выброс: если строки выше порога встречаются в 3 и более разных месяцах, это обычный спрос. Пример: установочная коробка SE уходит по 60–90 тыс. шт. на накладную каждый месяц — не режется.
4. Редкий товар (меньше 5 строк): разовая строка — та, что одна даёт ≥ 80% всех продаж товара и в 10+ раз больше остальных его строк. Так ловится «Петля металлическая LOOP»: накладная №20000064179 от 09.06.2025 — 210 000 шт. при обычной строке 1 шт.
5. Разовая строка исключается из регулярного спроса целиком (кейс: «исключать из расчёта регулярной потребности»); номер, дата и количество попадают в обоснование и на график.
6. За 2024 год накладных нет — там аномальные месяцы ловятся тем же порогом по месячным данным (фильтр Хампеля) и заменяются медианой.

Устойчивый рост не чистится: если продажи выросли на 3 месяца подряд, крупные строки есть в трёх месяцах — и правило 3 оставляет их в спросе.

Проверки must-have (tests/test_musthave.py)

Дополнительно: неполный месяц не влияет на заказ, путь после горизонта не вычитается, редкий спрос не обнуляется, «нет спроса» не заказывается даже с правилом менеджера, горизонт считается по дням; сервис, API и агент (tests/test_service.py, tests/test_api.py, tests/test_agent.py). Быстрые тесты — .venv/bin/python scripts/test_project.py; полный прогон с реальными архивами описан в docs/TESTING.md.

Утверждение и экспорт

Менеджер правит количество (проверяется кратность), утверждает или отклоняет с причиной; решение и разница «рекомендация → утверждено» сохраняются в SQLite. Экспорт в XLSX доступен только после утверждения: Код 1с | Артикул | Наименование | Ед. | Кол-во | Кратность | Срочность | Обоснование

• лист «Параметры и допущения». Правило менеджера («минимум N по SKU») сохраняется и применяется в следующих расчётах с отметкой в обосновании.

В веб-интерфейсе утвердить заказ нельзя, пока хоть одно количество не кратно партии (одна кнопка округляет вверх). XLSX и CSV из интерфейса: Код 1С | Артикул | Наименование | Ед. | Количество | Кратность | Поставщик | Срочность | Обоснование; ручная правка менеджера дописывается в обоснование («138 360 → 140 040 шт.»), на листе «Утверждение» — кто и когда утвердил.

Тренд спроса по категориям (обзор): медианный индекс очищенного спроса по товарам категории (каждый товар нормирован на свой средний спрос, поэтому шт/м/упак не смешиваются), изменение июнь–август к марту–маю и прогноз; клик открывает закупки по категории.

HTTP API (api.py)

Чат-агент

LangGraph: модель ⇄ инструменты, не больше 6 шагов. Инструменты только читают данные или считают «что если» без сохранения: сводка, список заказов, объяснение по SKU, схема таблиц, SQL-запрос (только SELECT, максимум 100 строк, без доступа к файлам), what-if, предложение правила (сохраняет его только менеджер). Инструментов отправки заказа нет; вызов неразрешённого инструмента отклоняется. Каждое число в ответе сверяется кодом с результатами инструментов — выдуманные числа помечаются. Названия товаров передаются модели как данные, а не инструкции.

Допущения и ограничения

• Срок поставки SE — 45 дн., допущение (в файле только дата прихода). ИЭК — из дат заказов.
• Текущий остаток ИЭК — оценка: остаток на 01.09 минус продажи 01–22.09, поступления сентября не видны. Строки помечены STOCK_ESTIMATED. Из-за этого часть позиций ИЭК может быть «критично» с запасом — нужна выгрузка текущего остатка.
• Нет клиента в продажах — разовые заказы определяются по размеру строки накладной.
• Нет цен ИЭК — сумма заказа считается только для SE (по себестоимости «СС реал»).
• Категории ИЭК — ABC по данным, а не справочник компании.
• Период заказа 30 дн. и уровни сервиса по категориям — параметры (config.yaml, интерфейс, API).

Структура

web/              интерфейс QadamSupply (JS, без сборки), данные из /ui/data
web_data.py       адаптер расчёта для frontend
app.py            запасной Streamlit-интерфейс
api.py            FastAPI: API сервиса + frontend (статические файлы только из web/)
service.py        общий сервис: расчёт, хранение, решения, экспорт, what-if
config.yaml       параметры расчёта и AI
engine/load.py    загрузка выгрузок 1С по поставщикам, кэш, оговорки при битых файлах
engine/calc.py    расчёт: выбросы, дефицит, сезонность, тренд, заказ, срочность, обоснование
engine/run.py     мост к сервису/API/агенту: параметры, схема OrderLine, правила менеджера
engine/loader.py  распознавание файлов по заголовкам (используется загрузчиком)
engine/models.py  контракты (Params, OrderLine); engine/validate.py — проверка строк
agent/            чат (graph, tools, prompts, security, numbers_check, critic, providers, memory)
export/excel.py   XLSX для 1С
tests/            must-have, загрузчик, сервис, API, агент