marketing/docs/FRONTEND_API_CHANGES_V2.md

# Изменения в API: Интеграция v2 анализа

## Обзор изменений

Добавлена возможность опционального создания и сохранения v2 анализа вместе с обычным анализом. Все v2 анализы сохраняются в MongoDB и доступны через новые эндпойнты.

---

## 1. POST `/api/marketing/analysis/start` - Обновлен

### Новый query параметр:

-   **`generateV2`** (boolean, опционально, по умолчанию `false`)
    -   Если `true`, вместе с обычным анализом создается и сохраняется v2 анализ
    -   Оба анализа автоматически связываются между собой

### Изменения в ответе:

**Если `generateV2=false` (по умолчанию):**

```json
{
    "success": true,
    "message": "Анализ запущен успешно",
    "data": {
        "analysisId": "string",
        "status": "processing",
        "estimatedCompletionTime": "2024-01-01T12:00:00",
        "message": "Комплексный анализ (...) запущен успешно..."
    }
}
```

**Если `generateV2=true`:**

```json
{
    "success": true,
    "message": "Анализ запущен успешно",
    "data": {
        "analysisId": "string",
        "status": "processing",
        "estimatedCompletionTime": "2024-01-01T12:00:00",
        "message": "Комплексный анализ (...) запущен успешно...",
        "v2AnalysisId": "string" // ← НОВОЕ ПОЛЕ
    }
}
```

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

```javascript
// Создание обычного анализа
POST /api/marketing/analysis/start
Body: { ... }

// Создание обычного анализа + v2 анализа
POST /api/marketing/analysis/start?generateV2=true
Body: { ... }
```

---

## 2. GET `/api/marketing/analysis/my` - Обновлен

### Новое поле в ответе:

Каждый элемент в списке теперь содержит опциональное поле `v2AnalysisId`:

```json
{
    "success": true,
    "data": [
        {
            "analysisId": "string",
            "businessNiche": "string",
            "product": "string",
            // ... другие поля ...
            "v2AnalysisId": "string" // ← НОВОЕ ПОЛЕ (может быть null)
        }
    ]
}
```

**Примечание:** Поле `v2AnalysisId` будет присутствовать только если для данного анализа был создан связанный v2 анализ.

---

## 3. GET `/api/marketing/analysis/{id}` - Обновлен

### Новое поле в ответе:

Эндпойнт теперь возвращает опциональное поле `v2AnalysisId`:

```json
{
  "success": true,
  "data": {
    "analysisId": "string",
    "status": "string",
    "createdAt": "2024-01-01T12:00:00",
    "completedAt": "2024-01-01T12:00:00",
    "v2AnalysisId": "string",  // ← НОВОЕ ПОЛЕ (может быть null)
    "report": { ... }
  }
}
```

**Примечание:** Поле `v2AnalysisId` будет присутствовать только если для данного анализа был создан связанный v2 анализ.

---

## 4. GET `/api/marketing/analysis/v2/{id}` - Новый эндпойнт

### Описание:

Получение сохраненного v2 анализа по ID.

### Параметры:

-   **Path:** `id` (string) - ID v2 анализа
-   **Header:** `Authorization` (JWT токен)

### Ответ:

**Успешный ответ (200):**

```json
{
  "success": true,
  "data": {
    "reportTitle": "string",
    "sections": {
      "marketOverview": { ... },
      "targetAudience": { ... },
      "competitiveEnvironment": { ... },
      // ... другие секции ...
    }
  }
}
```

**Ошибки:**

-   `401` - Не авторизован
-   `404` - Анализ не найден
-   `403` - Нет доступа к этому анализу

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

```javascript
GET /api/marketing/analysis/v2/507f1f77bcf86cd799439011
Authorization: Bearer <token>
```

---

## 5. POST `/api/marketing/analysis/start/v2` - Без изменений

Эндпойнт работает как прежде - создает только v2 анализ без связи с обычным анализом.

---

## Рекомендации для фронтенда

1. **При создании анализа:**

    - Используйте `generateV2=true` если нужен v2 анализ сразу
    - Сохраняйте `v2AnalysisId` из ответа для последующего доступа

2. **При отображении списка анализов:**

    - Проверяйте наличие поля `v2AnalysisId`
    - Если поле присутствует, можно показать кнопку/ссылку для просмотра v2 анализа

3. **При получении конкретного анализа:**

    - Поле `v2AnalysisId` доступно в ответе `GET /api/marketing/analysis/{id}`
    - Используйте это поле для навигации к v2 анализу

4. **При получении v2 анализа:**
    - Используйте `GET /api/marketing/analysis/v2/{id}` для получения полных данных
    - Обрабатывайте случаи, когда v2 анализ может быть не найден (404)

---

## Обратная совместимость

✅ Все изменения обратно совместимы:

-   Существующие запросы без `generateV2` работают как прежде
-   Поле `v2AnalysisId` опционально и не ломает существующий код
-   Новые эндпойнты не влияют на старую функциональность