# API Документация: Маркетинговый анализ

## Обзор

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

## Эндпоинт

**POST** `/api/marketing/analysis/start`

### Базовый URL

```
https://api.konturai.kz/api/marketing/analysis/start
```

## Запрос

### Заголовки

```
Content-Type: application/json
Authorization: Bearer {access_token}  // Опционально, если требуется аутентификация
```

### Тело запроса (JSON)

| Поле             | Тип    | Обязательный | Описание                       | Пример значения                  |
| ---------------- | ------ | ------------ | ------------------------------ | -------------------------------- |
| `product`        | string | ✅           | Название продукта или услуги   | "Веб-разработка"                 |
| `location`       | string | ✅           | Географическая локация работы  | "Алматы, Казахстан"              |
| `client`         | string | ✅           | Тип целевой аудитории          | "B2B клиенты"                    |
| `differentiator` | string | ✅           | Уникальные особенности бизнеса | "Быстрая разработка за 2 недели" |

### Валидация полей

#### `product` (string, обязательное)

-   **Минимальная длина**: 3 символа
-   **Максимальная длина**: 200 символов
-   **Паттерн**: Разрешены буквы, цифры, пробелы, дефисы, запятые
-   **Ошибка валидации**: `"product": "Поле 'product' должно содержать от 3 до 200 символов"`

#### `location` (string, обязательное)

-   **Минимальная длина**: 2 символа
-   **Максимальная длина**: 150 символов
-   **Паттерн**: Разрешены буквы, цифры, пробелы, запятые, дефисы
-   **Ошибка валидации**: `"location": "Поле 'location' должно содержать от 2 до 150 символов"`

#### `client` (string, обязательное)

-   **Допустимые значения**:
    -   `"B2B клиенты"`
    -   `"B2C клиенты"`
    -   `"Частные лица"`
    -   `"Корпорации"`
    -   `"Малый бизнес"`
-   **Ошибка валидации**: `"client": "Поле 'client' должно быть одним из: B2B клиенты, B2C клиенты, Частные лица, Корпорации, Малый бизнес"`

#### `differentiator` (string, обязательное)

-   **Минимальная длина**: 10 символов
-   **Максимальная длина**: 500 символов
-   **Паттерн**: Разрешены любые символы
-   **Ошибка валидации**: `"differentiator": "Поле 'differentiator' должно содержать от 10 до 500 символов"`

### Пример запроса

```json
{
    "product": "Разработка мобильных приложений",
    "location": "Нур-Султан, Казахстан",
    "client": "B2B клиенты",
    "differentiator": "Специализируемся на быстрой разработке MVP за 4 недели с использованием современных технологий"
}
```

## Ответ

### Успешный ответ (200 OK)

```json
{
    "success": true,
    "data": {
        "analysisId": "550e8400-e29b-41d4-a716-446655440000",
        "status": "processing",
        "estimatedCompletionTime": "2025-01-20T15:30:00Z",
        "message": "Анализ запущен успешно. Результаты будут готовы в течение 5-10 минут."
    }
}
```

#### Поля ответа

| Поле                           | Тип     | Описание                                                  |
| ------------------------------ | ------- | --------------------------------------------------------- |
| `success`                      | boolean | Флаг успешности операции                                  |
| `data.analysisId`              | string  | Уникальный идентификатор анализа (UUID)                   |
| `data.status`                  | string  | Статус анализа: `"processing"`, `"completed"`, `"failed"` |
| `data.estimatedCompletionTime` | string  | ISO 8601 дата/время ожидаемого завершения анализа         |
| `data.message`                 | string  | Информационное сообщение для пользователя                 |

### Асинхронная обработка (202 Accepted)

Если анализ требует длительной обработки, сервер может вернуть статус 202:

```json
{
    "success": true,
    "data": {
        "analysisId": "550e8400-e29b-41d4-a716-446655440000",
        "status": "queued",
        "queuePosition": 3,
        "estimatedWaitTime": 300,
        "message": "Запрос добавлен в очередь. Примерное время ожидания: 5 минут."
    }
}
```

## Обработка ошибок

### Ошибки валидации (400 Bad Request)

```json
{
    "success": false,
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "Ошибка валидации входных данных",
        "details": {
            "product": "Поле 'product' обязательно для заполнения",
            "client": "Недопустимое значение поля 'client'"
        }
    }
}
```

### Ошибка аутентификации (401 Unauthorized)

```json
{
    "success": false,
    "error": {
        "code": "UNAUTHORIZED",
        "message": "Требуется аутентификация"
    }
}
```

### Ошибка сервера (500 Internal Server Error)

```json
{
    "success": false,
    "error": {
        "code": "INTERNAL_SERVER_ERROR",
        "message": "Произошла внутренняя ошибка сервера. Попробуйте позже."
    }
}
```

### Ошибка таймаута (504 Gateway Timeout)

```json
{
    "success": false,
    "error": {
        "code": "TIMEOUT",
        "message": "Превышено время ожидания ответа от сервиса анализа"
    }
}
```

## Получение результатов анализа

После успешного запуска анализа, результаты можно получить по идентификатору:

**GET** `/api/marketing/analysis/{analysisId}`

### Пример запроса

```
GET /api/marketing/analysis/550e8400-e29b-41d4-a716-446655440000
```

### Пример ответа (когда анализ завершен)

```json
{
    "success": true,
    "data": {
        "analysisId": "550e8400-e29b-41d4-a716-446655440000",
        "status": "completed",
        "createdAt": "2025-01-20T15:00:00Z",
        "completedAt": "2025-01-20T15:08:00Z",
        "report": {
            "summary": "Краткое резюме анализа...",
            "targetAudience": {
                "description": "Описание целевой аудитории...",
                "channels": ["Instagram", "LinkedIn", "Telegram"]
            },
            "recommendations": ["Рекомендация 1", "Рекомендация 2"],
            "strategy": {
                "duration": "2 недели",
                "channels": ["Instagram", "Telegram", "21MC"],
                "contentTypes": ["посты", "сторис", "баннеры"]
            },
            "pdfUrl": "/api/marketing/analysis/550e8400-e29b-41d4-a716-446655440000/download"
        }
    }
}
```

### Статусы анализа

-   `queued` - Запрос в очереди на обработку
-   `processing` - Анализ выполняется
-   `completed` - Анализ завершен успешно
-   `failed` - Анализ завершился с ошибкой

## Рекомендации по реализации

### 1. Валидация на бэкенде

```java
// Пример валидации (Java/Spring Boot)
@PostMapping("/api/marketing/analysis/start")
public ResponseEntity<?> startAnalysis(@Valid @RequestBody MarketingAnalysisRequest request) {
    // Валидация выполняется автоматически через @Valid
    // Дополнительная бизнес-логика валидации
    if (!isValidClientType(request.getClient())) {
        return ResponseEntity.badRequest()
            .body(new ErrorResponse("VALIDATION_ERROR", "Недопустимый тип клиента"));
    }
    // Обработка запроса
}
```

### 2. Асинхронная обработка

Рекомендуется использовать асинхронную обработку для длительных операций:

```java
@Async
public CompletableFuture<AnalysisResult> processAnalysis(MarketingAnalysisRequest request) {
    // Длительная обработка
    // Генерация отчета
    // Сохранение результатов
    return CompletableFuture.completedFuture(result);
}
```

### 3. Хранение данных

Рекомендуемая структура таблицы в БД:

```sql
CREATE TABLE marketing_analysis (
    id UUID PRIMARY KEY,
    product VARCHAR(200) NOT NULL,
    location VARCHAR(150) NOT NULL,
    client_type VARCHAR(50) NOT NULL,
    differentiator TEXT NOT NULL,
    status VARCHAR(20) NOT NULL,
    created_at TIMESTAMP NOT NULL,
    completed_at TIMESTAMP,
    user_id UUID, -- Если требуется аутентификация
    report_data JSONB, -- JSON с результатами анализа
    CONSTRAINT valid_client_type CHECK (client_type IN (
        'B2B клиенты', 'B2C клиенты', 'Частные лица', 'Корпорации', 'Малый бизнес'
    )),
    CONSTRAINT valid_status CHECK (status IN (
        'queued', 'processing', 'completed', 'failed'
    ))
);
```

### 4. Интеграция с AI сервисом

Если используется внешний AI сервис для генерации анализа:

```java
public AnalysisResult generateAnalysis(MarketingAnalysisRequest request) {
    // Подготовка промпта для AI
    String prompt = String.format(
        "Проанализируй бизнес:\n" +
        "Продукт: %s\n" +
        "Локация: %s\n" +
        "Клиенты: %s\n" +
        "Уникальность: %s\n" +
        "Создай маркетинговую стратегию...",
        request.getProduct(),
        request.getLocation(),
        request.getClient(),
        request.getDifferentiator()
    );

    // Вызов AI API
    return aiService.generateReport(prompt);
}
```

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

```java
@ExceptionHandler(ValidationException.class)
public ResponseEntity<ErrorResponse> handleValidationException(ValidationException e) {
    return ResponseEntity.badRequest()
        .body(new ErrorResponse("VALIDATION_ERROR", e.getMessage(), e.getDetails()));
}

@ExceptionHandler(Exception.class)
public ResponseEntity<ErrorResponse> handleGenericException(Exception e) {
    log.error("Unexpected error", e);
    return ResponseEntity.status(500)
        .body(new ErrorResponse("INTERNAL_SERVER_ERROR", "Внутренняя ошибка сервера"));
}
```

## Тестирование

### Примеры тестовых запросов

#### Успешный запрос

```bash
curl -X POST https://api.konturai.kz/api/marketing/analysis/start \
  -H "Content-Type: application/json" \
  -d '{
    "product": "Разработка мобильных приложений",
    "location": "Алматы, Казахстан",
    "client": "B2B клиенты",
    "differentiator": "Специализируемся на быстрой разработке MVP за 4 недели"
  }'
```

#### Запрос с ошибкой валидации

```bash
curl -X POST https://api.konturai.kz/api/marketing/analysis/start \
  -H "Content-Type: application/json" \
  -d '{
    "product": "AB",
    "location": "Алматы",
    "client": "Неверный тип",
    "differentiator": "Коротко"
  }'
```

## Примечания

1. **Аутентификация**: Если требуется аутентификация, используйте JWT токен в заголовке `Authorization`
2. **Rate Limiting**: Рекомендуется ограничить количество запросов на пользователя (например, 10 запросов в час)
3. **Кэширование**: Можно кэшировать результаты для одинаковых запросов
4. **Логирование**: Все запросы должны логироваться для отладки и аналитики
5. **Мониторинг**: Отслеживайте время выполнения анализа и процент успешных завершений