Initial commit: VoIdeaAI - voice-first AI idea assistant

2026-05-13 12:51:42 +03:00
commit 688d043dad
421 changed files with 47915 additions and 0 deletions
@@ -0,0 +1,49 @@
+# Обработка ошибок
+
+## Иерархия исключений
+
+```python
+# app/core/exceptions.py
+AppError
+├── AuthenticationError    # 401 — неверный токен/пароль
+├── ForbiddenError         # 403 — нет прав
+├── NotFoundError          # 404 — ресурс не найден
+├── ConflictError          # 409 — дубликат, конфликт
+├── ValidationError        # 422 — неверные данные
+└── ServiceUnavailableError # 503 — внешний сервис недоступен
+```
+
+## Матрица по слоям
+
+| Слой | Что делаем | Пример |
+|------|-----------|--------|
+| **API** | HTTPException с detail и status_code | `raise HTTPException(404)` |
+| **Services** | Бизнес-исключения (из AppError) | `raise NotFoundError("Idea", id)` |
+| **Integrations** | try/except с fallback | `return AIResult(success=False)` |
+| **Agents** | AgentResult(success=False, error=...) | Без HTTP-статусов |
+| **Data/DB** | Ошибки не всплывают выше | Ловим в сервисе |
+
+## Fallback pattern (AI провайдеры)
+
+```python
+# app/integrations/ai/fallback.py
+# YandexGPT → GigaChat, 2 retry, 2s/5s backoff
+# При недоступности всех — AgentResult(success=False, message=...)
+```
+
+## Graceful degradation
+
+| Сервис недоступен | Реакция |
+|-------------------|---------|
+| PostgreSQL | 503 Service Unavailable |
+| Redis | Работаем без Celery (прямой вызов), log WARNING |
+| AI провайдер | Fallback на другой, потом Error |
+| Celery | Выполняем задачу синхронно |
+
+## Логирование ошибок
+
+| Уровень | Когда |
+|---------|-------|
+| WARNING | Timeout, retry, fallback |
+| ERROR | Ошибка внешнего API |
+| CRITICAL | Исчерпаны все retry |