docs(support-bot): спека своего ИИ-бота в чате Jivo + протокол обсуждения

Дизайн согласован владельцем 02.07.2026: свой бот через Jivo Bot API, YandexGPT Lite, база знаний = docs/help/ в репо, кнопка «Показать» (экскурсии), скорость 2-5 сек, v1 только общие вопросы. Словарь: +jivo/дживо/gigachat. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-02 18:15:18 +03:00
parent 80c5d90873
commit 7cb6542f00
3 changed files with 227 additions and 0 deletions
@@ -2273,3 +2273,22 @@ srv
 поставщиковых
 пулер
 пуло
+
+gzk
+noeviction
+автобэкапы
+ВТБ
+генерится
+деплоить
+затыков
+локал
+локалку
+ОКПО
+онли
+преflight
+Сбере
+синхрона
+golive
+jivo
+дживо
+gigachat
@@ -0,0 +1,142 @@
+# Спека: свой ИИ-бот техподдержки в чате JivoSite («Консультант»)
+
+**Дата:** 02.07.2026
+**Статус:** дизайн согласован владельцем (куски 1–4 приняты в диалоге 02.07.2026)
+**Протокол обсуждения:** `ПРОТОКОЛ-ии-дживосайт.md` (корень репо) — решения 1–8, открытые вопросы О-2/О-3
+**Связанные материалы:** `вебмастер-исходники-perplexity/Б3-ии-техподдержка.md` (архитектурное руководство RAG-поддержки), спека G7-A (`2026-06-19-g7a-client-support-design.md`), спека G7-B (`2026-06-19-g7b-impersonation-door-design.md`), мониторинг внешних сервисов (`2026-07-02-external-services-monitoring-design.md`)
+
+---
+
+## 1. Цель
+
+Клиент портала пишет в чат (виджет JivoSite в личном кабинете) — наш собственный ИИ-бот
+консультирует его по работе портала за 2–5 секунд и, где уместно, прикладывает кнопку
+«Показать на портале», запускающую экскурсию с подсветкой полей. Не готовый «ИИ-оператор»
+Jivo (12 990 ₽/мес, не видит наших данных и не умеет экскурсий), а свой бот через **Jivo Bot API**:
+окошко чата — Jivo, мозги — наш сервер.
+
+**Ключевые решения владельца** (протокол, решения 1–8):
+свой бот · внутри чата Jivo (Bot API) · v1 отвечает только на общие вопросы · сканирование
+сайта Jivo не используем · ответ + кнопка «Показать» (экскурсии) · база знаний = клиентская
+инструкция в репо, обновляется с каждой фичей · скорость 2–5 сек — жёсткое требование ·
+мозг — YandexGPT Lite.
+
+## 2. Архитектура (v1)
+
+```
+Клиент → виджет Jivo (уже встроен, JivoWidget.vue)
+       → серверы Jivo → POST https://liderra.ru/api/webhook/jivo/<секрет>   [CLIENT_MESSAGE]
+       → JivoBotController (ack ≤3 сек) → ProcessJivoMessageJob (очередь, приоритетная)
+       → KnowledgeSearch (pgvector, top 3–5 фрагментов docs/help/)
+       → YandexGptClient (Lite, строгий системный промпт)
+       → BOT_MESSAGE обратно в Jivo (текст + при наличии — ссылка-экскурсия)
+       → журнал bot_dialogs
+Fallback: нет ответа за ~10 сек / стоп-тема / просьба «человека» → INVITE_AGENT (живой оператор).
+Jivo сам зовёт оператора, если BOT_MESSAGE не пришёл за 15 сек — двойная страховка.
+```
+
+Компоненты:
+
+| Компонент | Назначение |
+|---|---|
+| `JivoBotController` | Приём webhook от Jivo: секрет в URL + валидация payload; мгновенный ack; постановка job |
+| `ProcessJivoMessageJob` | Оркестратор ответа: поиск → LLM → отправка → журнал. Таймаут-бюджет ~10 сек |
+| `KnowledgeSearch` | Семантический поиск по `knowledge_chunks` (pgvector, cosine), top-N фрагментов |
+| `YandexGptClient` | Вызов YandexGPT Lite (Yandex Cloud Foundation Models API), таймаут 8 сек |
+| `RebuildKnowledgeBaseJob` | Ночная джоба: перечитать `docs/help/*.md`, порезать на фрагменты, обновить эмбеддинги. + artisan-команда для ручного запуска |
+| `JivoBotLivenessProbe`-расширение | Метрики бота на плитке «Внешние сервисы»: жив, p95 времени ответа, % эскалаций |
+
+## 3. База знаний
+
+- **Источник — `docs/help/*.md`**: статьи простым языком по темам (что такое проект, тарифы
+  и списания, пополнение, смена источника, почему проект остановился, уведомления…).
+  Пишет Claude, вычитывает владелец. Эти же статьи — будущий раздел «Справка» для людей.
+- **Frontmatter статьи**: `title`, `tour` (имя экскурсии из каталога, опционально), `topics`.
+- **Индексация**: ночная `RebuildKnowledgeBaseJob` — режет статьи на фрагменты (~500 токенов),
+  считает эмбеддинги (Yandex Embeddings API), пишет в `knowledge_chunks`. Изменилась статья —
+  ночью бот знает новое; срочно — ручная команда.
+- **Правило против устаревания** (норматив): **фича не готова, пока не обновлена клиентская
+  инструкция** — добавить в CLAUDE.md через плагин claude-md-management при реализации.
+- **Чего в базе нет никогда**: данных клиентов, внутренней кухни (поставщик, секреты, админ-процессы),
+  всего, что нельзя показать любому клиенту.
+
+## 4. Ответ и «Показать на портале» (экскурсии)
+
+- Ответ = текст (только по найденным фрагментам) + если у статьи-источника задана `tour` —
+  ссылка-кнопка `https://liderra.ru/?tour=<имя>`.
+- **Каталог экскурсий** в портале: реестр сценариев (имя → шаги: экран, селектор элемента,
+  текст подсказки). Переиспользует механизм WelcomeTour. Первый набор 5–7: `create-project`,
+  `top-up-balance`, `change-source`, `tariffs`, `notifications`…
+- Обработчик `?tour=`: клиент вошёл → открыть нужный экран, запустить шаги; не вошёл →
+  сначала логин, после входа — экскурсия.
+- ИИ **не сочиняет шаги** — только выбирает готовую экскурсию из каталога (через frontmatter статьи).
+
+## 5. Безопасность и 152-ФЗ
+
+- Webhook: секрет в URL (по образцу приёма лидов поставщика) + проверка структуры/подписи
+  payload Jivo; посторонние запросы — 403 без утечки деталей.
+- **Изоляция v1**: у бота нет доступа к данным клиентов вообще — job работает через соединение,
+  видящее только `knowledge_chunks` и `bot_dialogs`. Prompt-injection «покажи чужой баланс»
+  упирается в отсутствие данных физически.
+- Системный промпт: отвечать ТОЛЬКО по контексту; не знаешь — скажи честно и предложи
+  человека; стоп-темы (личные деньги/данные, обещания скидок, юр-советы) → всегда эскалация.
+- Тракт данных целиком в РФ: Jivo (заявляет хранение в РФ) → наш сервер (Yandex Cloud) →
+  YandexGPT (Yandex Cloud). В политику конфиденциальности добавить упоминание Jivo.
+- Журнал `bot_dialogs` — новая таблица (не tenant-scoped в v1: диалоги анонимны до этапа
+  личных ответов): `id, jivo_chat_id, direction, message, matched_chunks, latency_ms,
+  escalated, created_at`. Запись в `db/schema.sql` + CHANGELOG по правилам.
+
+## 6. Скорость (жёсткая планка владельца)
+
+- Цель: ответ клиенту 2–5 сек. Бюджет: ack ≤1 c → очередь ≤1 c → поиск ≤0.3 c → LLM ≤3 c →
+  отправка ≤0.5 c.
+- Тест производительности: p95 полного цикла (mock LLM с реальными задержками) ≤5 с;
+  live-smoke при приёмке.
+- Не успели за ~10 с → сами шлём INVITE_AGENT; Jivo добивает страховкой на 15 с.
+
+## 7. Эскалация на человека
+
+- Триггеры: просьба клиента («человека», «оператора»), стоп-тема, низкая уверенность
+  (пустой/слабый поиск), таймаут.
+- INVITE_AGENT → диалог у живого оператора (владелец, приложение Jivo на телефоне).
+- Существующий канал G7-A (форма «Помощь» + почта) остаётся без изменений — запасной путь.
+
+## 8. Мониторинг
+
+- Плитка «Внешние сервисы» (выкачена 02.07.2026): статус бота, p95 latency,
+  доля эскалаций, диалогов/день. Красный при недоступности YandexGPT или росте таймаутов.
+- Алерты — по образцу email edge-trigger внешних сервисов.
+
+## 9. Деньги
+
+- Jivo корпоративный (Bot API): ~3 142 ₽/мес за оператора. Подключение бота — письмом
+  в info@jivosite.com (адрес endpoint + токен) — О-2 протокола.
+- YandexGPT Lite + эмбеддинги: при сотнях диалогов/мес — порядка 100–300 ₽/мес.
+- Итого ~3.5 тыс. ₽/мес против 12 990 ₽/мес за готовый ИИ-оператор Jivo (который без экскурсий).
+
+## 10. Этапы
+
+1. **Разведка (без кода):** включить бесплатный чат Jivo (JIVO_WIDGET_ID — О-3, разрешение
+   владельца), владелец отвечает сам; копим реальные вопросы. Параллельно — статьи `docs/help/`.
+2. **Бот-консультант (ядро v1):** webhook + job + поиск + YandexGPT + эскалация + журнал +
+   тесты скорости. TDD, worktree, не прод.
+3. **Экскурсии:** каталог + `?tour=` + кнопка в ответах + 5–7 сценариев.
+4. **Позже, отдельным решением владельца:** личные ответы через машинный ключ G7-B (`lpimp_`),
+   отдельная спека (сцепка «кто в чате = какой клиент», tenant-изоляция, RLS).
+
+## 11. Вне рамок v1
+
+- Личные данные в ответах (этап 4, отдельная спека).
+- Каналы Telegram/WhatsApp через Jivo (возможны позже — Bot API канал-агностичен).
+- Автоматический показ UI без клика (решение владельца: сначала кнопка).
+- Собственное чат-окошко вместо Jivo (отклонено владельцем 02.07.2026 в пользу Jivo).
+
+## 12. Критерии приёмки v1 (этапы 2–3)
+
+- Живой вопрос «что такое проект?» в чате портала → осмысленный ответ по инструкции
+  ≤5 сек + рабочая кнопка «Показать» → экскурсия подсвечивает форму создания проекта.
+- Вопрос «какой у меня баланс?» → вежливая передача живому оператору (INVITE_AGENT приходит).
+- Вопрос не из инструкции («какая погода») → честное «не знаю, позвать человека?».
+- Обновление статьи + ночная джоба → бот отвечает по-новому.
+- Pest: контроллер (секрет/403), job (бюджет времени, эскалации, журнал), поиск (релевантность
+  на фикстурах), клиент YandexGPT (таймаут/ретрай); Vitest: обработчик `?tour=`, каталог экскурсий.
@@ -0,0 +1,66 @@
+# ПРОТОКОЛ — ИИ-бот техподдержки в чате ДживоСайт
+
+**Заведён:** 02.07.2026 по указанию владельца. Здесь фиксируется всё, что обсуждаем и решаем
+по теме «свой ИИ-бот, который консультирует клиентов портала». Обновляется по ходу обсуждений.
+
+---
+
+## 1. Что решено (по состоянию на 02.07.2026)
+
+| № | Решение | Кто/когда |
+|---|---|---|
+| 1 | Делаем **своего бота**, а не готовый «ИИ-оператор» Jivo (12 990 ₽/мес). Готовый умеет консультировать только по загруженной базе знаний и не видит данных клиента; свой — полностью наш и растёт вместе с порталом. | Владелец, 02.07.2026 |
+| 2 | Бот живёт **внутри чата Jivo** (механизм Bot API): окошко чата — Jivo, мозги — наш сервер. Клиент пишет в чат → Jivo пересылает нам → наш бот отвечает. | Владелец, 02.07.2026 |
+| 3 | Первая версия отвечает на **общие вопросы** (как работает портал, тарифы, как создать проект…). Личные («какой у меня баланс») — вторым этапом; пока такие вопросы бот передаёт живому человеку. | Владелец, 02.07.2026 |
+| 4 | **Сканирование сайта роботом Jivo не используем** — базу знаний собираем только из своих проверенных материалов. | Владелец, 02.07.2026 |
+| 5 | Бот не только отвечает словами, но и **показывает на портале**: к ответу прикладывается кнопка «Показать» — клик открывает нужную форму и запускает экскурсию с подсветкой полей (механизм экскурсий в портале уже есть — WelcomeTour). Вариант «бот сам двигает экран без клика» — возможное развитие потом. | Владелец, 02.07.2026 |
+| 6 | **Обучение бота**: база знаний = клиентская инструкция, которая живёт в проекте рядом с кодом. Правило: сделали новую функцию — обновили инструкцию (обязанность Claude при каждой фиче). Бот перечитывает инструкцию автоматически (ночная джоба) — не отстаёт от портала. | Согласовано, 02.07.2026 |
+| 7 | **Скорость — жёсткое требование владельца**: никаких «думает 30–40 секунд». Целевой ответ — 2–5 секунд. Чат Jivo и сам обрывает бота на 15 секундах (передаёт человеку) — строим быстрого по определению. | Владелец, 02.07.2026 |
+| 8 | **Мозг бота — YandexGPT Lite** (Яндекс Облако): ответ ~1–3 сек, данные в РФ, один счёт с нашим облаком, копейки за ответ. | Владелец, 02.07.2026 |
+
+## 2. Открытые вопросы (не закрыты, ждут решения владельца)
+
+| № | Вопрос | Варианты / заметки |
+|---|---|---|
+| О-1 | ~~Какой ИИ-«мозг»~~ | **ЗАКРЫТ 02.07.2026** → решение 8: YandexGPT Lite. |
+| О-2 | Тариф Jivo | Bot API официально доступен на корпоративном тарифе (~3 142 ₽/мес за оператора). Подтвердить готовность платить, когда дойдём до подключения. Подключение своего бота — по письму в поддержку Jivo (info@jivosite.com), автоматической кнопки нет. |
+| О-3 | Когда включаем бесплатный чат Jivo (без бота, для разведки вопросов) | Код в портале готов, нужен только ключ виджета (JIVO_WIDGET_ID). Включение на боевом — только с разрешения владельца. |
+
+## 3. Что уже есть в портале (задел, ничего строить заново не надо)
+
+- **Виджет Jivo встроен** в личный кабинет (компонент JivoWidget, июнь 2026, G7-A). Спит, пока не задан ключ.
+- **Раздел «Помощь»**: форма заявки в поддержку + почта (support_requests) — останется запасным каналом.
+- **Машинный ключ ИИ** (`lpimp_…`, дверь G7-B): готовый безопасный способ для ИИ смотреть данные конкретного клиента — пригодится на этапе 2 (личные ответы).
+- **Механизм экскурсий** (WelcomeTour): подсветка элементов с пояснениями — переиспользуем для кнопки «Показать».
+- **Плитка «Внешние сервисы»** в админке уже следит, жив ли Jivo (проба JivoLivenessProbe).
+- **Руководство по постройке** своего ИИ-агента поддержки: `вебмастер-исходники-perplexity/Б3-ии-техподдержка.md` (архитектура: база знаний + поиск + ответ, борьба с выдумками, эскалация, метрики).
+
+## 4. Главные факты про Jivo (исследование 02.07.2026)
+
+- **Чат-платформа**: виджет на сайте, каналы Telegram/VK/WhatsApp/почта, приложение оператора на телефоне. Бесплатно до 2 операторов (без автоприглашений и WhatsApp); профессиональный ~1 342 ₽/мес, корпоративный ~3 142 ₽/мес за оператора.
+- **Готовый «ИИ-оператор» Jivo**: 12 990 ₽/мес, 2 000 диалогов, проба 7 дней. База знаний: файлы (до 5×30 МБ), вопрос-ответ пары (до 50), текст «о компании». Отвечает только по базе, личных данных клиента не видит, при незнании передаёт человеку. Модель — российская (у «ИИ-ассистента» официально GigaChat), данные в РФ.
+- **Bot API (наш путь)**: Jivo шлёт сообщение клиента на наш адрес → у нас 3 сек на «принял» и ~15 сек на ответ, иначе диалог уходит живому оператору. Ответ бота: текст или «позови человека». Доступен на корпоративном тарифе, подключение по письму.
+- **152-ФЗ**: Jivo заявляет хранение данных в РФ. В нашу политику конфиденциальности при включении чата добавить упоминание Jivo.
+
+## 5. Целевая картинка (как это будет работать)
+
+1. Клиент в личном кабинете нажимает кнопку чата (Jivo) и пишет: «а что такое проект?»
+2. Jivo мгновенно пересылает вопрос нашему серверу.
+3. Наш бот находит нужный кусок в клиентской инструкции и за 2–5 секунд отвечает: «Проект — это… Создаётся для…» + кнопка **«Показать на портале»**.
+4. Клик по кнопке → портал открывает форму создания проекта и по шагам подсвечивает поля: «здесь название… здесь источник… здесь лимит».
+5. Если бот не знает ответа или клиент просит человека — диалог передаётся владельцу (в приложение оператора Jivo на телефон).
+6. Каждый диалог сохраняется у нас — по ним пополняем инструкцию и видим, чего клиентам не хватает.
+
+## 6. Следующие шаги
+
+- [x] Закрыть О-1 (мозг бота) — YandexGPT Lite (решение 8).
+- [x] Согласовать дизайн целиком (куски 1–4 приняты владельцем 02.07.2026) → спека
+      `docs/superpowers/specs/2026-07-02-jivo-ai-support-bot-design.md`.
+- [ ] Ревью спеки владельцем + коммит протокола и спеки.
+- [ ] План реализации по шагам (writing-plans) → стройка по TDD в worktree, НЕ на проде.
+- [ ] Отдельно решить О-3 — включать ли бесплатный чат уже сейчас для разведки вопросов.
+- [ ] О-2 — подтвердить корпоративный тариф Jivo перед подключением бота.
+
+---
+
+*Журнал обновлений: 02.07.2026 — протокол заведён, зафиксированы решения 1–7, исследование Jivo, открытые вопросы О-1…О-3. Позже в тот же день: решение 8 (YandexGPT Lite), дизайн согласован кусками 1–4, спека записана.*