Bible API

REST API для работы с переводами Библии, озвучкой и аномалиями.

🔐 Авторизация

API использует двухуровневую систему авторизации:

1. Статичный API ключ (X-API-Key) - для публичных GET эндпоинтов
2. JWT токены (Authorization: Bearer) - для административных операций (24 часа)

# Публичные эндпоинты
curl -H "X-API-Key: bible-api-key-2024" http://localhost:8000/translations

# Административные эндпоинты
TOKEN=$(curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}' | jq -r '.access_token')

curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/voices/1/anomalies

📖 Документация: docs/AUTHENTICATION.md
🧪 Тестирование: python tests/test_auth.py

Аномалии озвучки

Статусы аномалий

• detected - ошибка выявлена автоматически (по умолчанию)
• confirmed - ошибка подтверждена при проверке
• disproved - ошибка опровергнута, не подтверждена проверкой
• corrected - выполнена ручная коррекция
• already_resolved - уже исправлена ранее (только для системного использования)

API методы

GET /voices/{voice_code}/anomalies

Получение списка аномалий для голоса с возможностью фильтрации по статусу.

Параметры:

• voice_code (path) - код голоса
• status (query, optional) - фильтр по статусу аномалии

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

GET /voices/1/anomalies?status=detected

PATCH /voices/anomalies/{anomaly_code}/status

Обновление статуса аномалии с возможностью корректировки временных меток.

Параметры:

• anomaly_code (path) - код аномалии

Тело запроса:

{
  "status": "detected|confirmed|disproved|corrected",
  "begin": 10.5,  // только для статуса "corrected"
  "end": 12.0     // только для статуса "corrected"
}

Правила валидации:

• Для статуса corrected поля begin и end обязательны
• Для других статусов поля begin и end недопустимы
• begin должно быть меньше end
• Статус already_resolved нельзя устанавливать вручную
• Нельзя изменить статус с corrected на confirmed

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

1. Подтверждение аномалии:

{
  "status": "confirmed"
}

2. Опровержение аномалии:

{
  "status": "disproved"
}

3. Коррекция с новыми временными метками:

{
  "status": "corrected",
  "begin": 10.5,
  "end": 12.0
}

POST /voices/anomalies

Создание новой аномалии озвучки.

Тело запроса:

{
  "voice": 1,
  "translation": 1,
  "book_number": 1,
  "chapter_number": 1,
  "verse_number": 1,
  "word": "слово",           // опционально
  "position_in_verse": 5,    // опционально
  "position_from_end": 3,    // опционально
  "duration": 1.5,           // опционально
  "speed": 2.0,              // опционально
  "ratio": 1.8,              // обязательно, должно быть > 0
  "anomaly_type": "manual",  // по умолчанию "manual"
  "status": "detected"       // по умолчанию "detected"
}

Типы аномалий:

• fast - быстрое произношение
• slow - медленное произношение
• long - длинная пауза
• short - короткая пауза
• manual - добавлена вручную (по умолчанию)

Правила валидации:

• Поле ratio обязательно и должно быть положительным числом
• Поля voice, translation, book_number, chapter_number, verse_number обязательны
• Система проверяет существование указанного голоса, перевода и стиха
• Тип аномалии должен быть одним из допустимых значений

Пример успешного ответа:

{
  "code": 123,
  "voice": 1,
  "translation": 1,
  "book_number": 1,
  "chapter_number": 1,
  "verse_number": 1,
  "word": "слово",
  "position_in_verse": 5,
  "position_from_end": 3,
  "duration": 1.5,
  "speed": 2.0,
  "ratio": 1.8,
  "anomaly_type": "manual",
  "status": "detected",
  "verse_start_time": 10.0,
  "verse_end_time": 12.0,
  "verse_text": "Текст стиха"
}

Логика работы с voice_manual_fixes

При обновлении статуса аномалии система автоматически управляет таблицей voice_manual_fixes:

Статусы DISPROVED и CORRECTED

• Создается или обновляется запись в voice_manual_fixes
• Для DISPROVED: используются оригинальные временные метки из voice_alignments
• Для CORRECTED: используются переданные в запросе begin и end

Статус CONFIRMED

• Если есть запись в voice_manual_fixes с совпадающими временными метками - она удаляется
• Если временные метки не совпадают - возвращается ошибка 422
• Если записи нет - никаких действий не выполняется

Это позволяет отслеживать стихи, которые были вручную проверены, чтобы при перепарсинге не создавать для них новые аномалии.

Отрывки с учетом корректировок

GET /excerpt_with_alignment

Метод получения отрывков Библии с временными метками озвучки теперь автоматически учитывает корректировки из таблицы voice_manual_fixes.

Логика работы:

• Если для стиха есть запись в voice_manual_fixes - используются скорректированные временные метки
• Если записи нет - используются оригинальные временные метки из voice_alignments
• Реализовано через SQL COALESCE: COALESCE(vmf.begin, a.begin) и COALESCE(vmf.end, a.end)

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

GET /excerpt_with_alignment?translation=16&excerpt=jhn 3:16-17&voice=1

В ответе поля begin и end для каждого стиха будут содержать актуальные временные метки с учетом всех корректировок.

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

Установка зависимостей

# Установить основные зависимости
pip install mysql-connector-python fastapi uvicorn pydantic

# Для разработки (опционально, может потребовать Python 3.12 или ниже)
pip install pytest requests

# Полная установка (может не работать с Python 3.13)
# pip install -r requirements.txt

Настройка базы данных

1. Скопируйте файл конфигурации:

cp app/config.sample.py app/config.py

2. Отредактируйте app/config.py с вашими настройками базы данных.

3. Выполните миграции:

docker compose exec bible-api python3 migrate.py migrate

Примечание: Миграции для рефакторинга voice_alignments уже выполнены:

• ✅ Добавлены поля book_number, chapter_number, verse_number
• ✅ Созданы индексы для оптимизации производительности
• ✅ Заполнены данные из связанных таблиц
• ✅ Обновлен код для использования новых полей

Запуск сервера

Вариант 1: Через Docker (рекомендуется)

# Запуск в фоновом режиме
docker compose up -d

# Проверить статус
docker compose ps

# Просмотр логов
docker logs bible-api

# Остановить
docker compose down

Сервер будет доступен на: http://localhost:8000

Вариант 2: Локальный запуск

# Запуск в режиме разработки
uvicorn app.main:app --reload --host 0.0.0.0 --port 8001

Сервер будет доступен на: http://localhost:8001

Проверка работы

# Swagger UI (Docker)
curl http://localhost:8000/docs

# Swagger UI (локальный запуск)
curl http://localhost:8001/docs

Запуск тестов

⚠️ ВАЖНО: Integration тесты пишут в БД! См. docs/TESTING_GUIDE.md

# Установить pytest если еще не установлен
pip install pytest

# ✅ Безопасно - только unit тесты (НЕ пишут в БД)
PYTHONPATH=/root/cep/bible-api/app pytest tests/ -k "not integration" -v

# ⚠️ ОПАСНО - все тесты (integration тесты ПИШУТ в БД!)
PYTHONPATH=/root/cep/bible-api/app pytest tests/ -v

Миграции

Система использует собственный механизм миграций для управления схемой базы данных. Рекомендуется запускать миграции внутри Docker-контейнера.

Tip

Вместо migrate.py можно также использовать migrations/migration_manager.py, но migrate.py короче и удобнее.

# Выполнить все ожидающие миграции
docker compose exec bible-api python3 migrate.py migrate

# Создать новую миграцию
docker compose exec bible-api python3 migrate.py create "migration_name"

# Показать статус миграций
docker compose exec bible-api python3 migrate.py status

# Откатить миграцию (только отметить как не выполненную)
docker compose exec bible-api python3 migrate.py rollback "migration_file.sql"

# Отметить миграцию как выполненную без запуска
docker compose exec bible-api python3 migrate.py mark-executed "migration_file.sql"

Для локального запуска (если у вас настроено окружение):

python3 migrate.py migrate

Подробнее см. migrations/README.md

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

• docs/DEVELOPMENT.md - Docker команды, структура проекта, ключевые таблицы БД
• docs/SECURITY.md - таблица защиты всех эндпоинтов, примеры авторизации
• docs/TESTING.md - ⚠️ запуск тестов (ВАЖНО! integration тесты используют БД)