projects/org/ideal-shop/docs/AI-ASSISTANT.md

AI-ASSISTANT — AI-помощник

Версия: 2.1.0
Дата: 2026-03-24


Концепция

Встроенный AI-ассистент с голосом и режимом демонстрации.


UI

Кнопка (свёрнуто)

                                    ┌───┐
                                    │ ? │  ← круглая кнопка
                                    └───┘
                                    56×56px, фиолетовый
                                    position: fixed
                                    right: 16px
                                    bottom: 100px (над FAB контактов)

Чат (развёрнуто)

┌─────────────────────────────────────────────┐
│  🤖 Ассистент                    [−] [×]   │
├─────────────────────────────────────────────┤
│                                             │
│  Привет! Я помогу выбрать                   │
│  фейерверк или ответить на вопросы.         │
│                                             │
│  ┌─────────────────────────────────────┐   │
│  │ 👤 Подбери салют на 10000₽          │   │
│  └─────────────────────────────────────┘   │
│                                             │
│  ┌─────────────────────────────────────┐   │
│  │ 🤖 Вот 3 варианта:                  │   │
│  │                                     │   │
│  │ 1. Большой праздник — 9 500₽        │   │
│  │    36 залпов, веер, пальма          │   │
│  │    [Показать] [В корзину]           │   │
│  │                                     │   │
│  │ 2. Фейерверк Люкс — 10 200₽         │   │
│  │    49 залпов, хризантема            │   │
│  │    [Показать] [В корзину]           │   │
│  │                                     │   │
│  │             [🔊 Озвучить]           │   │
│  └─────────────────────────────────────┘   │
│                                             │
├─────────────────────────────────────────────┤
│ [🎤]  [Напишите сообщение...]    [➤]       │
├─────────────────────────────────────────────┤
│ [👆 Покажи]  [📦 Мой заказ]  [❓ FAQ]      │
└─────────────────────────────────────────────┘

Режимы

1. Текстовый чат

Стандартный режим — пользователь пишет, AI отвечает.

2. Голосовой ввод

Mobile: Нативная клавиатура Google/iOS — пользователь нажимает 🎤 на клавиатуре.
- Бесплатно
- Уже работает
- Привычно (как в Telegram/WhatsApp)
- Никакой кастомной реализации

<!-- Просто обычный input -->
<input type="text" placeholder="Напишите или надиктуйте...">

Desktop: Web Speech API (опционально)

// Только если нужна кнопка в интерфейсе чата
const recognition = new webkitSpeechRecognition();
recognition.lang = 'ru-RU';
recognition.onresult = (event) => {
  const text = event.results[0][0].transcript;
  sendMessage(text);
};

3. Ответы: текст + голос

Ответ всегда показывается текстом + кнопка озвучить.

┌─────────────────────────────────────┐
│  🤖 Вот 3 варианта:                │
│                                     │
│  1. Большой праздник — 9 500₽       │
│     36 залпов, веер                 │
│                                     │
│  2. Фейерверк Люкс — 10 200₽        │
│     49 залпов                       │
│                                     │
│  [▶️ Прослушать]  ← озвучить текст │
└─────────────────────────────────────┘

TTS варианты:
| Сервис | Качество | Цена |
|--------|----------|------|
| Web Speech API | Среднее | Бесплатно |
| Yandex SpeechKit | Хорошее | ~2₽/1000 символов |
| ElevenLabs | Отличное | $5/мес ⚠️ иностранный SaaS |

Рекомендация: Web Speech API для старта, Yandex для продакшена.

4. Режим "Покажи" (Guided Tour)

AI управляет курсором и показывает элементы на сайте.

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│   Пользователь: "Как добавить в корзину?"                  │
│                                                             │
│   AI: "Сейчас покажу! Следите за курсором."                │
│                                                             │
│   ┌─────────────────────────────────────────────────────┐   │
│   │                                                     │   │
│   │    ┌─────────┐                                      │   │
│   │    │ Товар   │                                      │   │
│   │    │ [ФОТО]  │                                      │   │
│   │    │ 5000₽   │                                      │   │
│   │    │         │                                      │   │
│   │    │ ┌─────────────────┐ ◄── 🎯 курсор AI          │   │
│   │    │ │  🛒 В КОРЗИНУ   │     + подсветка            │   │
│   │    │ └─────────────────┘                            │   │
│   │    └─────────┘                                      │   │
│   │                                                     │   │
│   └─────────────────────────────────────────────────────┘   │
│                                                             │
│   💬 "Нажмите на эту кнопку, чтобы добавить товар"        │
│                                                             │
│   [Понятно] [Покажи ещё раз] [Сделай за меня]              │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Реализация:

// Анимированный курсор
const aiCursor = document.createElement('div');
aiCursor.className = 'ai-cursor';

function showElement(selector, message) {
  const element = document.querySelector(selector);
  const rect = element.getBoundingClientRect();

  // Анимация курсора к элементу
  aiCursor.animate([
    { left: aiCursor.style.left, top: aiCursor.style.top },
    { left: rect.left + 'px', top: rect.top + 'px' }
  ], { duration: 1000, easing: 'ease-in-out' });

  // Подсветка элемента
  element.classList.add('ai-highlight');

  // Показать подсказку
  showTooltip(element, message);
}

CSS:

.ai-cursor {
  position: fixed;
  width: 24px;
  height: 24px;
  background: url('cursor-ai.svg');
  pointer-events: none;
  z-index: 10000;
  transition: all 0.5s ease;
}

.ai-highlight {
  position: relative;
  z-index: 9999;
  box-shadow: 0 0 0 4px var(--color-brand-500),
              0 0 20px rgba(var(--color-brand-500), 0.5);
  animation: pulse 1.5s infinite;
}

@keyframes pulse {
  0%, 100% { box-shadow: 0 0 0 4px var(--color-brand-500); }
  50% { box-shadow: 0 0 0 8px var(--color-brand-300); }
}

.ai-tooltip {
  position: absolute;
  background: var(--color-gray-900);
  color: white;
  padding: 12px 16px;
  border-radius: var(--radius-lg);
  max-width: 280px;
  z-index: 10001;
}

Сценарии "Покажи"

Команда Действия AI
"Как найти товар?" Курсор → поиск → ввод примера → результаты
"Как добавить в корзину?" Курсор → карточка → кнопка → корзина открывается
"Как оформить заказ?" Курсор → корзина → checkout → поля по очереди
"Где мой заказ?" Курсор → личный кабинет → заказы → статус
"Как оплатить?" Демо checkout → выбор оплаты

Режим "Сделай за меня"

AI выполняет действия автоматически:

👤: "Добавь в корзину Большой праздник"

🤖: "Добавляю..."
    [Ищет товар]
    [Находит]
    [Клик "В корзину"]

🤖: "Готово! Товар в корзине. Оформить заказ?"
    [Да] [Нет, продолжить покупки]

Ограничения:
- Только навигация и добавление в корзину
- Оплата — только показывает, не вводит данные
- Требует подтверждения перед действием


Функции ассистента

Подбор товара

👤: "Салют на день рождения, бюджет 7000"

🤖: Анализирую...
    - Событие: день рождения
    - Бюджет: 7000₽
    - Рекомендую яркие эффекты, средняя длительность

    Вот подборка:
    1. Праздничный (6500₽) — 25 залпов, разноцветный
    2. Happy Birthday (7200₽) — 36 залпов, с надписью

    [Показать] [Сравнить] [В корзину]

Ответы на вопросы

👤: "Доставляете в Выборг?"

🤖: Да! Доставка в Выборг:
    • СДЭК до ПВЗ — 350₽, 2-3 дня
    • СДЭК курьер — 500₽, 2-3 дня

    [Выбрать ПВЗ на карте]

Статус заказа

👤: "Где мой заказ 12345?"

🤖: Заказ #12345:
    ✅ Оплачен
    ✅ Собран
    🚚 В пути (СДЭК)

    Трек: 1234567890
    Ожидаемая доставка: 23 декабря

    [Отследить на сайте СДЭК]

Сравнение

👤: "Сравни Большой праздник и Фейерверк Люкс"

🤖:
    | Параметр | Большой праздник | Фейерверк Люкс |
    |----------|------------------|----------------|
    | Цена     | 9 500₽           | 10 200₽        |
    | Залпы    | 36               | 49             |
    | Калибр   | 30мм             | 25мм           |
    | Время    | 45 сек           | 60 сек         |

    Рекомендую: Фейерверк Люкс — больше залпов за +700₽

    [Показать оба] [Фейерверк Люкс в корзину]

Быстрые кнопки

Под полем ввода:

Кнопка Действие
👆 Покажи Режим guided tour
📦 Мой заказ Запрос статуса
❓ FAQ Частые вопросы
🎯 Подобрать Мастер подбора
📞 Оператор Перевод на человека

Архитектура

┌────────────────────────────────────────────────────────────┐
                      FRONTEND                              
├────────────────────────────────────────────────────────────┤
  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     
    Chat Widget    Voice Input     AI Cursor         
    (Vue/React)    (Web Speech)    (Guided Tour)     
  └──────────────┘  └──────────────┘  └──────────────┘     
                                                           
                    WebSocket / REST                        
└────────────────────────────────────────────────────────────┘
                            
                            
┌────────────────────────────────────────────────────────────┐
                      BACKEND                               
├────────────────────────────────────────────────────────────┤
                                                            
  ┌──────────────────────────────────────────────────────┐ 
                     FastAPI                             
    /chat       обработка сообщений                     
    /voice      TTS озвучивание                         
    /actions    команды для guided tour                 
  └──────────────────────────────────────────────────────┘ 
                                                           
         ┌──────────────────┼──────────────────┐           
                                                        
  ┌────────────┐    ┌────────────┐    ┌────────────┐      
    Claude          Каталог         Заказы          
    API             (NocoDB)        (API)           
  └────────────┘    └────────────┘    └────────────┘      
                                                            
└────────────────────────────────────────────────────────────┘

Интеграция с каталогом

Векторный поиск

# Эмбеддинги товаров для семантического поиска
from sentence_transformers import SentenceTransformer

model = SentenceTransformer('paraphrase-multilingual-MiniLM-L12-v2')

# При добавлении товара
product_text = f"{name} {description} {category} залпов:{shots} калибр:{caliber}"
embedding = model.encode(product_text)
save_to_vector_db(product_id, embedding)

# При поиске
query = "салют на свадьбу недорогой красивый"
query_embedding = model.encode(query)
similar_products = vector_db.search(query_embedding, top_k=5)

Контекст для Claude

system_prompt = """
Ты — AI-ассистент магазина пиротехники.

КАТАЛОГ (релевантные товары):
{products_context}

FAQ:
{faq_context}

ПРАВИЛА:
- Рекомендуй только товары из каталога
- Указывай точные цены
- Предлагай альтернативы в бюджете
- Если не знаешь — скажи "уточню у оператора"

РЕЖИМ ПОКАЖИ:
Если пользователь просит показать — верни JSON:
{"action": "show", "selector": ".add-to-cart", "message": "Нажмите эту кнопку"}
"""

Стоимость

Компонент Цена
Claude API (500 чатов/день) ~$75/мес
Yandex SpeechKit TTS ~$10/мес
Vector DB (Qdrant self-hosted) $0
Хостинг backend $20/мес
Итого ~$105/мес

Оптимизация


Mobile

┌─────────────────────┐
                     
      КОНТЕНТ        
                     
              ┌───┐  
               ?      кнопка чата
              └───┘  
              ┌───┐  
               📞│     FAB контактов
              └───┘  
├─────────────────────┤
  🏠  🔍  🛒       
└─────────────────────┘

         tap

┌─────────────────────┐
 🤖 Ассистент    ×  
├─────────────────────┤
                     
  💬 Чат             
                     
├─────────────────────┤
 [🎤] [________] []
├─────────────────────┤
 [Покажи] [Заказ]   
└─────────────────────┘

Режим "Покажи" на mobile:
- Подсветка элемента
- Стрелка указывает
- Голосовое объяснение
- Автоскролл к элементу


AI-подборка

Кнопка [🤖 Подобрать] в каталоге:

┌─────────────────────────────────────────────────────────────┐
│  🤖 Опишите, что ищете:                                    │
│  [На свадьбу, бюджет 15000, чтобы красиво и долго горело]  │
│                                                    [Найти] │
└─────────────────────────────────────────────────────────────┘
        ↓
┌─────────────────────────────────────────────────────────────┐
│  🤖 ПОДБОРКА: Свадьба до 15 000₽                   [×]     │
├─────────────────────────────────────────────────────────────┤
│  "Выбрал 4 варианта с долгим горением и веерными          │
│   эффектами — идеально для фото"                           │
│                                                             │
│   ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐       │
│   │ 🎬 60с  │  │ 🎬 45с  │  │ 🎬 50с  │  │ 🎬 70с  │       │
│   │  ▶️     │  │  ▶️     │  │  ▶️     │  │  ▶️     │       │
│   └─────────┘  └─────────┘  └─────────┘  └─────────┘       │
│                                                             │
│  [▶️ Озвучить]  [📋 Сравнить]  [🛒 Всё в корзину]          │
└─────────────────────────────────────────────────────────────┘

URL: /selection?q=свадьба+15000+яркие — можно шарить.


Видео вместо перехода (SEO-совместимо)

Проблема

Видео inline = лучше конверсия, но убивает SEO.

Решение: SPA-переход с prefetch

ДЛЯ GOOGLEBOT:              ДЛЯ ПОЛЬЗОВАТЕЛЯ:
<a href="/product/xxx">     JavaScript:
  <img src="...">           1. Prefetch при hover
</a>                        2. При клике  мгновенный переход
                            3. Видео autoplay на странице
+ Schema.org Product        4. URL меняется (History API)
+ sitemap.xml               5. Кнопка "назад" работает

Результат

Кто Видит
Google Обычные ссылки, страницы, Schema.org
Пользователь Мгновенный переход + видео autoplay

Реализация

// Prefetch при hover
card.addEventListener('mouseenter', () => {
  prefetch('/product/' + productId);
});

// Мгновенный переход при клике
card.addEventListener('click', (e) => {
  e.preventDefault();
  navigateTo('/product/' + productId);  // SPA transition
});

Этапы разработки

Этап Что
1 Базовый чат + Claude API
2 Голосовой ввод (нативная клавиатура) + TTS
3 Интеграция с каталогом
4 AI-подборка
5 Режим "Покажи" (guided tour)
6 Режим "Сделай за меня"
7 SPA-переходы с видео

Библиотеки

Задача Библиотека
Guided tour Driver.js, Intro.js
Chat UI собственный или Chatbot UI
Voice input Web Speech API
Voice output Web Speech API / Yandex
WebSocket Socket.io
Vector search Pinecone / Qdrant / ChromaDB

Версия: 2.1.0