Discovery API Reference

Эндпоинты системы «Discovery via Dialogue» предназначены для управления интерактивным процессом подбора подарков.

1. Инициализация сессии

POST /recommendations/init

Метод вызывается сразу после того, как пользователь заполнил квиз. Он создает новую сессию и возвращает первый шаг диалога.

Request Body (`QuizAnswers`)

Стандартный объект ответов на квиз.

Response (`RecommendationSession`)

{
  "session_id": "uuid-string",
  "state": "branching",
  "selected_topic": "Музыка",
  "current_probe": {
    "question": "Так, давай уточним насчет музыки 🎵",
    "options": ["Просто слушает", "Играет сам", "Фанатеет"],
    "can_skip": true
  }
}

2. Взаимодействие (Interaction)

POST /recommendations/interact

Универсальный эндпоинт для всех действий пользователя в процессе поиска.

Request Body

Field	Type	Description
`session_id`	`uuid`	ID текущей сессии
`action`	`string`	Тип действия (см. ниже)
`value`	`string`	Значение (например, выбранная опция или ID гипотезы)

Допустимые Actions:

Action	Value	Эффект
`answer_probe`	Текст ответа / Опция	Переход к гипотезам или уточнение топика.
`like_hypothesis`	`hypothesis_id`	Переход в режим Deep Dive (просмотр всех товаров идеи).
`dislike_hypothesis`	`hypothesis_id`	Скрытие идеи и предложение альтернативы/пивота.
`pivot`	"new_topic" / "psychology"	Ручной запуск смены направления из тупика.

3. Машина состояний (DiscoveryState)

Сессия может находиться в одном из следующих состояний:

quiz: Начальное состояние получения данных.
branching: Система уточняет широкий интерес (выведен current_probe).
showing_hypotheses: На экране карточки идей (наполнен список current_hypotheses).
deep_dive: Пользователь выбрал идею и смотрит только товары по ней.
dead_end: Система не нашла вариантов и предлагает «Спас-карту».

4. Объект Hypothesis (Карточка Идеи)

Объект, который рендерится в интерфейсе (Скрин 3):

title: Заголовок (напр., «В поисках того самого звука»).
description: Описание идеи для пользователя.
primary_gap: Метка стратегии (catalyst, optimizer и т.д.).
preview_products: Список из 3-х товаров (GiftDTO) для наглядности.
search_queries: Внутренние запросы, по которым найдены превью.