Эндпоинт GET /api/v1/fridge/get-stock

Документация API: Выгрузка текущих запасов продуктов внутри семейной группы

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

Эндпоинт предназначен для получения актуального списка продуктов и их количества, находящихся в «цифровом холодильнике» конкретной семьи либо человека. Данные используются клиентским мобильным приложением FoodLifecycleApp для динамического построения интерфейсных плиток подбора ингредиентов (selectorNode).

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

• Метод: GET
• Маршрут: /api/v1/inventory/stock
• Формат данных: application/json

2.1. Заголовки запроса (Request Headers)

Заголовок	Тип	Обязательный	Описание
Authorization	String	Да	Авторизационный токен в формате Bearer <JWT_TOKEN>

3. Бизнес-логика бэкенда (FastAPI)

При получении запроса бэкенд выполняет следующие последовательные операции:

1. Аутентификация: Декодирует JWT-токен из Depends(security) и извлекает user_id пользователя.
2. Разрешение группы: На основе user_id находит связанный групповой идентификатор семьи (home_group_id).
3. Атомарное чтение базы данных: Инициализирует асинхронное соединение с PostgreSQL Business DB и выполняет SQL-запрос для извлечения только тех позиций, баланс которых строго больше нуля (\(quantity > 0\)):

SELECT id, product_name, quantity, unit, metadata 
FROM fridge_inventory 
WHERE home_group_id = \$1 AND quantity > 0 
ORDER BY product_name ASC;

4. Спецификация ответов сервера

4.1. Успешный ответ (200 OK)

Возвращает JSON-объект, содержащий идентификатор домашней группы и массив нод (плиток) продуктов.

{
  "home_group_id": 1042,
  "nodes": [
    {
      "id": 45,
      "name": "Молоко 3.2%",
      "qty": 2.0,
      "unit": "шт",
      "ui_key": "prod_45",
      "metadata": {
        "fat_percentage": 3.2,
        "expiration_date": "2026-06-25"
      }
    },
    {
      "id": 89,
      "name": "Яблоки",
      "qty": 1.5,
      "unit": "кг",
      "ui_key": "prod_89",
      "metadata": {
        "variety": "Гренни Смит"
      }
    }
  ]
}

4.2. Ошибки авторизации (401 Unauthorized)

Возвращается, если JWT-токен отсутствует, просрочен или имеет некорректную цифровую подпись.

{
  "detail": "Could not validate credentials"
}