diff --git a/API Документация: Генерация стратегии продвижения (Frontend/Документация для фронтенда: Генерация изображений для постов.md b/API Документация: Генерация стратегии продвижения (Frontend/Документация для фронтенда: Генерация изображений для постов.md new file mode 100644 index 0000000..e201db1 --- /dev/null +++ b/API Документация: Генерация стратегии продвижения (Frontend/Документация для фронтенда: Генерация изображений для постов.md @@ -0,0 +1,548 @@ +# Документация для фронтенда: Генерация изображений для постов + +## Обзор изменений + +В систему добавлена автоматическая генерация изображений для постов в социальных сетях. Теперь при создании маркетинговой стратегии для каждого поста автоматически генерируется уникальное изображение с помощью OpenAI DALL-E API. Изображения сохраняются в MinIO и прикрепляются к постам при публикации в Facebook. + +--- + +## Новые поля в API + +### 1. PostCalendarItem (Календарь постов) + +В объекте `PostCalendarItem` добавлены два новых поля для работы с изображениями: + +| Поле | Тип | Описание | Обязательное | +| --------------- | ------ | ------------------------------------------------------------ | ------------ | +| `imageUrl` | string | Имя файла изображения (используется для получения через API) | Нет | +| `imageFilename` | string | Имя файла изображения | Нет | + +**Важно:** + +- Поля могут быть `null`, если генерация изображения не удалась +- В этом случае пост публикуется без изображения +- Оба поля содержат одинаковое значение (имя файла) +- Для получения изображения используйте API эндпоинт `/api/marketing/analysis/images/{imageFilename}` + +### 2. PostingTask (Задачи публикации) + +В объекте `PostingTask` также добавлены поля для изображений: + +| Поле | Тип | Описание | Обязательное | +| --------------- | ------ | ------------------------------------------------------------ | ------------ | +| `imageUrl` | string | Имя файла изображения (используется для получения через API) | Нет | +| `imageFilename` | string | Имя файла изображения | Нет | + +--- + +## Изменения в API эндпоинтах + +### GET `/api/marketing/strategy/{strategyId}` + +Ответ теперь включает поля изображений в каждом элементе календаря постов. + +#### Пример ответа + +```json +{ + "success": true, + "data": { + "strategyId": "507f1f77bcf86cd799439011", + "analysisId": "507f1f77bcf86cd799439012", + "status": "completed", + "strategy": { + "postCalendar": [ + { + "publishDate": "2024-01-15T10:00:00", + "platform": "Facebook", + "contentType": "пост", + "theme": "Презентация нового продукта", + "postText": "Мы рады представить наш новый продукт...", + "hashtags": ["#новинка", "#продукт", "#маркетинг"], + "publishTime": "10:00", + "imageUrl": "post_image_1705312800000_1234567890.png", + "imageFilename": "post_image_1705312800000_1234567890.png" + } + ] + } + } +} +``` + +### GET `/api/marketing/analysis/{analysisId}/strategy` + +Аналогично, ответ включает поля изображений в календаре постов. + +--- + +## Получение изображений + +### Через бэкенд API + +Все изображения должны получаться через бэкенд API. Прямой доступ к MinIO с фронтенда не предусмотрен. + +#### Эндпоинт для получения изображения + +**GET** `/api/marketing/analysis/images/{imageFilename}` + +Возвращает изображение поста в формате PNG. + +#### Параметры пути + +| Параметр | Тип | Описание | +| --------------- | ------ | --------------------- | +| `imageFilename` | string | Имя файла изображения | + +#### Заголовки запроса + +| Заголовок | Тип | Обязательный | Описание | +| --------------- | ------ | ------------ | ------------------------------------ | +| `Authorization` | string | Да | JWT токен в формате `Bearer {token}` | + +#### Пример запроса + +```javascript +const imageUrl = `/api/marketing/analysis/images/${post.imageFilename}`; + +fetch(imageUrl, { + headers: { + Authorization: `Bearer ${token}` + } +}) + .then((response) => { + if (response.ok) { + return response.blob(); + } + throw new Error('Failed to load image'); + }) + .then((blob) => { + const imageObjectUrl = URL.createObjectURL(blob); + // Используйте imageObjectUrl для отображения + }); +``` + +#### Пример ответа + +- **Успешный ответ (200 OK):** + + - Content-Type: `image/png` + - Body: бинарные данные изображения PNG + +- **Ошибка 401 Unauthorized:** + + - Токен отсутствует или невалиден + +- **Ошибка 404 Not Found:** + + - Изображение не найдено на сервере + +- **Ошибка 500 Internal Server Error:** + - Внутренняя ошибка сервера при загрузке изображения + +#### Кэширование + +Сервер возвращает заголовок `Cache-Control: public, max-age=3600`, что позволяет браузеру кэшировать изображения на 1 час. + +--- + +## Рекомендации по отображению + +### 1. Проверка наличия изображения + +Всегда проверяйте наличие изображения перед отображением: + +```javascript +// Пример на JavaScript/TypeScript +const PostCard = ({ post, apiBaseUrl, authToken }) => { + const hasImage = post.imageUrl && post.imageFilename; + const imageUrl = hasImage ? `${apiBaseUrl}/api/marketing/analysis/images/${post.imageFilename}` : null; + + return ( +
{post.postText}
+ + {imageUrl ? ( +Изображение не сгенерировано
+{post.postText}
+ +Изображение не сгенерировано
+{{ post.postText }}
+ + + + +