# Руководство администратора — SmartSales AI

## Содержание

1. [Вход в админ-панель](#вход-в-админ-панель)
2. [Панель управления](#панель-управления)
3. [Товары](#товары)
4. [База знаний](#база-знаний)
5. [Промпты](#промпты)
6. [Сессии чата](#сессии-чата)
7. [Настройки чата](#настройки-чата)
8. [Режимы работы AI](#режимы-работы-ai)
9. [Кэш ответов](#кэш-ответов)
10. [Логи](#логи)
11. [Миграция БД](#миграция-бд)
12. [Интеграция чата на сайт](#интеграция-чата-на-сайт)
13. [API для импорта товаров](#api-для-импорта-товаров)
14. [Проактивные follow-up (cron)](#проактивные-follow-up-cron)

---

## Вход в админ-панель

1. Откройте `http://ваш-домен/admin/`
2. Войдите с логином `admin` и паролем `admin123`
3. При первом входе система потребует сменить пароль
4. После смены пароля вы попадёте на панель управления

### Восстановление пароля

Если забыли пароль:
1. На странице входа нажмите «Забыли пароль?»
2. Введите email администратора
3. Получите ссылку для сброса (действительна 1 час)
4. Задайте новый пароль

---

## Панель управления

На главной странице админки:
- **Статистика** — количество сессий, сообщений, товаров, промптов
- **Активные сессии** — список текущих диалогов, обновляется каждые 10 секунд
- **Требуется менеджер** — сессии, где клиент просит соединить с оператором (красная подсветка)
- **Последние сообщения** — лента последних 20 сообщений

---

## Товары

**Админка → Товары**

### Добавление товара вручную

Заполните поля:
- **Название** — краткое наименование
- **Описание** — характеристики, особенности, преимущества
- **Категория** — группа товара (например, «Электроника», «Бытовая техника»)
- **Цена** — в рублях
- **Ссылка (URL)** — ссылка на товар в вашем магазине (для кнопки «Заказать»)
- **Наличие (stock)** — количество на складе (>0 = в наличии)
- **Популярность** — число для ранжирования (больше = выше в результатах)
- **Атрибуты (JSON)** — дополнительные параметры: `{"цвет":"чёрный","размер":"L"}`

### Как AI ищет товары

При запросе клиента AI:
1. Извлекает поисковые термины из сообщения
2. Ищет совпадения в названии, описании, категории (LIKE-поиск)
3. Ранжирует: совпадение в названии > популярность > цена
4. Фильтрует по бюджету, цвету, размеру (если указаны)
5. Возвращает топ-3 наиболее подходящих товара

### Импорт через API

См. раздел [API для импорта товаров](#api-для-импорта-товаров).

---

## База знаний

**Админка → База знаний**

База знаний — это информация о вашем магазине, которую AI использует для ответов на вопросы клиентов (доставка, оплата, гарантия, контакты и т.д.).

### Категории

Создайте категории для группировки знаний:
- **Главная** — записи из этой категории передаются AI в каждом сообщении. Сюда стоит добавить самую важную информацию (контакты, общие условия)
- Остальные категории — подгружаются, когда клиент упоминает ключевое слово из названия категории

Примеры категорий: «Доставка», «Оплата», «Гарантия», «Контакты», «Скидки»

### Записи

Каждая запись содержит:
- **Заголовок** — краткое название (например, «Доставка по России»)
- **Содержание** — подробный текст
- **Категория** — привязка к разделу

### Как AI использует базу знаний

1. Записи из категории «Главная» — всегда в контексте AI
2. Если клиент упоминает слово из названия категории — все записи этой категории подгружаются
3. Дополнительный поиск по терминам в заголовках и текстах

---

## Промпты

**Админка → Промпты**

Промпты — это инструкции для AI, определяющие стиль и логику ответов.

### Как работают промпты

- Каждый промпт имеет **паттерн** (регулярное выражение) и **приоритет**
- При поступлении сообщения AI проверяет промпты от высокого приоритета к низкому
- Первый промпт, паттерн которого совпал с сообщением, используется как системный
- Если ни один не совпал — используется промпт по умолчанию (паттерн `.*`, приоритет 0)

### Рекомендуемые промпты

1. **Основной** (паттерн `.*`, приоритет 0) — базовое поведение консультанта
2. **Сравнение и характеристики** (паттерн `(сравн|характеристик|таблиц|...)`, приоритет 110) — инструкция форматировать данные в HTML-таблицы

### Адаптивный промпт

Помимо промптов из таблицы, система использует **адаптивный промпт** — он формируется динамически в зависимости от:
- **Режима AI** (inform / sell / aggressive) — см. [Режимы работы AI](#режимы-работы-ai)
- **Типа запроса** (products / info / clarification / complaint / off_topic / none)

Адаптивный промпт дополняет, а не заменяет промпты из таблицы.

---

## Сессии чата

**Админка → Сессии чата**

Здесь вы видите все диалоги с клиентами:

- **AI** — сессия обслуживается AI автоматически
- **РУЧН** — менеджер включил ручной режим (AI не отвечает, сообщения отправляет менеджер)
- **МЕНЕДЖЕР!** (красная подсветка) — клиент просит соединить с оператором

### Перехват диалога

1. Откройте сессию
2. Нажмите «Перевести в ручной режим»
3. AI перестанет отвечать — теперь вы пишете ответы лично
4. Чтобы вернуть AI — нажмите «Вернуть AI-режим»

---

## Настройки чата

**Админка → Настройки чата**

### Основные настройки

- **Имя консультанта** — отображается в заголовке чата
- **Аватар** — изображение (загружается через обрезку, сохраняется в Base64)
- **Цвет чата** — основной цвет виджета (HEX, например `#2563eb`). Текст на кнопках автоматически подбирается для контраста
- **Шаблон приветствия** — если задан, используется как статичное приветствие (без AI). Если пусто — AI генерирует приветствие

### Модели AI

- **Основная модель** — для товарных запросов, рекомендаций, сравнений
- **Лёгкая модель** — для приветствий и простых вопросов (болтовня)

Рекомендуется: `qwen2.5:3b` для обеих. Можно использовать разные модели для экономии ресурсов.

### Режим работы AI

См. [Режимы работы AI](#режимы-работы-ai).

### Проактивные рекомендации

Включите, чтобы AI анализировал диалог и предлагал товары, которые могут заинтересовать клиента, даже если он о них не спрашивал. Работает только в режимах `sell` и `aggressive`.

### Контакты поддержки

- **Телефон поддержки** — отображается при жалобах
- **Email поддержки** — отображается при жалобах

---

## Режимы работы AI

Три стратегии рекомендаций — выбираются в Настройках:

### inform — «Информирование» (по умолчанию)

- Отвечает по существу: описывает товары, перечисляет характеристики
- Не навязывает допродажи, если клиент явно не просит сравнить
- Добавляет кнопку «Заказать» к рекомендуемым товарам
- Подходит для магазинов, где клиент сам принимает решение

### sell — «Продажа с преукрашиванием»

- Подчёркивает все плюсы и преимущества товара
- Создаёт ощущение, что это лучший выбор
- После основной рекомендации предлагает 1 альтернативу (±30% по цене)
- Мягкий призыв: «этот вариант пользуется спросом», «рекомендую не откладывать»
- Подходит для большинства интернет-магазинов

### aggressive — «Максимум продаж»

- В КАЖДОМ ответе (кроме жалоб) предлагает минимум один товар
- На вопросы про телефон — 2-3 аналога из той же категории
- На вопросы про доставку/оплату — блок «Кстати, сейчас популярны» с товарами
- Приветствие + сразу 2-3 хита продаж
- Допродажи: до 4 товаров той же категории ±30% по цене
- Заканчивает ответ призывом к покупке
- Подходит для магазинов с высокой конкуренцией

---

## Кэш ответов

**Админка → Кэш ответов**

Система кэширует ответы AI для снижения нагрузки на модель.

### Как работает кэш

- При поступлении запроса вычисляется SHA256-хэш нормализованного сообщения + контекст пользователя (бюджет, цвет, размер)
- Если ответ есть в кэше и контекст (товары/БЗ) не изменился — отдаётся из кэша мгновенно
- Кэш инвалидируется при добавлении/изменении товаров или записей базы знаний (через хэш контекста)
- TTL кэша — 24 часа (настраивается в `saveCachedResponse`)
- Болтовня (тип `none`) не кэшируется

### Управление

- Просмотр записей кэша с счётчиком попаданий
- Очистка кэша (полная или по типу запроса)
- Удаление устаревших записей

---

## Логи

### Логи рассуждений

**Админка → Логи рассуждений**

Показывает полный контекст, отправленный модели, и её ответ (с рассуждениями). Полезно для отладки качества ответов AI.

### Логи ошибок AI

**Админка → Логи ошибок AI** (ссылка внизу сайдбара)

Логи всех запросов к Ollama: статус (success/error/timeout), время ответа, тело запроса и ответа. Помогает диагностировать проблемы с моделью.

---

## Миграция БД

Если вы обновили проект до новой версии, запустите миграцию:

**Через админку:** в сайдбаре внизу — ссылка «🔧 Миграция БД»

**Через CLI:** `php fix_db.php`

Миграция:
- Добавляет недостающие колонки и таблицы
- Обновляет промпты
- Не удаляет данные

---

## Интеграция чата на сайт

Добавьте две строки на любую HTML-страницу вашего сайта:

```html
<link rel="stylesheet" href="path/to/chat.css">
<script src="path/to/chat.js"></script>
```

Виджет автоматически:
- Создаст кнопку чата в правом нижнем углу (появляется через 5 секунд)
- Создаст окно чата с возможностью перетаскивания и изменения размера
- Загрузит настройки (имя, цвет, аватар) из админки
- Сохранит session_id в localStorage (история сохраняется при обновлении страницы)

### На мобильных

На устройствах <480px чат открывается в полноэкранном режиме.

---

## API управления товарами

Подробная документация: [docs/API_IMPORT_RU.md](API_IMPORT_RU.md)

Эндпоинты: `add_product`, `delete_product`, `list_products` — все через `POST/GET /api.php?action=...&hash=КЛЮЧ`.

### Авторизация

API-ключ передаётся как query-параметр `hash` в URL (не в заголовке Authorization):

```
POST /api.php?action=add_product&hash=ваш_api_ключ
```

API-ключ задаётся в таблице `settings` (ключ `api_key`).

### Поля запроса (JSON)

```json
{
  "name": "iPhone 15 Pro",
  "description": "256GB, титановый корпус, A17 Pro",
  "category": "Электроника",
  "price": 129000,
  "url": "https://shop.ru/iphone-15-pro",
  "ext_id": "ext_12345"
}
```

### Пример (curl)

```bash
curl -X POST "https://ваш-домен/api.php?action=add_product&hash=ваш_api_ключ" \
  -H "Content-Type: application/json" \
  -d '{"name":"iPhone 15 Pro","description":"256GB","category":"Электроника","price":129000,"url":"https://shop.ru/iphone-15-pro"}'
```

---

## Проактивные follow-up (cron)

Скрипт `follow_up.php` отправляет наводящие вопросы клиентам, которые перестали отвечать или закрыли чат.

### Настройка cron

```bash
# Запускать каждые 3 минуты
*/3 * * * * /usr/bin/php /путь/к/aimanager/follow_up.php
```

### Логика

- Если клиент не отвечает 5+ минут — AI отправляет 1 наводящий вопрос
- Максимум 1 follow-up на сессию
- Не тревожит сессии старше 1 часа
- Не работает в ручном режиме

Настройки (в начале `follow_up.php`):
- `IDLE_TIMEOUT_MINUTES` — через сколько минут простоя писать (по умолчанию 5)
- `MAX_FOLLOW_UPS` — сколько раз максимум напоминать (по умолчанию 1)