# Обновление 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 **Статус**: ✅ Актуально