marketing-parser/FRONTEND_API_CHANGES_MARKETING_ANALYSIS.md

# Изменения в API маркетингового анализа

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

Проведен рефакторинг метода генерации JSON-анализа для повышения детализации данных. Структура ответа API для фронтенда **осталась прежней**, но изменилась внутренняя структура данных в `chartsData`.

## Структура ответа API (без изменений)

Ответ API остается прежним:

```json
{
  "analysisId": "string",
  "status": "completed",
  "createdAt": "2024-01-01T00:00:00",
  "completedAt": "2024-01-01T00:05:00",
  "report": {
    "summary": "string",
    "fullAnalysis": "string",
    "chartsData": {
      /* ← ИЗМЕНЕНИЯ ЗДЕСЬ */
    },
    "targetAudience": {
      "description": "string",
      "channels": ["Instagram", "Telegram"]
    },
    "recommendations": ["string"],
    "strategy": {
      "duration": "2 недели",
      "channels": ["Instagram", "Telegram"],
      "contentTypes": ["посты", "сторис"]
    },
    "pdfUrl": "/api/marketing/analysis/{id}/download"
  }
}
```

## Изменения в `chartsData`

### 1. Анализ аудитории (`audienceSegmentation`)

**Было:**

```json
{
  "audienceSegmentation": {
    "ageGroups": [{ "label": "25-34", "value": "40" }],
    "genders": [{ "label": "Женщины", "value": "60" }],
    "segments": [{ "label": "Сегмент 1", "value": "35" }]
  }
}
```

**Стало (расширенная структура):**

```json
{
  "audienceSegmentation": {
    "ageGroups": [
      { "label": "18-24", "value": "15" },
      { "label": "25-34", "value": "40" },
      { "label": "35-44", "value": "30" },
      { "label": "45+", "value": "15" }
    ],
    "genders": [
      { "label": "Женщины", "value": "60" },
      { "label": "Мужчины", "value": "40" }
    ],
    "segments": [
      {
        "label": "Молодые профессионалы",
        "value": "35"
      }
    ],
    "segmentsChannelMatrix": [
      // ← НОВОЕ
      {
        "segmentName": "Молодые профи",
        "instagram": "high",
        "telegram": "medium",
        "youtube": "low"
      }
    ],
    "keyTakeaways": [
      // ← НОВОЕ
      "Вывод 1",
      "Вывод 2",
      "Вывод 3"
    ]
  }
}
```

**Что изменилось:**

- ✅ Структура `ageGroups`, `genders`, `segments` осталась прежней
- ➕ Добавлено поле `segmentsChannelMatrix` — матрица соответствия сегментов и каналов (heatmap)
- ➕ Добавлено поле `keyTakeaways` — ключевые выводы по аудитории

### 2. Анализ конкурентов (`competitors`)

**Было:**

```json
{
  "competitors": [
    {
      "name": "Конкурент А",
      "reach": 50000,
      "activity": 85,
      "reviews": 1200,
      "strengths": "Не указано",
      "weaknesses": "Не указано"
    }
  ]
}
```

**Стало (расширенная структура):**

```json
{
  "marketShareChart": [
    // ← НОВОЕ
    { "name": "Наш бренд", "value": 25 },
    { "name": "Конкурент А", "value": 30 },
    { "name": "Конкурент B", "value": 20 },
    { "name": "Другие", "value": 25 }
  ],
  "competitors": [
    {
      "name": "Конкурент А",
      "reach": 50000,
      "followers": 12000, // ← НОВОЕ
      "activity": 85,
      "priceStrategy": "Высокая", // ← НОВОЕ
      "channelsHeatmap": {
        // ← НОВОЕ
        "Instagram": 90,
        "TikTok": 20,
        "Telegram": 70,
        "YouTube": 40
      }
    }
  ],
  "comparisonTable": [
    // ← НОВОЕ
    {
      "feature": "Ценовая политика",
      "us": "Средняя",
      "compA": "Высокая",
      "compB": "Низкая"
    }
  ],
  "swotCompetitors": {
    // ← НОВОЕ
    "strengths": ["..."],
    "weaknesses": ["..."]
  }
}
```

**Что изменилось:**

- ✅ Массив `competitors` остался, но с дополнительными полями
- ➕ Добавлено поле `marketShareChart` — доли рынка для графика
- ➕ Добавлено поле `comparisonTable` — сравнительная таблица характеристик
- ➕ Добавлено поле `swotCompetitors` — SWOT-анализ по рынку
- ➕ В объектах конкурентов добавлены: `followers`, `priceStrategy`, `channelsHeatmap`

### 3. Сезонность (`seasonality`)

**Без изменений:**

```json
{
  "seasonality": {
    "Январь": 45,
    "Февраль": 50,
    "Март": 60
    // ... остальные месяцы
  }
}
```

### 4. Рынок (`market`) — НОВОЕ

**Добавлено:**

```json
{
  "market": {
    "size": "средний",
    "growthRate": "растущий",
    "trends": ["Тренд 1", "Тренд 2"],
    "opportunities": ["Возможность 1"],
    "threats": ["Угроза 1"]
  }
}
```

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

Для обеспечения обратной совместимости, следующие поля могут присутствовать в `chartsData` (если использовалась старая структура):

- `channelsPotential` — каналы продвижения
- `conversionFunnel` — воронка конверсии
- `swot` — SWOT-анализ

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

## Миграция фронтенда

### Шаг 1: Обновите обработку `audienceSegmentation`

```typescript
// Было
const ageGroups = chartsData.audienceSegmentation?.ageGroups || [];
const genders = chartsData.audienceSegmentation?.genders || [];
const segments = chartsData.audienceSegmentation?.segments || [];

// Стало (добавьте новые поля)
const ageGroups = chartsData.audienceSegmentation?.ageGroups || [];
const genders = chartsData.audienceSegmentation?.genders || [];
const segments = chartsData.audienceSegmentation?.segments || [];
const segmentsChannelMatrix =
  chartsData.audienceSegmentation?.segmentsChannelMatrix || []; // НОВОЕ
const keyTakeaways = chartsData.audienceSegmentation?.keyTakeaways || []; // НОВОЕ
```

### Шаг 2: Обновите обработку конкурентов

```typescript
// Было
const competitors = chartsData.competitors || [];

// Стало (добавьте новые поля)
const marketShareChart = chartsData.marketShareChart || []; // НОВОЕ
const competitors = chartsData.competitors || [];
const comparisonTable = chartsData.comparisonTable || []; // НОВОЕ
const swotCompetitors = chartsData.swotCompetitors || {}; // НОВОЕ

// Обновите обработку объектов конкурентов
competitors.forEach((comp) => {
  const followers = comp.followers; // НОВОЕ
  const priceStrategy = comp.priceStrategy; // НОВОЕ
  const channelsHeatmap = comp.channelsHeatmap; // НОВОЕ
});
```

### Шаг 3: Добавьте обработку рынка

```typescript
// НОВОЕ
const market = chartsData.market || {};
const marketSize = market.size;
const growthRate = market.growthRate;
const trends = market.trends || [];
const opportunities = market.opportunities || [];
const threats = market.threats || [];
```

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

### 1. Heatmap сегментов и каналов

```typescript
const segmentsChannelMatrix =
  chartsData.audienceSegmentation?.segmentsChannelMatrix || [];

// Отображение heatmap
segmentsChannelMatrix.forEach((row) => {
  const segmentName = row.segmentName;
  const instagram = row.instagram; // "high" | "medium" | "low"
  const telegram = row.telegram;
  const youtube = row.youtube;
  // ... отрисовка heatmap
});
```

### 2. График долей рынка

```typescript
const marketShareChart = chartsData.marketShareChart || [];

// Отображение pie chart
marketShareChart.forEach((item) => {
  const name = item.name; // "Наш бренд", "Конкурент А", etc.
  const value = item.value; // процент доли рынка
  // ... отрисовка графика
});
```

### 3. Сравнительная таблица

```typescript
const comparisonTable = chartsData.comparisonTable || [];

// Отображение таблицы
comparisonTable.forEach((row) => {
  const feature = row.feature; // "Ценовая политика", "УТП", etc.
  const us = row.us;
  const compA = row.compA;
  const compB = row.compB;
  // ... отрисовка таблицы
});
```

## Резюме изменений

| Поле                              | Статус           | Описание                                                       |
| --------------------------------- | ---------------- | -------------------------------------------------------------- |
| `chartsData.audienceSegmentation` | ✅ Расширено     | Добавлены `segmentsChannelMatrix` и `keyTakeaways`             |
| `chartsData.competitors`          | ✅ Расширено     | Добавлены поля `followers`, `priceStrategy`, `channelsHeatmap` |
| `chartsData.marketShareChart`     | ➕ Новое         | График долей рынка                                             |
| `chartsData.comparisonTable`      | ➕ Новое         | Сравнительная таблица                                          |
| `chartsData.swotCompetitors`      | ➕ Новое         | SWOT-анализ по рынку                                           |
| `chartsData.market`               | ➕ Новое         | Данные о рынке                                                 |
| `chartsData.seasonality`          | ✅ Без изменений | Осталось прежним                                               |

## Вопросы?

Если возникнут вопросы по миграции, обращайтесь к бэкенд-команде.