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 (по умолчанию):

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

Если generateV2=true:

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

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

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

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

---

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

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

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

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

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

---

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

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

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

{
  "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):

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

Ошибки:

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

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

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 опционально и не ломает существующий код
• Новые эндпойнты не влияют на старую функциональность