16. Анализ плана закупок — ключ analize в ответе списка документов (type=procurement_plan)

Date: 2026-02-08

Status

Accepted

Context

При запросе GET /api/v2/documents/?type__key__in=procurement_plan&... необходимо возвращать структурированный анализ плана закупки: выполнение по позициям (с ограничением 100%), экономия относительно исторической базы, метрики для фин. директора и рекомендации.

Decision

Добавить в ответ каждого документа типа procurement_plan поле analize (SerializerMethodField в AllDocumentSerializerV2). Для документов с type.key != 'procurement_plan' поле равно null. Имя поля оставлено «analize» в соответствии с ТЗ.

Структура analize:

• positions_fulfillment — по каждой позиции: position_id, required_quantity, purchased_quantity, fulfillment_percent (макс 100%), capped_at_100
• plan_fulfillment_summary — сводка: total_required, total_purchased, avg_fulfillment_percent, positions_count, positions_over_100_count
• savings_analysis — avg_last_2_supplies, planned_purchase_avg, avg_last_3_we_buy, savings_vs_baseline, savings_percent, interpretation
• metrics — бюджет (planned/ordered/supplied), просрочки, концентрация поставщиков, конверсия офферов
• recommendations — массив текстовых рекомендаций по порогам

Обоснование

1. Единая точка входа — анализ доступен в том же эндпоинте, что и список планов, без отдельного запроса.
2. Обратная совместимость — поле опционально (null для не‑план-документов), существующие клиенты не ломаются.
3. Польза для фин. директора — один объект содержит исполнение плана, экономию, бюджет и рекомендации.

Consequences

• (+) Фронт и отчёты получают готовый анализ без дублирования логики.
• (-) Увеличение времени ответа при списке планов из‑за расчёта analize; смягчено prefetch (ADR-005).

---

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