# Обзор Архитектуры Контакт-Центра (MVP)

Контакт-центр спроектирован на базе микросервисной архитектуры с использованием событийно-ориентированного подхода (Event-Driven Architecture). Описываемая платформа поддерживает омниканальные коммуникации (Голос, Telegram, Email, Webchat, WhatsApp) с глубокой интеграцией AI-операторов (Voice AI V1, Telegram AI) и полноценной системой маршрутизации.

## 1. Основные компоненты (Микросервисы)

Архитектура состоит из множества независимых сервисов, написанных на Python (FastAPI):

### Базовые и инфраструктурные сервисы
- **`api-gateway`** — Единая точка входа для клиентских интерфейсов (UI оператора/супервизора/админа).
- **`auth-service`** — Сервис аутентификации и RBAC. Поддерживает OIDC (Keycloak) и авторизацию по `APP_TOKEN_SECRET`.
- **`audit-service`** — Служба записи логов аудита системных действий (подключена к шине событий).
- **`event-bus-service`** — Асинхронная шина событий. Реализует паттерн Transactional Outbox/Inbox поверх брокера **RabbitMQ** для надежной доставки сообщений между сервисами.

### Клиентоцентричные сервисы и роутинг
- **`customer-service`** — Хранит профили клиентов. Управляет связыванием номеров телефонов и Telegram/Webchat-аккаунтов в единый профиль (`customer_external_identities`).
- **`interaction-service`** — Канонический источник истины об "обращениях" (Interactions). Хранит таймлайн общения клиента и статусы тикетов.
- **`routing-service`** — Умная маршрутизация: оценка занятости сотрудников, скилл-бейзд роутинг, распределение по очередям.

### Телефония и Медиа каналы (Adapters)
- **`asterisk-bridge-service`** — Главный мост с Asterisk телефонией (перехват AMI-событий с префиксом `MVPCC`). Отслеживает звонки, трансферы и командует Asterisk'ом.
- **`ivr-service`** — Сервис голосового меню. Настраивает IVR потоки (flows) через интерфейс администратора и обрабатывает DTMF клики.
- **`recording-service`** — Сервис управления записями звонков. Позволяет скачивать (SFTP) и локально управлять аудиофайлами звонков.
- **`voice-adapter-service`** — Сохраняет события жизненного цикла звонков в БД.
- **`telegram-adapter-service`** / **`email_adapter_service`** / **`webchat_adapter_service`** / **`whatsapp_adapter_service`** — Адаптеры интеграции с внешними цифровыми каналами (мессенджерами и веб-чатами).

### Интеллект и База Знаний (AI & KB)
- **`kb-service`** — Локальная База Знаний. Содержит категории, статьи и обеспечивает быстрый поиск.
- **`ai_orchestrator_service`** — Детерминированный мозг ИИ. Принимает решения о генерации ответа или передаче диалога (Handoff) оператору на основе контекста и бизнес-правил.
- **`ai_voice_runtime_service`** — Реал-тайм прослойка аудио-моста (Speech-to-Text / Text-to-Speech) для голосового робота. Обрабатывает перебивания (barge-in) в реальном времени.

### Аналитика, Отчетность и Надзор
- **`reporting-service`** — Агрегация KPI (Service Level, ASA, AHT, Abandon Rate, FCR) в разрезе каналов и агентов.
- **`supervisor-service`** — "Живой" мониторинг контакт-центра (статусы агентов, метрики, прослушка записей).

## 2. Пользовательские Интерфейсы (UI Shells)

Проект предоставляет несколько разделенных рабочих сред:
- `/operator` — Единое окно оператора (Обработка звонков: «Взять в работу», «Трансфер», «Сброс», переписка Telegram/Webchat). ИИ-сводки по звонкам.
- `/supervisor` — Окно супервизора (Мониторинг очередей, статусов агентов, поиск и прослушивание записей звонков из `recording-service`).
- `/admin` — Администрирование (Назначение ролей, управление очередями, конфигурация IVR деревьев, превью маршрутизации).
- `/analyst` — Выгрузки и детальная панель исторических KPI и отчетов.

## 3. Стратегия Данных и Развертывание

1. **Хранение данных:** Каждый микросервис спроектирован так, чтобы иметь изолированную логическую базу. 
   - По умолчанию используется локальный **SQLite**.
   - Для K8s Scale/Продакшена используется **PostgreSQL** DB Pooling (настраивается через переменные `DB_POOL_SIZE`, `DB_MAX_OVERFLOW`).
   - Исходным механизмом миграций является `Alembic` (скрипт `scripts/migrate_core_db.py`).
2. **Инфраструктура / Развертывание:** 
   - Разработка ведется через локальные Docker Compose конфигурации (`docker-compose.yml`, `docker-compose.server.yml`). Готов набор PS/Bash скриптов в директории `scripts/` (например, `scripts/prepare_demo.ps1`).
   - Для серверов и Enterprise масштабов написаны Kubernetes Helm Chart (`deployment/helm`) и K8s манифесты.
   - Шина **RabbitMQ** используется как канонический брокер сообщений для `event_outbox`/`event_inbox` логики обмена.