# AI-генерация маркетинговых стратегий — Документация

## Обзор

Система AI-генерации создаёт профессиональные маркетинговые стратегии на 4 недели с 16 постами, используя строгую валидацию и профессиональные промпты.

## Архитектура

```
┌─────────────────────────────────────────────────────────────┐
│                     ФРОНТЕНД (Vue 3)                        │
├─────────────────────────────────────────────────────────────┤
│  AIStrategyGenerator.vue (UI компонент)                     │
│       ↓                                                      │
│  strategyPromptGenerator.ts (генерация промпта)             │
│       ↓                                                      │
│  AIStrategyService.ts (сервис API + валидация)              │
│       ↓                                                      │
│  validateAIStrategy.ts (полная валидация)                   │
│       ↓                                                      │
│  ai-strategy.types.ts (TypeScript интерфейсы)               │
└─────────────────────────────────────────────────────────────┘
       ↓
┌─────────────────────────────────────────────────────────────┐
│                     BACKEND API                             │
│  POST /api/ai/strategy/generate                             │
│  Тело: { prompt, model, temperature, maxTokens }            │
└─────────────────────────────────────────────────────────────┘
```

## Файлы

| Файл | Назначение |
|------|-----------|
| `src/types/ai-strategy.types.ts` | TypeScript интерфейсы и константы |
| `src/utils/validateAIStrategy.ts` | Утилита полной валидации AI-ответа |
| `src/utils/strategyPromptGenerator.ts` | Генератор промпта и парсер JSON |
| `src/service/AIStrategyService.ts` | Сервис работы с AI-стратегиями |
| `src/components/marketing/AIStrategyGenerator.vue` | UI компонент генератора |
| `src/views/pages/marketing/AIStrategyGeneratorPage.vue` | Страница генератора |

## TypeScript интерфейсы

### PostCalendarItem

```typescript
interface PostCalendarItem {
  postIndex: number;           // 0-15
  publishDate: string;         // "2026-04-13T09:00:00"
  weekNumber: 1 | 2 | 3 | 4;
  platform: 'Instagram' | 'TikTok';
  contentType: 'фото' | 'видео';
  theme: string;               // Конкретная тема
  postText: string;            // 150+ слов
  hashtags: string[];          // 5-8 хэштегов
  publishTime: '09:00' | '12:00' | '18:00' | '20:00';
  imageUrl?: string;
  videoUrl?: string;
  taskStatus?: string;
}
```

### WeeklyPlan

```typescript
interface WeeklyPlan {
  weekNumber: 1 | 2 | 3 | 4;
  mainThemes: string[];         // Ровно 4 темы
  contentRecommendations: string; // 50+ слов
  priorityPlatforms: string[];
}
```

### AIStrategyResponse

```typescript
interface AIStrategyResponse {
  selectedModel: string;
  scoringRationale: string;
  recommendedDurationWeeks: 4;
  recommendedPlatforms: string[];
  rationale: string;            // 60+ слов
  weeklyPlans: WeeklyPlan[];    // 4 недели
  postCalendar: PostCalendarItem[]; // 16 постов
}
```

## Правила валидации

### Критические ошибки (ERROR)

| Правило | Проверка |
|---------|---------|
| **Количество постов** | Ровно 16 (4 × 4 недели) |
| **Недели** | Каждая из 4 недель представлена |
| **Даты** | ISO формат, правильные дни (Пн, Ср, Пт, Сб) |
| **Время** | Только 09:00, 12:00, 18:00, 20:00 |
| **Видео** | Ровно 4 (первый пост каждой недели) |
| **Фото** | Ровно 12 (остальные посты) |
| **Хэштеги** | 5-8 на пост, каждый начинается с # |
| **Текст** | 150+ слов на пост |
| **Темы** | Конкретные, не абстрактные |

### Предупреждения (WARNING)

| Правило | Проверка |
|---------|---------|
| **Абстрактные темы** | Темы без конкретики |
| **Стиль** | Рекомендации по улучшению |

## Использование

### 1. Через UI

Перейдите на `/marketing-analysis/ai-strategy`

Заполните:
- Ниша бизнеса
- Название бренда
- Город продвижения
- Модель стратегии (ENTRY/AUTHORITY/TRUST/CONVERSION)
- Дата начала (опционально)

### 2. Программно

```typescript
import AIStrategyService from '@/service/AIStrategyService';

const result = await AIStrategyService.generateAIStrategy({
  niche: 'Кондитерская',
  brand: 'Sweet Dreams',
  city: 'Алматы',
  model: 'CONVERSION'
});

console.log(result.strategy);      // AIStrategyResponse
console.log(result.validation);    // ValidationResult
```

### 3. Валидация готовй стратегии

```typescript
import { validateAIStrategy } from '@/utils/validateAIStrategy';

const validation = validateAIStrategy(myStrategy);
if (!validation.isValid) {
  console.error(validation.errors);
}
```

### 4. Экспорт

```typescript
// JSON
AIStrategyService.exportStrategyAsJSON(strategy, 'my-strategy');

// CSV
AIStrategyService.exportCalendarAsCSV(strategy, 'my-calendar');
```

## Константы

```typescript
STRATEGY_CONSTANTS = {
  TOTAL_POSTS: 16,
  POSTS_PER_WEEK: 4,
  TOTAL_WEEKS: 4,
  TOTAL_VIDEOS: 4,
  TOTAL_PHOTOS: 12,
  MIN_POST_WORDS: 150,
  MIN_HASHTAGS: 5,
  MAX_HASHTAGS: 8,
  MIN_WEEKLY_RECOMMENDATION_WORDS: 50,
  MIN_RATIONALE_WORDS: 60,
  VALID_PUBLISH_TIMES: ['09:00', '12:00', '18:00', '20:00']
}
```

## Модели стратегий

| Модель | Описание | Когда использовать |
|--------|---------|-------------------|
| **ENTRY** | Вход / Формирование присутствия | Новые бизнес, узнаваемость |
| **AUTHORITY** | Экспертность / Компетентность | B2B, длинный цикл сделки |
| **TRUST** | Усиление доверия | Высокая конкуренция |
| **CONVERSION** | Прямая конверсия | Быстрые покупки, B2C |

## API Endpoints

### Генерация стратегии

```
POST /api/ai/strategy/generate
Content-Type: application/json

{
  "prompt": "...",
  "model": "gpt-4",
  "temperature": 0.7,
  "maxTokens": 8000
}

Response:
{
  "data": {
    "content": "{...JSON стратегии...}"
  }
}
```

## Распределение постов

### Неделя 1-4 (одинаковая структура)

| Пост | День | Время | Тип |
|------|------|-------|-----|
| 1 | Понедельник | 09:00 | 🎥 Видео |
| 2 | Среда | 12:00 | 📸 Фото |
| 3 | Пятница | 18:00 | 📸 Фото |
| 4 | Суббота | 20:00 | 📸 Фото |

## Пример правильного ответа AI

```json
{
  "selectedModel": "CONVERSION",
  "scoringRationale": "Модель Conversion оптимальна...",
  "recommendedDurationWeeks": 4,
  "recommendedPlatforms": ["Instagram", "TikTok"],
  "rationale": "Instagram и TikTok являются...",
  "weeklyPlans": [
    {
      "weekNumber": 1,
      "mainThemes": ["Кейс клиента", "Процесс работы", "Отзыв", "Экспертный"],
      "contentRecommendations": "На этой неделе фокусируемся...",
      "priorityPlatforms": ["Instagram"]
    }
  ],
  "postCalendar": [
    {
      "postIndex": 0,
      "publishDate": "2026-04-13T09:00:00",
      "weekNumber": 1,
      "platform": "Instagram",
      "contentType": "видео",
      "theme": "Кейс: Как клиент увеличил продажи на 40%",
      "postText": "Хотите узнать, как наш клиент из Алматы...",
      "hashtags": ["#кейс", "#алматы", "#бизнес"],
      "publishTime": "09:00"
    }
  ]
}
```

## Troubleshooting

### Ошибка: "Невалидный JSON"

AI вернул текст с markdown блоками. Функция `extractJSONFromResponse` автоматически очищает ответ.

### Ошибка валидации: "postCalendar должен содержать ровно 16 постов"

AI вернул меньше или больше постов. Проверьте промпт и температуру (рекомендуется 0.7).

### Предупреждение: "Тема выглядит абстрактной"

AI создал тему без конкретики. Стратегия валидна, но темы можно улучшить.

## Roadmap

- [ ] Сохранение стратегии на бэкенде
- [ ] Интеграция с автопостингом
- [ ] Редактор постов в UI
- [ ] A/B тестирование тем
- [ ] Мульти-язычность

## Лицензия

Внутренний проект Konturai.