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

**Версия 2.0**

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

---

## Backend (Spring Boot)

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

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

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

-   **`Channel`**: Каналы для постинга.
    ```java
    @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`**: Маркетинговые кампании.
    ```java
    @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`**: Очередь контента для публикации.
    ```java
    @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`**: Опубликованные сообщения.
    ```java
    @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`**: Срезы по ключевым метрикам для аналитики.
    ```java
    @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-эндпоинтов.