# Обновление API: Виды анализа для маркетингового анализа (Frontend/AI Agent)

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

В API маркетингового анализа добавлена поддержка **опциональных видов анализа**, которые могут быть переданы от фронтенда и будут включены в промпт для AI-генерации отчета.

**Дата обновления**: 2025-01-20

---

## Что изменилось

### Новые опциональные поля в запросе

В эндпоинт `POST /api/marketing/analysis/start` добавлены 5 новых опциональных полей для видов анализа:

1. **`market`** - Анализ рынка
2. **`competitors`** - Анализ конкурентов
3. **`targetAudienceAnalysis`** - Анализ целевой аудитории
4. **`channels`** - Анализ каналов
5. **`swot`** - SWOT анализ

Эти данные будут:

- ✅ Включены в контекст промпта для AI-генерации
- ✅ Сохранены в отчете
- ✅ Отображены в PDF-отчете в разделе "Виды анализа"

---

## Обновленная структура запроса

### Эндпоинт

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

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

#### Обязательные поля (без изменений)

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

#### Новые опциональные поля

| Поле                     | Тип    | Обязательный | Описание                                                    | Максимальная длина | Пример значения                                                                 |
| ------------------------ | ------ | ------------ | ----------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------- |
| `market`                 | string | ❌           | Анализ рынка (размер, тренды, возможности)                  | 2000 символов      | "Рынок веб-разработки в Казахстане растет на 15% ежегодно..."                   |
| `competitors`            | string | ❌           | Анализ конкурентов (основные игроки, их преимущества)       | 2000 символов      | "Основные конкуренты: Компания X, Компания Y..."                                |
| `targetAudienceAnalysis` | string | ❌           | Детальный анализ целевой аудитории                          | 2000 символов      | "Целевая аудитория: IT-директора средних компаний..."                           |
| `channels`               | string | ❌           | Анализ маркетинговых каналов                                | 2000 символов      | "Рекомендуемые каналы: LinkedIn для B2B, Instagram для визуального контента..." |
| `swot`                   | string | ❌           | SWOT анализ (Strengths, Weaknesses, Opportunities, Threats) | 2000 символов      | "Strengths: Быстрая разработка... Weaknesses: Ограниченный бюджет..."           |

### Валидация новых полей

Все новые поля имеют одинаковые правила валидации:

- **Тип**: `string`
- **Обязательность**: ❌ Опциональное (можно не передавать)
- **Максимальная длина**: 2000 символов
- **Минимальная длина**: Нет ограничений (может быть пустой строкой)

---

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

### Пример 1: Запрос только с обязательными полями (как раньше)

```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 недели',
    }),
  }
);
```

**Результат**: Работает как раньше, без изменений в функциональности.

---

### Пример 2: Запрос с одним видом анализа

```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 недели',
      market:
        'Рынок мобильной разработки в Казахстане показывает стабильный рост на 20% в год. Основные драйверы: цифровизация бизнеса, рост числа стартапов, увеличение инвестиций в IT-сектор.',
    }),
  }
);
```

**Результат**: Данные об анализе рынка будут включены в промпт и отображены в отчете.

---

### Пример 3: Запрос со всеми видами анализа

```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 недели',

      // Виды анализа
      market:
        'Рынок мобильной разработки в Казахстане растет на 20% ежегодно. Основные сегменты: корпоративные приложения, e-commerce, финтех.',

      competitors:
        'Основные конкуренты: TechCorp (лидер рынка, 30% доля), DevStudio (средний сегмент, 15% доля), StartupDev (нишевый игрок, 5% доля). Их преимущества: большая команда, долгосрочные контракты.',

      targetAudienceAnalysis:
        'Целевая аудитория: IT-директора средних и крупных компаний (50-500 сотрудников), возраст 35-50 лет, техническое образование. Боли: долгие сроки разработки, высокие цены, отсутствие гибкости.',

      channels:
        'Рекомендуемые каналы: LinkedIn (основной для B2B), Telegram-каналы для IT-сообщества, отраслевые конференции, контент-маркетинг через блог.',

      swot: 'Strengths: Быстрая разработка MVP, опытная команда, гибкие методологии. Weaknesses: Ограниченный бюджет на маркетинг, небольшая команда. Opportunities: Рост спроса на мобильные решения, цифровизация госсектора. Threats: Конкуренция с крупными игроками, экономическая нестабильность.',
    }),
  }
);
```

**Результат**: Все виды анализа будут включены в промпт для более точной генерации отчета и отображены в PDF.

---

## Как это влияет на генерацию отчета

### Включение в промпт

Когда вы передаете виды анализа, они автоматически добавляются в контекст промпта для AI:

```
Продукт/услуга: Разработка мобильных приложений
Локация: Нур-Султан, Казахстан
Тип клиентов: B2B клиенты
Уникальные особенности: Специализируемся на быстрой разработке MVP за 4 недели

Анализ рынка:
Рынок мобильной разработки в Казахстане растет на 20% ежегодно...

Анализ конкурентов:
Основные конкуренты: TechCorp...

...
```

Это позволяет AI генерировать более точные и релевантные рекомендации, учитывая предоставленную аналитику.

### Отображение в PDF-отчете

Если виды анализа были переданы, они будут отображены в PDF-отчете в отдельном разделе:

```markdown
## Виды анализа

### Анализ рынка

Рынок мобильной разработки в Казахстане растет на 20% ежегодно...

### Анализ конкурентов

Основные конкуренты: TechCorp...

### Анализ целевой аудитории

Целевая аудитория: IT-директора средних и крупных компаний...

### Анализ каналов

Рекомендуемые каналы: LinkedIn (основной для B2B)...

### SWOT анализ

Strengths: Быстрая разработка MVP...
```

---

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

✅ **Полная обратная совместимость**: Старые запросы без новых полей продолжают работать без изменений.

✅ **Опциональные поля**: Все новые поля опциональны, их можно не передавать.

✅ **Валидация**: Если поля переданы, они валидируются (максимум 2000 символов).

---

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

### 1. UI/UX

Рекомендуется добавить в форму создания анализа:

- **Опциональные секции** для каждого вида анализа
- **Текстовые поля** (textarea) с ограничением в 2000 символов
- **Подсказки** о том, какую информацию следует включить в каждый вид анализа
- **Индикатор прогресса** заполнения (опционально)

### 2. Валидация на фронтенде

```javascript
// Пример валидации на фронтенде
const validateAnalysisTypes = (data) => {
  const errors = {};

  const analysisTypes = [
    'market',
    'competitors',
    'targetAudienceAnalysis',
    'channels',
    'swot',
  ];

  analysisTypes.forEach((field) => {
    if (data[field] && data[field].length > 2000) {
      errors[field] = `Поле "${field}" не должно превышать 2000 символов`;
    }
  });

  return errors;
};
```

### 3. Структура данных

```typescript
// TypeScript интерфейс для запроса
interface MarketingAnalysisRequest {
  // Обязательные поля
  product: string; // 3-200 символов
  location: string; // 2-150 символов
  client: string; // Одно из допустимых значений
  differentiator: string; // 10-500 символов

  // Опциональные виды анализа
  market?: string; // до 2000 символов
  competitors?: string; // до 2000 символов
  targetAudienceAnalysis?: string; // до 2000 символов
  channels?: string; // до 2000 символов
  swot?: string; // до 2000 символов
}
```

---

## Примеры ответов API

### Успешный ответ (без изменений)

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

### Ошибка валидации (если поле превышает лимит)

```json
{
  "success": false,
  "message": "Ошибка валидации",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Ошибка валидации входных данных",
    "details": {
      "market": "Поле 'market' должно содержать не более 2000 символов"
    }
  }
}
```

**HTTP статус**: `400 Bad Request`

---

## Часто задаваемые вопросы (FAQ)

### Q: Обязательно ли передавать все виды анализа?

**A**: Нет, все поля опциональны. Вы можете передать только те, которые у вас есть.

### Q: Что произойдет, если я передам пустую строку?

**A**: Пустые строки игнорируются, они не будут включены в промпт и отчет.

### Q: Можно ли передать только часть видов анализа?

**A**: Да, вы можете передать любое количество видов анализа (от 0 до 5).

### Q: Влияет ли это на время генерации отчета?

**A**: Нет, время генерации остается прежним (5-10 минут). Дополнительные данные могут улучшить качество отчета.

### Q: Будут ли виды анализа отображаться в JSON-ответе?

**A**: Виды анализа сохраняются в отчете и могут быть доступны через структуру `reportData`, но в текущей версии API они не возвращаются в стандартном JSON-ответе. Они включены в PDF-отчет.

---

## Миграция для существующих клиентов

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

**Никаких изменений не требуется!** Старые запросы продолжают работать без изменений.

### Для новых интеграций

Если вы хотите использовать новые возможности:

1. Добавьте новые поля в форму запроса (опционально)
2. Соблюдайте лимит в 2000 символов для каждого поля
3. Передавайте только те виды анализа, которые у вас есть

---

## Технические детали

### Структура хранения

Виды анализа сохраняются в MongoDB в поле `reportData.analysisTypes`:

```json
{
  "reportData": {
    "summary": "...",
    "targetAudience": {...},
    "recommendations": [...],
    "strategy": {...},
    "analysisTypes": {
      "market": "Рынок...",
      "competitors": "Конкуренты...",
      "targetAudienceAnalysis": "ЦА...",
      "channels": "Каналы...",
      "swot": "SWOT..."
    }
  }
}
```

### Включение в промпт

Виды анализа добавляются в контекст промпта в следующем формате:

```
Анализ рынка:
[содержимое поля market]

Анализ конкурентов:
[содержимое поля competitors]

...
```

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

---

## Поддержка

Если у вас возникли вопросы или проблемы с использованием новых полей, обратитесь к документации API или свяжитесь с командой разработки.

---

**Версия документа**: 1.0  
**Дата обновления**: 2025-01-20  
**Статус**: ✅ Актуально
