Метод GET /api/v1/waste/analytics

Документация API: Агрегация логов утилизации и финансового мусора для аналитического контура экосистемы

Published

July 2, 2026

INVENTORY-2XX Backlog — Краткое Описание задачи 1.
INVENTORY-1XX Refinement (Уточнение) — Краткое Описание задачи 2.

1 Функциональное назначение

Метод предназначен для формирования консолидированных отчетов по утилизированным продуктам в рамках конкретного семейного или корпоративного контура (home_group_id).

Метод решает следующие архитектурные задачи:

Анализ финансового мусора (Waste Metrics): Группирует объемы выброшенной еды по каноничным кодам причин (Enum), позволяя рассчитывать коэффициент полезного использования продуктов (KPI склада).
Аудит теневых задолженностей: Подсчитывает процент утилизаций, которые произошли в режиме «теневой экономики» (без чека) и до сих пор висят в виде неразрешенных строк в таблице fridge_shadow_debts.
Оптимизация UI-выдачи: Возвращает агрегированную структуру данных за выбранный временной период для рендеринга графиков и текстовых алертов («Здоровье холодильника») во Flutter.

2 Протокол взаимодействия (HTTP Контракт)

Метод: GET
Маршрут: /api/v1/waste/analytics
Формат данных: application/json (только ответ)

2.1 Спецификация параметров запроса (Query Parameters)

Параметр	Тип	Обязательный	Описание	Пример значения
`period_days`	Integer	Нет	Глубина анализа в днях (по умолчанию — 30 суток)	`30`

2.2 Спецификация заголовков (HTTP Headers)

Заголовок	Обязательный	Описание	Пример значения
`Authorization`	Да	Токен доступа (`Access Token`) для проверки контекста `home_group_id`.	`Bearer eyJhbGciOiJIUzI1Ni...`
`X-Request-ID`	Да	Сквозной ID запроса для профилирования скорости аналитического запроса	`req-waste-anl-77bb`

2.3 Спецификация структуры ответа (Response Body)

Метод возвращает распределение утилизированных объемов по причинам и выводит общую сумму нерешенных теневых долгов.

2.3.1 Пример JSON-ответа (Payload):

{
  "home_group_id": "group-772-alpha",
  "analyzed_period_days": 30,
  "summary": {
    "total_waste_events": 14,
    "unresolved_shadow_debts_count": 3
  },
  "metrics_by_reason": [
    {
      "waste_reason": "REASON_SPOILED",
      "total_items_count": 8,
      "description": "Продукты испортились или сгнили"
    },
    {
      "waste_reason": "REASON_EXPIRED",
      "total_items_count": 6,
      "description": "Истек официальный срок годности"
    }
  ]
}

3 Схема обработки запроса пользователя (Mermaid)

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

Важное примечание

В настоящей публичной документации отображены не все шаги и сценарии для приложения в частности и для системы цифровых симуляторов бизнес-процессов в общем.

sequenceDiagram
    autonumber
    actor User as Пользователь (Экран Статистики)
    participant APP as Мобильное приложение (Flutter)
    participant WS as Сервис Утилизации (FastAPI)
    participant DB as База Данных (PostgreSQL)

    User->>APP: Открывает вкладку "Аналитика мусора / Здоровье"
    APP->>WS: HTTP GET /api/v1/waste/analytics?period_days=30 (с JWT токеном)
    activate WS
    
    WS->>DB: Вызов SQL-запроса агрегации логов утилизации по home_group_id
    activate DB
    note over DB: Шаг 4: Подсчет инцидентов в waste_history_log с группировкой по Enum
    note over DB: Шаг 5: COUNT(*) из fridge_shadow_debts WHERE is_resolved = FALSE
    DB-->>WS: Возвращает консолидированные числовые метрики
    deactivate DB
    
    WS-->>APP: HTTP 200 OK (JSON с метриками и объемом теневых долгов)
    deactivate WS
    note over APP: Экран Flutter рендерит аналитические графики порчи продуктов

4 Спецификация серверной логики (SQL)

Для одновременного извлечения среза исторических утилизаций и объема текущего теневого дефицита на уровне PostgreSQL используется агрегационный запрос с подзапросом (Subquery).

SELECT 
    whl.waste_reason,
    COUNT(whl.id) AS total_items_count,
    -- Внедряем подзапрос для подсчета незакрытых теневых долгов "теневой экономики"
    (
        SELECT COUNT(*) 
        FROM fridge_shadow_debts fsd 
        WHERE fsd.home_group_id = \$1 AND fsd.is_resolved = FALSE
    ) AS unresolved_shadow_debts_count
FROM waste_history_log whl
WHERE whl.home_group_id = \$1
  AND whl.created_at >= NOW() - CAST(\$2 || ' days' AS INTERVAL)
GROUP BY whl.waste_reason;

5 Вилки исключений и обработка ошибок

5.0.1 Ошибка: Превышение максимального интервала анализа (HTTP 400 Bad Request)

Выбрасывается на стороне FastAPI, если передан параметр period_days со значением больше 365, защищая СУБД от сканирования избыточных исторических индексов.

{
  "error_code": "ERR-ANALYTICS-PERIOD-EXCEEDED",
  "message": "Глубина аналитического отчета не может превышать 365 дней.",
  "details": {
    "requested_period": 500,
    "allowed_max_period": 365
  }
}