# API Документация: Маркетинговый анализ и стратегии (Frontend/AI Agent)

## Базовый URL

```
https://api.konturai.kz
```

## Обзор

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

**Важные изменения:**

- ✅ Все эндпоинты теперь требуют JWT токен в заголовке `Authorization`
- ✅ Пользователи могут видеть только свои анализы и стратегии
- ✅ Добавлена детальная история статусов для каждого анализа и стратегии
- ✅ Новые эндпоинты для получения списка всех анализов/стратегий пользователя
- ✅ **НОВОЕ**: Добавлена поддержка типов анализов (РЫНОК, КОНКУРЕНТЫ, ЦА, КАНАЛЫ, SWOT)

---

## Аутентификация

Все запросы должны включать JWT токен в заголовке `Authorization`:

```
Authorization: Bearer <your_jwt_token>
```

### Структура JWT токена

JWT токен содержит следующую информацию:

- **sub**: Email пользователя
- **uid**: ID пользователя (Long) - используется для связи данных
- **roles**: Роли пользователя (String, разделённые запятыми)

### Ошибки аутентификации

Если токен отсутствует или невалиден, API вернет:

```json
{
  "success": false,
  "message": "Не авторизован",
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Требуется аутентификация. Пожалуйста, предоставьте валидный JWT токен."
  }
}
```

**HTTP статус**: `401 Unauthorized`

---

## Эндпоинты

### 1. Запуск маркетингового анализа

**POST** `/api/marketing/analysis/start`

Создает новую задачу на генерацию маркетингового анализа и запускает асинхронную обработку. Анализ автоматически связывается с пользователем из JWT токена.

#### Заголовки запроса

```
Content-Type: application/json
Authorization: Bearer <your_jwt_token>
```

#### Тело запроса (JSON)

| Поле             | Тип    | Обязательный | Описание                       | Пример значения                  |
| ---------------- | ------ | ------------ | ------------------------------ | -------------------------------- |
| `product`        | string | ✅           | Название продукта или услуги   | "Веб-разработка"                 |
| `location`       | string | ✅           | Географическая локация работы  | "Алматы, Казахстан"              |
| `client`         | string | ✅           | Тип целевой аудитории          | "B2B клиенты"                    |
| `differentiator` | string | ✅           | Уникальные особенности бизнеса | "Быстрая разработка за 2 недели" |
| `analysisType`   | string | ✅           | Тип анализа для генерации      | "РЫНОК"                          |

#### Валидация полей

**`product`** (string, обязательное)

- Минимальная длина: 3 символа
- Максимальная длина: 200 символов

**`location`** (string, обязательное)

- Минимальная длина: 2 символа
- Максимальная длина: 150 символов

**`client`** (string, обязательное)

- Допустимые значения:
  - `"B2B клиенты"`
  - `"B2C клиенты"`
  - `"Частные лица"`
  - `"Корпорации"`
  - `"Малый бизнес"`

**`differentiator`** (string, обязательное)

- Минимальная длина: 10 символов
- Максимальная длина: 500 символов

**`analysisType`** (string, обязательное)

- Допустимые значения (регистр не важен, но рекомендуется использовать заглавные буквы):
  - `"РЫНОК"` - Анализ рынка (размер рынка, динамика роста, сегменты, тренды)
  - `"КОНКУРЕНТЫ"` - Анализ конкурентов (основные конкуренты, их сильные/слабые стороны, позиционирование)
  - `"ЦА"` - Анализ целевой аудитории (демография, психография, потребности, поведение)
  - `"КАНАЛЫ"` - Анализ маркетинговых каналов (эффективность каналов, рекомендации по выбору)
  - `"SWOT"` - SWOT-анализ (сильные стороны, слабые стороны, возможности, угрозы)

#### Пример запроса

```javascript
const response = await fetch(
  'https://api.konturai.kz/api/marketing/analysis/start',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${jwtToken}`,
    },
    body: JSON.stringify({
      product: 'Разработка мобильных приложений',
      location: 'Нур-Султан, Казахстан',
      client: 'B2B клиенты',
      differentiator: 'Специализируемся на быстрой разработке MVP за 4 недели',
      analysisType: 'РЫНОК',
    }),
  }
);
```

#### Пример успешного ответа (200 OK)

```json
{
  "success": true,
  "message": "Анализ запущен успешно",
  "data": {
    "analysisId": "507f1f77bcf86cd799439011",
    "status": "processing",
    "estimatedCompletionTime": "2025-01-20T15:38:00",
    "message": "Анализ запущен успешно. Результаты будут готовы в течение 5-10 минут."
  }
}
```

---

### 2. Получение результата анализа

**GET** `/api/marketing/analysis/{analysisId}`

Возвращает статус и результаты анализа по идентификатору. Пользователь может получить только свои анализы.

#### Заголовки запроса

```
Authorization: Bearer <your_jwt_token>
```

#### Параметры пути

| Параметр     | Тип    | Описание              |
| ------------ | ------ | --------------------- |
| `analysisId` | string | Идентификатор анализа |

#### Пример запроса

```javascript
const response = await fetch(
  `https://api.konturai.kz/api/marketing/analysis/${analysisId}`,
  {
    headers: {
      Authorization: `Bearer ${jwtToken}`,
    },
  }
);
```

#### Пример ответа (когда анализ завершен - 200 OK)

```json
{
  "success": true,
  "message": "Операция выполнена успешно",
  "data": {
    "analysisId": "507f1f77bcf86cd799439011",
    "status": "completed",
    "createdAt": "2025-01-20T15:30:00",
    "completedAt": "2025-01-20T15:38:00",
    "report": {
      "summary": "Краткое резюме анализа...",
      "targetAudience": {
        "description": "Описание целевой аудитории...",
        "channels": ["Instagram", "LinkedIn", "Telegram"]
      },
      "recommendations": ["Рекомендация 1", "Рекомендация 2"],
      "strategy": {
        "duration": "2 недели",
        "channels": ["Instagram", "Telegram", "21MC"],
        "contentTypes": ["посты", "сторис", "баннеры"]
      },
      "pdfUrl": "/api/marketing/analysis/507f1f77bcf86cd799439011/download"
    }
  }
}
```

#### Статусы анализа

| Статус       | Описание                      |
| ------------ | ----------------------------- |
| `queued`     | Запрос в очереди на обработку |
| `processing` | Анализ выполняется            |
| `completed`  | Анализ завершен успешно       |
| `failed`     | Анализ завершился с ошибкой   |

#### Ошибки доступа

Если пользователь пытается получить доступ к анализу другого пользователя:

```json
{
  "success": false,
  "message": "Доступ запрещен",
  "error": {
    "code": "FORBIDDEN",
    "message": "У вас нет доступа к этому анализу"
  }
}
```

**HTTP статус**: `403 Forbidden`

---

### 3. Получение списка всех анализов пользователя

**GET** `/api/marketing/analysis/my`

Возвращает список всех анализов текущего пользователя, отсортированных по дате создания (новые первыми).

#### Заголовки запроса

```
Authorization: Bearer <your_jwt_token>
```

#### Пример запроса

```javascript
const response = await fetch(
  'https://api.konturai.kz/api/marketing/analysis/my',
  {
    headers: {
      Authorization: `Bearer ${jwtToken}`,
    },
  }
);
```

#### Пример успешного ответа (200 OK)

```json
{
  "success": true,
  "message": "Операция выполнена успешно",
  "data": [
    {
      "analysisId": "507f1f77bcf86cd799439011",
      "product": "Разработка мобильных приложений",
      "location": "Нур-Султан, Казахстан",
      "clientType": "B2B клиенты",
      "differentiator": "Быстрая разработка MVP за 4 недели",
      "status": "completed",
      "userId": "12345",
      "createdAt": "2025-01-20T15:30:00",
      "completedAt": "2025-01-20T15:38:00",
      "statusHistory": [
        {
          "status": "queued",
          "timestamp": "2025-01-20T15:30:00",
          "message": "Анализ создан и добавлен в очередь"
        },
        {
          "status": "processing",
          "timestamp": "2025-01-20T15:30:05",
          "message": "Начата обработка анализа"
        },
        {
          "status": "completed",
          "timestamp": "2025-01-20T15:38:00",
          "message": "Анализ успешно завершен"
        }
      ]
    },
    {
      "analysisId": "507f1f77bcf86cd799439012",
      "product": "Веб-разработка",
      "location": "Алматы, Казахстан",
      "clientType": "B2C клиенты",
      "differentiator": "Современные технологии",
      "status": "processing",
      "userId": "12345",
      "createdAt": "2025-01-20T14:00:00",
      "completedAt": null,
      "statusHistory": [
        {
          "status": "queued",
          "timestamp": "2025-01-20T14:00:00",
          "message": "Анализ создан и добавлен в очередь"
        },
        {
          "status": "processing",
          "timestamp": "2025-01-20T14:00:05",
          "message": "Начата обработка анализа"
        }
      ]
    }
  ]
}
```

#### Структура ответа

| Поле                               | Тип    | Описание                                               |
| ---------------------------------- | ------ | ------------------------------------------------------ |
| `data[].analysisId`                | string | Уникальный идентификатор анализа                       |
| `data[].product`                   | string | Название продукта или услуги                           |
| `data[].location`                  | string | Географическая локация                                 |
| `data[].clientType`                | string | Тип целевой аудитории                                  |
| `data[].differentiator`            | string | Уникальные особенности бизнеса                         |
| `data[].status`                    | string | Текущий статус анализа                                 |
| `data[].userId`                    | string | ID пользователя (из JWT)                               |
| `data[].createdAt`                 | string | ISO 8601 дата/время создания                           |
| `data[].completedAt`               | string | ISO 8601 дата/время завершения (null если не завершен) |
| `data[].statusHistory`             | array  | Детальная история изменений статуса                    |
| `data[].statusHistory[].status`    | string | Статус на момент изменения                             |
| `data[].statusHistory[].timestamp` | string | ISO 8601 дата/время изменения статуса                  |
| `data[].statusHistory[].message`   | string | Описание изменения статуса                             |

---

### 4. Получение детальной истории анализа

**GET** `/api/marketing/analysis/{analysisId}/history`

Возвращает детальную информацию об анализе, включая полную историю изменений статуса.

#### Заголовки запроса

```
Authorization: Bearer <your_jwt_token>
```

#### Параметры пути

| Параметр     | Тип    | Описание              |
| ------------ | ------ | --------------------- |
| `analysisId` | string | Идентификатор анализа |

#### Пример запроса

```javascript
const response = await fetch(
  `https://api.konturai.kz/api/marketing/analysis/${analysisId}/history`,
  {
    headers: {
      Authorization: `Bearer ${jwtToken}`,
    },
  }
);
```

#### Пример успешного ответа (200 OK)

```json
{
  "success": true,
  "message": "Операция выполнена успешно",
  "data": {
    "analysisId": "507f1f77bcf86cd799439011",
    "product": "Разработка мобильных приложений",
    "location": "Нур-Султан, Казахстан",
    "clientType": "B2B клиенты",
    "differentiator": "Быстрая разработка MVP за 4 недели",
    "status": "completed",
    "userId": "12345",
    "createdAt": "2025-01-20T15:30:00",
    "completedAt": "2025-01-20T15:38:00",
    "statusHistory": [
      {
        "status": "queued",
        "timestamp": "2025-01-20T15:30:00",
        "message": "Анализ создан и добавлен в очередь"
      },
      {
        "status": "processing",
        "timestamp": "2025-01-20T15:30:05",
        "message": "Начата обработка анализа"
      },
      {
        "status": "completed",
        "timestamp": "2025-01-20T15:38:00",
        "message": "Анализ успешно завершен"
      }
    ]
  }
}
```

---

### 5. Скачивание PDF отчета

**GET** `/api/marketing/analysis/{analysisId}/download`

Возвращает PDF файл с полным маркетинговым отчетом. Пользователь может скачать только свои отчеты.

#### Заголовки запроса

```
Authorization: Bearer <your_jwt_token>
```

#### Параметры пути

| Параметр     | Тип    | Описание              |
| ------------ | ------ | --------------------- |
| `analysisId` | string | Идентификатор анализа |

#### Пример запроса

```javascript
const response = await fetch(
  `https://api.konturai.kz/api/marketing/analysis/${analysisId}/download`,
  {
    headers: {
      Authorization: `Bearer ${jwtToken}`,
    },
  }
);

if (response.ok) {
  const blob = await response.blob();
  const url = window.URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = `marketing_analysis_${analysisId}.pdf`;
  a.click();
}
```

#### Успешный ответ (200 OK)

- **Content-Type**: `application/pdf`
- **Content-Disposition**: `attachment; filename="marketing_analysis_{analysisId}_{timestamp}.pdf"`
- **Body**: Бинарные данные PDF файла

---

### 6. Генерация маркетинговой стратегии

**POST** `/api/marketing/analysis/strategy/generate`

Создает маркетинговую стратегию на основе завершенного анализа. Стратегия автоматически связывается с пользователем из JWT токена.

#### Заголовки запроса

```
Content-Type: application/json
Authorization: Bearer <your_jwt_token>
```

#### Параметры запроса

| Параметр            | Тип     | Обязательный | Описание                                      |
| ------------------- | ------- | ------------ | --------------------------------------------- |
| `analysisId`        | string  | ✅           | ID завершенного анализа (query parameter)     |
| `durationWeeks`     | integer | ❌           | Длительность стратегии в неделях (default: 4) |
| `priorityPlatforms` | array   | ❌           | Приоритетные платформы (массив строк)         |

#### Тело запроса (JSON, опционально)

```json
{
  "durationWeeks": 4,
  "priorityPlatforms": ["Instagram", "LinkedIn", "Telegram"]
}
```

#### Пример запроса

```javascript
const response = await fetch(
  `https://api.konturai.kz/api/marketing/analysis/strategy/generate?analysisId=${analysisId}`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${jwtToken}`,
    },
    body: JSON.stringify({
      durationWeeks: 4,
      priorityPlatforms: ['Instagram', 'LinkedIn', 'Telegram'],
    }),
  }
);
```

#### Пример успешного ответа (200 OK)

```json
{
  "success": true,
  "message": "Генерация стратегии запущена успешно. Результаты будут готовы в течение 3-5 минут.",
  "data": {
    "strategyId": "507f1f77bcf86cd799439020",
    "analysisId": "507f1f77bcf86cd799439011",
    "status": "queued",
    "createdAt": "2025-01-20T15:40:00",
    "completedAt": null,
    "durationWeeks": 4,
    "priorityPlatforms": ["Instagram", "LinkedIn", "Telegram"]
  }
}
```

---

### 7. Получение результата стратегии

**GET** `/api/marketing/analysis/strategy/{strategyId}`

Возвращает статус и результаты стратегии. Пользователь может получить только свои стратегии.

#### Заголовки запроса

```
Authorization: Bearer <your_jwt_token>
```

#### Параметры пути

| Параметр     | Тип    | Описание                |
| ------------ | ------ | ----------------------- |
| `strategyId` | string | Идентификатор стратегии |

#### Пример ответа (когда стратегия завершена - 200 OK)

```json
{
  "success": true,
  "message": "Операция выполнена успешно",
  "data": {
    "strategyId": "507f1f77bcf86cd799439020",
    "analysisId": "507f1f77bcf86cd799439011",
    "status": "completed",
    "createdAt": "2025-01-20T15:40:00",
    "completedAt": "2025-01-20T15:43:00",
    "durationWeeks": 4,
    "priorityPlatforms": ["Instagram", "LinkedIn", "Telegram"],
    "strategy": {
      "weeklyPlans": [
        {
          "weekNumber": 1,
          "mainThemes": ["Презентация продукта", "Преимущества"],
          "contentRecommendations": "Создавайте контент, который демонстрирует ценность продукта",
          "priorityPlatforms": ["Instagram", "LinkedIn"]
        }
      ],
      "postCalendar": [
        {
          "publishDate": "2025-01-21T10:00:00",
          "platform": "Instagram",
          "contentType": "пост",
          "theme": "Презентация продукта",
          "postText": "Полный текст поста для публикации...",
          "hashtags": ["#маркетинг", "#бизнес"],
          "publishTime": "10:00"
        }
      ]
    }
  }
}
```

---

### 8. Получение стратегии по ID анализа

**GET** `/api/marketing/analysis/{analysisId}/strategy`

Возвращает стратегию, связанную с указанным анализом. Пользователь может получить только стратегии для своих анализов.

#### Заголовки запроса

```
Authorization: Bearer <your_jwt_token>
```

#### Параметры пути

| Параметр     | Тип    | Описание              |
| ------------ | ------ | --------------------- |
| `analysisId` | string | Идентификатор анализа |

---

### 9. Получение списка всех стратегий пользователя

**GET** `/api/marketing/analysis/strategy/my`

Возвращает список всех стратегий текущего пользователя, отсортированных по дате создания (новые первыми).

#### Заголовки запроса

```
Authorization: Bearer <your_jwt_token>
```

#### Пример успешного ответа (200 OK)

```json
{
  "success": true,
  "message": "Операция выполнена успешно",
  "data": [
    {
      "strategyId": "507f1f77bcf86cd799439020",
      "analysisId": "507f1f77bcf86cd799439011",
      "status": "completed",
      "userId": "12345",
      "durationWeeks": 4,
      "priorityPlatforms": ["Instagram", "LinkedIn", "Telegram"],
      "createdAt": "2025-01-20T15:40:00",
      "completedAt": "2025-01-20T15:43:00",
      "statusHistory": [
        {
          "status": "queued",
          "timestamp": "2025-01-20T15:40:00",
          "message": "Стратегия создана и добавлена в очередь"
        },
        {
          "status": "processing",
          "timestamp": "2025-01-20T15:40:05",
          "message": "Начата генерация стратегии"
        },
        {
          "status": "completed",
          "timestamp": "2025-01-20T15:43:00",
          "message": "Стратегия успешно сгенерирована"
        }
      ]
    }
  ]
}
```

---

### 10. Получение детальной истории стратегии

**GET** `/api/marketing/analysis/strategy/{strategyId}/history`

Возвращает детальную информацию о стратегии, включая полную историю изменений статуса.

#### Заголовки запроса

```
Authorization: Bearer <your_jwt_token>
```

#### Параметры пути

| Параметр     | Тип    | Описание                |
| ------------ | ------ | ----------------------- |
| `strategyId` | string | Идентификатор стратегии |

#### Пример успешного ответа (200 OK)

```json
{
  "success": true,
  "message": "Операция выполнена успешно",
  "data": {
    "strategyId": "507f1f77bcf86cd799439020",
    "analysisId": "507f1f77bcf86cd799439011",
    "status": "completed",
    "userId": "12345",
    "durationWeeks": 4,
    "priorityPlatforms": ["Instagram", "LinkedIn", "Telegram"],
    "createdAt": "2025-01-20T15:40:00",
    "completedAt": "2025-01-20T15:43:00",
    "statusHistory": [
      {
        "status": "queued",
        "timestamp": "2025-01-20T15:40:00",
        "message": "Стратегия создана и добавлена в очередь"
      },
      {
        "status": "processing",
        "timestamp": "2025-01-20T15:40:05",
        "message": "Начата генерация стратегии"
      },
      {
        "status": "completed",
        "timestamp": "2025-01-20T15:43:00",
        "message": "Стратегия успешно сгенерирована"
      }
    ]
  }
}
```

---

## Обработка ошибок

### Коды ошибок

| Код                      | HTTP статус | Описание                        |
| ------------------------ | ----------- | ------------------------------- |
| `UNAUTHORIZED`           | 401         | Требуется аутентификация        |
| `FORBIDDEN`              | 403         | Нет доступа к ресурсу           |
| `VALIDATION_ERROR`       | 400         | Ошибка валидации входных данных |
| `NOT_FOUND`              | 404         | Ресурс не найден                |
| `INVALID_ANALYSIS`       | 404         | Анализ не найден                |
| `ANALYSIS_NOT_COMPLETED` | 400         | Анализ еще не завершен          |
| `INTERNAL_SERVER_ERROR`  | 500         | Внутренняя ошибка сервера       |

### Формат ошибки

```json
{
  "success": false,
  "message": "Описание ошибки",
  "error": {
    "code": "ERROR_CODE",
    "message": "Детальное сообщение об ошибке",
    "details": {
      "field1": "Сообщение об ошибке для поля 1"
    }
  }
}
```

---

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

### JavaScript/TypeScript (Fetch API)

#### Получение JWT токена

```javascript
// Предполагается, что токен получен при логине
const jwtToken = localStorage.getItem('jwtToken');
```

#### Запуск анализа с JWT

```javascript
async function startMarketingAnalysis(data, jwtToken) {
  const response = await fetch(
    'https://api.konturai.kz/api/marketing/analysis/start',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${jwtToken}`,
      },
      body: JSON.stringify(data),
    }
  );

  if (!response.ok) {
    if (response.status === 401) {
      throw new Error('Требуется аутентификация');
    }
    const error = await response.json();
    throw new Error(error.error?.message || 'Ошибка при запуске анализа');
  }

  const result = await response.json();
  return result.data.analysisId;
}
```

#### Получение списка всех анализов пользователя

```javascript
async function getMyAnalyses(jwtToken) {
  const response = await fetch(
    'https://api.konturai.kz/api/marketing/analysis/my',
    {
      headers: {
        Authorization: `Bearer ${jwtToken}`,
      },
    }
  );

  if (!response.ok) {
    throw new Error('Ошибка при получении списка анализов');
  }

  const result = await response.json();
  return result.data; // Массив анализов
}
```

#### Получение детальной истории анализа

```javascript
async function getAnalysisHistory(analysisId, jwtToken) {
  const response = await fetch(
    `https://api.konturai.kz/api/marketing/analysis/${analysisId}/history`,
    {
      headers: {
        Authorization: `Bearer ${jwtToken}`,
      },
    }
  );

  if (!response.ok) {
    if (response.status === 403) {
      throw new Error('Нет доступа к этому анализу');
    }
    throw new Error('Ошибка при получении истории');
  }

  const result = await response.json();
  return result.data;
}
```

#### Полный пример: создание анализа и отслеживание статуса

```javascript
async function createAndTrackAnalysis(
  product,
  location,
  client,
  differentiator,
  jwtToken
) {
  try {
    // 1. Запускаем анализ
    const analysisId = await startMarketingAnalysis(
      {
        product,
        location,
        client,
        differentiator,
      },
      jwtToken
    );

    console.log(`Анализ запущен: ${analysisId}`);

    // 2. Получаем историю для отслеживания статуса
    const checkStatus = async () => {
      const history = await getAnalysisHistory(analysisId, jwtToken);

      // Показываем последний статус
      const lastStatus =
        history.statusHistory[history.statusHistory.length - 1];
      console.log(`Статус: ${lastStatus.status} - ${lastStatus.message}`);

      return history.status;
    };

    // 3. Polling: проверяем статус каждые 10 секунд
    const pollInterval = setInterval(async () => {
      const status = await checkStatus();

      if (status === 'completed') {
        clearInterval(pollInterval);
        console.log('Анализ завершен!');
        // Получаем полный результат
        const fullResult = await getAnalysisResult(analysisId, jwtToken);
        return fullResult;
      } else if (status === 'failed') {
        clearInterval(pollInterval);
        throw new Error('Анализ завершился с ошибкой');
      }
    }, 10000);

    // Останавливаем polling через 15 минут
    setTimeout(() => {
      clearInterval(pollInterval);
      console.log('Превышено время ожидания');
    }, 15 * 60 * 1000);
  } catch (error) {
    console.error('Ошибка:', error);
    throw error;
  }
}
```

#### Получение списка стратегий пользователя

```javascript
async function getMyStrategies(jwtToken) {
  const response = await fetch(
    'https://api.konturai.kz/api/marketing/analysis/strategy/my',
    {
      headers: {
        Authorization: `Bearer ${jwtToken}`,
      },
    }
  );

  if (!response.ok) {
    throw new Error('Ошибка при получении списка стратегий');
  }

  const result = await response.json();
  return result.data; // Массив стратегий
}
```

---

## Рекомендации по интеграции

### 1. Обработка JWT токена

- Сохраняйте токен в безопасном месте (например, `localStorage` или `sessionStorage`)
- Проверяйте срок действия токена перед запросами
- Реализуйте механизм обновления токена при истечении

### 2. Обработка ошибок аутентификации

При получении `401 Unauthorized`:

- Перенаправляйте пользователя на страницу входа
- Очищайте сохраненный токен
- Показывайте понятное сообщение пользователю

### 3. Обработка ошибок доступа

При получении `403 Forbidden`:

- Показывайте сообщение о том, что ресурс недоступен
- Не пытайтесь повторять запрос с теми же параметрами

### 4. Polling стратегия

Для отслеживания статуса анализа/стратегии:

- Используйте интервал 10-15 секунд
- Максимальное время ожидания: 15 минут
- Показывайте прогресс пользователю на основе `statusHistory`

### 5. Отображение истории статусов

Используйте `statusHistory` для:

- Показывать временную шкалу изменений статуса
- Отображать детальную информацию о каждом этапе
- Информировать пользователя о прогрессе

### 6. Кэширование

- Кэшируйте список анализов/стратегий пользователя
- Обновляйте кэш при создании новых записей
- Используйте `analysisId`/`strategyId` как ключи кэша

---

## Примечания

1. **Формат даты**: Все даты возвращаются в формате ISO 8601 без timezone (LocalDateTime)
2. **Идентификаторы**: Используются MongoDB ObjectId (24 символа hex)
3. **Асинхронность**: Анализ и стратегия выполняются асинхронно
4. **Безопасность**: Все эндпоинты требуют валидный JWT токен
5. **Изоляция данных**: Пользователи видят только свои данные
6. **История статусов**: Детальная история доступна для всех анализов и стратегий

---

## Изменения: Поддержка типов анализов

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

В API добавлена поддержка различных типов маркетинговых анализов. Теперь при создании анализа можно указать тип анализа, который определяет фокус и содержание генерируемого отчета.

### Новое поле в запросе

**Поле**: `analysisType` (обязательное)

**Тип**: `string`

**Допустимые значения**:

- `"РЫНОК"` - Анализ рынка
- `"КОНКУРЕНТЫ"` - Анализ конкурентов
- `"ЦА"` - Анализ целевой аудитории
- `"КАНАЛЫ"` - Анализ маркетинговых каналов
- `"SWOT"` - SWOT-анализ

### Описание типов анализов

#### 1. РЫНОК

Генерирует анализ рынка, включающий:

- Размер рынка
- Динамику роста
- Основные сегменты
- Тренды и перспективы развития

#### 2. КОНКУРЕНТЫ

Генерирует анализ конкурентов, включающий:

- Основных конкурентов
- Их сильные и слабые стороны
- Позиционирование
- Ценовую политику
- Маркетинговые стратегии

#### 3. ЦА (Целевая аудитория)

Генерирует анализ целевой аудитории, включающий:

- Демографические характеристики
- Психографический профиль
- Потребности и боли
- Поведенческие паттерны
- Предпочтения

#### 4. КАНАЛЫ

Генерирует анализ маркетинговых каналов, включающий:

- Оценку эффективности различных каналов коммуникации
- Рекомендации по выбору каналов
- Особенности использования каждого канала
- Бюджетные рекомендации

#### 5. SWOT

Генерирует SWOT-анализ, включающий:

- Сильные стороны (Strengths)
- Слабые стороны (Weaknesses)
- Возможности (Opportunities)
- Угрозы (Threats)

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

В ответе анализа теперь присутствует поле `analysisType` в объекте `reportData`, которое содержит название типа анализа.

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

```javascript
// Запрос на создание SWOT-анализа
const response = await fetch(
  'https://api.konturai.kz/api/marketing/analysis/start',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${jwtToken}`,
    },
    body: JSON.stringify({
      product: 'Разработка мобильных приложений',
      location: 'Нур-Султан, Казахстан',
      client: 'B2B клиенты',
      differentiator: 'Специализируемся на быстрой разработке MVP за 4 недели',
      analysisType: 'SWOT', // Указываем тип анализа
    }),
  }
);
```

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

1. **UI для выбора типа анализа**: Добавьте выпадающий список или радиокнопки для выбора типа анализа перед отправкой запроса.

2. **Валидация на фронтенде**: Убедитесь, что отправляется только один из допустимых значений.

3. **Отображение типа анализа**: При показе результатов анализа отображайте тип анализа для контекста.

4. **Обратная совместимость**: Если поле `analysisType` не указано, API вернет ошибку валидации. Это обязательное поле.

### Миграция существующих интеграций

Если у вас есть существующие интеграции, которые не используют поле `analysisType`, необходимо:

1. Добавить поле `analysisType` в запрос
2. Выбрать подходящий тип анализа по умолчанию или позволить пользователю выбрать
3. Обновить UI для отображения выбора типа анализа

---

## Поддержка

При возникновении проблем с API обращайтесь в техническую поддержку с указанием:

- `analysisId` или `strategyId` (если есть)
- Время запроса
- Описание проблемы
- Код ошибки (если есть)
- JWT токен (только для отладки, не в продакшене!)