Metadata-Version: 2.4
Name: payment-rescue
Version: 1.0.0
Summary: Sistema de Pagamento Enterprise com PayRescue - Strategy Pattern + Retry + Fallback + Dead Letter Queue
Home-page: https://github.com/seu-usuario/payment-rescue
Author: Seu Nome
Author-email: Seu Nome <seu.email@example.com>
License: MIT
Project-URL: Homepage, https://github.com/seu-usuario/payment-rescue
Project-URL: Documentation, https://github.com/seu-usuario/payment-rescue/blob/main/README.md
Project-URL: Repository, https://github.com/seu-usuario/payment-rescue.git
Project-URL: Issues, https://github.com/seu-usuario/payment-rescue/issues
Keywords: payment,payrescue,strategy-pattern,retry,exponential-backoff,fallback,dead-letter-queue,enterprise,solid-principles
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: Portuguese (Brazilian)
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Sistema de Pagamento Enterprise com PayRescue

## 📋 Visão Geral

Módulo de pagamento **production-ready** implementado em Python com os seguintes recursos:

- **Padrão Strategy** para métodos de pagamento plugáveis
- **PayRescue**: Sistema inteligente de recuperação para pagamentos falhados
- **Retry Automático** com Exponential Backoff
- **Fallback Strategies** para métodos alternativos
- **Dead Letter Queue** para pagamentos irrecuperáveis
- **Princípios SOLID** rigorosamente aplicados
- **Injeção de Dependência** para Logger e Banco de Dados
- **Exceções Customizadas** para tratamento robusto de erros
- **Tipagem Forte** com Python type hints

---

## 🏗️ Arquitetura

```
┌─────────────────────────────────────────────────────────────┐
│            PaymentProcessor (Orquestrador)                  │
│                   (SOLID Principles)                        │
└──────────────────────┬──────────────────────────────────────┘
                       │
            ┌──────────┴──────────┐
            │                     │
            ▼                     ▼
    ┌───────────────┐     ┌──────────────────┐
    │PaymentMethod  │     │  PayRescueSystem │
    │  (Strategy)   │     │                  │
    └───────────────┘     └─────────┬────────┘
            │                       │
    ┌───────┴─────────┬─────┐      │
    │                 │     │      │
    ▼                 ▼     ▼      ▼
 Credit Card        PIX   Wallet  Retry + Backoff
 (Strategy)      (Strategy)(S.)   Fallback
                                   DLQ
```

### Componentes Principais

#### 1. **PaymentMethod (Interface Strategy)**
```python
class PaymentMethod(ABC):
    def process_payment(request) -> PaymentResponse
    def validate_payment_details(details) -> bool
    def supports_recurring_payment() -> bool
    def supports_partial_refund() -> bool
    def get_method_type() -> PaymentMethodType
```

#### 2. **Implementações Concretas**
- `CreditCardPayment`: Processamento de cartão de crédito
- `PIXPayment`: Transferência instantânea (Brasil)
- `DigitalWalletPayment`: Apple Pay, Google Pay, Samsung Pay

#### 3. **PayRescueSystem**
- **Retry automático** com `ExponentialBackoffStrategy`
- **Fallback strategies** para métodos alternativos
- **Dead Letter Queue** para recuperação posterior
- **Callback** para intervenção manual

#### 4. **PaymentProcessor**
- Orquestrador central
- Gerencia ciclo de vida de transações
- Coordena com PayRescue em falhas
- Mantém histórico de transações

---

## 🔧 Instalação

### Requisitos
- Python 3.10+
- Nenhuma dependência externa (usa apenas stdlib)

### Setup
```bash
# Clonar ou extrair o projeto
cd Depedencia

# (Opcional) Criar ambiente virtual
python -m venv venv
source venv/bin/activate  # Linux/Mac
# ou
venv\Scripts\activate  # Windows
```

---

## 📖 Uso Rápido

### Exemplo Básico

```python
from payment_method import PaymentRequest, PaymentMethodType
from payment_strategies import CreditCardPayment
from payment_processor import PaymentProcessor
from services import MockPaymentGatewayClient

# 1. Criar processador
processor = PaymentProcessor()

# 2. Registrar método de pagamento
gateway = MockPaymentGatewayClient(approval_rate=0.9)
credit_card = CreditCardPayment(gateway)
processor.register_payment_method(credit_card)

# 3. Criar requisição
request = PaymentRequest(
    transaction_id="TXN-2024-001",
    amount=150.00,
    currency="BRL",
    customer_id="CUST-12345",
    payment_method_type=PaymentMethodType.CREDIT_CARD,
    payment_details={
        "card_token": "tok_visa_4242",
        "cardholder_name": "João Silva",
        "expiry_date": "12/25"
    }
)

# 4. Processar pagamento
try:
    response = processor.process_payment(request)
    print(f"✅ Autorizado: {response.authorization_code}")
except PaymentException as e:
    print(f"❌ Falha: {str(e)}")
```

### Configurar Fallback Strategies

```python
# Registrar fallback: se cartão falhar, tenta PIX
processor.register_fallback_strategy(
    error_type=PaymentException,
    fallback_methods=[PaymentMethodType.PIX]
)

# Ao processar, se cartão falhar:
# 1. Tenta retry (3x) com exponential backoff
# 2. Se ainda falhar, tenta PIX
# 3. Se tudo falhar, move para Dead Letter Queue
```

### Intervenção Manual em Falhas

```python
def handle_manual_intervention(dlq_message):
    """Callback para processar pagamentos irrecuperáveis."""
    print(f"⚠️ Intervenção requerida para: {dlq_message.transaction_id}")
    # Notificar operador, criar ticket, etc.

response = processor.process_payment(
    request,
    manual_intervention_callback=handle_manual_intervention
)
```

### Monitorar Dead Letter Queue

```python
# Verificar status
dlq_status = processor.get_dead_letter_queue_status()
print(f"Mensagens pendentes: {dlq_status['size']}")

# Reprocessar DLQ
stats = processor.process_dead_letter_queue_with_retry(max_attempts=5)
print(f"Processadas: {stats['successful']}, Falhadas: {stats['failed']}")
```

---

## 📊 Exponential Backoff

O sistema implementa Exponential Backoff com Jitter para evitar "thundering herd":

```
Tentativa  | Delay (segundos) | Motivo
─────────────────────────────────────────
   1       | 1.0              | Inicial
   2       | 2.0              | 2x anterior
   3       | 4.0              | 2x anterior
   4       | 8.0              | 2x anterior
   5       | 16.0             | 2x anterior
   ...     | até 300s (máx)   | Capped
```

Com **Jitter**: adiciona variação aleatória (±10%) para desincronizar requisições.

---

## 🛡️ SOLID Principles

### Single Responsibility
- `PaymentMethod`: Apenas processa pagamento
- `PayRescueSystem`: Apenas gerencia recuperação
- `PaymentProcessor`: Apenas orquestra fluxo
- `ExponentialBackoffStrategy`: Apenas calcula delays

### Open/Closed
```python
# ✅ Aberto para extensão (novos métodos)
class BankTransferPayment(PaymentMethod):
    def process_payment(self, request):
        # Nova implementação
        pass

processor.register_payment_method(BankTransferPayment())

# ❌ Fechado para modificação (não modifica PaymentProcessor)
```

### Liskov Substitution
Qualquer `PaymentMethod` pode ser usado como substituto:
```python
primary_method: PaymentMethod = CreditCardPayment(...)
fallback_method: PaymentMethod = PIXPayment(...)
# Ambos funcionam da mesma forma
```

### Interface Segregation
Interfaces mínimas e focadas:
```python
class PaymentMethod(ABC):
    def process_payment(request) -> PaymentResponse  # Core
    def validate_payment_details(details) -> bool    # Core
    # Apenas métodos relevantes
```

### Dependency Inversion
```python
# ❌ Dependência em implementação
class OldProcessor:
    def __init__(self):
        self.logger = FileLogger()  # Concreto

# ✅ Dependência em abstração
class NewProcessor:
    def __init__(self, logger_service=None):
        self.logger = logger_service  # Abstrato, injetado
```

---

## 🚨 Tratamento de Erros

### Hierarquia de Exceções

```python
PaymentException (Base)
├── PaymentRejectedException
├── PaymentTimeoutException
├── InsufficientFundsException
├── PaymentGatewayException
├── RescueTimeoutException
├── FallbackStrategyFailedException
└── InvalidPaymentMethodException
```

### Exemplo de Uso

```python
try:
    processor.process_payment(request)
except PaymentRejectedException as e:
    # Cartão rejeitado
    print(f"Provider: {e.provider}, Reason: {e.reason}")
except RescueTimeoutException as e:
    # Resgate esgotou tentativas
    print(f"Transaction: {e.transaction_id}, Attempts: {e.attempts}")
except PaymentGatewayException as e:
    # Falha na comunicação
    print(f"Gateway: {e.gateway_name}, Status: {e.status_code}")
except PaymentException as e:
    # Qualquer erro de pagamento
    print(f"Error: {e.message}, Code: {e.error_code}")
```

---

## 🧪 Testes

### Executar Suite de Testes

```bash
python tests.py
```

### Cobertura de Testes

- ✅ Validação de requisições
- ✅ Processamento de pagamentos
- ✅ Exponential backoff
- ✅ Fallback strategies
- ✅ Dead Letter Queue
- ✅ Tratamento de exceções
- ✅ Injeção de dependência

---

## 📊 Exemplos de Uso Completo

### Executar Demonstração

```bash
python example_usage.py
```

**Exemplos incluídos:**
1. Pagamento bem-sucedido
2. Pagamento falhado com PayRescue automático
3. Processamento de Dead Letter Queue
4. Múltiplos métodos de pagamento
5. Visualização de Exponential Backoff

---

## 🔌 Injeção de Dependência

### Logger Service

```python
class LoggerService(ABC):
    def log_transaction_start(request)
    def log_transaction_complete(response)
    def log_rescue_attempt(transaction_id, attempt_number)

# Implementação
processor = PaymentProcessor(
    logger_service=MyLoggerService(),  # Seu logger
    db_service=MyDatabaseService()     # Seu BD
)
```

### Database Service

```python
class DatabaseService(ABC):
    def save_transaction(response)
    def save_dead_letter_message(message)
    def get_transaction(transaction_id)

# Implementação
processor = PaymentProcessor(
    logger_service=...,
    db_service=MyDatabaseService()  # Seu banco de dados
)
```

---

## 📈 Monitoramento e Observabilidade

### Logs Estruturados

```python
# Transações são logadas em cada etapa
- [TRANSACTION_START]    # Início da transação
- [PROCESSING]           # Processando com método
- [RESCUE_ATTEMPT]       # Tentativa de resgate
- [TRANSACTION_COMPLETE] # Conclusão
- [DEAD_LETTER]          # Movido para DLQ
```

### Métricas Recomendadas

```python
# Implementar monitoramento para:
- Taxa de aprovação por método
- Latência média de processamento
- Número de tentativas por transação
- Taxa de sucesso do PayRescue
- Tamanho da Dead Letter Queue
- Tempo médio de resolução
```

---

## 🚀 Produção: Próximos Passos

### Segurança
- [ ] Criptografar dados de cartão (PCI-DSS)
- [ ] Sanitizar inputs
- [ ] Implementar rate limiting
- [ ] Adicionar autenticação/autorização
- [ ] CORS e headers de segurança

### Escalabilidade
- [ ] Implementar circuit breaker pattern
- [ ] Cache de resultados
- [ ] Load balancing entre gateways
- [ ] Sharding de Dead Letter Queue
- [ ] Worker assíncrono para DLQ

### Confiabilidade
- [ ] Testes de carga/stress
- [ ] Simulação de falhas (chaos engineering)
- [ ] Alertas em tempo real
- [ ] SLA monitoramento
- [ ] Disaster recovery plan

### Compliance
- [ ] Auditoria de transações
- [ ] Conformidade com regulamentações
- [ ] Retenção de dados configurável
- [ ] Direito ao esquecimento (LGPD)
- [ ] Relatórios de conformidade

---

## 📋 Estrutura de Arquivos

```
Depedencia/
├── exceptions.py              # Exceções customizadas
├── payment_method.py          # Interface Strategy + datatypes
├── payment_strategies.py      # Implementações (Credit Card, PIX, Wallet)
├── rescue_system.py           # PayRescue com retry + fallback + DLQ
├── payment_processor.py       # Orquestrador principal
├── services.py                # Mocks de Logger e Database
├── example_usage.py           # Exemplos completos
├── tests.py                   # Suite de testes unitários
└── README.md                  # Este arquivo
```

---

## 📚 Referências de Design

### Padrões Utilizados

1. **Strategy Pattern**: PaymentMethod
2. **Decorator Pattern**: ExponentialBackoff (implícito)
3. **Factory Pattern**: PaymentMethodType resolver
4. **Observer Pattern**: Callbacks de intervenção manual
5. **Queue Pattern**: Dead Letter Queue

### SOLID Principles

- [S]ingle Responsibility Principle
- [O]pen/Closed Principle
- [L]iskov Substitution Principle
- [I]nterface Segregation Principle
- [D]ependency Inversion Principle

---

## 🤝 Contribuindo

Para adicionar um novo método de pagamento:

```python
from payment_method import PaymentMethod, PaymentMethodType

class NewPaymentMethod(PaymentMethod):
    def process_payment(self, request: PaymentRequest) -> PaymentResponse:
        # Implementar lógica específica
        pass
    
    def validate_payment_details(self, payment_details: dict) -> bool:
        # Validar dados específicos do método
        pass
    
    def supports_recurring_payment(self) -> bool:
        return True or False
    
    def supports_partial_refund(self) -> bool:
        return True or False
    
    def get_method_type(self) -> PaymentMethodType:
        return PaymentMethodType.YOUR_METHOD

# Registrar no processor
processor.register_payment_method(NewPaymentMethod())
```

---

## 📄 Licença

Este módulo é fornecido como referência de arquitetura enterprise.

---

## 👨‍💼 Autor

Desenvolvido seguindo práticas de engenharia de software senior e padrões de produção.

**Última atualização**: 2024
**Versão**: 1.0.0 (Production-Ready)
