.

2026-01-03 13:26:31 +05:00
parent e186e36a74
commit 606f5af28d
12 changed files with 2768 additions and 517 deletions
@@ -0,0 +1,193 @@
+# Изменения в 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` опционально и не ломает существующий код
+-   Новые эндпойнты не влияют на старую функциональность