discussion: Возможность отвечать клиентам из tenant dashboard

[dapi]

Описание

Обсуждение возможности отправлять сообщения клиентам из раздела "Чаты" в tenant dashboard.

Бизнес-контекст

Проблема

Владельцы автосервисов (tenants) имеют доступ только к просмотру переписок с клиентами (#102). При этом AI-бот, несмотря на высокую эффективность, не может покрыть 100% кейсов:

• Нестандартные ситуации: сложные переговоры о скидках, VIP-клиенты
• Конфликты: недовольство качеством, споры по стоимости
• Экстренные случаи: срочные заказы, изменения в расписании
• Уточнение деталей: специфические технические вопросы

Связь с Product Constitution

⚠️ Важно: Product Constitution требует "AI-First Approach" и "Dialogue-Only Interaction". Любое решение должно:

• Сохранять AI как основной интерфейс (не заменять его)
• Не создавать жёстких кнопок/меню для клиента
• Поддерживать естественный диалог

---

👥 Персоны пользователей

Персона 1: Менеджер автосервиса (Анна)

• Роль: Управляет клиентами и записями
• Боль: Видит, что бот не справился с запросом VIP-клиента, но не может вмешаться
• Потребность: Возможность "подхватить" сложный диалог

Персона 2: Владелец автосервиса (Сергей)

• Роль: Контролирует бизнес-процессы
• Боль: Теряет клиентов из-за невозможности оперативно отреагировать на нестандартный запрос
• Потребность: Полный контроль над коммуникацией с клиентами

Персона 3: Клиент автосервиса (Иван)

• Боль: Ждёт ответа от бота, который не может решить его специфический вопрос
• Потребность: Быстрое решение проблемы, не важно от кого — бота или человека

---

📋 Use Cases

UC-1: Эскалация при неудовлетворённости клиента

Актёры: Клиент, AI-бот, Менеджер
Предусловие: Клиент выражает недовольство в чате

Основной сценарий:

1. Клиент пишет: "Это слишком дорого, в другом сервисе дешевле!"
2. AI-бот отвечает стандартно о качестве услуг
3. Клиент: "Хочу поговорить с человеком!"
4. AI-бот не может передать диалог (текущее состояние)
5. Проблема: Клиент уходит к конкуренту

Желаемый сценарий:
1-3. Те же шаги
4. Менеджер видит в dashboard индикатор "проблемный диалог"
5. Менеджер перехватывает диалог
6. Менеджер: "Здравствуйте! Меня зовут Анна. Давайте обсудим персональную скидку..."
7. Клиент записывается на услугу

Бизнес-ценность: Сохранение клиента, увеличение конверсии на 15-20%

---

UC-2: VIP-клиент с нестандартным запросом

Актёры: VIP-клиент, AI-бот, Владелец
Предусловие: VIP-клиент (постоянный, высокий LTV) делает нестандартный заказ

Основной сценарий:

1. VIP-клиент: "Нужно покрасить машину в эксклюзивный цвет, хочу обсудить детали"
2. AI-бот даёт стандартную информацию о покраске
3. VIP-клиент: "Вы не понимаете, мне нужен именно 'Racing Green Metallic Pearl'"
4. AI-бот не знает про специфические цвета
5. Проблема: VIP-клиент разочарован, уходит

Желаемый сценарий:
1-2. Те же шаги
3. Владелец видит VIP-клиента в dashboard (отмечен специальным значком)
4. Владелец перехватывает: "Добрый день! Конечно, работаем с эксклюзивными цветами..."
5. Клиент доволен персональным подходом

Бизнес-ценность: Удержание VIP-клиентов, сохранение высокомаржинальных заказов

---

UC-3: Срочное изменение расписания

Актёры: Клиент, AI-бот, Менеджер
Предусловие: Клиент записан на завтра, но обстоятельства изменились

Основной сценарий:

1. Клиент: "Мне срочно нужно перенести запись с завтра на сегодня!"
2. AI-бот проверяет расписание — слотов нет
3. AI-бот: "К сожалению, на сегодня все слоты заняты"
4. Проблема: Менеджер знает, что можно "уплотнить" расписание, но не может вмешаться

Желаемый сценарий:
1-2. Те же шаги
3. Менеджер видит срочный запрос
4. Менеджер вмешивается: "Сделаем исключение, приезжайте в 18:00"
5. Клиент благодарен за гибкость

Бизнес-ценность: Повышение лояльности, положительные отзывы

---

UC-4: Техническая консультация

Актёры: Клиент, AI-бот, Мастер
Предусловие: Клиент задаёт глубокий технический вопрос

Основной сценарий:

1. Клиент: "После вашей покраски появились пузыри через месяц. Это брак?"
2. AI-бот даёт общую информацию о гарантии
3. Клиент: "Мне нужен конкретный ответ — возможно ли это из-за температуры сушки?"
4. AI-бот не имеет глубокой технической экспертизы
5. Проблема: Клиент не получает ответа, пишет негативный отзыв

Желаемый сценарий:
1-2. Те же шаги
3. Мастер (или менеджер) подключается к диалогу
4. Мастер объясняет причины и предлагает решение
5. Клиент удовлетворён, проблема решена

Бизнес-ценность: Снижение негативных отзывов, экспертный имидж

---

UC-5: Проактивное предложение допуслуг

Актёры: Клиент, AI-бот, Менеджер
Предусловие: Клиент обсуждает базовую услугу

Основной сценарий:

1. Клиент записывается на полировку
2. AI-бот подтверждает запись
3. Менеджер видит, что можно предложить защитную плёнку
4. Проблема: Менеджер не может отправить предложение

Желаемый сценарий:
1-2. Те же шаги
3. Менеджер: "Рекомендую также рассмотреть нанесение защитной плёнки — сейчас акция 20%!"
4. Клиент соглашается на доп. услугу

Бизнес-ценность: Увеличение среднего чека на 20-30%

---

📊 Бизнес-метрики

Текущее состояние (без функции)

• Conversion Rate: ~70% (30% теряются на сложных кейсах)
• Customer Satisfaction: ~80% (недовольство невозможностью связаться с человеком)
• Average Order Value: базовый (без upsell через чат)

Ожидаемый эффект

Метрика	До	После	Изменение
Conversion Rate	70%	85%	+15%
Customer Satisfaction	80%	92%	+12%
Average Order Value	100%	120%	+20%
VIP Retention	85%	95%	+10%

Критерии успеха

• ✅ < 5% диалогов требуют вмешательства менеджера
• ✅ Время реакции менеджера < 5 минут
• ✅ 90% эскалаций завершаются успешной конверсией

---

Варианты реализации

Вариант 1: Только просмотр (текущий)

Плюсы:

• Простая реализация
• Бот остаётся единственным источником ответов — консистентность
• Полностью соответствует Product Constitution
• Нет риска конфликтов бот/менеджер

Минусы:

• Менеджер не может вмешаться в сложных ситуациях
• Клиент может ждать ответа бота, когда нужен человек
• Потеря клиентов на сложных кейсах

Рекомендация: ✅ Для MVP достаточно

---

Вариант 2: Ответ от имени бота

Менеджер пишет сообщение → оно уходит клиенту в Telegram от имени бота.

Плюсы:

• Клиент не видит разницы — seamless experience
• Менеджер может помочь в сложных случаях

Минусы:

• ⚠️ Этический вопрос: клиент думает, что общается с AI
• Нужна логика "передачи" диалога от бота к менеджеру и обратно
• Бот может ответить параллельно с менеджером

Технические вопросы:

• Как бот узнаёт, что не нужно отвечать?
• Таймаут на "режим менеджера"?
• Индикатор в UI, что менеджер взял диалог?

Рекомендация: ⚠️ Не рекомендуется из-за этических вопросов

---

Вариант 3: Явная передача диалога (Рекомендуемый)

Кнопка "Взять диалог" → бот отключается → бот сообщает: "Вас переключили на менеджера" → менеджер отвечает → кнопка "Вернуть боту".

Плюсы:

• ✅ Чёткое разделение ответственности
• ✅ Этично: клиенту сообщают о переключении
• ✅ Соответствует Product Constitution (AI остаётся основным)
• Нет конфликтов бот/менеджер

Минусы:

• Сложнее в реализации
• Менеджер должен явно "отдать" диалог обратно
• Что если менеджер забыл вернуть диалог?

Митигация рисков:

• Авто-возврат диалога боту через 30 мин неактивности
• Уведомление менеджеру "Вы забыли вернуть диалог"
• Dashboard показывает все "захваченные" диалоги

Рекомендация: ✅ Лучший вариант для production

---

Вариант 4: Гибридный режим ("Комментарий менеджера")

Бот отвечает, но менеджер может отправить сообщение с пометкой: "💬 Менеджер Анна: ..."

Плюсы:

• Клиент понимает, кто отвечает
• Бот продолжает работать
• Менеджер может уточнить/исправить

Минусы:

• Может быть confusing для клиента
• Два источника ответов одновременно
• Бот может ответить неуместно после сообщения менеджера

Рекомендация: ⚠️ Возможен как fallback

---

⚠️ Риски и митигации

Риск	Вероятность	Влияние	Митигация
Менеджер забывает вернуть диалог	Высокая	Средняя	Авто-возврат через 30 мин
Конфликт сообщений бот/менеджер	Средняя	Высокая	Явный режим "перехвата"
Злоупотребление (спам клиентам)	Низкая	Высокая	Audit log, лимиты сообщений
Снижение AI usage	Средняя	Средняя	KPI на % диалогов с вмешательством

---

🎯 Рекомендация по приоритету

Фаза 1: MVP (текущий #102)

• ✅ Только просмотр
• Сбор статистики: % диалогов, требующих вмешательства

Фаза 2: После сбора данных (если > 10% требуют вмешательства)

• Реализовать Вариант 3: Явная передача диалога
• Включить audit log всех вмешательств

Фаза 3: Оптимизация

• AI-детекция "проблемных" диалогов
• Автоматическое уведомление менеджера
• Интеграция с CRM для VIP-клиентов

---

Вопросы для обсуждения

1. Нужна ли эта функция вообще? Или бота достаточно?

2. Как часто менеджеру нужно вмешиваться?

   • Редко (< 5% диалогов) → может не стоит усложнять
   • Часто (> 20%) → критически важно

3. Этика: какой вариант прозрачнее для клиента?

4. Приоритет: сейчас или после сбора статистики на MVP?

5. Метрики: какие KPI будут отслеживаться?

---

Связанные issues

• feat(tenants): Раздел Чаты в tenant dashboard #102 — Раздел "Чаты" (только просмотр) ✅ CLOSED

---

🤖 Generated with Claude Code

[dapi]

📋 User Story создана

Создана полная User Story для Варианта 3: Явная передача диалога:

Документ: docs/requirements/user-stories/US-010-tenant-chat-takeover.md

Ключевые моменты:

Story Points: 8
Estimated Time: 5-7 дней
Приоритет: Medium

Фазы реализации:

1. MVP (3-4 дня): Базовый takeover/release, отправка сообщений
2. Полировка (2-3 дня): Авто-возврат, аналитика, audit log
3. Оптимизация (после launch): AI-детекция проблемных диалогов

Зависимости:

• ✅ feat(tenants): Раздел Чаты в tenant dashboard #102 (Раздел Чаты) - CLOSED

---

🤖 Generated with Claude Code

[dapi]

📐 Technical Specification создана

Создана полная техническая спецификация:

Документ: docs/requirements/tsd/TSD-011-tenant-chat-takeover.md

Ключевые решения:

Архитектура:

• ChatTakeoverService — управление takeover/release
• ManagerMessageService — отправка сообщений
• ChatTakeoverTimeoutJob — авто-возврат через 30 мин

Модель данных:

• Chat.mode — enum [:ai_mode, :manager_mode]
• Chat.taken_by — ссылка на User
• Message.sender_type — enum [:ai, :manager, :client, :system]
• ChatTakeoverLog — audit log

Фазы реализации:

Фаза	Время	Описание
1. Database & Models	4ч	Миграции, модели
2. Services	6ч	Takeover, Message, Timeout
3. Controller & Routes	4ч	API endpoints
4. Views & UI	6ч	Turbo Streams, Stimulus
5. Testing	6ч	Unit, Integration, E2E
6. Polish	4ч	Analytics, documentation

Итого: ~30 часов (5-7 дней)

---

🤖 Generated with Claude Code

[dapi]

✅ Фаза 1 выполнена

Реализован read-only просмотр чатов в tenant dashboard:

• 📋 Список чатов с пагинацией и сортировкой
• 💬 Просмотр переписки (Telegram-style UI)
• 👤 Информация о клиенте + ссылки
• 📊 Счётчики сообщений и заявок

Код: app/controllers/tenants/chats_controller.rb, app/views/tenants/chats/

---

Ожидается решение по Фазе 2: нужна ли возможность отвечать клиентам?

[dapi]

🏗️ Архитектура и план реализации Фазы 2

Архитектура

┌─────────────────────────────────────────────────────────────────┐
│                     Tenant Dashboard                             │
│  ┌─────────────────┐  ┌──────────────────────────────────────┐  │
│  │   Chat List     │  │         Chat View                     │  │
│  │                 │  │  ┌────────────────────────────────┐  │  │
│  │  [🔴 Manager]   │  │  │ Messages...                    │  │  │
│  │  [🤖 Bot]       │  │  └────────────────────────────────┘  │  │
│  │  [🤖 Bot]       │  │  ┌────────────────────────────────┐  │  │
│  │                 │  │  │ [Взять диалог] или [Ввод...]   │  │  │
│  └─────────────────┘  │  └────────────────────────────────┘  │  │
└─────────────────────────────────────────────────────────────────┘
           │                         │
           ▼                         ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Rails Backend                                │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │ ChatsController                                              ││
│  │   POST /chats/:id/take_over   → ManagerTakeoverService      ││
│  │   POST /chats/:id/messages    → ManagerMessageService       ││
│  │   POST /chats/:id/release     → ManagerReleaseService       ││
│  └─────────────────────────────────────────────────────────────┘│
│  ┌─────────────────────────────────────────────────────────────┐│
│  │ Chat Model                                                   ││
│  │   + manager_active: boolean                                  ││
│  │   + manager_active_until: datetime                           ││
│  │   + manager_user_id: references                              ││
│  └─────────────────────────────────────────────────────────────┘│
│  ┌─────────────────────────────────────────────────────────────┐│
│  │ Message Model                                                ││
│  │   role: user | assistant | manager | tool | system          ││
│  │   + sent_by_user_id: references (для manager messages)      ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────────┐
│                   Telegram Bot API                               │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │ TelegramMessageSender                                        ││
│  │   send_message(chat_id, text)                                ││
│  │   → Telegram::Bot::Client.new(token).send_message(...)      ││
│  └─────────────────────────────────────────────────────────────┘│
│  ┌─────────────────────────────────────────────────────────────┐│
│  │ WebhookController (изменения)                                ││
│  │   if chat.manager_active?                                    ││
│  │     → НЕ отвечать ботом, только сохранить сообщение         ││
│  │   else                                                       ││
│  │     → Обычная обработка AI                                   ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘

---

📋 План реализации

Этап 1: Модель данных (1-2 часа)

• Миграция: добавить в chats поля manager_active, manager_active_until, manager_user_id
• Миграция: добавить в messages поле sent_by_user_id
• Добавить роль manager в enum Message#role
• Валидации и scopes в моделях

Этап 2: Сервисы (2-3 часа)

• ManagerTakeoverService — взять диалог (установить флаг + отправить уведомление клиенту)
• ManagerMessageService — отправить сообщение (сохранить + отправить в Telegram)
• ManagerReleaseService — вернуть диалог боту (сбросить флаг + уведомить клиента)
• TelegramMessageSender — низкоуровневая отправка через Bot API

Этап 3: Контроллер (1-2 часа)

• POST /chats/:id/take_over — взять диалог
• POST /chats/:id/messages — отправить сообщение
• POST /chats/:id/release — вернуть боту
• Авторизация: только owner/member tenant'а

Этап 4: UI (2-3 часа)

• Кнопка "Взять диалог" (когда manager_active = false)
• Форма отправки сообщения (когда manager_active = true)
• Кнопка "Вернуть боту"
• Индикатор в списке чатов (🔴 менеджер / 🤖 бот)
• Turbo Streams для real-time обновлений

Этап 5: Интеграция с ботом (1-2 часа)

• Изменить WebhookController: проверка chat.manager_active?
• Если менеджер активен → сохранить сообщение, НЕ вызывать AI
• Auto-release: job для сброса manager_active по таймауту (30 мин)

Этап 6: Тесты (2-3 часа)

• Unit тесты сервисов
• Controller тесты
• Integration тесты (takeover → message → release flow)

---

⚠️ Важные решения

Вопрос	Решение
Таймаут менеджера	30 минут неактивности → auto-release
Уведомление клиенту	"Вас переключили на менеджера" / "Вас вернули боту"
Роль сообщения	manager (отдельная от assistant)
Отображение для клиента	Сообщения от менеджера приходят от того же бота

---

📊 Оценка

Этап	Время
Модель данных	1-2 ч
Сервисы	2-3 ч
Контроллер	1-2 ч
UI	2-3 ч
Интеграция с ботом	1-2 ч
Тесты	2-3 ч
Итого	9-15 часов

---

🔗 Зависимости

• Требуется: telegram-bot gem (уже есть)
• Требуется: Turbo Streams для real-time (уже настроен)

Готов к реализации после подтверждения архитектуры.

[dapi]

📋 Подзадачи Фазы 2

#	Задача	Оценка	Зависимости
#154	Модель данных для manager takeover	1-2 ч	—
#155	Сервисы для manager takeover	2-3 ч	#154
#156	API endpoints для manager takeover	1-2 ч	#154, #155
#157	UI для отправки сообщений	2-3 ч	#156
#158	Интеграция manager mode с ботом	1-2 ч	#154, #155

Порядок реализации: #154 → #155 → #156, #158 (параллельно) → #157

Итого: 9-15 часов

[dapi]

🌿 Ветка разработки

Branch: feature/103-manager-reply-from-dashboard

Все дочерние задачи должны создавать ветки от этой родительской:

git checkout feature/103-manager-reply-from-dashboard
git checkout -b feature/XXX-your-feature

Дочерние issues:

• feat(chat): Модель данных для manager takeover #154 — Модель данных
• feat(chat): Сервисы для manager takeover #155 — Сервисы
• feat(chat): API endpoints для manager takeover #156 — API endpoints
• feat(chat): UI для отправки сообщений менеджером #157 — UI
• feat(chat): Интеграция manager mode с ботом #158 — Интеграция с ботом