From 0b074d62818a3d7ef89b84fe246f625359ef2aba Mon Sep 17 00:00:00 2001 From: root Date: Wed, 3 Dec 2025 09:05:00 +0500 Subject: [PATCH] . --- docs/marketing-analysis-api-updated-fields.md | 700 ++++++++++++++++++ src/router/index.js | 41 +- src/service/MarketingService.js | 70 +- .../pages/marketing/MarketingAnalysesList.vue | 83 ++- .../pages/marketing/MarketingAnalysis.vue | 180 ++++- ....timestamp-1764696470038-eccc95bbad6b6.mjs | 47 ++ 6 files changed, 1023 insertions(+), 98 deletions(-) create mode 100644 docs/marketing-analysis-api-updated-fields.md create mode 100644 vite.config.mjs.timestamp-1764696470038-eccc95bbad6b6.mjs diff --git a/docs/marketing-analysis-api-updated-fields.md b/docs/marketing-analysis-api-updated-fields.md new file mode 100644 index 0000000..97494e5 --- /dev/null +++ b/docs/marketing-analysis-api-updated-fields.md @@ -0,0 +1,700 @@ +# API Документация: Обновленные поля для генерации бизнес-анализа (Frontend/AI Agent) + +## Обзор изменений + +API для генерации маркетингового анализа был обновлен с новыми полями, которые более точно отражают требования бизнес-анализа. Все старые поля были заменены новыми для улучшения качества анализа. + +--- + +## Изменения в структуре запроса + +### Удаленные поля (больше не используются) + +Следующие поля были **удалены** из API и больше не принимаются: + +- ❌ `location` - заменено на `region` +- ❌ `client` - заменено на `targetAudience` +- ❌ `differentiator` - заменено на комбинацию `businessNiche`, `strongSide`, `weakSide` + +### Новые обязательные поля + +| Поле | Тип | Обязательный | Описание | Пример значения | +| ---------------- | ------ | ------------ | -------------------------------------- | ------------------------------------------------------ | +| `businessNiche` | string | ✅ | Ниша бизнеса | "E-commerce платформы" | +| `product` | string | ✅ | Продукт или услуга | "Разработка мобильных приложений" | +| `targetAudience` | string | ✅ | Целевая аудитория (детальное описание) | "Малый и средний бизнес, владельцы интернет-магазинов" | +| `region` | string | ✅ | Регион (город Казахстана) | "Алматы" | +| `goal` | string | ✅ | Цель на 6-12 месяцев | "Увеличить количество клиентов на 50%" | +| `detailLevel` | string | ✅ | Уровень детализации анализа | "СТАНДАРТНО" | +| `analysisType` | string | ✅ | Тип анализа | "РЫНОК" | + +### Новые опциональные поля + +| Поле | Тип | Обязательный | Описание | Пример значения | +| ------------ | ------ | ------------ | ----------------------- | ------------------------------------------------- | +| `strongSide` | string | ❌ | Сильная сторона бизнеса | "Опытная команда разработчиков, быстрая доставка" | +| `weakSide` | string | ❌ | Слабая сторона бизнеса | "Ограниченный маркетинговый бюджет" | + +--- + +## Детальное описание полей + +### 1. `businessNiche` (обязательное) + +**Описание**: Ниша бизнеса, в которой работает компания. + +**Валидация**: + +- Минимальная длина: 3 символа +- Максимальная длина: 200 символов +- Разрешены: буквы, цифры, пробелы, дефисы, запятые +- Паттерн: `^[\p{L}\p{N}\s\-,]+$` + +**Примеры**: + +```json +"businessNiche": "E-commerce платформы" +"businessNiche": "Образовательные технологии" +"businessNiche": "Финансовые услуги для малого бизнеса" +``` + +--- + +### 2. `product` (обязательное) + +**Описание**: Конкретный продукт или услуга, которую предоставляет компания. + +**Валидация**: + +- Минимальная длина: 3 символа +- Максимальная длина: 200 символов +- Разрешены: буквы, цифры, пробелы, дефисы, запятые +- Паттерн: `^[\p{L}\p{N}\s\-,]+$` + +**Примеры**: + +```json +"product": "Разработка мобильных приложений" +"product": "Консультации по маркетингу" +"product": "Веб-разработка и дизайн" +``` + +--- + +### 3. `targetAudience` (обязательное) + +**Описание**: Детальное описание целевой аудитории. Это поле заменяет старое поле `client` и должно содержать более подробную информацию. + +**Валидация**: + +- Минимальная длина: 3 символа +- Максимальная длина: 300 символов +- Разрешены любые символы + +**Примеры**: + +```json +"targetAudience": "Малый и средний бизнес, владельцы интернет-магазинов в возрасте 30-50 лет" +"targetAudience": "Стартапы и технологические компании, нуждающиеся в быстрой разработке MVP" +"targetAudience": "Частные лица, желающие создать личный бренд в социальных сетях" +``` + +**Примечание**: В отличие от старого поля `client`, которое принимало только фиксированные значения, `targetAudience` принимает свободный текст для более гибкого описания. + +--- + +### 4. `region` (обязательное) + +**Описание**: Регион (город Казахстана), в котором работает бизнес. Это поле заменяет старое поле `location`. + +**Валидация**: + +- Должно быть одним из допустимых городов Казахстана +- Проверка выполняется через валидатор `@ValidRegion` + +**Допустимые значения** (точное совпадение): + +- `"Алматы"` +- `"Астана"` +- `"Шымкент"` +- `"Караганда"` +- `"Актобе"` +- `"Тараз"` +- `"Павлодар"` +- `"Усть-Каменогорск"` +- `"Семей"` +- `"Костанай"` +- `"Кызылорда"` +- `"Уральск"` +- `"Петропавловск"` +- `"Атырау"` +- `"Актау"` +- `"Туркестан"` +- `"Кокшетау"` +- `"Талдыкорган"` +- `"Экибастуз"` +- `"Рудный"` + +**Примеры**: + +```json +"region": "Алматы" +"region": "Астана" +"region": "Шымкент" +``` + +**Важно**: Значение должно точно совпадать с одним из допустимых городов (регистр важен). + +--- + +### 5. `goal` (обязательное) + +**Описание**: Цель бизнеса на период 6-12 месяцев. Это новое поле, которое помогает AI лучше понять приоритеты бизнеса. + +**Валидация**: + +- Минимальная длина: 10 символов +- Максимальная длина: 500 символов +- Разрешены любые символы + +**Примеры**: + +```json +"goal": "Увеличить количество клиентов на 50% за следующие 6 месяцев" +"goal": "Выйти на рынок соседних регионов и открыть 3 новых филиала" +"goal": "Повысить узнаваемость бренда и увеличить продажи через онлайн-каналы на 30%" +``` + +--- + +### 6. `detailLevel` (обязательное) + +**Описание**: Уровень детализации анализа. Влияет на объем и глубину генерируемого анализа. + +**Валидация**: + +- Должно быть одним из допустимых значений +- Проверка выполняется через валидатор `@ValidDetailLevel` + +**Допустимые значения** (точное совпадение, регистр важен): + +- `"КРАТКО"` - Краткий анализ (1-2 абзаца) +- `"СТАНДАРТНО"` - Стандартный анализ (3-5 абзацев) - **рекомендуется по умолчанию** +- `"ПОДРОБНО"` - Подробный анализ (5-8 абзацев) + +**Влияние на анализ**: + +| Уровень | Длина ответов | Количество рекомендаций | Детализация стратегии | +| ------------ | ------------- | ----------------------- | ------------------------ | +| `КРАТКО` | 1-2 абзаца | 3-4 рекомендации | Краткая | +| `СТАНДАРТНО` | 3-5 абзацев | 4-6 рекомендаций | Стандартная | +| `ПОДРОБНО` | 5-8 абзацев | 6-8 рекомендаций | Детальная с обоснованием | + +**Примеры**: + +```json +"detailLevel": "КРАТКО" +"detailLevel": "СТАНДАРТНО" +"detailLevel": "ПОДРОБНО" +``` + +--- + +### 7. `strongSide` (опциональное) + +**Описание**: Сильная сторона бизнеса. Помогает AI лучше понять конкурентные преимущества. + +**Валидация**: + +- Максимальная длина: 500 символов +- Разрешены любые символы +- Может быть пустым или отсутствовать + +**Примеры**: + +```json +"strongSide": "Опытная команда разработчиков с 10+ летним опытом, быстрая доставка проектов" +"strongSide": "Уникальная технология, низкие цены, отличная поддержка клиентов" +``` + +**Примечание**: Если поле не указано, AI будет анализировать сильные стороны на основе других данных. + +--- + +### 8. `weakSide` (опциональное) + +**Описание**: Слабая сторона бизнеса. Помогает AI лучше понять области для улучшения. + +**Валидация**: + +- Максимальная длина: 500 символов +- Разрешены любые символы +- Может быть пустым или отсутствовать + +**Примеры**: + +```json +"weakSide": "Ограниченный маркетинговый бюджет, недостаточная узнаваемость бренда" +"weakSide": "Небольшая команда, ограниченные ресурсы для масштабирования" +``` + +**Примечание**: Если поле не указано, AI будет анализировать слабые стороны на основе других данных. + +--- + +### 9. `analysisType` (обязательное) + +**Описание**: Тип анализа, который необходимо провести. Поле осталось без изменений. + +**Допустимые значения**: + +- `"РЫНОК"` - Анализ рынка +- `"КОНКУРЕНТЫ"` - Анализ конкурентов +- `"ЦА"` - Анализ целевой аудитории +- `"КАНАЛЫ"` - Анализ маркетинговых каналов +- `"SWOT"` - SWOT-анализ + +--- + +## Полный пример запроса + +### POST `/api/marketing/analysis/start` + +```json +{ + "businessNiche": "E-commerce платформы", + "product": "Разработка мобильных приложений для интернет-магазинов", + "targetAudience": "Малый и средний бизнес, владельцы интернет-магазинов в возрасте 30-50 лет, нуждающиеся в мобильных решениях", + "region": "Алматы", + "goal": "Увеличить количество клиентов на 50% за следующие 6 месяцев и выйти на рынок соседних регионов", + "detailLevel": "СТАНДАРТНО", + "strongSide": "Опытная команда разработчиков с 10+ летним опытом, быстрая доставка проектов, использование современных технологий", + "weakSide": "Ограниченный маркетинговый бюджет, недостаточная узнаваемость бренда в новых регионах", + "analysisType": "РЫНОК" +} +``` + +--- + +## Примеры использования на фронтенде + +### JavaScript/TypeScript + +```typescript +interface MarketingAnalysisRequest { + businessNiche: string; + product: string; + targetAudience: string; + region: string; + goal: string; + detailLevel: 'КРАТКО' | 'СТАНДАРТНО' | 'ПОДРОБНО'; + strongSide?: string; + weakSide?: string; + analysisType: 'РЫНОК' | 'КОНКУРЕНТЫ' | 'ЦА' | 'КАНАЛЫ' | 'SWOT'; +} + +// Список допустимых регионов +const VALID_REGIONS = [ + 'Алматы', + 'Астана', + 'Шымкент', + 'Караганда', + 'Актобе', + 'Тараз', + 'Павлодар', + 'Усть-Каменогорск', + 'Семей', + 'Костанай', + 'Кызылорда', + 'Уральск', + 'Петропавловск', + 'Атырау', + 'Актау', + 'Туркестан', + 'Кокшетау', + 'Талдыкорган', + 'Экибастуз', + 'Рудный', +]; + +// Список уровней детализации +const DETAIL_LEVELS = ['КРАТКО', 'СТАНДАРТНО', 'ПОДРОБНО'] as const; + +// Функция для отправки запроса +async function startMarketingAnalysis( + data: MarketingAnalysisRequest +): Promise { + const response = await fetch( + 'https://api.konturai.kz/api/marketing/analysis/start', + { + method: 'POST', + headers: { + 'Content-Type': 'application/json', + Authorization: 'Bearer YOUR_JWT_TOKEN', // Если требуется + }, + body: JSON.stringify(data), + } + ); + + const result = await response.json(); + + if (!result.success) { + throw new Error(result.error?.message || 'Failed to start analysis'); + } + + return result.data.analysisId; +} + +// Пример использования +const analysisId = await startMarketingAnalysis({ + businessNiche: 'E-commerce платформы', + product: 'Разработка мобильных приложений', + targetAudience: 'Малый и средний бизнес, владельцы интернет-магазинов', + region: 'Алматы', + goal: 'Увеличить количество клиентов на 50% за следующие 6 месяцев', + detailLevel: 'СТАНДАРТНО', + strongSide: 'Опытная команда, быстрая доставка', + weakSide: 'Ограниченный маркетинговый бюджет', + analysisType: 'РЫНОК', +}); +``` + +### React компонент с формой + +```tsx +import React, { useState } from 'react'; + +const MarketingAnalysisForm: React.FC = () => { + const [formData, setFormData] = useState({ + businessNiche: '', + product: '', + targetAudience: '', + region: '', + goal: '', + detailLevel: 'СТАНДАРТНО', + strongSide: '', + weakSide: '', + analysisType: 'РЫНОК', + }); + + const handleSubmit = async (e: React.FormEvent) => { + e.preventDefault(); + + try { + const analysisId = await startMarketingAnalysis(formData); + console.log('Analysis started:', analysisId); + // Перенаправление на страницу с результатами + } catch (error) { + console.error('Error:', error); + } + }; + + return ( +
+
+ + + setFormData({ ...formData, businessNiche: e.target.value }) + } + required + minLength={3} + maxLength={200} + /> +
+ +
+ + + setFormData({ ...formData, product: e.target.value }) + } + required + minLength={3} + maxLength={200} + /> +
+ +
+ +