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           # Главный файл приложения
│   ├── database.py       # Конфигурация БД
│   ├── models.py         # SQLAlchemy модели
│   ├── crud.py           # CRUD операции
│   └── api/
│       ├── __init__.py
│       └── uis.py        # API endpoints для UIS
├── docker-compose.yaml
├── Dockerfile
├── requirements.txt
└── .env.example

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

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
cp .env.example .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-abcde",
  "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

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

Query параметры:

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

GET /v1/uis/events/{call_session_id}

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

GET /v1/uis/events/employee/{employee_id}

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

Query параметры:

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

База данных

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

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

• id - уникальный идентификатор (автоинкремент)
• event_type - тип события
• call_session_id - уникальный ID сессии звонка
• direction - направление звонка (in/out)
• employee_id - ID сотрудника
• employee_full_name - ФИО сотрудника
• contact_phone_number - телефон контакта
• called_phone_number - набранный телефон
• communication_group_name - название группы коммуникации
• start_time - время начала звонка
• finish_time - время окончания звонка
• talk_time_duration - длительность разговора (в секундах)
• full_record_file_link - ссылка на запись звонка
• campaign_name - название кампании
• created_at - дата создания записи
• updated_at - дата последнего обновления

Подключение к 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