# Архитектура Голосового ИИ (Voice AI V1)

Этот документ описывает техническое устройство и жизненный цикл обработки входящих голосовых звонков с помощью ИИ-оператора. ИИ интегрирован поверх базовой телефонии Asterisk и не заменяет ее полностью, выступая как первая линия поддержки (L1).

## 1. Ключевые принципы

1. **AI-first**: Звонок сначала направляется ИИ, если очередь настроена соответствующим образом.
2. **Перехват звонка (Handoff)**: Исходный звонок детерминированно переключается на человека-оператора, если ИИ не может решить проблему или если клиент явно просит человека.
3. **Единый источник истины**: Asterisk остается мастер-системой для SIP-потока, записи звонков и маршрутизации.
4. **Безопасность (Read-Only)**: В версии V1 ИИ работает исключительно на чтение и выдачу справочной информации. Апдейт критичных финансовых данных в базе строго запрещен для ИИ и требует переключения на человека.

## 2. Архитектура обработки звонка

Процесс обработки звонка ИИ разделен на два основных микросервиса:

- **`ai_voice_runtime_service` (Аудио-прослойка):** Осуществляет прием аудио-потока. Работает в Real-time. Слушает аудио (через ASR модель) и отправляет синтезированную речь обратно клиенту (через TTS модель). Также отлавливает попытки клиента перебить робота (Barge-in), мгновенно прерывая воспроизведение.
- **`ai_orchestrator_service` (Мозг ИИ):** Не работает со звуком. Получает только готовый текстовый транскрипт (реплику). Принимает решение:
  1. Найти знания в `kb-service` (RAG).
  2. Сгенерировать текстовый ответ для клиента (который будет озвучен через TTS).
  3. Если запрос слишком сложный — отправить команду "Переключить на живого человека".

## 3. Флоу входящего звонка (Step-by-step)

1. Абонент звонит на платформу.
2. **`asterisk-bridge-service`** улавливает событие и решает направить звонок в `voice_lab`.
3. Поднимаются две параллельные сессии: `voice_ai_session` (отслеживание аудио) и `ai_session` (бизнес-логика).
4. Абонент подключается к медиа-интерфейсу `ai_voice_runtime_service`. Проигрывается дисклеймер: "Здравствуйте, я голосовой помощник...".
5. Абонент озвучивает свой вопрос.
6. ASR распознает вопрос и отправляет текст в **`ai_orchestrator_service`**.
7. Оркестратор смотрит историю клиента, ищет ответ в базе знаний, генерирует ответ и возвращает команду в runtime "Скажи это".
8. Если оркестратор понимает, что нужна помощь:
   - Отправляет сигнал `needs_handoff` с детальной "Сводкой ИИ" для оператора.
   - Звонок перехватывается, и абонент слушает музыку ожидания в очереди к живым людям.

## 4. Интеграция с Operator UI

Когда звонок поступает к оператору после ИИ, оператор не видит отдельный ИИ-интерфейс. Он видит стандартную карточку звонка. Но внутри этой карточки динамически выводится:
- **AI Summary (Сводка):** Что клиент сказал, что ИИ попытался сделать и почему перевел звонок на человека.
- **Таймлайн:** В историю обращений клиента логгируется, что "ИИ запрашивал перевод на специалиста".