chat/docs/NUTRITION_SERVICE_API.md

# Nutrition Service API Documentation

## Overview

Nutrition Service предоставляет API для отслеживания питания, подсчета калорий и получения информации о продуктах питания через интеграцию с FatSecret API. Сервис позволяет пользователям контролировать свой рацион и отслеживать потребление воды.

**Base URL:** `/api/v1/nutrition`

## Authentication

Все эндпоинты требуют JWT аутентификацию.

**Headers:**
```
Authorization: Bearer <jwt_token>
```

## API Endpoints

### 🔍 Поиск продуктов

#### Найти продукты по названию
```http
GET /api/v1/nutrition/foods?query=яблоко
Authorization: Bearer <token>
```

**Параметры:**
- `query` (string, required): Поисковый запрос для поиска продуктов
- `page` (number, optional): Номер страницы результатов, по умолчанию 1
- `page_size` (number, optional): Количество результатов на странице, по умолчанию 20

**Response:**
```json
{
  "results": [
    {
      "food_id": "123456",
      "name": "Яблоко, сырое, с кожурой",
      "brand": "",
      "calories": 52,
      "serving_size": "100г",
      "nutrients": {
        "carbohydrates": 13.8,
        "protein": 0.3,
        "fat": 0.2,
        "fiber": 2.4
      }
    }
  ],
  "total": 25,
  "page": 1,
  "page_size": 20
}
```

### 📝 Записи о питании

#### Добавить запись о питании
```http
POST /api/v1/nutrition/entries
Authorization: Bearer <token>
```

**Body:**
```json
{
  "food_id": "123456",
  "date": "2025-10-16",
  "meal_type": "lunch",
  "quantity": 1.0,
  "serving_size": "100г",
  "notes": "Красное яблоко"
}
```

**Варианты типов приема пищи (meal_type):**
- `breakfast` - завтрак
- `lunch` - обед
- `dinner` - ужин
- `snack` - перекус

#### Получить записи о питании
```http
GET /api/v1/nutrition/entries?date=2025-10-16
Authorization: Bearer <token>
```

**Параметры:**
- `date` (string, optional): Дата в формате YYYY-MM-DD
- `start_date` (string, optional): Начальная дата для получения записей за период
- `end_date` (string, optional): Конечная дата для получения записей за период
- `meal_type` (string, optional): Фильтр по типу приема пищи

#### Удалить запись о питании
```http
DELETE /api/v1/nutrition/entries/{entry_id}
Authorization: Bearer <token>
```

### 💧 Отслеживание воды

#### Добавить запись о потреблении воды
```http
POST /api/v1/nutrition/water
Authorization: Bearer <token>
```

**Body:**
```json
{
  "date": "2025-10-16",
  "amount_ml": 250,
  "time": "12:30:00"
}
```

#### Получить записи о потреблении воды
```http
GET /api/v1/nutrition/water?date=2025-10-16
Authorization: Bearer <token>
```

### 📊 Сводки и статистика

#### Получить дневную сводку по питанию
```http
GET /api/v1/nutrition/daily-summary?date=2025-10-16
Authorization: Bearer <token>
```

**Response:**
```json
{
  "date": "2025-10-16",
  "total_calories": 1578,
  "total_carbohydrates": 175.3,
  "total_proteins": 78.2,
  "total_fats": 52.8,
  "total_water": 1200,
  "entries": [
    {
      "id": 123,
      "food_name": "Яблоко, сырое, с кожурой",
      "meal_type": "lunch",
      "calories": 52,
      "quantity": 1.0,
      "serving_size": "100г"
    }
  ]
}
```

#### Получить недельную аналитику
```http
GET /api/v1/nutrition/weekly-summary?start_date=2025-10-10
Authorization: Bearer <token>
```

## Интеграция с FatSecret API

Сервис использует FatSecret API для получения информации о питательной ценности продуктов. Ключи API хранятся в конфигурации сервера и не требуют дополнительной настройки со стороны клиента.

## Примеры использования

### JavaScript
```javascript
// Пример поиска продуктов
async function searchFoods(query) {
  const response = await fetch(`http://localhost:8000/api/v1/nutrition/foods?query=${query}`, {
    headers: { 'Authorization': `Bearer ${token}` }
  });
  return response.json();
}

// Пример добавления записи о питании
async function addNutritionEntry(entryData) {
  const response = await fetch('http://localhost:8000/api/v1/nutrition/entries', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify(entryData)
  });
  return response.json();
}
```