401 lines
17 KiB
Markdown
401 lines
17 KiB
Markdown
# Отличия между ТЗ и текущей реализацией
|
||
|
||
## Обзор
|
||
|
||
Документ описывает расхождения между техническим заданием (ТЗ 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. **Привести статусы** к единому виду
|