# FoodAI — Техническая архитектура

## 1. Стек технологий

| Компонент | Технология | Обоснование |
|-----------|-----------|-------------|
| Backend | Go | Высокая производительность, встроенная конкурентность (горутины для очередей), строгая типизация, простой деплой (один бинарник) |
| База данных | PostgreSQL | Надёжная реляционная БД, JSONB для гибких структур (нутриенты, шаги рецептов), полнотекстовый поиск, зрелая экосистема |
| Клиент | Flutter (Android, iOS, Web) | Единая кодовая база на три платформы, нативная производительность на мобильных, зрелая экосистема виджетов |
| Авторизация | Firebase Auth | Бесплатно до 50K MAU, email + Google + Apple из коробки, официальный Go SDK, отличная интеграция с Flutter |
| AI (vision + текст) | Google Gemini 2.5 Flash | Единая модель для распознавания фото (чеки, продукты, блюда), генерации рецептов, меню и замены ингредиентов. Free tier для разработки |
| Изображения | Pexels API | Фото к рецептам. Бесплатно до 20K req/мес, коммерческое использование без атрибуции |
| Хранение файлов | S3-совместимое (MinIO / Cloud Storage) | Фото блюд от пользователей, загружаемые для распознавания |

---

## 2. Архитектура системы

```
┌──────────────────────────────────────────────────────────┐
│                    Flutter Client                         │
│              (Android / iOS / Web)                        │
│                                                          │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐              │
│  │ Firebase  │  │  REST    │  │  File    │              │
│  │ Auth SDK  │  │  Client  │  │  Upload  │              │
│  └─────┬────┘  └─────┬────┘  └─────┬────┘              │
└────────┼─────────────┼─────────────┼─────────────────────┘
         │             │             │
         │ idToken     │ JWT         │ multipart
         ▼             ▼             ▼
┌──────────────────────────────────────────────────────────┐
│                     Go Backend                            │
│                                                          │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────┐  │
│  │  Auth       │  │  API         │  │  AI Queue      │  │
│  │  Middleware  │  │  Handlers    │  │  Manager       │  │
│  │             │  │              │  │                │  │
│  │  Firebase   │  │  /products   │  │  Priority      │  │
│  │  Token      │  │  /recipes    │  │  Queues:       │  │
│  │  Verify     │  │  /menu       │  │  - paid (fast) │  │
│  │  → JWT      │  │  /diary      │  │  - free (slow) │  │
│  └──────┬──────┘  │  /ai         │  │                │  │
│         │         │  /shopping   │  │  Rate Limiter  │  │
│         │         └──────┬───────┘  │  Budget Guard  │  │
│         │                │          └───────┬────────┘  │
│         │                │                  │           │
│  ┌──────┴────────────────┴──────────────────┴────────┐  │
│  │              Service Layer                         │  │
│  │                                                    │  │
│  │  ┌──────────┐ ┌───────────┐ ┌──────────────────┐  │  │
│  │  │ Product  │ │ Recipe    │ │ AI Service       │  │  │
│  │  │ Service  │ │ Service   │ │ (interface)      │  │  │
│  │  └────┬─────┘ └─────┬─────┘ └────┬─────────────┘  │  │
│  └───────┼─────────────┼────────────┼────────────────┘  │
│          │             │            │                    │
└──────────┼─────────────┼────────────┼────────────────────┘
           │             │            │
           ▼             │            ▼
┌──────────────────┐     │     ┌──────────────────┐
│                  │     │     │                  │
│   PostgreSQL     │     │     │   Gemini API     │
│                  │     │     │   (Flash /       │
│   - users        │     │     │    Flash-Lite)   │
│   - products     │     │     │                  │
│   - recipes      │     │     └──────────────────┘
│   - menu_plans   │     │
│   - meal_diary   │     ▼
│   - reviews      │  ┌──────────────────┐
│   - ai_tasks     │  │                  │
│                  │  │  Pexels API      │
└──────────────────┘  │  (фото к рец.)   │
                      │                  │
                      └──────────────────┘
```

---

## 3. Авторизация

### Поток авторизации

```
Flutter                    Firebase              Go Backend
  │                           │                      │
  │  1. signInWithGoogle()    │                      │
  │  ──────────────────────►  │                      │
  │                           │                      │
  │  2. Firebase idToken      │                      │
  │  ◄──────────────────────  │                      │
  │                           │                      │
  │  3. POST /auth/login      │                      │
  │     {firebase_token}      │                      │
  │  ─────────────────────────┼─────────────────►    │
  │                           │                      │
  │                           │  4. VerifyIDToken()  │
  │                           │  ◄───────────────    │
  │                           │  ───────────────►    │
  │                           │     (uid, email)     │
  │                           │                      │
  │                           │  5. Upsert user      │
  │                           │     в PostgreSQL     │
  │                           │                      │
  │  6. {jwt, refresh_token,  │                      │
  │      user}                │                      │
  │  ◄────────────────────────┼──────────────────    │
  │                           │                      │
  │  7. Сохранить JWT         │                      │
  │     в Secure Storage      │                      │
```

### Детали

- **Firebase Auth** обрабатывает все провайдеры (email/password, Google, Apple) на стороне клиента.
- **Go backend** получает Firebase `idToken`, верифицирует его через Firebase Admin SDK (`firebase.google.com/go/v4/auth`), извлекает `uid`, `email`, `name`.
- **Backend выдаёт собственный JWT** (подписанный секретом сервера) с `user_id`, `role` (free/paid), `exp`. Это позволяет не зависеть от Firebase при каждом API-запросе.
- **Refresh token** хранится в БД, ротируется при каждом использовании.
- **Apple Sign-In** обязателен на iOS при наличии любого стороннего входа (политика App Store). Firebase Auth обрабатывает Apple прозрачно.
- Flutter-пакеты: `firebase_auth`, `google_sign_in`, `sign_in_with_apple`.

---

## 4. AI-подсистема (ядро приложения)

### Абстракция

AI-провайдер скрыт за интерфейсами. Это позволяет заменить Gemini на OpenAI или специализированный API без изменения бизнес-логики.

```
┌─────────────────────────────────────────┐
│            AI Service (interface)        │
│                                         │
│  FoodRecognizer                         │
│  ├── RecognizeReceipt(image) → []Item   │
│  ├── RecognizeProducts(image) → []Item  │
│  └── RecognizeDish(image) → DishInfo    │
│                                         │
│  RecipeGenerator                        │
│  ├── GenerateRecipes(req) → []Recipe    │
│  └── SuggestSubstitutions(req) → []Sub  │
│                                         │
│  MenuPlanner                            │
│  └── GenerateMenu(req) → MenuPlan      │
│                                         │
│  NutritionEstimator                     │
│  └── EstimateNutrition(dish) → KBJU    │
│                                         │
└──────────────┬──────────────────────────┘
               │
      ┌────────┴────────┐
      ▼                 ▼
┌───────────┐   ┌───────────┐
│  Gemini   │   │  OpenAI   │
│  Adapter  │   │  Adapter  │
│  (active) │   │  (резерв) │
└───────────┘   └───────────┘
```

### AI-задачи: детали

#### 4.1. Распознавание чека

- **Модель:** Gemini 2.5 Flash (vision)
- **Вход:** фото чека (JPEG/PNG)
- **Промпт:** системная инструкция + фото → structured JSON
- **Выход:**

```json
{
  "items": [
    {
      "name": "Молоко 2.5%",
      "quantity": 1,
      "unit": "л",
      "category": "dairy",
      "price": 49.0,
      "confidence": 0.95
    }
  ],
  "unrecognized": [
    { "raw_text": "ТОВ АРТИК 1ШТ", "price": 89.0 }
  ]
}
```

- **Стратегия промпта:** «Ты — OCR-система для чеков из продуктовых магазинов. Извлеки список продуктов. Для каждого определи название, количество, единицу измерения, категорию. Если не можешь распознать позицию — добавь в unrecognized с оригинальным текстом. Ответ строго в JSON.»
- **Fallback:** если confidence < 0.5 — элемент идёт в `unrecognized`.

#### 4.2. Распознавание продуктов (фото)

- **Модель:** Gemini 2.5 Flash (vision)
- **Вход:** фото продуктов (холодильник, стол)
- **Выход:** аналогичная структура (без цены), но с приблизительным весом/количеством
- **Нюанс:** поддержка нескольких фото — результаты объединяются на бэкенде (дедупликация по названию + суммирование количеств).

#### 4.3. Распознавание блюда

- **Модель:** Gemini 2.5 Flash (vision)
- **Вход:** фото готового блюда
- **Выход:**

```json
{
  "dish_name": "Паста Карбонара",
  "weight_grams": 450,
  "calories": 580,
  "protein": 24,
  "fat": 28,
  "carbs": 56,
  "confidence": 0.85,
  "similar_dishes": ["Паста с беконом", "Спагетти алла Грича"]
}
```

- **Нюанс:** `similar_dishes` используется для поиска похожих рецептов в нашей БД (по названию, fuzzy search).

#### 4.4. Генерация рецептов / подбор меню

- **Модель:** Gemini 2.5 Flash-Lite (текст) — дешевле, vision не нужен
- **Ключевой принцип:** Gemini генерирует рецепты с нуля на основе контекста пользователя. Статическая база рецептов не нужна.

```
1. Backend собирает контекст: продукты пользователя (с учётом сроков хранения),
   профиль (цель, КБЖУ), предпочтения кухни, диетические ограничения
2. Gemini генерирует полные рецепты: название, ингредиенты с граммовками,
   шаги, КБЖУ на порцию, image_query для Pexels
3. Backend параллельно запрашивает фото из Pexels по image_query
4. Результат возвращается клиенту; при сохранении → пишется в saved_recipes
```

- **Промпт для рекомендаций:**

```
Ты — диетолог-повар. Предложи 5 рецептов на русском языке.

Профиль:
- Цель: похудение, 1800 ккал/день
- Ограничения: без орехов
- Предпочтения: русская, азиатская кухня

Доступные продукты (приоритет — скоро истекают):
- Куриное филе 500г (истекает завтра ⚠)
- Морковь 3 шт · Рис 400г · Яйца 4 шт

Верни ТОЛЬКО валидный JSON без markdown. Для каждого рецепта:
title, description, cuisine, difficulty, prep_time_min, cook_time_min,
servings, image_query (EN), ingredients, steps, tags, nutrition_per_serving.
```

- **Выход:** массив рецептов с `image_query` — бэкенд дозапрашивает Pexels и возвращает готовый объект с `image_url`.

#### 4.5. AI-генерация персональных рецептов

Отдельный кейс — когда в БД нет подходящего рецепта из имеющихся продуктов:

- **Модель:** Gemini 2.5 Flash-Lite
- **Промпт:** «Из продуктов [список] предложи рецепт. Формат: JSON с названием, ингредиентами (с граммовками), шагами, калорийностью, БЖУ.»
- **Результат:** сохраняется в БД как `source = 'ai_generated'`, помечается в UI как «AI-рецепт».
- **Валидация нутриентов:** значения КБЖУ от Gemini считаются приблизительными и помечаются «≈» в UI. Точная верификация через USDA FoodData Central запланирована в будущем (см. TODO.md).

#### 4.6. Замена ингредиентов

- **Модель:** Gemini 2.5 Flash-Lite
- **Вход:** ингредиент + доступные продукты
- **Выход:** `[{ "original": "пекорино", "substitute": "пармезан", "ratio": "1:1", "note": "Менее острый вкус" }]`
- **Кеширование:** результаты замен кешируются в БД (таблица `ingredient_substitutions`), чтобы не запрашивать AI повторно для одинаковых пар.

---

## 5. Маппинг ингредиентов (нормализация продуктов пользователя)

### Проблема

Пользователи вводят продукты свободным текстом: "куриное филе", "куриная грудка", "курица без кости". Это одно и то же. Нужен слой нормализации — чтобы при генерации рекомендаций Gemini понимал, что у пользователя есть, и чтобы не дублировались продукты.

### Решение: таблица `ingredient_mappings`

Каноническая таблица с алиасами на русском и английском. Заполняется по мере работы приложения через Gemini (рантайм-дополнение).

```
┌───────────────────────────────────────────────────────┐
│                ingredient_mappings                     │
│───────────────────────────────────────────────────────│
│ id                  UUID                               │
│ canonical_name      "chicken_breast"                   │
│ canonical_name_ru   "куриная грудка"                   │
│ aliases (JSONB)     ["куриное филе", "куриная грудка", │
│                      "грудка курицы", "chicken breast"]│
│ category            "meat"                             │
│ default_unit        "g"                                │
│ calories_per_100g   165  (≈ от Gemini)                 │
│ protein_per_100g    31                                 │
│ fat_per_100g        3.6                                │
│ storage_days        3                                  │
└───────────────────────────────────────────────────────┘
```

### Как работает связка

```
Продукт юзера         ingredient_mappings        Промпт для Gemini
──────────────         ───────────────────        ──────────────────

"Куриное филе"                 │                 canonical_name_ru:
      │                        │                 "куриная грудка"
      │    Fuzzy search        │                       │
      └────по aliases ────►  canonical_name  ──────────►│
                              "chicken_breast"   Gemini понимает
                                                 что это за продукт
```

### Потоки по сценариям

#### Сценарий 1: Добавление продукта (чек/фото → запасы)

```
1. Gemini возвращает: "Куриное филе, 500г"
2. Backend: fuzzy search по ingredient_mappings.aliases
   SELECT * FROM ingredient_mappings
   WHERE aliases @> '"куриное филе"'::jsonb
   OR similarity(canonical_name, 'куриное филе') > 0.3
3. Найдено → product.mapping_id = ingredient_mappings.id
   Автоподставляются: category, default_unit, storage_days, нутриенты
4. Не найдено → разовый запрос к Gemini:
   "К какому каноническому ингредиенту относится 'филе индейки'?
    Ответь JSON: { canonical_name, category, calories_per_100g, ... }"
   Результат сохраняется в ingredient_mappings (новая строка)
   Следующий юзер с таким же продуктом — AI не нужен
```

#### Сценарий 2: Проверка "есть ли ингредиент рецепта в запасах"

```
1. Рецепт "Паста Карбонара" содержит ингредиент: canonical_name = "spaghetti"
2. products: ищем WHERE mapping_id IN (
     SELECT id FROM ingredient_mappings WHERE canonical_name = 'spaghetti'
   )
3. Найдено в products → отметка ✅ (есть в запасах)
   Не найдено → отметка ❌ (нет) или 🔄 (есть замена через ingredient_substitutions)
```

#### Сценарий 3: Рекомендации рецептов "из моих продуктов"

```
1. Продукты юзера → через mapping_id → набор canonical_names_ru
   ["куриная грудка", "рис", "морковь", "лук"]

2. Backend формирует промпт для Gemini:
   - профиль пользователя (цель, КБЖУ-норма, ограничения)
   - список продуктов с количеством и сроками
   - приоритет: продукты, истекающие скоро

3. Gemini генерирует 5 рецептов с нуля, используя имеющиеся продукты.
   Каждый рецепт содержит image_query (EN) для запроса Pexels.

4. Backend параллельно запрашивает Pexels по image_query.

5. Результат: персонализированные рецепты с фото.
   Статическая база рецептов не нужна.
```

#### Сценарий 4: Распознавание блюда (фото → калории)

```
1. Gemini определяет: "Паста Карбонара"
2. Backend: full-text search по recipes.title
   SELECT * FROM recipes
   WHERE to_tsvector('russian', title) @@ plainto_tsquery('russian', 'Паста Карбонара')
   ORDER BY review_count DESC LIMIT 5
3. Найдено → привязка к рецепту (точные нутриенты из БД)
   Не найдено → используются нутриенты от Gemini (помечены "≈ приблизительно")
```

#### Сценарий 5: Генерация меню

```
1. Backend собирает контекст:
   - профиль (цель, КБЖУ-норма, кухни, ограничения)
   - продукты пользователя (canonical_names, количество, сроки)
   - период меню (например, 7 дней × 3 приёма пищи)

2. Gemini генерирует полное меню с нуля:
   - 7 дней, 3 приёма пищи в день
   - каждый слот: полный рецепт (ингредиенты, шаги, КБЖУ, image_query)
   - баланс КБЖУ в рамках дневной нормы
   - приоритет продуктам с истекающим сроком

3. Backend параллельно запрашивает Pexels для каждого рецепта.

4. Меню сохраняется в menu_plans + menu_items.
   Рецепты из меню — в saved_recipes (source = 'ai').

→ Gemini генерирует контент полностью. Никакой статической базы не нужно.
```

### Наполнение таблицы маппингов

| Этап | Источник | Объём |
|------|----------|-------|
| Начальный seed | Ручное составление топ-200 базовых ингредиентов | Aliases на русском и английском |
| Рантайм-дополнение | Gemini (при нераспознанном продукте) | По мере роста юзеров |
| Пользовательская обратная связь | Юзер корректирует продукт на экране редактирования | Новые aliases |

Со временем маппинг растёт, и AI для распознавания ингредиентов вызывается всё реже.

### Сводная таблица: где Gemini, а где нет

| Задача | Gemini? | Как стыкуется с БД |
|--------|---------|---------------------|
| OCR чека → продукты | Да (vision) | Fuzzy match по `ingredient_mappings.aliases` |
| Фото продуктов → список | Да (vision) | То же |
| Фото блюда → калории | Да (vision) | Результат логируется в `ai_tasks` |
| Рекомендации рецептов из продуктов | **Да (текст)** | Продукты передаются в промпт; результат → `saved_recipes` |
| Генерация меню на неделю | Да (текст) | Генерирует с нуля; сохраняется в `menu_plans` + `menu_items` |
| Замена ингредиентов | Да (текст) | Кеш в `ingredient_substitutions` |
| Нераспознанный ингредиент | Да (текст, разово) | Результат сохраняется в `ingredient_mappings` |

---

## 6. Система очередей AI-запросов

### Проблема

Gemini API имеет ограничения по RPM (requests per minute) и стоит денег. Нужно:
1. Не допустить перерасход бюджета
2. Дать приоритет платным пользователям
3. Не блокировать систему при пиковых нагрузках

### Архитектура

```
                        Входящий AI-запрос
                               │
                               ▼
                    ┌─────────────────────┐
                    │   Rate Limiter      │
                    │   (per-user)        │
                    │                     │
                    │   Free: 20 req/час  │
                    │   Paid: 100 req/час │
                    └──────────┬──────────┘
                               │
                        ┌──────┴──────┐
                        │             │
                   Paid user     Free user
                        │             │
                        ▼             ▼
              ┌─────────────┐ ┌─────────────┐
              │ Paid Queue  │ │ Free Queue  │
              │             │ │             │
              │ N воркеров  │ │ 1 воркер    │
              │ (быстро)    │ │ (медленно)  │
              └──────┬──────┘ └──────┬──────┘
                     │               │
                     └───────┬───────┘
                             │
                             ▼
                  ┌─────────────────────┐
                  │   Budget Guard      │
                  │                     │
                  │   Daily limit: $X   │
                  │   Current: $Y       │
                  │                     │
                  │   Y >= X? → REJECT  │
                  │   Y >= 0.8X? → WARN │
                  └──────────┬──────────┘
                             │
                             ▼
                  ┌─────────────────────┐
                  │   Gemini API Call   │
                  │                     │
                  │   + Track cost      │
                  │   + Log to ai_tasks │
                  └─────────────────────┘
```

### Компоненты

#### Rate Limiter (per-user)
- Алгоритм: token bucket (горутина + каналы в Go).
- Лимиты хранятся в конфигурации, разделены по тарифу (free/paid).
- При превышении: HTTP 429 + заголовок `Retry-After`.
- Клиент показывает: «Слишком много запросов. Попробуйте через N секунд.»

#### Priority Queues
- **Paid Queue:** N воркеров (горутин), обрабатывающих запросы параллельно. N зависит от лимита RPM Gemini API (например, при лимите 60 RPM и двух очередях — 50 RPM на paid, 10 RPM на free).
- **Free Queue:** 1 воркер, обрабатывает запросы последовательно. Пользователи free-тарифа ждут дольше, но результат получают.
- Реализация: `chan AITask` в Go с горутинами-воркерами. Без внешних брокеров сообщений на данном этапе.
- При масштабировании: миграция на Redis Streams или NATS.

#### Budget Guard
- **Daily budget cap:** максимальная сумма затрат на Gemini API в день (например, $50).
- **Учёт затрат:** каждый запрос логируется с оценочной стоимостью (input_tokens × price + output_tokens × price). Gemini API возвращает `usage_metadata` с точными токенами.
- **Пороги:**
  - 80% бюджета: предупреждение в логи, приоритет только paid-очереди.
  - 100% бюджета: free-очередь останавливается, paid продолжает (из резерва).
  - 120% бюджета (абсолютный лимит): все AI-запросы отклоняются.
- **Graceful degradation:** при отклонении запроса клиент показывает: «AI-распознавание временно недоступно. Вы можете добавить продукты вручную.»

#### Таблица `ai_tasks` (лог)

| Поле | Тип | Описание |
|------|-----|----------|
| id | UUID | |
| user_id | UUID | FK → users |
| task_type | ENUM | receipt_ocr, product_recognition, dish_recognition, recipe_generation, menu_planning, substitution |
| status | ENUM | queued, processing, completed, failed, rejected |
| priority | ENUM | free, paid |
| input_tokens | INT | Токены на вход (от API) |
| output_tokens | INT | Токены на выход (от API) |
| estimated_cost | DECIMAL | Оценочная стоимость в $ |
| queue_time_ms | INT | Время ожидания в очереди |
| process_time_ms | INT | Время обработки |
| created_at | TIMESTAMP | |
| completed_at | TIMESTAMP | |

Используется для: аналитики затрат, мониторинга, оптимизации промптов.

---

## 7. Рецепты и контент

### Источники рецептов

Статической базы рецептов нет. Все рецепты генерируются Gemini on-demand и сохраняются пользователями.

```
┌─────────────────────────────────────────────────┐
│                  Recipe Service                  │
│                                                 │
│  ┌──────────────────────┐  ┌──────────────────┐ │
│  │   AI-generated       │  │  User Recipes    │ │
│  │   (Gemini)           │  │  (будущее)       │ │
│  │                      │  │                  │ │
│  │   source: 'ai'       │  │  source: 'user'  │ │
│  └──────────┬───────────┘  └────────┬─────────┘ │
│             │                       │           │
│             └──────────┬────────────┘           │
│                        │                        │
│                        ▼                        │
│             ┌──────────────────┐                │
│             │  saved_recipes   │                │
│             │  (per-user)      │                │
│             └──────────────────┘                │
└─────────────────────────────────────────────────┘
```

### Принцип работы с рецептами

- **Генерация:** Gemini создаёт рецепты с нуля на основе контекста пользователя (продукты, профиль, цели).
- **Фото:** Pexels API по `image_query` (EN), которую Gemini включает в ответ.
- **КБЖУ:** приблизительные значения от Gemini, помечаются «≈» в UI.
- **Сохранение:** пользователь тапает ❤ → рецепт сохраняется в `saved_recipes`. До сохранения нигде не хранится.
- **Отсутствие глобального каталога:** каждый пользователь видит только свои сохранённые рецепты и свежие рекомендации. Полноценный каталог с поиском — в TODO.md (требует постоянной базы).

### Согласованность рецептов

- Все данные рецепта (ингредиенты, шаги, КБЖУ, image_url) приходят от Gemini+Pexels в одном запросе.
- Сохранённый рецепт хранится целиком в `saved_recipes` как JSONB — нет риска рассинхронизации.
- КБЖУ помечены как приблизительные — пользователь понимает точность данных.

---

## 8. Доменные сущности (схема БД)

```
┌──────────────┐       ┌──────────────────┐
│    users     │       │    products      │
│──────────────│       │──────────────────│
│ id           │◄──┐   │ id               │
│ firebase_uid │   │   │ user_id (FK)     │──► users
│ email        │   │   │ mapping_id (FK)  │──► ingredient_mappings
│ name         │   │   │ name             │
│ avatar_url   │   │   │ quantity         │
│ height_cm    │   │   │ unit             │
│ weight_kg    │   │   │ category         │
│ age          │   │   │ storage_days     │
│ gender       │   │   │ added_at         │
│ activity     │   │   │ expires_at       │
│ goal         │   │   │ (computed)       │
│              │   │   └──────────────────┘
│ plan (free/  │   │
│       paid)  │   │   ┌──────────────────┐
│ preferences  │   │   │    recipes       │
│ (JSONB)      │   │   │──────────────────│
│ created_at   │   │   │ id               │
└──────────────┘   │   │ source           │
                   │   │ title            │
                   │   │ description      │
                   │   │ cuisine          │
                   │   │ difficulty       │
                   │   │ prep_time_min    │
                   │   │ calories         │
                   │   │ protein          │
                   │   │ fat              │
                   │   │ carbs            │
                   │   │ servings         │
                   │   │ image_url        │
                   │   │ ingredients      │
                   │   │ (JSONB)          │
                   │   │ steps (JSONB)    │
                   │   │ tags (JSONB)     │
                   │   │ avg_rating       │
                   │   │ review_count     │
                   │   │ created_by       │──► users (NULL для ai-generated)
                   │   └──────────────────┘
                   │
┌──────────────────┤   ┌──────────────────┐
│   menu_plans     │   │   menu_items     │
│──────────────────│   │──────────────────│
│ id               │   │ id               │
│ user_id (FK)  ───┘   │ menu_plan_id(FK) │──► menu_plans
│ week_start       │   │ day_of_week      │
│ created_at       │   │ meal_type        │
│ template_name    │   │ recipe_id (FK)   │──► recipes
│ (NULL если не    │   │ servings         │
│  шаблон)         │   └──────────────────┘
└──────────────────┘
                       ┌──────────────────┐
                       │   meal_diary     │
                       │──────────────────│
                       │ id               │
                       │ user_id (FK)     │──► users
                       │ date             │
                       │ meal_type        │
                       │ recipe_id (FK)   │──► recipes (NULL для ручного ввода)
                       │ name             │
                       │ portions         │
                       │ calories         │
                       │ protein          │
                       │ fat              │
                       │ carbs            │
                       │ source           │
                       │ (menu/photo/     │
                       │  manual/recipe)  │
                       │ created_at       │
                       └──────────────────┘

┌──────────────────┐   ┌──────────────────┐
│    reviews       │   │  shopping_lists  │
│──────────────────│   │──────────────────│
│ id               │   │ id               │
│ user_id (FK)     │──►│ user_id (FK)     │──► users
│ recipe_id (FK)   │──►│ menu_plan_id(FK) │──► menu_plans
│ rating (1-5)     │   │ items (JSONB)    │
│ text             │   │ created_at       │
│ photo_url        │   └──────────────────┘
│ created_at       │
└──────────────────┘   ┌──────────────────┐
                       │  water_tracker   │
                       │──────────────────│
                       │ id               │
                       │ user_id (FK)     │──► users
                       │ date             │
                       │ glasses          │
                       └──────────────────┘

┌──────────────────┐   ┌──────────────────────────┐
│    ai_tasks      │   │ ingredient_substitutions │
│──────────────────│   │──────────────────────────│
│ (см. раздел 6)   │   │ id                       │
└──────────────────┘   │ original_mapping_id (FK) │──► ingredient_mappings
                       │ substitute_mapping_id(FK)│──► ingredient_mappings
                       │ ratio                    │
                       │ note                     │
                       │ created_at               │
                       └──────────────────────────┘

┌────────────────────────────┐
│    ingredient_mappings     │
│────────────────────────────│
│ id                         │
│ canonical_name             │
│ canonical_name_ru          │
│ aliases (JSONB)            │
│ category                   │
│ default_unit               │
│ calories_per_100g          │
│ protein_per_100g           │
│ fat_per_100g               │
│ carbs_per_100g             │
│ storage_days               │
│ created_at                 │
└────────────────────────────┘
```

### Ключевые решения по схеме

- **`products.mapping_id`** — FK на `ingredient_mappings`. Связывает продукт пользователя с каноническим ингредиентом. Через эту связь определяется наличие ингредиентов рецепта в запасах. Может быть NULL (если продукт не удалось сопоставить).
- **`ingredient_mappings`** — каноническая таблица ингредиентов. `canonical_name_ru` — русское название. `aliases` (JSONB) содержит все варианты написания на разных языках. Нутриенты на 100г используются для пересчёта калорийности при необходимости. `storage_days` — дефолтный срок хранения для категории. Наполняется вручную (seed) и автоматически через Gemini при нераспознанных продуктах.
- **`ingredient_substitutions`** — кеш замен ингредиентов. Ссылается на `ingredient_mappings` по обоим ингредиентам (оригинал и замена). Один раз определённая AI-замена переиспользуется для всех пользователей.
- **`products.storage_days`** — период хранения после покупки (не фиксированная дата). `expires_at` вычисляется как `added_at + storage_days`. При отображении: «осталось X дней». Дефолт берётся из `ingredient_mappings.storage_days` при привязке.
- **`products.unit`** — ENUM: g, kg, ml, l, pcs, bunch, pack. Фронтенд отображает локализованные названия. Дефолт берётся из `ingredient_mappings.default_unit`.
- **`recipes.ingredients`** — JSONB массив: `[{ "name": "...", "amount": 200, "unit": "g", "optional": false }]`. JSONB позволяет гибко хранить без нормализации, при этом поддерживая поиск (`@>` оператор).
- **`recipes.steps`** — JSONB массив: `[{ "order": 1, "title": "...", "description": "...", "image_url": "...", "timer_seconds": null }]`. `timer_seconds` не null → на шаге отображается таймер.
- **`recipes.source`** — ENUM: ai, user. Определяет происхождение рецепта.
- **`meal_diary.source`** — откуда записано: из меню, через фото, вручную, из рецепта.
- **`shopping_lists.items`** — JSONB: `[{ "name": "...", "amount": 1, "unit": "l", "category": "dairy", "checked": false, "manual": false }]`.

---

## 9. API-дизайн (ключевые эндпоинты)

### Авторизация

| Метод | Путь | Описание |
|-------|------|----------|
| POST | `/auth/login` | Firebase token → JWT |
| POST | `/auth/refresh` | Обновить JWT |
| POST | `/auth/logout` | Инвалидировать refresh token |

### Продукты

| Метод | Путь | Описание |
|-------|------|----------|
| GET | `/products` | Список продуктов (фильтры: category, expiring) |
| POST | `/products` | Добавить продукт вручную |
| POST | `/products/batch` | Массовое добавление (после распознавания) |
| PUT | `/products/{id}` | Обновить (вес, количество, срок) |
| PATCH | `/products/{id}/consume` | Частичное использование |
| DELETE | `/products/{id}` | Удалить |
| DELETE | `/products` | Очистить все (с подтверждением в query param) |
| GET | `/products/storage-defaults` | Дефолтные сроки хранения по категориям |
| PUT | `/products/storage-defaults` | Обновить дефолтные сроки |

### AI-операции

| Метод | Путь | Описание |
|-------|------|----------|
| POST | `/ai/recognize-receipt` | Фото чека → список продуктов |
| POST | `/ai/recognize-products` | Фото продуктов → список |
| POST | `/ai/recognize-dish` | Фото блюда → калории, БЖУ |
| POST | `/ai/suggest-recipes` | Подбор рецептов из продуктов |
| POST | `/ai/generate-menu` | Генерация меню на период |
| POST | `/ai/substitute` | Замена ингредиента |
| GET | `/ai/tasks/{id}` | Статус AI-задачи (для polling) |

Все `/ai/*` эндпоинты возвращают `{ task_id }` (HTTP 202 Accepted). Клиент получает результат через polling `/ai/tasks/{id}` или через WebSocket (будущее улучшение). Это позволяет обрабатывать запросы асинхронно через очереди.

### Рекомендации

| Метод | Путь | Описание |
|-------|------|----------|
| GET | `/recommendations?count=5` | Персональные рекомендации (Gemini + Pexels) |

### Сохранённые рецепты

| Метод | Путь | Описание |
|-------|------|----------|
| GET | `/saved-recipes` | Список сохранённых рецептов |
| POST | `/saved-recipes` | Сохранить рецепт |
| GET | `/saved-recipes/{id}` | Карточка сохранённого рецепта |
| DELETE | `/saved-recipes/{id}` | Удалить из сохранённых |

### Меню

| Метод | Путь | Описание |
|-------|------|----------|
| GET | `/menu?week=2026-W08` | Меню на неделю |
| PUT | `/menu/items/{id}` | Обновить слот меню |
| POST | `/menu/items` | Добавить блюдо в слот |
| DELETE | `/menu/items/{id}` | Убрать блюдо |
| POST | `/menu/templates` | Сохранить как шаблон |
| GET | `/menu/templates` | Список шаблонов |
| POST | `/menu/from-template/{id}` | Применить шаблон |

### Дневник питания

| Метод | Путь | Описание |
|-------|------|----------|
| GET | `/diary?date=2026-02-15` | Записи за день |
| POST | `/diary` | Добавить запись |
| PUT | `/diary/{id}` | Изменить (порция, и т.д.) |
| DELETE | `/diary/{id}` | Удалить запись |

### Список покупок

| Метод | Путь | Описание |
|-------|------|----------|
| GET | `/shopping-list` | Текущий список |
| POST | `/shopping-list/generate` | Сгенерировать из меню |
| PUT | `/shopping-list/items/{index}` | Обновить позицию |
| PATCH | `/shopping-list/items/{index}/check` | Отметить купленным |
| POST | `/shopping-list/items` | Добавить вручную |

### Статистика

| Метод | Путь | Описание |
|-------|------|----------|
| GET | `/stats?period=week` | Статистика за период |
| GET | `/stats/water?date=2026-02-15` | Трекер воды |
| PUT | `/stats/water` | Обновить стаканы |

### Профиль

| Метод | Путь | Описание |
|-------|------|----------|
| GET | `/profile` | Данные профиля |
| PUT | `/profile` | Обновить |
| PUT | `/profile/preferences` | Обновить предпочтения кухонь |
| PUT | `/profile/restrictions` | Обновить ограничения |

---

## 10. Оценка затрат

### Стоимость по стадиям (в месяц)

| Компонент | 1K MAU | 10K MAU | 50K MAU |
|-----------|--------|---------|---------|
| Firebase Auth | $0 | $0 | $0 (лимит 50K) |
| Gemini API | $50–150 | $500–1 500 | $2 500–7 500 |
| Pexels API | $0 | $0 | $0 (Free tier) |
| Хостинг (Cloud Run / Fly.io) | $10–20 | $50–100 | $200–500 |
| PostgreSQL (managed) | $15 | $50 | $150–300 |
| S3 (фото) | $5 | $20 | $50–100 |
| **Итого** | **$80–190** | **$620–1 670** | **$2 900–8 400** |

### Оптимизация затрат на AI

- **Кеширование результатов:** замены ингредиентов, распознавание типовых блюд.
- **Batch-запросы:** при генерации меню на неделю — один запрос вместо семи.
- **Снижение detail для фото:** Gemini поддерживает `low` / `high` detail. Для чеков `high`, для фото продуктов `low` достаточно.
- **Мониторинг:** дашборд затрат по `ai_tasks` — какие задачи дорогие, где можно оптимизировать промпты.