FileAudioAPI/README.md

# FileAudioAPI

## Назначение и роль в экосистеме

**FileAudioAPI** — сервис **учёта аудио и результатов распознавания** между диском, GPU-распознаванием и веб-клиентом. На **FastAPI**: хранит метаданные и статусы в БД, складывает файлы в общий каталог **`AUDIOFILES_PATH`** (тот же volume `audiofiles`, что у **GigaAM_API** и **Calls_WEB_Client_main**), инициирует ASR в **GigaAM_API**, принимает обратно текст/заключение, при необходимости дергает webhook в **Calls_WEB_Client_main**.

| Направление | Роль |
|-------------|------|
| **Внутренние файлы** | Регистрация, очереди `process-all`, статусы `recognition_*`, связь с `AiConclusion`. |
| **Внешние файлы** | Загрузка с опциональным `callback_url`, сохранение под UUID-именем в общей папке, **всегда** постановка на распознавание в GigaAM. |
| **Интеграция** | `GIGAAM_API_URL`, `CALLS_WEB_CLIENT_URL` / `WEBHOOK_API_KEY` для доставки результатов в основное приложение. |

Swagger: **`/api/v1/docs`** (см. ниже).

---

Сервис для хранения аудиофайлов, индексации файлов, записи и выдачи результатов распознавания, реализованный на **FastAPI**.

## 🚀 Быстрый старт

```bash
# Перейти в директорию сервиса (от корня репозитория SpeechAnalytics)
cd FileAudioAPI

# Запуск с Docker (рекомендуется)
docker-compose up -d

# Или использовать Makefile
make up
```

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

API документация:
- 📚 **Swagger UI**: http://localhost:8000/api/v1/docs
- 📖 **ReDoc**: http://localhost:8000/api/v1/redoc

## 📚 Документация

- 📘 [Quick Start Guide](START.md) - Быстрый старт
- 📗 [API Documentation](README_FASTAPI.md) - Полная документация API
- 📕 [Docker Deployment](README_DOCKER.md) - Развертывание в Docker

## 🎯 Возможности

- ✅ Загрузка аудиофайлов (MP3, WAV, OGG, FLAC, M4A, AAC)
- ✅ Хранение файлов с автоматической индексацией
- ✅ Асинхронное распознавание аудио в фоне
- ✅ Отслеживание статуса распознавания
- ✅ Получение результатов распознавания
- ✅ RESTful API с автоматической документацией
- ✅ Валидация данных с Pydantic
- ✅ Docker поддержка

## 🏗️ Архитектура

```
apiApp/
├── schemas/          # Pydantic модели (валидация)
├── services/         # Business logic (CRUD операции)
├── routers/          # API endpoints (контроллеры)
├── database/         # SQLAlchemy модели
├── dbApi/           # Legacy compatibility layer
├── config.py        # Конфигурация
└── database.py      # SQLAlchemy настройка
```

## 🔧 Технологии

- **FastAPI** - Современный веб-фреймворк
- **SQLAlchemy 2.0** - ORM для работы с БД
- **Pydantic** - Валидация данных
- **Uvicorn** - ASGI сервер
- **Docker** - Контейнеризация

## 📋 Основные endpoints

| Метод | Endpoint | Описание |
|-------|----------|----------|
| POST | `/api/v1/upload` | Загрузка аудиофайла |
| GET | `/api/v1/audio/list` | Список всех файлов |
| GET | `/api/v1/audio/{id}` | Информация о файле |
| GET | `/api/v1/audio/file/{id}` | Скачать файл |
| DELETE | `/api/v1/audio/delete/{id}` | Удалить файл |
| POST | `/api/v1/recognize/{id}` | Запустить распознавание |
| GET | `/api/v1/recognize/{id}` | Статус распознавания |
| GET | `/api/v1/recognize/task/{task_id}` | Статус по task_id |
| GET | `/api/v1/recognize/{id}/result` | Результат распознавания |

## 🛠️ Установка и запуск

### С Docker (рекомендуется)

```bash
# Использование Makefile
make up

# Или напрямую с Docker Compose
docker-compose up -d

# Просмотр логов
make logs
# или
docker-compose logs -f
```

### Локально

```bash
# Установка зависимостей
make install
# или
pip3 install -r requirements.txt

# Создание базы данных
make db-migrate

# Запуск
make dev
# или
python3 run.py
```

## 🔧 Makefile команды

```bash
make help      # Показать все команды
make build     # Собрать Docker образ
make up        # Запустить контейнеры
make down      # Остановить контейнеры
make restart   # Перезапустить
make logs      # Логи
make shell     # Shell в контейнере
make test      # Запуск тестов
make clean     # Очистка
```

## 📝 Примеры использования

### Загрузка файла

```bash
curl -X POST http://localhost:8000/api/v1/upload \
  -F "file=@audio.mp3"
```

### Запуск распознавания

```bash
curl -X POST http://localhost:8000/api/v1/recognize/{audio_id}
```

### Получение статуса

```bash
curl http://localhost:8000/api/v1/recognize/{audio_id}
```

### Получение результата

```bash
curl http://localhost:8000/api/v1/recognize/{audio_id}/result
```

## 🔒 Production

Для production развертывания:

1. Используйте PostgreSQL вместо SQLite
2. Настройте Redis для хранения статусов задач
3. Ограничьте CORS origins
4. Добавьте аутентификацию
5. Настройте SSL/HTTPS
6. Используйте несколько workers

Подробнее в [Docker Deployment Guide](README_DOCKER.md)

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

```bash
# Запуск тестов
make test

# Или напрямую
pytest tests/ -v
```

## 📊 Мониторинг

```bash
# Health check
curl http://localhost:8000/health

# Docker stats
docker stats file-audio-api

# Логи
docker-compose logs -f app
```

## 🤝 Рефакторинг

Проект был успешно рефакторин из Flask в FastAPI с улучшением архитектуры:

**Основные изменения:**
- ✅ Многослойная архитектура (schemas → services → routers)
- ✅ Разделение по доменам
- ✅ Асинхронная обработка задач
- ✅ Автодокументация API
- ✅ Type hints и валидация
- ✅ Docker поддержка

## 📄 Лицензия

[MIT License](LICENSE)

## 👨‍💻 Автор

Speech Analytics Team

---

📖 Более подробная информация в документации:
- [Quick Start](START.md)
- [API Docs](README_FASTAPI.md)
- [Docker Guide](README_DOCKER.md)