## Введение

Данный артефакт описывает контракт API и алгоритм для генерации инженерных решений на основе ИИ. Он предназначен для реализации в рамках системы n2j.ru и должен обеспечивать точную обработку запросов, форматирование вывода и обработку ошибок.

## Входные данные (Input)

| Поле | Тип | Описание |
|------|-----|----------|
| `prompt` | String | Человеческое описание инженерной задачи |
| `domain` | String | Домен задачи (например, "автомобиль", "электроника") |
| `constraints` | Array<String> | Ограничения, например, "размер", "мощность", "материал" |

## Выходные данные (Output)

| Поле | Тип | Описание |
|------|-----|----------|
| `solution_id` | UUID | Уникальный ID решения |
| `prompt` | String | Исходный запрос |
| `generated_solution` | JSON | Сгенерированное инженерное решение |
| `status` | Enum("success", "error") | Статус обработки |

## Шаги алгоритма

### 1. Валидация входных данных
- Проверка поля `prompt`: не пустой, максимум 500 символов
- Проверка поля `domain`: допустимые значения: "автомобиль", "электроника", "строительство"
- Проверка массива `constraints`: каждый элемент — строка длиной до 100 символов

### 2. Предобработка запроса
- Приведение к стандартному формату (lowercase, удаление лишних пробелов)
- Очистка от мешающих символов и спецсимволов

### 3. Генерация решения с помощью ИИ
- Запрос к модели `gpt-4-engineering`
- Добавление prompt в формат: "Реализуй инженерное решение для {domain} при следующих ограничениях: {constraints}. {prompt}".

### 4. Постобработка вывода
- Проверка JSON на корректность структуры
- Удаление лишних пробелов и форматирование
- Назначение `solution_id`

### 5. Запись в базу данных
- Сохранение решения с указанием даты создания
- Валидация уникальности `solution_id`

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

| Шаг | Что считается ошибкой | Обработка |
|-----|------------------------|-----------|
| 1   | Некорректный prompt или domain | Ответ с кодом 400 и сообщением "Некорректные входные данные" |
| 2   | Ошибка в данных запроса | Отправка ошибки 500 |
| 3   | Не удалось получить ответ от ИИ | Возврат ошибки 503 с причиной "Ошибка генерации" |
| 4   | Некорректный JSON | Завершение с кодом 500 и сообщением "Невалидный формат решения" |

## Псевдокод алгоритма
```python
# Определение входных данных
input_prompt = request.get("prompt")
input_domain = request.get("domain")
input_constraints = request.get("constraints")

# Валидация
if not input_prompt or len(input_prompt) > 500:
    return error_400("Некорректный prompt")

if input_domain not in ["автомобиль", "электроника", "строительство"]:
    return error_400("Некорректный домен")

# Предобработка
cleaned_prompt = clean(input_prompt)

# Генерация решения
generated_solution = generate_with_ai(prompt=cleaned_prompt, domain=input_domain, constraints=input_constraints)

# Проверка JSON
if not is_valid_json(generated_solution):
    return error_500("Невалидный формат решения")

# Формирование ID и запись
solution_id = uuid4()
save_to_db(solution_id=solution_id, solution=generated_solution)
return {
  "solution_id": solution_id,
  "prompt": input_prompt,
  "generated_solution": generated_solution,
  "status": "success"
}
```

## Ограничения и сложность
- Время генерации: до 3 секунд на запрос
- Объем данных в одном решении: до 10KB
- Максимально возможный размер массива `constraints`: 5 элементов
- Предел на количество одновременных вызовов: 200 запросов/секунда

## Тестовый пример

Вход:
```json
{
  "prompt": "Создать компонент для снижения шума в двигателе",
  "domain": "автомобиль",
  "constraints": ["размер до 10 см", "вес менее 500 г"]
}
```

Выход:
```json
{
  "solution_id": "e7f8a9b0-c2d3-e4f5-g6h7-i8j9k0l1m2n3",
  "prompt": "Создать компонент для снижения шума в двигателе",
  "generated_solution": {
    "component_name": "Шумопоглощающий элемент",
    "description": "Элемент из наноматериала, уменьшающий уровень звука при работе двигателя",
    "dimensions": {"length": "9 см", "width": "5 см", "height": "2 см"},
    "weight": "400 г"
  },
  "status": "success"
}
```

## Проверка на маленьком примере
1. Вводим запрос с `prompt`, `domain` и `constraints`
2. Выполняем шаги алгоритма по порядку
3. Проверяем, что возвращается корректный JSON с `solution_id`
4. Проверяем, что все поля соответствуют формату (валидация)
5. Записываем результат в БД

В случае ошибки — проверяем код 400/500 и сообщение.