call-review-platform/services/ingest-service

Ingest Service

Микросервис для приема и хранения событий звонков от UIS.

Технологии

• Python 3.9
• FastAPI
• PostgreSQL
• SQLAlchemy (async)
• Docker & Docker Compose

Структура проекта

ingest-service/
├── app/
│   ├── __init__.py
│   ├── main.py                 # Главный файл приложения
│   ├── crud.py                 # CRUD операции
│   ├── api/
│   │   ├── __init__.py
│   │   └── uis.py              # API endpoints для UIS
│   ├── infrastructure/
│   │   ├── __init__.py
│   │   └── database.py         # Конфигурация БД
│   └── models/
│       ├── __init__.py
│       └── call_event.py       # SQLAlchemy модели
├── alembic/                    # Миграции БД
│   ├── env.py
│   └── versions/
├── alembic.ini
├── Dockerfile
├── requirements.txt
└── .env

Быстрый старт

1. Запуск через Docker Compose (рекомендуется)

# Запустить все сервисы (PostgreSQL + приложение)
docker-compose up -d

# Проверить логи
docker-compose logs -f app

# Остановить сервисы
docker-compose down

Приложение будет доступно по адресу: http://localhost:8000

Swagger документация: http://localhost:8000/docs

2. Локальный запуск для разработки

# Создать виртуальное окружение
python -m venv venv
source venv/bin/activate  # для Linux/Mac
# или
venv\Scripts\activate  # для Windows

# Установить зависимости
pip install -r requirements.txt

# Запустить только PostgreSQL через Docker
docker-compose up -d postgres

# Убедиться, что файл .env настроен правильно

# Запустить приложение
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

API Endpoints

POST /v1/uis/webhook

Webhook для приема событий звонков от UIS

Пример запроса:

{
  "eventType": "call_completed",
  "call_session_id": 12345,
  "direction": "in",
  "employee_id": 100,
  "employee_full_name": "Иванов Иван Иванович",
  "contact_phone_number": "+79001234567",
  "called_phone_number": "+78001234567",
  "communication_group_name": "Продажи",
  "start_time": "2024-01-15T10:30:00",
  "finish_time": "2024-01-15T10:35:00",
  "talk_time_duration": 300,
  "full_record_file_link": "https://example.com/records/12345.mp3",
  "campaign_name": "Зимняя кампания"
}

GET /v1/uis/events (TODO)

Получить список всех событий звонков

Query параметры:

• skip - количество пропускаемых записей (пагинация)
• limit - максимальное количество записей (по умолчанию 100)

Примечание: Endpoint запланирован к реализации

GET /v1/uis/events/{call_session_id} (TODO)

Получить конкретное событие звонка по session_id

Примечание: Endpoint запланирован к реализации

GET /v1/uis/events/employee/{employee_id} (TODO)

Получить все звонки конкретного сотрудника

Query параметры:

• skip - количество пропускаемых записей
• limit - максимальное количество записей

Примечание: Endpoint запланирован к реализации

База данных

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

Таблица call_events содержит следующие поля:

• id - уникальный идентификатор (UUID)
• call_session_id - уникальный ID сессии звонка (BigInteger, индексируется)
• direction - направление звонка (in/out)
• notification_mnemonic - мнемоника уведомления (тип события)
• last_answered_employee_full_name - ФИО сотрудника, ответившего на звонок
• employee_id - ID сотрудника
• finish_time - время окончания звонка (Unix timestamp)
• total_time_duration - общая длительность звонка (в секундах)
• wait_time_duration - длительность ожидания (в секундах)
• total_wait_time_duration - общая длительность ожидания (в секундах)
• talk_time_duration - длительность разговора (в секундах)
• clean_talk_time_duration - чистая длительность разговора (в секундах)
• full_record_file_link - ссылка на запись звонка
• tcm_topcrm_notification_name - название уведомления TCM/TopCRM (название кампании)

Подключение к PostgreSQL

Для подключения к базе данных используйте:

# Через Docker
docker exec -it ingest-postgres psql -U postgres -d ingest_db

# Или напрямую (если PostgreSQL запущен локально)
psql -h localhost -p 5432 -U postgres -d ingest_db

Пароль: postgres

Полезные SQL команды

-- Посмотреть все таблицы
\dt

-- Посмотреть структуру таблицы
\d call_events

-- Посмотреть все записи
SELECT * FROM call_events;

-- Количество звонков по сотрудникам
SELECT employee_full_name, COUNT(*) as call_count
FROM call_events
GROUP BY employee_full_name;

Разработка

Миграции (Alembic)

Для работы с миграциями базы данных:

# Инициализация Alembic (уже выполнено)
alembic init alembic

# Создать новую миграцию
alembic revision --autogenerate -m "описание изменений"

# Применить миграции
alembic upgrade head

# Откатить последнюю миграцию
alembic downgrade -1

Тестирование

# Установить зависимости для тестирования
pip install pytest pytest-asyncio httpx

# Запустить тесты (когда будут созданы)
pytest

Переменные окружения

• DATABASE_URL - строка подключения к PostgreSQL
• APP_HOST - хост для запуска приложения
• APP_PORT - порт для запуска приложения

Troubleshooting

Ошибка подключения к БД

Если не удается подключиться к базе данных:

1. Проверьте, что PostgreSQL запущен: docker-compose ps
2. Проверьте логи: docker-compose logs postgres
3. Проверьте правильность DATABASE_URL в переменных окружения

Ошибка при создании таблиц

Если таблицы не создаются автоматически:

1. Подключитесь к БД
2. Удалите все таблицы: DROP TABLE IF EXISTS call_events CASCADE;
3. Перезапустите приложение

Лицензия

MIT