core/Техническое задание №3 Модуль AI-генерации контента.md

Техническое задание №3: Модуль AI-генерации контента

Цель: Реализовать ключевую функцию SMM-модуля — автоматическую генерацию черновиков контента (текст и изображения) с помощью AI. Этот модуль будет ядром "умного" контент-плана, позволяя пользователям быстро создавать посты на заданную тему.

---

1. Data Transfer Objects (DTOs)

GenerateContentRequest.java

Используется для запроса на генерацию нового поста.

public class GenerateContentRequest {
    @NotNull
    private UUID campaignId; // К какой кампании относится пост
    @NotBlank
    private String topic;    // Тема для генерации
    @NotBlank
    private String locale;   // Локаль ("ru" или "kk")
}

GeneratedContentDto.java

Используется в ответе и представляет собой DTO для ContentQueue.

public class GeneratedContentDto {
    private UUID id;
    private UUID campaignId;
    private String locale;
    private String topic;
    private PostDraftDto postDraft;
    private List<String> assetsRefs;
    private ContentStatus status;
}

// Вспомогательный DTO для JSON-поля postDraft
public class PostDraftDto {
    private String title;
    private String body;
    private List<String> hashtags;
}

---

2. Интеграция с внешними AI-сервисами

Необходимо создать два новых сервиса-клиента для взаимодействия с внешними AI API.

LanguageModelClient.java (Агент "Writer/Researcher")

• Задача: Отправлять запросы к LLM (например, Ollama, OpenAI) для генерации текста.
• Методы:
  • String generatePostText(String topic, String locale): Генерирует основной текст поста.
  • String generateTitle(String postText): Генерирует заголовок на основе текста.
  • List<String> generateHashtags(String postText): Генерирует хештеги.
• Промпты (примерные):
  • Для текста: "Напиши экспертный пост для [соцсеть] на тему '[topic]' на [locale] языке. Стиль: [стиль]. Целевая аудитория: [аудитория]."
  • Для хештегов: "Подбери 5-7 релевантных хештегов для этого текста. В ответе дай только список через запятую."

ImageGenerationClient.java (Агент "Designer")

• Задача: Отправлять запросы к API для генерации изображений (например, Stable Diffusion, Midjourney API).
• Методы:
  • String generateImage(String textPrompt): Принимает текстовое описание и возвращает URL или путь к сгенерированному изображению.
• Логика: Сервис должен уметь формировать промпт для картинки на основе темы и основного текста поста.

---

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

ContentGenerationService.java

Основной сервис, который оркестрирует процесс генерации.

• Зависимости: LanguageModelClient, ImageGenerationClient, ContentQueueRepository, CampaignRepository.
• Основной метод: GeneratedContentDto generateContent(GenerateContentRequest request)
• Алгоритм работы метода:
  1. Проверить существование кампании по campaignId из запроса. Если не найдена — ошибка.
  2. Вызвать languageModelClient.generatePostText() для создания основного текста.
  3. На основе полученного текста вызвать languageModelClient.generateTitle() и languageModelClient.generateHashtags().
  4. Сформировать объект PostDraftDto из полученных текста, заголовка и хештегов.
  5. Вызвать imageGenerationClient.generateImage(), передав промпт, основанный на теме и тексте.
  6. Создать новую сущность ContentQueue.
  7. Заполнить ее данными: campaign, topic, locale, postDraft (в виде JSON), assetsRefs (массив с путем к картинке).
  8. Установить status = ContentStatus.DRAFT.
  9. Сохранить сущность в базу данных через ContentQueueRepository.
  10. Вернуть GeneratedContentDto созданного черновика.

---

4. API Endpoint (REST Controller)

ContentController.java

Необходимо добавить новый эндпоинт в существующий ContentController.

• POST /api/smm/content/generate
  • Описание: Запускает процесс генерации нового черновика поста.
  • Тело запроса: GenerateContentRequest
  • Успешный ответ (201 Created): GeneratedContentDto (созданный черновик).
  • Ответ при ошибке (400 Bad Request): Если тело запроса невалидно.
  • Ответ при ошибке (503 Service Unavailable): Если внешние AI-сервисы недоступны.

---

5. Обработка ошибок

• Сервис должен корректно обрабатывать ошибки от внешних API (LLM, Image API). Если один из сервисов недоступен, вся операция должна завершиться ошибкой, и в лог должно быть записано информативное сообщение.
• Необходимо реализовать глобальный обработчик исключений (@ControllerAdvice) для перехвата ошибок от AI-сервисов и возврата клиенту статуса 503 Service Unavailable.

---

Критерии выполнения

• Созданы и реализованы LanguageModelClient и ImageGenerationClient.
• Реализован ContentGenerationService с полной бизнес-логикой по генерации и сохранению черновика.
• В ContentController добавлен эндпоинт POST /api/smm/content/generate, который корректно принимает запрос и возвращает DTO созданного черновика.
• При вызове эндпоинта в таблице content_queue появляется новая запись со статусом DRAFT, заполненными полями postDraft и assetsRefs.
• Реализована корректная обработка ошибок от внешних AI-сервисов.