SOMNA AI BACKEND — ИНСТРУКЦИЯ ПО ПОДКЛЮЧЕНИЮ
=========================================

1. ОБЩАЯ ИДЕЯ
--------------

Этот бэкенд — универсальный чат/ассистент бренда Somna Secra.
Его можно подключить:
- к любому сайту (через HTTP-запросы или WebSocket/Socket.io),
- к плагину WordPress,
- к любому другому бекэнду или приложению, которое умеет отправлять HTTP/WS-запросы.

Основной сценарий:
- фронтенд/плагин отправляет текст пользователя и (опционально) идентификатор сессии,
- бэкенд отдаёт ответ ассистента + sessionId + историю диалога.


2. HTTP API (REST): ОСНОВНОЙ ЭНДПОИНТ
-------------------------------------

URL (относительный):
- POST /chat/message

Пример полного URL:
- http://YOUR_DOMAIN_OR_IP:PORT/chat/message

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

Обязательные и опциональные поля:

{
  "content": "Текст пользователя",           // ОБЯЗАТЕЛЬНО
  "sessionId": "optional-session-id",       // ОПЦИОНАЛЬНО
  "model": "apifreellm",                    // ОПЦИОНАЛЬНО
  "allowHtml": true,                          // ОПЦИОНАЛЬНО
  "productSelection": false                   // ОПЦИОНАЛЬНО
}

Пояснения:
- content (string, обязательно)
  Текст, который написал пользователь. Это основной вход.

- sessionId (string, опционально)
  Идентификатор текущей сессии диалога.
  - Если НЕ передавать: будет создана новая сессия.
  - Если передавать: диалог продолжится в рамках этой сессии.

- model (string, опционально)
  Имя модели для запроса к FreeLLM. По умолчанию apifreellm, можно не трогать.

- allowHtml (boolean, опционально)
  Управление HTML в ответах ассистента:
  - true (или не указан): ассистент МОЖЕТ использовать лёгкий HTML (например, абзацы, списки).
  - false: ассистент ПОЛУЧИТ СИСТЕМНУЮ ИНСТРУКЦИЮ НЕ использовать HTML и писать только обычным текстом.

  Это удобно, если, например, вы хотите выводить текст как простой plain text без разметки.

- productSelection (boolean, опционально)
  Включает режим «подбор продукта».
  - false (или не указан): обычный режим консультации.
  - true: ассистент получает специальную инструкцию:
    - сначала задать 2–3 уточняющих вопроса ОДНИМ сообщением (списком),
    - после ответов пользователя подобрать 1–3 конкретных продукта Somna Secra,
    - объяснить, почему именно эти продукты подходят,
    - мягко предложить оформить заказ или взять набор.


2.2. Пример запроса (JavaScript, сайт)

async function sendMessage(text, sessionId = null) {
  const response = await fetch('https://your-domain.com/chat/message', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      content: text,
      sessionId: sessionId,
      model: 'apifreellm',
      allowHtml: false,          // отключаем HTML
      productSelection: false    // обычный режим
    })
  });

  const data = await response.json();

  // важные поля
  const newSessionId = data.sessionId;          // запомнить, чтобы продолжить диалог
  const assistantText = data.message.content;   // ответ ассистента

  return { newSessionId, assistantText, full: data };
}


2.3. Пример запроса (WordPress, PHP)

function somna_ai_send_message($text, $session_id = null, $product_selection = false, $allow_html = true) {
    $url = 'https://your-domain.com/chat/message';

    $body = array(
        'content' => $text,
        'allowHtml' => $allow_html,
        'productSelection' => $product_selection,
    );

    if ($session_id) {
        $body['sessionId'] = $session_id;
    }

    $response = wp_remote_post($url, array(
        'headers' => array(
            'Content-Type' => 'application/json',
        ),
        'body'    => wp_json_encode($body),
        'timeout' => 30,
    ));

    if (is_wp_error($response)) {
        return $response; // ошибка
    }

    $data = json_decode(wp_remote_retrieve_body($response), true);

    return array(
        'sessionId'     => $data['sessionId'],
        'assistantText' => $data['message']['content'],
        'fullResponse'  => $data,
    );
}


3. КАК ОТКЛЮЧИТЬ HTML В ОТВЕТАХ
--------------------------------

Флаг: allowHtml (boolean) в теле запроса.

- Если allowHtml НЕ указан или true:
  Ассистент может использовать лёгкую разметку (HTML/markdown).

- Если allowHtml = false:
  Внутри промпта ассистент получает явную инструкцию НЕ использовать HTML-теги.
  Он должен отвечать только обычным текстом (plain text) с переносами строк.

Использование:
- В REST:
  {
    "content": "Мой вопрос",
    "allowHtml": false
  }

- В WebSocket (см. ниже):
  socket.emit('send_message', {
    content: 'Мой вопрос',
    allowHtml: false
  });


4. РЕЖИМ ПОДБОРА ПРОДУКТА (productSelection)
-------------------------------------------

Флаг: productSelection (boolean) в теле запроса.

Когда productSelection = true:
- Ассистент работает в «режиме продавца/стилиста» с усиленной задачей ПРОДАТЬ и ПОДОБРАТЬ конкретный продукт.
- Логика (зашита в системных инструкциях в CosmeticsValidator.enrichPrompt):
  1) Если в истории нет ответов на уточняющие вопросы,
     ассистент в одном сообщении задаёт 2–3 коротких вопроса списком, например:
     - тип волос/кожи,
     - главная проблема (сухость, выпадение, тусклость и т.д.),
     - желаемый эффект (рост, блеск, объём, увлажнение),
     - предпочтения по аромату,
     - примерный бюджет.
  2) После того как пользователь ответит,
     ассистент анализирует ответы и предлагает 1–3 конкретных продукта Somna Secra,
     объясняя, почему они подходят.
  3) В конце мягко предлагает оформить заказ или взять набор (Upsell, но без давления).

Пример запуска режима через REST:
{
  "content": "Подбери, пожалуйста, уход для волос",
  "productSelection": true
}

Пример через WebSocket:

socket.emit('send_message', {
  content: 'Хочу подобрать молочко для тела',
  productSelection: true
});

ВАЖНО:
- Режим productSelection завязан на промпте и истории, а не на отдельном состоянии на сервере.
- Обычно достаточно включить productSelection в первом запросе сценария подбора, далее история сама будет вести диалог.


5. WebSocket / Socket.io (ОНЛАЙН-ЧАТ НА САЙТЕ)
----------------------------------------------

Сервер Socket.io уже настроен в ChatGateway.

5.1. Подключение

const socket = io('https://your-domain.com', {
  transports: ['websocket']
});

socket.on('connect', () => {
  console.log('connected');

  // присоединение к чату
  socket.emit('join_chat', {
    userId: 'optional-user-id',
    // sessionId: 'если есть сохранённая сессия'
  });
});

socket.on('chat_joined', (data) => {
  console.log('session', data.sessionId);
  console.log('history', data.history);
});

5.2. Отправка сообщения через WebSocket

socket.emit('send_message', {
  content: 'Мой вопрос',
  model: 'apifreellm',          // опционально
  allowHtml: false,             // отключить HTML
  productSelection: false       // или true для режима подбора
});

События от сервера:
- 'typing' — индикатор, что ассистент печатает;
- 'new_message' — новое сообщение ассистента:
  {
    message: { ... },
    sessionId: '...' 
  }
- 'history_updated' — обновление счётчика сообщений.

5.3. Очистка истории / новая сессия

socket.emit('clear_history');

Сервер создаст новую сессию и отправит события 'history_cleared' и 'chat_joined' с новой history.


6. ПОВЕДЕНИЕ АССИСТЕНТА: ПРОДАЖИ И ДРУЖЕЛЮБНЫЙ ТОН
---------------------------------------------------

Логика характера и продаж зашита в файле:
- src/validation/cosmetics.validator.ts
- метод: enrichPrompt()

Основные моменты (уже реализованы):
- Ассистент — тёплый, дружелюбный, экспертный консультант бренда Somna Secra.
- Говорит только о продуктах Somna Secra.
- Объясняет пользу товаров, помогает подобрать оптимальный уход.
- В режиме productSelection активно уточняет потребности и даёт конкретные рекомендации.

Если захочешь сам поменять характер:
- Открой файл src/validation/cosmetics.validator.ts.
- Найди метод enrichPrompt().
- Отредактируй текст в блоке [SYSTEM_INSTRUCTIONS] — это и есть «характер» ассистента.


7. БАЗА ДАННЫХ ТОВАРОВ (JSON) — КАК ЗАПОЛНЯТЬ
---------------------------------------------

Сейчас в проекте есть файл с ключевыми словами для определения тематики:
- src/validation/keywords.json

В нём уже лежат:
- categories — словари ключевых слов по категориям;
- negative_keywords — слова, по которым запрос считается «оффтопом» (не про Somna).

Этот файл можно расширять и использовать как простую «базу знаний».

7.1. Структура текущего файла keywords.json

{
  "categories": {
    "уход за волосами": ["волосы", "рост волос", ...],
    "уход за кожей тела": ["кожа", "сухая кожа", ...],
    "продукты Somna Secra": ["Somna Secra", "Midnight Sun", ...],
    ...
  },
  "negative_keywords": [
    "другой бренд", "L'Oreal", "автомобиль", "спорт", ...
  ]
}

Ты можешь:
- добавлять новые категории;
- дописывать ключевые слова в существующие категории;
- добавлять новые негативные ключевые слова.

7.2. Пример, как завести отдельный JSON с товарами (рекомендуемая схема)

Если хочешь полноценную «базу товаров» в формате JSON, удобно сделать отдельный файл, например:
- src/validation/products.json

Пример структуры:

{
  "brand": {
    "name": "Somna Secra",
    "founder": "Екатерина Гребенко",
    "production": "Россия (премиум ингредиенты)",
    "description": "Премиальный бренд ухода за волосами и телом."
  },
  "products": [
    {
      "id": "growing-moon-tonic",
      "line": "THE GROWING MOON",
      "name": "Пептидный тоник для роста волос",
      "category": "уход за волосами",
      "price": 3498,
      "size": "100ml",
      "description": "Ускоряет рост, снижает выпадение, результат за 4–6 недель.",
      "problems": ["выпадение", "медленный рост", "ослабленные волосы"]
    },
    {
      "id": "midnight-sun-set",
      "line": "MIDNIGHT SUN",
      "name": "Набор для восстановления волос",
      "category": "уход за волосами",
      "price": 1618,
      "size": "набор",
      "description": "Шампунь, кондиционер и маска без сульфатов для блеска и восстановления.",
      "problems": ["повреждённые", "тусклые", "сухие волосы"]
    }
  ]
}

Как заполнять:
- brand — общая информация о бренде;
- products — массив товаров;
- у каждого товара желательно указать:
  - id — уникальная строка (англ. через дефис);
  - line — линейка (THE GROWING MOON, MIDNIGHT SUN и т.п.);
  - name — название продукта, как показывать пользователю;
  - category — тип продукта (уход за волосами, уход за телом и т.д.);
  - price — цена в рублях;
  - size — объём/формат (100ml, набор и др.);
  - description — короткое продающее описание (1–2 предложения);
  - problems — список проблем, при которых этот продукт особенно хорошо подходит.

ВАЖНО:
- По умолчанию код сейчас использует жёстко прописанный текст каталога в enrichPrompt(),
  который уже описывает основные линейки и продукты.
- Если захочешь, чтобы ассистент читал товары напрямую из JSON,
  нужно будет доработать CosmeticsValidator: загрузить products.json
  и собрать текст для [CATALOG_KNOWLEDGE] на основе JSON.


8. ГДЕ МЕНЯТЬ ХАРАКТЕР И ПРОДАЮЩЕЕ ПОВЕДЕНИЕ
-------------------------------------------

Основной файл для настроек логики ассистента:
- src/validation/cosmetics.validator.ts

Ключевые места:
- isCosmeticsRelated() — определяет, относится ли вопрос к тематике Somna;
- getOffTopicResponse() — что отвечать на оффтоп;
- enrichPrompt() — САМЫЙ ВАЖНЫЙ метод: там задаётся роль и стиль ассистента.

Чтобы усилить продажи или изменить тон:
1. Открой cosmetics.validator.ts.
2. Найди метод enrichPrompt().
3. Отредактируй блок [SYSTEM_INSTRUCTIONS]:
   - можешь сделать тон более дерзким, более экспертным, более спокойным и т.д.;
   - можешь усилить или ослабить «продающий» стиль;
   - можешь добавить правила для формата ответов.


9. РЕЗЮМЕ ПО ИСПОЛЬЗОВАНИЮ
---------------------------

- Для простого подключения к сайту или WP:
  - используй POST /chat/message;
  - передавай content и (по желанию) sessionId;
  - чтобы отключить HTML — добавь allowHtml: false;
  - чтобы запустить сценарий подбора продукта — добавь productSelection: true.

- Для живого чата:
  - используй Socket.io и события join_chat, send_message, clear_history.

- Для настройки ассортимента и характера ассистента:
  - редактируй keywords.json (ключевые слова),
  - редактируй текст в enrichPrompt() в cosmetics.validator.ts,
  - при необходимости заведи свой products.json по предложенной схеме.

Эта инструкция лежит в корне проекта и может использоваться как шпаргалка при интеграции с любым фронтендом или плагином.