marketing/Техническое задание Модуль SMM-автоматизации.md

Техническое задание: Модуль SMM-автоматизации

Версия 2.0

Это ТЗ описывает разработку backend и frontend компонентов для модуля AI-продвижения в соцсетях. Оркестрация через n8n на данном этапе не реализуется, но архитектура закладывает основу для будущей интеграции. Управление процессами временно осуществляется через UI.

---

Backend (Spring Boot)

Backend будет содержать всю бизнес-логику, модели данных и API для взаимодействия с frontend и внешними сервисами (соцсети, LLM).

1. Модели данных (JPA Entities)

На основе схемы БД из первоначального ТЗ, создаем следующие JPA-сущности:

• Channel: Каналы для постинга.

  @Entity
  public class Channel {
      @Id @GeneratedValue
      private UUID id;
      private String name; // e.g., "Telegram Official"
      private String type; // ENUM: TELEGRAM, VK, INSTAGRAM, etc.
      private String apiKeyRef; // Ссылка на secret в Vault или аналоге
      private boolean isActive;
  }
  

• Campaign: Маркетинговые кампании.

  @Entity
  public class Campaign {
      @Id @GeneratedValue
      private UUID id;
      private String name;
      private String goal;
      private BigDecimal budget;
      private ZonedDateTime startAt;
      private ZonedDateTime endAt;
      private String status; // ENUM: PLANNED, ACTIVE, COMPLETED
  }
  

• ContentQueue: Очередь контента для публикации.

  @Entity
  public class ContentQueue {
      @Id @GeneratedValue
      private UUID id;
      @ManyToOne
      private Campaign campaign;
      private String locale; // ENUM: "ru", "kk"
      private String topic;
      @JdbcTypeCode(SqlTypes.JSON)
      private String postDraft; // JSON: { "title": "...", "body": "...", "hashtags": [...] }
      @JdbcTypeCode(SqlTypes.JSON)
      private String assetsRefs; // JSON: ["path/to/image1.jpg"]
      private ZonedDateTime scheduledAt;
      private int priority;
      private String status; // ENUM: DRAFT, PENDING_APPROVAL, APPROVED, PUBLISHED, FAILED
  }
  

• Message: Опубликованные сообщения.

  @Entity
  public class Message {
      @Id @GeneratedValue
      private UUID id;
      @ManyToOne
      private Channel channel;
      @OneToOne
      private ContentQueue content;
      private String externalId; // ID поста в соцсети
      private String url;
      private ZonedDateTime postedAt;
  }
  

• KpiSnapshot: Срезы по ключевым метрикам для аналитики.

  @Entity
  public class KpiSnapshot {
      @Id @GeneratedValue
      private UUID id;
      private LocalDate date;
      @ManyToOne
      private Channel channel;
      private String metric; // e.g., "CTR", "ER", "LEADS"
      private BigDecimal value;
  }
  

---

2. API Endpoints (REST Controllers)

Создаем REST контроллеры для управления сущностями.

CampaignController

• GET /api/smm/campaigns — получить список всех кампаний.
• GET /api/smm/campaigns/{id} — получить детали одной кампании.
• POST /api/smm/campaigns — создать новую кампанию.
  • Body: CampaignDto { name, goal, budget, startAt, endAt }
• PUT /api/smm/campaigns/{id} — обновить кампанию.

ContentController

• GET /api/smm/content — получить очередь контента с фильтрами (по дате, статусу, кампании).
• GET /api/smm/content/{id} — получить конкретный элемент из очереди.
• POST /api/smm/content/generate — (Ключевой метод) запустить генерацию контента.
  • Body: GenerateRequestDto { topic, locale, channelType }
  • Response: ContentQueue в статусе DRAFT.
• PUT /api/smm/content/{id} — обновить пост вручную (текст, картинки, время публикации).
• POST /api/smm/content/{id}/approve — изменить статус на APPROVED.
• DELETE /api/smm/content/{id} — удалить черновик.

PublishingController

• POST /api/smm/publishing/post/{contentId} — принудительно опубликовать пост (для ручного управления).

ChannelController

• GET /api/smm/channels — получить список подключенных каналов.
• POST /api/smm/channels — подключить новый канал (сохранить токен).

---

3. Сервисный слой (Business Logic)

Логика "AI-агентов" реализуется в сервисах.

• CampaignService: CRUD-операции для кампаний.
• ContentGenerationService:
  • Интегрируется с API LLM (Writer, Researcher).
  • Интегрируется с API для генерации изображений (Designer).
  • Выполняет проверку на стоп-слова (Compliance).
  • Создает запись в ContentQueue со статусом DRAFT.
• PublishingService:
  • Содержит логику для постинга в каждый конкретный канал (Telegram, VK и т.д.) через их API.
  • Запускается по расписанию (@Scheduled в Spring) для постов со статусом APPROVED и подошедшим scheduledAt.
  • После успешной публикации создает запись в Message и обновляет статус в ContentQueue.
• AnalyticsService:
  • По расписанию собирает статистику по опубликованным постам (Message).
  • Сохраняет данные в KpiSnapshot.

4. Placeholder для n8n

Для будущей интеграции создаем специальный контроллер.

WorkflowTriggerController

• POST /api/smm/workflows/start-weekly-planning — этот эндпоинт будет вызывать n8n, чтобы запустить цепочку. Сейчас он не используется, но должен быть заложен в архитектуру. Пока что эту логику будет инициировать пользователь через UI.

---

Frontend (Vue.js)

Frontend-модуль предоставляет пользовательский интерфейс для управления всем SMM-циклом вручную.

1. Компоненты и страницы (Views & Components)

Страница "Кампании" (/smm/campaigns)

• Вид: Таблица со списком всех кампаний (id, name, status, period).
• Функционал:
  • Кнопка "Создать кампанию", открывающая модальное окно с формой.
  • Просмотр и редактирование существующих кампаний.

Страница "Контент-план" (/smm/content-plan)

• Вид: Основной рабочий экран. Реализовать в виде календаря или Канбан-доски (колонки: "Черновик", "На согласовании", "Запланировано", "Опубликовано").
• Функционал:
  • Отображение карточек постов из ContentQueue. На карточке: тема, канал, дата.
  • Кнопка "Сгенерировать идею/пост", которая вызывает POST /api/smm/content/generate.
  • Drag-n-drop карточек для изменения даты публикации (scheduledAt).
  • Клик на карточку открывает модальное окно редактора поста.

Компонент "Редактор поста"

• Вид: Модальное окно или отдельная страница.
• Поля:
  • Редактируемый текст поста для RU и KZ версий (вкладки или два поля).
  • Превью сгенерированного изображения. Возможность загрузить свое.
  • Выбор даты и времени публикации.
  • Статус поста.
• Кнопки:
  • "Сохранить" (PUT /api/smm/content/{id}).
  • "Перегенерировать" (повторный вызов генерации для этого поста).
  • "Согласовать" (POST /api/smm/content/{id}/approve).
  • "Опубликовать сейчас" (POST /api/smm/publishing/post/{contentId}).
  • "Удалить".

Страница "Аналитика" (/smm/analytics)

• Вид: Дашборд с графиками и ключевыми метриками (CTR, ER, Лиды) из KpiSnapshot.
• Функционал: Фильтры по дате, кампании, каналу.

Страница "Настройки" (/smm/settings)

• Вид: Управление подключенными каналами (Channel).
• Функционал: Добавление новых аккаунтов соцсетей (ввод токенов API), проверка статуса подключения.

2. Взаимодействие с Backend

• Использовать axios или аналогичный HTTP-клиент для всех запросов к API.
• Для управления состоянием (списки кампаний, контента) использовать Pinia.
• Обеспечить обработку ошибок API и отображение уведомлений для пользователя.

Этот подход позволит вам разработать и протестировать всю основную функциональность модуля независимо от n8n, а когда придет время, вы просто настроите n8n на вызов уже готовых и отлаженных API-эндпоинтов.