17. Анализ плана закупок — выполнение по позициям, ограничение 100% (cap)

Date: 2026-02-08

Status

Accepted

Context

Требование: если позиции закупили больше 100% от плана, в отчёте показывать 100%, а не фактический перевыполнение.

Decision

В сервисе анализа по каждой позиции плана:

• purchased_quantity = сумма offer_quantity по офферам с we_buy=True по этой позиции.
• fulfillment_percent = min(100, (purchased_quantity / required_quantity) * 100).
• Флаг capped_at_100 = True, если расчётный процент > 100%.

При required_quantity == 0 считать fulfillment_percent = 0, capped_at_100 = False.

Обоснование

1. Соответствие ТЗ — «если позиции закупили больше 100%, то пишется 100%».
2. Единообразие KPI — перевыполнение не раздувает средний % выполнения плана.
3. Прозрачность — capped_at_100 и purchased_quantity позволяют при необходимости видеть факт перевыполнения.

Consequences

• (+) Метрики исполнения плана сопоставимы между планами и периодами.
• (-) Для детального анализа перезаказа нужны сырые данные (purchased_quantity остаётся в ответе).

---

Источник: backend/narmak_v2/app/document/ADR.md (ADR-002)