marketing-parser/FRONTEND_API_CHANGES_MARKETING_ANALYSIS.md

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

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

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

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

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

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

Было:

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

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

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

Было:

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

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

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

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

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

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

Добавлено:

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

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

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

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

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

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

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

// Было
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: Обновите обработку конкурентов

// Было
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: Добавьте обработку рынка

// НОВОЕ
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 сегментов и каналов

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. График долей рынка

const marketShareChart = chartsData.marketShareChart || [];

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

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

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	✅ Без изменений	Осталось прежним

Вопросы?

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