Merge remote-tracking branch 'origin/main'

# Conflicts: # API Документация Генерация стратегии продвижения (Frontend/Документация для фронтенда Генерация изображений для постов.md
2026-02-25 10:32:12 +05:00
parent db1aa7a154 4092659baa
commit b517ee4ba0
1 changed files with 548 additions and 0 deletions
@@ -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 (
        <div className="post-card">
            <h3>{post.theme}</h3>
            <p>{post.postText}</p>
            {imageUrl ? (
                <img
                    src={imageUrl}
                    alt={post.theme}
                    onError={(e) => {
                        // Fallback если изображение не загрузилось
                        e.target.style.display = 'none';
                    }}
                    // Если требуется авторизация, используйте fetch с заголовками
                />
            ) : (
                <div className="no-image-placeholder">Изображение не сгенерировано</div>
            )}
            <div className="hashtags">
                {post.hashtags.map((tag) => (
                    <span key={tag}>#{tag}</span>
                ))}
            </div>
        </div>
    );
 };
 ```
 ### 2. Обработка ошибок загрузки
 Всегда предусматривайте fallback для случаев, когда:
 -   Изображение не сгенерировано (`imageUrl` = `null`)
 -   Изображение не найдено на сервере
 -   Ошибка при загрузке изображения
 ```javascript
 const [imageError, setImageError] = useState(false);
 const getImageUrl = (imageFilename) => {
    if (!imageFilename) return null;
    return `${API_BASE_URL}/api/marketing/analysis/images/${imageFilename}`;
 };
 const handleImageError = () => {
    setImageError(true);
 };
 return (
    <>
        {post.imageUrl && !imageError ? (
            <img src={getImageUrl(post.imageFilename)} alt={post.theme} onError={handleImageError} />
        ) : (
            <div className="image-placeholder">
                <Icon name="image" />
                <span>Изображение недоступно</span>
            </div>
        )}
    </>
 );
 ```
 ### 3. Оптимизация загрузки
 Рекомендуется использовать lazy loading для изображений:
 ```javascript
 <img src={post.imageUrl ? `${API_BASE_URL}/api/marketing/analysis/images/${post.imageFilename}` : null} alt={post.theme} loading="lazy" className="post-image" />
 ```
 ### 4. Размеры изображений
 Изображения генерируются в размере **1024x1024 пикселей** (квадратные). При отображении учитывайте это при настройке CSS:
 ```css
 .post-image {
    width: 100%;
    max-width: 512px;
    height: auto;
    border-radius: 8px;
    object-fit: cover;
 }
 ```
 ---
 ## Примеры использования
 ### React компонент для отображения поста
 ```typescript
 import React, { useState } from 'react';
 interface PostCalendarItem {
  publishDate: string;
  platform: string;
  contentType: string;
  theme: string;
  postText: string;
  hashtags: string[];
  publishTime: string;
  imageUrl?: string | null;
  imageFilename?: string | null;
 }
 interface PostCardProps {
  post: PostCalendarItem;
  apiBaseUrl: string;
 }
 const PostCard: React.FC<PostCardProps> = ({ post, apiBaseUrl }) => {
  const [imageError, setImageError] = useState(false);
  const getImageUrl = (): string | null => {
    if (!post.imageFilename) return null;
    return `${apiBaseUrl}/api/marketing/analysis/images/${post.imageFilename}`;
  };
  const imageUrl = getImageUrl();
  return (
    <div className='post-card'>
      <div className='post-header'>
        <span className='platform-badge'>{post.platform}</span>
        <span className='content-type'>{post.contentType}</span>
        <span className='publish-time'>{post.publishTime}</span>
      </div>
      <h3 className='post-theme'>{post.theme}</h3>
      {imageUrl && !imageError ? (
        <div className='post-image-container'>
          <img
            src={imageUrl}
            alt={post.theme}
            className='post-image'
            loading='lazy'
            onError={() => setImageError(true)}
          />
        </div>
      ) : (
        <div className='no-image-placeholder'>
          <svg width='64' height='64' viewBox='0 0 24 24' fill='none'>
            <path
              d='M21 19V5c0-1.1-.9-2-2-2H5c-1.1 0-2 .9-2 2v14c0 1.1.9 2 2 2h14c1.1 0 2-.9 2-2zM8.5 13.5l2.5 3.01L14.5 12l4.5 6H5l3.5-4.5z'
              fill='currentColor'
            />
          </svg>
          <p>Изображение не сгенерировано</p>
        </div>
      )}
      <p className='post-text'>{post.postText}</p>
      <div className='post-hashtags'>
        {post.hashtags.map((tag, index) => (
          <span key={index} className='hashtag'>
            {tag.startsWith('#') ? tag : `#${tag}`}
          </span>
        ))}
      </div>
      <div className='post-footer'>
        <span className='publish-date'>
          {new Date(post.publishDate).toLocaleDateString('ru-RU')}
        </span>
      </div>
    </div>
  );
 };
 export default PostCard;
 ```
 ### Vue компонент
 ```vue
 <template>
    <div class="post-card">
        <div class="post-header">
            <span class="platform-badge">{{ post.platform }}</span>
            <span class="content-type">{{ post.contentType }}</span>
            <span class="publish-time">{{ post.publishTime }}</span>
        </div>
        <h3 class="post-theme">{{ post.theme }}</h3>
        <div v-if="imageUrl && !imageError" class="post-image-container">
            <img :src="imageUrl" :alt="post.theme" class="post-image" loading="lazy" @error="imageError = true" />
        </div>
        <div v-else class="no-image-placeholder">
            <Icon name="image" />
            <p>Изображение не сгенерировано</p>
        </div>
        <p class="post-text">{{ post.postText }}</p>
        <div class="post-hashtags">
            <span v-for="(tag, index) in post.hashtags" :key="index" class="hashtag">
                {{ tag.startsWith('#') ? tag : `#${tag}` }}
            </span>
        </div>
        <div class="post-footer">
            <span class="publish-date">
                {{ formatDate(post.publishDate) }}
            </span>
        </div>
    </div>
 </template>
 <script setup lang="ts">
 import { computed, ref } from 'vue';
 interface PostCalendarItem {
    publishDate: string;
    platform: string;
    contentType: string;
    theme: string;
    postText: string;
    hashtags: string[];
    publishTime: string;
    imageUrl?: string | null;
    imageFilename?: string | null;
 }
 const props = defineProps<{
    post: PostCalendarItem;
    apiBaseUrl: string;
 }>();
 const imageError = ref(false);
 const imageUrl = computed(() => {
    if (!props.post.imageFilename) return null;
    return `${props.apiBaseUrl}/api/marketing/analysis/images/${props.post.imageFilename}`;
 });
 const formatDate = (dateString: string) => {
    return new Date(dateString).toLocaleDateString('ru-RU');
 };
 </script>
 ```
 ---
 ## Важные замечания
 ### 1. Генерация изображений
 -   Изображения генерируются **автоматически** при создании стратегии
 -   Процесс генерации может занять время (обычно 10-30 секунд на изображение)
 -   Если генерация не удалась, пост все равно будет создан, но без изображения
 ### 2. Хранение изображений
 -   Все изображения хранятся на бэкенде
 -   Формат изображений: **PNG**
 -   Размер изображений: **1024x1024 пикселей**
 -   Имя файла уникально для каждого поста
 -   Доступ к изображениям только через API эндпоинт
 ### 3. Публикация постов
 -   При публикации поста в Facebook изображение автоматически прикрепляется
 -   Если изображение отсутствует, пост публикуется только с текстом
 -   Это не влияет на успешность публикации
 ### 4. Обратная совместимость
 -   Старые стратегии, созданные до добавления этой функции, не будут иметь изображений
 -   Поля `imageUrl` и `imageFilename` будут `null` для таких постов
 -   Фронтенд должен корректно обрабатывать `null` значения
 ---
 ## Конфигурация
 Для работы с изображениями вам понадобится базовый URL вашего API:
 ```typescript
 // config.ts
 export const API_CONFIG = {
    baseUrl: 'http://your-backend-url' // URL вашего бэкенда
    // Например: 'http://localhost:8080' или 'https://api.example.com'
 };
 ```
 ---
 ## Миграция существующего кода
 Если у вас уже есть компоненты для отображения постов, обновите их следующим образом:
 1. **Добавьте проверку наличия изображения:**
    ```typescript
    const hasImage = post.imageUrl && post.imageFilename;
    ```
 2. **Добавьте отображение изображения:**
    ```jsx
    {
        hasImage && <img src={`${API_BASE_URL}/api/marketing/analysis/images/${post.imageFilename}`} alt={post.theme} />;
    }
    ```
 3. **Обновите типы/интерфейсы:**
    ```typescript
    interface PostCalendarItem {
        // ... существующие поля
        imageUrl?: string | null;
        imageFilename?: string | null;
    }
    ```
 ---
 ## Поддержка
 При возникновении проблем:
 1. Проверьте, что `imageUrl` и `imageFilename` не `null`
 2. Убедитесь, что используете правильный API эндпоинт: `/api/marketing/analysis/images/{imageFilename}`
 3. Проверьте, что JWT токен валиден и передается в заголовке `Authorization`
 4. Проверьте консоль браузера на наличие ошибок сети или авторизации
 5. Убедитесь, что используете правильный базовый URL API
 ---
 ## Пример полного ответа API
 ```json
 {
    "success": true,
    "data": {
        "strategyId": "507f1f77bcf86cd799439011",
        "analysisId": "507f1f77bcf86cd799439012",
        "status": "completed",
        "createdAt": "2024-01-15T10:00:00",
        "completedAt": "2024-01-15T10:05:00",
        "durationWeeks": 4,
        "priorityPlatforms": ["Facebook", "Instagram"],
        "strategy": {
            "weeklyPlans": [
                {
                    "weekNumber": 1,
                    "mainThemes": ["Презентация продукта", "Преимущества"],
                    "contentRecommendations": "Создавайте контент...",
                    "priorityPlatforms": ["Facebook"]
                }
            ],
            "postCalendar": [
                {
                    "publishDate": "2024-01-16T10:00:00",
                    "platform": "Facebook",
                    "contentType": "пост",
                    "theme": "Презентация нового продукта",
                    "postText": "Мы рады представить наш новый продукт, который поможет вам...",
                    "hashtags": ["#новинка", "#продукт", "#маркетинг"],
                    "publishTime": "10:00",
                    "imageUrl": "post_image_1705312800000_1234567890.png",
                    "imageFilename": "post_image_1705312800000_1234567890.png"
                },
                {
                    "publishDate": "2024-01-18T14:00:00",
                    "platform": "Instagram",
                    "contentType": "сторис",
                    "theme": "Преимущества продукта",
                    "postText": "Узнайте о главных преимуществах нашего продукта...",
                    "hashtags": ["#преимущества", "#качество"],
                    "publishTime": "14:00",
                    "imageUrl": null,
                    "imageFilename": null
                }
            ]
        }
    }
 }
 ```
 Обратите внимание, что второй пост не имеет изображения (`imageUrl` и `imageFilename` равны `null`). Это нормальная ситуация, если генерация изображения не удалась.
 ---
 **Дата обновления:** 2024-01-15  
 **Версия API:** 1.0