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

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

Published

July 2, 2026

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

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

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

  1. Анализ финансового мусора (Waste Metrics): Группирует объемы выброшенной еды по каноничным кодам причин (Enum), позволяя рассчитывать коэффициент полезного использования продуктов (KPI склада).
  2. Аудит теневых задолженностей: Подсчитывает процент утилизаций, которые произошли в режиме «теневой экономики» (без чека) и до сих пор висят в виде неразрешенных строк в таблице fridge_shadow_debts.
  3. Оптимизация 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)

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

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

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

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 рендерит аналитические графики порчи продуктов

Шаг Действие Параметры / Запросы Ошибки (Исключения / Статусы)
Шаг 1 (User -> APP) Пользователь открывает экран аналитики и запрашивает сводные данные по утилизации. Переход на вкладку «Аналитика мусора / Здоровье» NavigationException (ошибка роутинга)
Шаг 2 (APP -> WS) Мобильное приложение запрашивает агрегированную статистику за указанный временной период. HTTP GET /api/v1/waste/analytics?period_days=30
Headers: Bearer JWT		 DioException: connection timeout
HTTP 401 Unauthorized
Шаг 3 (WS -> DB) Сервис утилизации инициирует расчет метрик и запрашивает консолидированные данные из хранилища. Передача параметров фильтрации по идентификатору home_group_id Таймаут пула: PostgreSQL: PoolTimeoutError
HTTP 504 Gateway Timeout
Шаг 4 (DB -> DB) Внутреннее действие: Хранилище подсчитывает количество инцидентов порчи с группировкой по категориям. Агрегация записей лога истории утилизации по типам причин (Enum) PostgreSQL: BadGroupingException
Шаг 5 (DB -> DB) Внутреннее действие: Хранилище вычисляет объем текущих незакрытых задолженностей по вводу веса. Подсчет количества неразрешенных записей теневого долга инвентаря PostgreSQL: ColumnNotFound
Шаг 6 (DB -> WS) Хранилище передает вычисленный массив числовых метрик обратно в слой приложения. Результат: сырые агрегированные числовые показатели и объемы PostgreSQL: Connection timeout
Шаг 7 (WS -> APP) Сервис преобразует метрики в контрактный формат и возвращает успешный ответ клиенту. HTTP 200 OK
Payload: JSON-структура со статистикой и флагом долгов		 HTTP 500 Serialization Error
Шаг 8 (APP -> APP) Внутреннее действие: Мобильное приложение парсит ответ и перерисовывает интерфейс. Рендеринг круговых и линейных графиков на основе полученного массива StateManagementException

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
  }
}