digiops/marketing
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
69d1dcd805d113bc6bbcbd964f9345db512eb341
marketing/marketing-analysis-types-update-frontend.md
T
root 24cc534fed .
2025-12-01 11:01:56 +05:00

18 KiB
Raw Blame History

Обновление 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: Запрос только с обязательными полями (как раньше)

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: Запрос с одним видом анализа

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: Запрос со всеми видами анализа

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-отчете в отдельном разделе:

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

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

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

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

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

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

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

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

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

### SWOT анализ

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

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

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

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

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

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

1. UI/UX

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

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

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

// Пример валидации на фронтенде
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 интерфейс для запроса
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

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

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

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

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

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

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

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

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

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

...

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

Поддержка

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

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

Reference in New Issue View Git Blame Copy Permalink