Bible API

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

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

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

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

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

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

curl -H "Authorization: Bearer $TOKEN" http://localhost/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

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

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

{
  "status": "confirmed"
}

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

{
  "status": "disproved"
}

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

{
  "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 для каждого стиха будут содержать актуальные временные метки с учетом всех корректировок.

Скачивание аудио (MP3)

Аудио-файлы хранятся в структуре:

Где берется из БД () и заполняется плейсхолдерами по аналогии с .

Скрипт скачивания находится в и берёт активные голоса из БД:

Запуск (внутри контейнера ):

По умолчанию файлы пишутся в (обычно внутри контейнера).

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

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

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

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

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

Создайте runtime-переменные окружения для контейнера:

cp .env.example .env

Отредактируйте .env (DB_, API_KEY, JWT_, ADMIN_*). Для ADMIN_PASSWORD_HASH используйте формат с $$ (например $$2b$$12$$...).
Выполните миграции:

docker compose exec bible-api python3 migrate.py migrate

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

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

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

Вариант 1: Прод-режим через Docker (по умолчанию)

# Запуск в фоне (production mode)
docker compose up -d --build

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

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

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

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

Вариант 2: Dev-режим через Docker override

# Запуск с override (development mode + bind mounts)
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build

# Остановить
docker compose -f docker-compose.yml -f docker-compose.dev.yml down

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

# Swagger UI (Docker)
curl http://localhost/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/REVERSE_PROXY_SETUP.md - схема портов, Nginx reverse proxy и маршрутизация yourdomain.com/api.yourdomain.com
docs/SECURITY.md - таблица защиты всех эндпоинтов, примеры авторизации
docs/TESTING.md - ⚠️ запуск тестов (ВАЖНО! integration тесты используют БД)

Скачивание аудио (MP3)

Аудио-файлы хранятся в структуре:

<MP3_FILES_PATH>/<translation_alias>/<voice_alias>/mp3/<book_zerofill>/<chapter_zerofill>.mp3

Где link_template берется из БД (voices.link_template) и заполняется плейсхолдерами по аналогии с /root/cep/php-parser/include.php:get_chapter_audio_url.

Скрипт скачивания: scripts/download_audio.py.

Он скачивает mp3 для всех активных голосов из БД:

voices.active = 1
translations.active = 1

Запуск (внутри контейнера bible-api):

# посмотреть, что будет скачиваться (без скачивания)
docker exec bible-api python3 /code/scripts/download_audio.py --dry-run

# скачать всё (может быть десятки ГБ)
docker exec bible-api python3 /code/scripts/download_audio.py --yes --max-workers 8

# скачать только один перевод/голос
docker exec bible-api python3 /code/scripts/download_audio.py --yes --translation-alias syn --voice-alias bondarenko

# NPU (npu/npu_uk): источник open.bible, там аудио в ZIP-архивах по книгам
docker exec bible-api python3 /code/scripts/download_audio.py --yes --translation-alias npu --voice-alias npu_uk

По умолчанию файлы пишутся в MP3_FILES_PATH (обычно /audio внутри контейнера).

Compose bind mounts (AUDIO_DIR / SITE_DIR)

docker-compose.yml uses host bind mounts and expects these variables in .env:

AUDIO_DIR (required): host directory with downloaded mp3 files. It will be mounted into the API container as /audio.
SITE_DIR (optional): host directory with static files for the root website. Used only by the web service. Defaults to ./site (inside this repo).

If you do not need the static site, you can run only the API:

docker compose up -d bible-api

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Bible API

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

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

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

API методы

GET /voices/{voice_code}/anomalies

PATCH /voices/anomalies/{anomaly_code}/status

POST /voices/anomalies

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

Статусы DISPROVED и CORRECTED

Статус CONFIRMED

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

GET /excerpt_with_alignment

Скачивание аудио (MP3)

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

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

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

Вариант 1: Прод-режим через Docker (по умолчанию)

Вариант 2: Dev-режим через Docker override

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

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

Миграции

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

Скачивание аудио (MP3)

Compose bind mounts (AUDIO_DIR / SITE_DIR)

About

Uh oh!

Releases

Packages

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 94 Commits
app		app
deploy/nginx		deploy/nginx
docs		docs
migrations		migrations
scripts		scripts
site		site
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.yml		docker-compose.yml
extract-openapi.py		extract-openapi.py
migrate.py		migrate.py
openapi.yaml		openapi.yaml
requirements.txt		requirements.txt

MariaPaypoint/bible-api

Folders and files

Latest commit

History

Repository files navigation

Bible API

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

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

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

API методы

GET /voices/{voice_code}/anomalies

PATCH /voices/anomalies/{anomaly_code}/status

POST /voices/anomalies

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

Статусы DISPROVED и CORRECTED

Статус CONFIRMED

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

GET /excerpt_with_alignment

Скачивание аудио (MP3)

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

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

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

Вариант 1: Прод-режим через Docker (по умолчанию)

Вариант 2: Dev-режим через Docker override

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

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

Миграции

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

Скачивание аудио (MP3)

Compose bind mounts (AUDIO_DIR / SITE_DIR)

About

Resources

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

Packages