# Отличия между ТЗ и текущей реализацией

## Обзор

Документ описывает расхождения между техническим заданием (ТЗ v0.2) и текущей реализацией модуля «Маркетинг».

---

## Блок А. Маркетинговый анализ

### 1. Поля ввода формы

#### ТЗ (Шаг А1):

- **Чем занимается ваш бизнес?** (строка, max 255)
- **Где вы работаете?** (строка) - примеры: "Алматы", "Астана", "Онлайн по всему Казахстану"
- **Что вы продаёте?** (строка)
- **Кто ваш клиент?** (опционально, строка + быстрые кнопки выбора)

#### Реализация:

- ✅ **businessNiche** (ниша бизнеса) - соответствует "Чем занимается ваш бизнес?"
- ✅ **product** (продукт/услуга) - соответствует "Что вы продаёте?"
- ✅ **targetAudience** (целевая аудитория) - соответствует "Кто ваш клиент?", но **обязательное поле** (в ТЗ опциональное)
- ✅ **region** (регион) - соответствует "Где вы работаете?", но **только города Казахстана** (в ТЗ допускается "Онлайн по всему Казахстану")
- ❌ **goal** (цель на 6-12 месяцев) - **новое поле, отсутствует в ТЗ**
- ❌ **detailLevel** (уровень детализации) - **новое поле, отсутствует в ТЗ**
- ❌ **strongSide** (сильная сторона) - **новое поле, отсутствует в ТЗ**
- ❌ **weakSide** (слабая сторона) - **новое поле, отсутствует в ТЗ**

**Вывод**: Реализация расширена дополнительными полями, которые улучшают качество анализа, но не соответствуют минималистичному подходу из ТЗ.

---

### 2. Статусы анализа

#### ТЗ:

- `PENDING` → `IN_PROGRESS` → `COMPLETED` / `FAILED`

#### Реализация:

- `queued` → `processing` → `completed` / `failed`

**Вывод**: Разные названия статусов, но логика идентична.

---

### 3. Эндпоинты API

#### ТЗ:

- `POST /api/marketing/analyses` - создание анализа
- `GET /api/marketing/analyses/{id}/status` - проверка статуса
- `GET /api/marketing/analyses/{id}` - получение результата

#### Реализация:

- ✅ `POST /api/marketing/analysis/start` - создание анализа (путь отличается: `analysis` вместо `analyses`)
- ❌ `GET /api/marketing/analysis/{id}/status` - **отсутствует отдельный эндпоинт для статуса**
- ✅ `GET /api/marketing/analysis/{id}` - получение результата (путь отличается)

**Вывод**: Пути API отличаются (единственное число vs множественное), отсутствует отдельный эндпоинт для проверки статуса (статус возвращается вместе с результатом).

---

### 4. Структура ответа анализа

#### ТЗ (Шаг А4):

Отчёт должен содержать блоки:

- Обзор бизнеса
- Рынок (MarketInsights)
- Конкуренты (CompetitorInsights)
- Целевая аудитория (AudienceProfile)
- Каналы (ChannelInsights)
- SWOT (SwotAnalysis)
- Рекомендации (список Recommendation)

#### Реализация:

Ответ содержит:

- ✅ `summary` - резюме анализа (соответствует обзору)
- ✅ `targetAudience` - целевая аудитория с описанием и каналами
- ✅ `recommendations` - список рекомендаций
- ✅ `strategy` - маркетинговая стратегия с каналами и типами контента
- ❌ **Нет отдельных блоков** для Рынка, Конкурентов, SWOT, Каналов - всё объединено в `summary` на основе `analysisType`

**Вывод**: В ТЗ предполагается комплексный анализ со всеми блоками, в реализации анализ зависит от выбранного `analysisType` (один тип за раз).

---

### 5. Тип анализа

#### ТЗ:

Анализ включает **все типы одновременно**:

- Анализ рынка (MarketInsights)
- Анализ конкурентов (CompetitorInsights)
- Анализ ЦА (AudienceProfile)
- Анализ каналов (ChannelInsights)
- SWOT (SwotAnalysis)

#### Реализация:

Пользователь **выбирает один тип анализа**:

- `РЫНОК` - только анализ рынка
- `КОНКУРЕНТЫ` - только анализ конкурентов
- `ЦА` - только анализ целевой аудитории
- `КАНАЛЫ` - только анализ каналов
- `SWOT` - только SWOT-анализ

**Вывод**: Критическое отличие - в ТЗ анализ комплексный, в реализации пользователь выбирает один тип.

---

## Блок B. Автоматическое продвижение

### 1. Название сущности

#### ТЗ:

- `Campaign` (кампания)
- `CampaignGoal` (цель кампании)
- `Strategy` (стратегия)
- `CampaignChannel` (каналы кампании)
- `ContentItem` (контент-единицы)

#### Реализация:

- `MarketingStrategy` (маркетинговая стратегия) - **другое название**
- Нет сущности `Campaign` - вместо неё используется `MarketingStrategy`
- Нет сущности `CampaignGoal` - цели не реализованы
- ✅ `MarketingStrategy.WeeklyPlan` - недельные планы
- ✅ `MarketingStrategy.PostCalendarItem` - календарь постов (аналог ContentItem)

**Вывод**: Концептуальное отличие - в ТЗ есть отдельные сущности Campaign и Strategy, в реализации всё объединено в MarketingStrategy.

---

### 2. Эндпоинты продвижения

#### ТЗ:

- `POST /api/promotion/campaigns` - создание кампании с `business_id`, `analysis_id`, `goal_id`
- `GET /api/promotion/campaigns/{campaign_id}` - получение стратегии кампании
- `POST /api/promotion/campaigns/{id}/activate` - активация кампании

#### Реализация:

- ✅ `POST /api/marketing/analysis/strategy/generate` - генерация стратегии (путь отличается, нет `goal_id`)
- ✅ `GET /api/marketing/analysis/strategy/{strategyId}` - получение стратегии
- ✅ `POST /api/marketing/analysis/strategy/{strategyId}/start` - запуск стратегии (аналог активации)

**Вывод**: Пути API отличаются (`/api/promotion/campaigns` vs `/api/marketing/analysis/strategy`), отсутствует выбор цели кампании (`goal_id`).

---

### 3. Выбор цели продвижения

#### ТЗ (Шаг B1):

Пользователь выбирает цель из карточек:

- Увеличить продажи (`increase_sales`)
- Получить больше заявок/звонков (`get_leads`)
- Повысить узнаваемость бренда (`awareness`)
- Продвигать акцию или спецпредложение (`promo`)

#### Реализация:

- ❌ **Выбор цели отсутствует** - стратегия генерируется автоматически без выбора цели пользователем

**Вывод**: Критическое отличие - в ТЗ пользователь выбирает цель, в реализации цель определяется автоматически системой.

---

### 4. Формирование стратегии

#### ТЗ (Шаг B2):

Стратегия формируется на основе:

- `AudienceProfile`
- `ChannelInsights`
- `MarketInsights`
- `Recommendation`

Создаются:

- `Strategy` - описание, длительность (7-14 дней)
- `CampaignChannel` - каналы
- `ContentItem` - контент-единицы (черновики)

#### Реализация:

Стратегия формируется на основе:

- ✅ Данных из `MarketingAnalysis`
- ✅ `targetAudience` из анализа
- ✅ `recommendations` из анализа

Создаются:

- ✅ `MarketingStrategy` - описание, длительность в неделях
- ✅ `priorityPlatforms` - приоритетные платформы
- ✅ `WeeklyPlan` - недельные планы с темами
- ✅ `PostCalendarItem` - календарь постов с текстами и хештегами

**Вывод**: Логика похожа, но структура данных отличается (недельные планы и календарь постов вместо простых ContentItem).

---

### 5. Экран "Материалы кампании"

#### ТЗ (Шаг B4):

Отображаются `ContentItem`:

- Тип: пост / сторис / баннер / email
- Канал
- Черновой текст
- Подсказка по визуалу

#### Реализация:

Отображаются `PostCalendarItem`:

- ✅ `platform` - канал
- ✅ `contentType` - тип контента (пост, сторис, видео, баннер)
- ✅ `postText` - текст поста
- ✅ `hashtags` - хештеги
- ✅ `publishDate` - дата публикации
- ✅ `publishTime` - время публикации
- ❌ **Нет подсказок по визуалу**

**Вывод**: Реализация более детальная (даты, время, хештеги), но отсутствуют подсказки по визуалу.

---

## Блок C. Результаты кампаний

### 1. Эндпоинты результатов

#### ТЗ:

- `GET /api/promotion/campaigns?business_id=...` - список кампаний
- Детали кампании через тот же эндпоинт

#### Реализация:

- ❌ **Эндпоинты для результатов кампаний отсутствуют**
- ✅ Есть `GET /api/marketing/analysis/strategy/my` - список стратегий пользователя
- ✅ Есть `PostingTask` - задачи на публикацию, но нет метрик

**Вывод**: Блок C (Результаты кампаний) **не реализован**. Нет метрик, графиков, итоговых выводов.

---

### 2. Метрики кампаний

#### ТЗ (Шаг C2):

Должны отображаться:

- Охват (суммарно)
- Вовлечённость (лайки/клики/сообщения)
- Заявки/обращения
- График по дням
- Метрики по каналам (Instagram, Telegram и т.д.)
- Итоговый вывод системы

#### Реализация:

- ❌ **Метрики отсутствуют**
- ❌ **Графики отсутствуют**
- ❌ **Итоговые выводы отсутствуют**
- ✅ Есть `PostingTask` - задачи на публикацию, но без метрик выполнения

**Вывод**: Функционал отслеживания результатов кампаний полностью отсутствует.

---

## Общие отличия

### 1. API версионирование

#### ТЗ:

- API должен быть версионируемым: `/api/v1/...`

#### Реализация:

- ❌ **Версионирование отсутствует** - используется `/api/marketing/...`

**Вывод**: Не соответствует требованию версионирования API.

---

### 2. Структура данных

#### ТЗ:

Сущности:

- `BusinessProfile`
- `MarketingAnalysis`
- `MarketInsights`
- `CompetitorInsights`
- `AudienceProfile`
- `ChannelInsights`
- `SwotAnalysis`
- `Recommendation`
- `Campaign`
- `CampaignGoal`
- `Strategy`
- `CampaignChannel`
- `ContentItem`
- `CampaignMetrics`

#### Реализация:

Сущности:

- ✅ `MarketingAnalysis`
- ✅ `MarketingStrategy`
- ✅ `PostingTask`
- ❌ **Нет отдельных сущностей** для `MarketInsights`, `CompetitorInsights`, `AudienceProfile`, `ChannelInsights`, `SwotAnalysis` - данные хранятся в `reportData` как Map
- ❌ **Нет `Campaign`** - используется `MarketingStrategy`
- ❌ **Нет `CampaignGoal`**
- ❌ **Нет `CampaignMetrics`**

**Вывод**: Структура данных упрощена - многие сущности объединены или отсутствуют.

---

### 3. Минималистичный подход

#### ТЗ:

> "Собирает минимальные данные о бизнесе"
> "Нельзя заставлять пользователя выбирать типы рекламы, форматы продвижения"

#### Реализация:

- ❌ Пользователь должен выбрать `analysisType` (тип анализа)
- ❌ Пользователь должен выбрать `detailLevel` (уровень детализации)
- ❌ Добавлены дополнительные поля (`goal`, `strongSide`, `weakSide`)

**Вывод**: Реализация требует больше данных от пользователя, чем предполагалось в ТЗ.

---

## Резюме критических отличий

### 🔴 Критические расхождения:

1. **Тип анализа**: В ТЗ анализ комплексный (все типы сразу), в реализации - выбор одного типа
2. **Блок C (Результаты)**: Полностью не реализован - нет метрик, графиков, выводов
3. **Выбор цели кампании**: Отсутствует в реализации
4. **Структура данных**: Упрощена, многие сущности объединены или отсутствуют
5. **API версионирование**: Отсутствует

### 🟡 Значительные отличия:

1. **Поля формы**: Добавлены дополнительные поля, не указанные в ТЗ
2. **Пути API**: Отличаются от указанных в ТЗ
3. **Названия сущностей**: `Campaign` → `MarketingStrategy`
4. **Статусы**: Разные названия (`PENDING` vs `queued`)

### 🟢 Незначительные отличия:

1. **Детализация стратегии**: Реализация более детальная (недельные планы, календарь)
2. **Структура ответа**: Данные организованы по-другому, но информация присутствует

---

## Рекомендации по приведению к ТЗ

### Приоритет 1 (Критично):

1. **Реализовать комплексный анализ** - генерировать все типы анализа одновременно, а не по выбору
2. **Реализовать Блок C** - добавить метрики, графики, итоговые выводы
3. **Добавить выбор цели кампании** - перед генерацией стратегии

### Приоритет 2 (Важно):

1. **Упростить форму** - убрать лишние поля или сделать их опциональными
2. **Привести пути API** к указанным в ТЗ или обновить ТЗ
3. **Добавить версионирование API** - `/api/v1/...`

### Приоритет 3 (Желательно):

1. **Переименовать сущности** или обновить ТЗ под текущую реализацию
2. **Добавить подсказки по визуалу** в материалы кампании
3. **Привести статусы** к единому виду