.

Модуль м.md

@@ -0,0 +1,232 @@
+ТЕХНИЧЕСКОЕ ЗАДАНИЕ v0.2
+Подсистема: модуль «Маркетинг» (Анализ + Продвижение + Результаты) платформы NAK.AI
+
+1. Общие положения
+   Цель подсистемы:Реализовать единый модуль «Маркетинг», который для предпринимателя МСБ выполняет полный цикл:
+   Собирает минимальные данные о бизнесе.
+   Проводит автоматический маркетинговый анализ (рынок, конкуренты, ЦА, каналы, SWOT).
+   Формирует понятный аналитический отчёт с рекомендациями простым языком.
+   Позволяет на основе анализа создать и запустить продвижение (кампанию).
+   Отображает результаты продвижения в виде метрик и простых выводов.
+   Роль пользователя: владелец или представитель МСБ (без штатного маркетолога).Интерфейс: полностью на русском языке, без перегруза терминами.
+
+2. Целевая аудитория и сценарий использования
+   Малый и средний бизнес в Казахстане.
+   Пользователь не обязан разбираться в маркетинге.
+   Ожидание: “я отвечу на несколько вопросов → система сама всё посчитает → покажет выводы → предложит готовое продвижение”.
+   Важно:Нельзя заставлять пользователя:
+   выбирать типы рекламы (таргет/контекст и т.д.),
+   выбирать форматы продвижения “по-умному”,
+   считать бюджеты и вручную настраивать каналы.
+   Система сама принимает сложные решения и даёт гибкий, но простой интерфейс.
+
+3. Общая структура модуля «Маркетинг»
+   Модуль «Маркетинг» включает 3 логических блока:
+   Блок А. Маркетинговый анализ
+   Блок B. Автоматическое продвижение
+   Блок C. Результаты кампаний
+   В UI это один раздел “Маркетинг” с навигацией по шагам.
+
+4. Блок А. Маркетинговый анализ
+   4.1. Назначение блока
+   Собрать минимальный набор входных данных и выполнить автоматический анализ, чтобы:
+   объяснить предпринимателю, на каком рынке он работает,
+   кто его конкуренты,
+   кто его клиент,
+   какие каналы и форматы для него перспективны,
+   в чём его сильные и слабые стороны.
+   4.2. Пользовательский поток (step-by-step)
+   Шаг А1. Экран «Начать анализ»
+   Поля ввода (всё максимально простым языком):
+   Чем занимается ваш бизнес?Тип: строка, max 255Примеры подсказок:
+   «Студия маникюра»
+   «Магазин детской одежды»
+   «СТО по ремонту авто»
+   Где вы работаете?Тип: строкаПримеры:
+   «Алматы»
+   «Астана»
+   «Онлайн по всему Казахстану»
+   Что вы продаёте?Тип: строкаПримеры:
+   «Наращивание ресниц»
+   «Пальто зимние»
+   «Установка дверей»
+   Кто ваш клиент? (опционально)Тип: строка + быстрые кнопки выбора:
+   Женщины 20–40
+   Мужчины 25–45
+   Семьи
+   Молодёжь
+   Все подряд
+   Кнопка: «Начать анализ»
+   После нажатия создаётся сущность MarketingAnalysis со статусом PENDING.
+
+Шаг А2. Обработка анализа
+Бэкенд:
+Меняет статус PENDING → IN_PROGRESS.
+Запускает внутренние алгоритмы анализа (в рамках MVP можно сделать заглушки/правила).
+Подзадачи анализа:
+Анализ рынка (MarketInsights)
+Анализ конкурентов (CompetitorInsights)
+Анализ ЦА (AudienceProfile)
+Анализ каналов (ChannelInsights)
+SWOT (SwotAnalysis)
+Формирование рекомендаций (Recommendation)
+
+Шаг А3. Экран «Анализ выполняется»
+Пользователь видит:
+Прогресс-бар (этапы: рынок → конкуренты → ЦА → SWOT → отчёт)
+Сообщение:
+«Система анализирует ваш рынок, конкурентов и целевую аудиторию. Это может занять немного времени.»
+Опрашивается GET /api/marketing/analyses/{id}/status до состояния COMPLETED или FAILED.
+
+Шаг А4. Экран «Готовый отчёт»
+После завершения анализа:
+UI запрашивает GET /api/marketing/analyses/{id} и отображает блоки:
+Обзор бизнеса (кратко, на основе BusinessProfile + входных)
+Рынок (MarketInsights)
+Конкуренты (CompetitorInsights)
+Целевая аудитория (AudienceProfile)
+Каналы (ChannelInsights)
+SWOT (SwotAnalysis)
+Рекомендации (список Recommendation)
+Кнопки:
+«Сохранить отчёт» (на будущее – выгрузка PDF/Word)
+«Перейти к продвижению» → открывает блок B.
+
+5. Блок B. Автоматическое продвижение
+   5.1. Назначение блока
+   На основе данных анализа автоматически:
+   сформировать цель кампании,
+   предложить стратегию,
+   создать структуру кампании и контент-пакет,— чтобы предпринимателю не пришлось самому разбираться в каналах и форматах.
+   5.2. Пользовательский поток (step-by-step)
+   Шаг B1. Экран «Выбор цели продвижения»
+   Появляется после клика «Перейти к продвижению» или при заходе в маркетинг → вкладка «Продвижение».
+   Пользователь видит вопрос:
+   «Какой результат вы хотите получить?»
+   Карточки-цели (CampaignGoal):
+   Увеличить продажи (increase_sales)
+   Получить больше заявок/звонков (get_leads)
+   Повысить узнаваемость бренда (awareness)
+   Продвигать акцию или спецпредложение (promo)
+   Кнопка: «Продолжить»
+   После выбора вызывается POST /api/promotion/campaigns с:
+   {
+   "business_id": "<id>",
+   "analysis_id": "<last_or_selected>",
+   "goal_id": "increase_sales"
+   }
+   Создаётся Campaign со статусом DRAFT.
+
+Шаг B2. Автоматическое формирование стратегии
+Бэкенд:
+Читает MarketingAnalysis по analysis_id.
+Использует данные:
+AudienceProfile
+ChannelInsights
+MarketInsights
+Recommendation
+Формирует сущности:
+Strategy: общее описание, длительность (например, 7–14 дней).
+CampaignChannel: какие каналы будут использоваться.
+ContentItem: список контентных единиц (черновики).
+Пример:
+Каналы: Instagram, Telegram, 2GIS
+План:
+3 поста в Instagram
+7 сторис
+1 подборка на маркетплейсе/каталоге
+1 простая рассылка по клиентам (если есть база – позже)
+
+Шаг B3. Экран «Стратегия продвижения»
+UI запрашивает GET /api/promotion/campaigns/{campaign_id} и отображает:
+Цель кампании (человекочитаемый текст)
+Каналы, которые выбрала система
+Краткое текстовое описание стратегии:
+«На основе вашего анализа система рекомендует 2 недели активного продвижения в Instagram и Telegram с упором на отзывы и примеры работ.»
+Пользователь может:
+«Принять стратегию» → переход к контенту
+«Редактировать детали» (в MVP можно просто подсветить, что это появится позже или минимально корректировать текст/названия)
+
+Шаг B4. Экран «Материалы кампании» (контент-пакет)
+Отображаются ContentItem:
+Список:
+Тип: пост / сторис / баннер / email
+Канал
+Черновой текст (который может быть сгенерирован системой)
+Подсказка по визуалу (например: «фото до/после», «фото товара на человеке»)
+Пользователь может:
+Просмотреть
+При необходимости подправить текст (на фронте)
+Нажать «Готово, перейти к запуску»
+
+Шаг B5. Экран «Запуск кампании»
+Простой экран подтверждения:
+«Кампания готова к запуску.Вы можете использовать эти материалы для публикации на своих площадках.В следующих версиях система сможет автоматически публиковать материалы через интеграции.»
+Кнопка:
+«Зафиксировать запуск кампании» → POST /api/promotion/campaigns/{id}/activate
+Статус Campaign меняется на ACTIVE.
+
+6. Блок C. Результаты кампаний
+   6.1. Назначение
+   Показать предпринимателю понятную картину, как сработало продвижение:
+   без сложных метрик,
+   с упором на результат: охват, вовлечённость, заявки, наиболее эффективные каналы.
+   6.2. Пользовательский поток
+   Шаг C1. Список кампаний
+   Экран:
+   Таблица или карточки кампаний:
+   Название кампании
+   Цель
+   Статус: DRAFT, ACTIVE, FINISHED
+   Краткая метрика: например, «Охват: 13 200, Заявок: 31»
+   Данные: GET /api/promotion/campaigns?business_id=...
+
+Шаг C2. Экран «Результаты продвижения» (детали кампании)
+Показывает:
+Основные показатели (CampaignMetrics):
+Охват (суммарно)
+Вовлечённость (лайки/клики/сообщения)
+Заявки/обращения (если будут интеграции/ручной ввод)
+График:
+Ось X: дни
+Ось Y: охват/клики или композитный KPI
+По каналам:
+Instagram: охват, вовлечённость
+Telegram: охват, клики
+Прочие
+Итоговый вывод системы (короткий текст):
+«Лучше всего сработал Instagram, основная активность пришлась на 3–5 день кампании. Рекомендуется повторить подобный формат постов и усилить работу с отзывами.»
+
+7. Сущности данных (укрупнённо)
+   (Ты их уже видел, но теперь в рамках одного модуля.)
+   7.1. Общие
+   BusinessProfile
+   MarketingAnalysis
+   MarketInsights
+   CompetitorInsights
+   AudienceProfile
+   ChannelInsights
+   SwotAnalysis
+   Recommendation
+   7.2. Продвижение
+   Campaign
+   CampaignGoal
+   Strategy
+   Channel
+   CampaignChannel
+   ContentItem
+   CampaignMetrics
+   Связь главная:Campaign.analysis_id → MarketingAnalysis.id
+
+8. Важные бизнес-правила и нюансы
+   Пользователь не выбирает тип продвижения (“таргет” / “контекст”) — только цель, всё остальное решает система.
+   Не задаём вопрос про бюджет на этом этапе (подписная модель).
+   Не перегружаем терминами: CTA, CTR, CPC и т.д. — только человекочитаемые объяснения.
+   В модуле «Маркетинг» нет технических слов “AI”, “нейросеть”, вместо этого — “система”, “анализ”.
+   Переход от блока Анализа к Продвижению — мягкий, логичный, без ощущения “другого продукта”.
+
+9. Нефункциональные требования (кратко)
+   Все тексты для пользователя — на русском.
+   Логирование действий пользователя и ключевых событий.
+   API версионируемый: /api/v1/...
+   Архитектура должна позволять вынести анализ и кампании в отдельные сервисы/очереди при росте нагрузки.