errors/
├── __init__.py          # Экспорт всех исключений
├── base.py             # Базовые классы исключений
├── validation.py       # Ошибки валидации (E020-E039)
├── transport.py        # Транспортные ошибки (E040-E059)
├── integration.py      # Интеграционные ошибки (E060-E079)
├── mcp.py              # MCP-специфичные исключения
├── mapping.py          # Маппинг 1С ↔ Python
├── example_usage.py    # Примеры использования
└── test_simple.py      # Простые тесты

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

Базовый класс McpError

ErrorCode: Код ошибки в формате E001-E099
ErrorType: Тип ошибки (system/validation/transport/integration/auth/database/mcp)
CorrelationID: Уникальный идентификатор для отслеживания
Context: Дополнительный контекст ошибки
Recoverable: Возможность восстановления
Severity: Серьезность ошибки (low/medium/high/critical)

Категории исключений

1. Системные ошибки (E001-E019)

Общие системные сбои
Ошибки инициализации
Недостаток ресурсов

2. Ошибки валидации (E020-E039)

Некорректные входные данные
Отсутствующие поля
Нарушения формата
Невосстановимые - требуют исправления данных

3. Транспортные ошибки (E040-E059)

Сетевые ошибки
Таймауты
Недоступность сервисов
Восстановимые - поддерживают retry

4. Интеграционные ошибки (E060-E079)

Ошибки внешних сервисов
Проблемы авторизации
Нарушения контрактов API
Зависит от типа ошибки

5. Аутентификационные ошибки (E080-E089)

Неверные учетные данные
Истекшие токены
Недостаточно прав

6. БД ошибки (E090-E099)

Транзакционные ошибки
Нарушения целостности
Дедлоки

7. MCP ошибки

Нарушения протокола
Ошибки инструментов
Проблемы с ресурсами

🔄 Маппинг 1С ↔ Python

Система обеспечивает прозрачную трансляцию ошибок между системами:

from errors.mapping import translate_python_error_to_1c, translate_1c_error_to_python

# Python → 1С
python_error = ValidationError("E020", field_name="email")
one_c_data = translate_python_error_to_1c(python_error)

# 1С → Python  
python_error = translate_1c_error_to_python(one_c_data)

🚀 Использование

Базовое исключение

from errors import McpError

error = McpError(
    error_code="E001",
    error_type="system",
    user_message="Общая системная ошибка",
    correlation_id="req-123456"
)

Ошибка валидации

from errors.validation import InvalidInputDataError

raise InvalidInputDataError(
    field_name="email",
    field_value="invalid-email",
    expected_format="user@domain.com"
)

Транспортная ошибка

from errors.transport import ConnectionTimeoutError

raise ConnectionTimeoutError(
    url="https://api.example.com",
    timeout_seconds=30.0
)

Интеграционная ошибка

from errors.integration import ExternalServiceUnavailableError

raise ExternalServiceUnavailableError(
    service_name="payment_api",
    service_url="https://payments.example.com"
)

📊 MCP Интеграция

Формат ответа MCP

response = error.to_mcp_response()
# {
#     "error": {
#         "code": "E040",
#         "message": "Сетевая ошибка",
#         "data": {
#             "type": "transport",
#             "correlation_id": "uuid",
#             "context": {...}
#         }
#     }
# }

Нормализованные ответы

tools/list - список инструментов
tools/call - вызов инструмента
resources - работа с ресурсами
prompts - управление промптами

🔧 Fallback стратегии

Graceful Degradation: При недоступности сервиса возвращаем кэшированные данные
Retry Logic: Автоматические повторы для восстановимых ошибок
Circuit Breaker: Защита от каскадных сбоев
Fallback Responses: Альтернативные ответы при ошибках

📈 Мониторинг и логирование

Структурированное логирование

error = McpError("E042", "ServiceUnavailable", "Сервис недоступен")
log_data = error.to_structured_log()

# JSON для ELK/Splunk
{
    "error_code": "E042",
    "error_type": "ServiceUnavailable", 
    "correlation_id": "uuid",
    "severity": "high",
    "recoverable": true,
    "timestamp": "2025-10-29T22:20:38Z"
}

Метрики

Количество ошибок по типам
Время восстановления
Процент восстановимых ошибок
Топ ошибок по частоте

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

# Запуск простых тестов
python test_simple.py

# Запуск примеров использования
python example_usage.py

📚 Дополнительно

Версия: 1.0.0
Лицензия: MIT
Совместимость: Python 3.8+

🔍 Диагностика

Типичные ошибки

ConnectionTimeoutError: Проверьте сетевое подключение
ExternalServiceUnavailableError: Проверьте статус внешнего сервиса
ValidationError: Исправьте входные данные
McpProtocolError: Проверьте соответствие спецификации MCP

Полезные методы

error.is_retryable()           # Можно ли повторить
error.get_retry_after()        # Время до повтора
error.to_dict()               # Сериализация
error.add_context()           # Добавить контекст
error.to_mcp_response()       # MCP формат

Документация автоматически генерируется из кода и комментариев