Merge branch 'dev' of https://git.pirogov.ai/PoturaevPetr/FileAudioAPI into dev

README.md

@@ -1,12 +1,26 @@
 # 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
-# Клонировать и перейти в директорию
-cd /Users/petr/SpeechAnalytics/FileAudioAPI
+# Перейти в директорию сервиса (от корня репозитория SpeechAnalytics)
+cd FileAudioAPI
 
 # Запуск с Docker (рекомендуется)
 docker-compose up -d

apiApp/routers/ai_conclusion_router.py

@@ -228,15 +228,39 @@ async def mark_recognition_failed(request: RecognitionFailedRequest, db: Session
     """
     audio = db.query(Audio).filter(Audio.filename == request.filename).first()
     if not audio:
+        logger.warning(f"⚠️ Попытка пометить failed для несуществующего аудио: {request.filename}, error={request.error}")
         raise HTTPException(status_code=404, detail=f"Файл не найден: {request.filename}")
 
     audio.recognition_status = "failed"
     audio.recognition_last_error = request.error
     db.commit()
 
+    logger.warning(f"❌ Распознавание помечено failed для {request.filename}. Причина: {request.error}")
+
+    # Отправляем вебхук об ошибке в Calls_WEB_Client_main, чтобы синхронизировать pipeline_status
+    try:
+        if (audio.sourse or "").lower() != "external":
+            failed_webhook_payload = {
+                "audio_id": str(audio.id),
+                "filename": request.filename,
+                "status": "failed",
+                "error": request.error
+            }
+            webhook_url = f"{CALLS_WEB_CLIENT_URL}/api/transcription/failed"
+            logger.info(f"📤 Отправка failed-webhook в Calls_WEB_Client_main: {webhook_url}")
+            requests.post(
+                webhook_url,
+                json=failed_webhook_payload,
+                headers={"X-Webhook-Key": WEBHOOK_API_KEY},
+                timeout=10
+            )
+    except Exception as e:
+        logger.error(f"❌ Ошибка отправки failed-webhook в Calls_WEB: {e}")
+
     return AiConclusionResponse(
         success=True,
         message="Recognition marked as failed",
         audio_id=str(audio.id),
         filename=audio.filename
     )
+