237 lines
7.6 KiB
Markdown
237 lines
7.6 KiB
Markdown
# 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 (рекомендуется)
|
||
|
||
```bash
|
||
# Запустить все сервисы (PostgreSQL + приложение)
|
||
docker-compose up -d
|
||
|
||
# Проверить логи
|
||
docker-compose logs -f app
|
||
|
||
# Остановить сервисы
|
||
docker-compose down
|
||
```
|
||
|
||
Приложение будет доступно по адресу: http://localhost:8000
|
||
|
||
Swagger документация: http://localhost:8000/docs
|
||
|
||
### 2. Локальный запуск для разработки
|
||
|
||
```bash
|
||
# Создать виртуальное окружение
|
||
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
|
||
|
||
**Пример запроса:**
|
||
```json
|
||
{
|
||
"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
|
||
|
||
Для подключения к базе данных используйте:
|
||
|
||
```bash
|
||
# Через 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 команды
|
||
|
||
```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)
|
||
|
||
Для работы с миграциями базы данных:
|
||
|
||
```bash
|
||
# Инициализация Alembic (уже выполнено)
|
||
alembic init alembic
|
||
|
||
# Создать новую миграцию
|
||
alembic revision --autogenerate -m "описание изменений"
|
||
|
||
# Применить миграции
|
||
alembic upgrade head
|
||
|
||
# Откатить последнюю миграцию
|
||
alembic downgrade -1
|
||
```
|
||
|
||
### Тестирование
|
||
|
||
```bash
|
||
# Установить зависимости для тестирования
|
||
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
|
||
|