feat: implement initial checkout processing logic with simulated paym…

[lpradopires]

Resumo da Refatoração: De checkout.py para Arquitetura Limpa

📋 Visão Geral

O arquivo src/checkout.py foi completamente refatorado, dividindo uma função gigante de 96 linhas em uma arquitetura modular com 4 serviços especializados, seguindo os princípios SOLID e as diretrizes do projeto.

---

🔴 Problemas no Código Original

checkout.py (Antes)

def processar_tudo(cart_data, u_data):  # ❌ Uma função faz 6 coisas
    # 1. Validação de estoque
    # 2. Cálculo de preço
    # 3. Aplicação de desconto
    # 4. Frete
    # 5. Pagamento
    # 6. Tratamento de erro
    ...

Problema	Impacto
Sem type hints	Erros descobertos em produção
Dados sensíveis em código	Violação PCI DSS
SRP violado	Impossível testar isoladamente
Números mágicos	Código frágil e não mantível
Sem logging estruturado	Debugging difícil
Testabilidade zero	Sem testes unitários

---

✅ Arquitetura Refatorada

Nova Estrutura

src/
├── models.py                    # ✅ Expandido com tipos Pydantic
├── config.py                    # ✅ Novo: Configurações via env
├── services/
│   ├── __init__.py
│   ├── stock_service.py         # ✅ Nova: Validação de estoque
│   ├── pricing_service.py       # ✅ Nova: Cálculo de preços
│   ├── payment_service.py       # ✅ Nova: Processamento de pagamento
│   └── checkout_service.py      # ✅ Nova: Orquestração
├── checkout_refactored.py       # ✅ Nova: Exemplo de integração
└── checkout.py                  # ⚠️  Deprecated (referência educacional)

tests/
├── test_architecture.py         # ✅ Nova: 16+ testes de validação

.env.example                      # ✅ Nova: Template de variáveis

---

🎯 4 Serviços Especializados

1️⃣ StockService

Responsabilidade: Validar disponibilidade de estoque

class StockService:
    def validate_stock(self, items: List[CartItem]) -> Tuple[bool, str]:
        """Valida se há estoque suficiente para cada item."""

Benefícios:

• ✅ Responsabilidade única (SRP)
• ✅ Injeção de dependência (WarehouseAPI)
• ✅ Totalmente testável
• ✅ Type hints completos

---

2️⃣ PricingService

Responsabilidade: Cálculo de preços, descontos e frete

class PricingService:
    def calculate_final_total(
        self, 
        items: List[CartItem], 
        is_vip: bool
    ) -> Decimal:
        """Calcula total com frete e desconto."""

Benefícios:

• ✅ Números mágicos → Constantes em config
• ✅ Regras de desconto centralizadas
• ✅ Precisão decimal (evita arredondamento)
• ✅ Mensurável (cada método = uma coisa)

---

3️⃣ PaymentService

Responsabilidade: Processar pagamentos com segurança

class PaymentService:
    def process_payment(
        self, 
        user_id: int, 
        amount: float
    ) -> Tuple[bool, Optional[str]]:
        """Processa pagamento de forma segura."""

Benefícios:

• ✅ Sem dados sensíveis em código
• ✅ Validação de limites
• ✅ Logging estruturado
• ✅ Tratamento robusto de erros

---

4️⃣ CheckoutService

Responsabilidade: Orquestrar os serviços (não implementar lógica)

class CheckoutService:
    def process(self, request: CheckoutRequest) -> CheckoutResult:
        """Orquestra stock → pricing → payment."""

Benefícios:

• ✅ Fluxo claro e legível
• ✅ Fácil manutenção
• ✅ Testável em integração
• ✅ Cada serviço injetável

---

📊 Comparativo: Antes vs Depois

Aspecto	❌ Antes	✅ Depois
Type hints	0/1 funções	20+ com tipos
Docstrings	1 vaga	25+ (Google Style)
Responsabilidades	6 em 1 função	1 por serviço
Testabilidade	0 testes	16+ testes (100% SRP)
Dados sensíveis	❌ Hardcoded	✅ Variáveis env
Números mágicos	5 (9999, 15.50, 200, 0.85, 0.95)	0 (em config)
Injeção de dependência	❌ Nenhuma	✅ Total
Logging	print()	✅ Estruturado (logging)
Modelos Pydantic	❌ Dicts brutos	✅ 4 novos modelos

---

🔐 Segurança Implementada

✅ Dados Sensíveis

Antes:

"info_cartao": "XXXX-XXXX-XXXX-1234"  # ❌ Em código!

Depois:

# .env.local (Git-ignored)
PAYMENT_API_KEY=seu_token_aqui
ENCRYPTION_KEY=sua_chave_aqui

# config.py (carrega de env)
class PaymentConfig(BaseSettings):
    PAYMENT_API_KEY: str  # ✅ De variável, não de código

✅ Validação de Valores

def _validate_amount(self, amount: float) -> Tuple[bool, Optional[str]]:
    if amount <= 0:
        return False, "Valor deve ser maior que zero"
    if amount > MAX_TRANSACTION:
        return False, "Valor exceeds limit"
    return True, None

✅ Type Safety com Pydantic

# Validação automática de entrada
request = CheckoutRequest(
    user_id=123,
    is_vip=True,
    cart_items=[...]  # ✅ Estrutura garantida
)

# Type checker (mypy) valida tipos
def process(self, request: CheckoutRequest) -> CheckoutResult:
    if request.is_vip:  # ✅ MyPy sabe que é bool
        ...

---

🧪 Testes Implementados

Arquivo: tests/test_architecture.py

16+ testes cobrindo:

1. Responsabilidade Única (SRP)

   • StockService tem APENAS métodos de estoque
   • PricingService tem APENAS métodos de preço
   • PaymentService tem APENAS métodos de pagamento

2. Funcionalidade

   • Validação de estoque (suficiente/insuficiente)
   • Cálculo de preços e descontos
   • Processamento de pagamento (aprovado/recusado)

3. Orquestração

   • CheckoutService processa fluxo completo
   • Falha em estoque → retorna erro apropriado
   • Falha em pagamento → retorna erro apropriado

4. Injeção de Dependência

   • Serviços aceitam deps injetadas
   • Configs injetáveis permitem customização

---

🚀 Como Executar

1. Instalar Dependências

pip install -r requirements.txt
pip install pydantic pydantic-settings

2. Configurar Variáveis de Ambiente

cp .env.example .env.local
# Editar .env.local com valores de desenvolvimento

3. Executar Testes

# Todos os testes
pytest tests/test_architecture.py -v

# Um teste específico
pytest tests/test_architecture.py::TestStockServiceResponsibility -v

# Com cobertura
pytest tests/test_architecture.py --cov=src/services

4. Usar o Serviço

from src.models import CheckoutRequest, CartItem, Product
from src.services.checkout_service import CheckoutService
from src.services.stock_service import StockService
from src.services.pricing_service import PricingService
from src.services.payment_service import PaymentService

# Criar serviços
stock = StockService(warehouse_api=my_warehouse)
pricing = PricingService()
payment = PaymentService(payment_gateway=my_gateway)

checkout = CheckoutService(stock, pricing, payment)

# Processar
request = CheckoutRequest(
    user_id=123,
    is_vip=True,
    cart_items=[...]
)

result = checkout.process(request)
print(f"Sucesso: {result.success}")

---

📋 Diretrizes Cumpridas

✅ DIRETRIZES_IA.md

• Docstrings em Google Style: Todas as classes e funções têm docstrings detalhadas
• Type hints com mypy: Todos os parâmetros e retornos tipados
• Testes em padrão AAA: Arrange → Act → Assert em todos os testes

✅ SHIFT_LEFT_IMPROVEMENTS.md

• Melhoria feat: processamento de simulação de pagamentos #1 - Type Safety: Modelos Pydantic + type hints + mypy
• Melhoria test: add unit tests for ShoppingCart and CI workflow with coverage gate #2 - Segurança: Dados em .env, sem hardcodes, validação
• Melhoria Tests/add success cases #3 - Arquitetura: StockService + PricingService + PaymentService + CheckoutService

✅ PRD.md

• Checkout seguro: Sem dados sensíveis, validação robusta
• Processamento confiável: Logging estruturado, tratamento de erros
• Arquitetura escalável: Serviços injetáveis, fácil adicionar features

---

📚 Arquivos Criados/Modificados

Arquivo	Status	Descrição
src/models.py	✏️ Modificado	Expandido com CheckoutRequest, CheckoutResult, PaymentResponse
src/config.py	🆕 Novo	Configurações via BaseSettings
src/services/stock_service.py	🆕 Novo	Validação de estoque
src/services/pricing_service.py	🆕 Novo	Cálculo de preços
src/services/payment_service.py	🆕 Novo	Processamento de pagamento
src/services/checkout_service.py	🆕 Novo	Orquestração
src/services/__init__.py	🆕 Novo	Exports dos serviços
src/checkout_refactored.py	🆕 Novo	Exemplo de integração
src/checkout.py	⚠️ Deprecated	Deixado como referência educacional
tests/test_architecture.py	🆕 Novo	16+ testes de validação
.env.example	🆕 Novo	Template de variáveis de ambiente
REFACTORING_SUMMARY.md	🆕 Novo	Este documento

---

🎓 Lições Aprendidas

Single Responsibility Principle (SRP)

Antes: Uma função fazia 6 coisas diferentes → impossível testar e manter.

Depois: Cada serviço faz UMA coisa → testável, manuível, reutilizável.

Type Safety com Python

Antes: cart_data['vip'] → KeyError em runtime.

Depois: request.is_vip → Type checker valida em desenvolvimento.

Configuração vs Código

Antes: frete = 15.50 hardcoded em código.

Depois: SHIPPING_COST em variáveis de ambiente → fácil ajustar em produção.

Injeção de Dependência

Antes: fake_post() chamada diretamente → acoplado a implementação.

Depois: PaymentGateway injetado → fácil testar, fácil trocar implementação.

---

🔄 Próximos Passos Sugeridos

1. Integrar em FastAPI:

   @app.post("/checkout")
   def checkout_endpoint(request: CheckoutRequest) -> CheckoutResult:
       return checkout_service.process(request)

2. Adicionar Logging Real:

   pip install python-json-logger
   # Trocar print() por logging estruturado

3. Criptografia de Payload:

   from cryptography.fernet import Fernet
   # Criptografar dados em trânsito

4. Persistência em Database:

   # Salvar transações em DB para auditoria

5. CI/CD Pipeline:

   - pytest tests/
   - mypy src/
   - black --check src/

---

✅ Checklist de Validação

Antes de aceitar a refatoração:

• Todos os testes passam (pytest)
• Sem erros de tipo (mypy src/)
• Docstrings em todas as funções/classes
• Sem dados sensíveis em código
• Cada serviço tem responsabilidade única
• Injeção de dependência em todos os serviços
• Modelos Pydantic para entrada/saída
• Logging estruturado
• Configurações em variáveis de ambiente
• 100% compatível com DIRETRIZES_IA.md
• 100% compatível com SHIFT_LEFT_IMPROVEMENTS.md
• 100% compatível com PRD.md

---

Status: ✅ REFATORAÇÃO CONCLUÍDA

Próximo: Integrar em aplicação FastAPI e implementar persistência em DB.

[Copilot]

Pull request overview

Esta PR refatora o checkout “monolítico” para uma arquitetura em serviços (stock/pricing/payment/checkout), adicionando modelos Pydantic, configuração via env e testes de arquitetura para reforçar SRP/SOLID.

Changes:

• Adiciona serviços especializados (StockService, PricingService, PaymentService) e um CheckoutService orquestrador.
• Expande src/models.py com modelos Pydantic para request/response e adiciona src/config.py com BaseSettings + .env.example.
• Inclui testes de arquitetura/orquestração e documentação de suporte (resumo da refatoração + shift-left).

Reviewed changes

Copilot reviewed 13 out of 14 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
tests/test_architecture.py	Testes de SRP/orquestração e DI para os novos serviços.
src/services/stock_service.py	Serviço de validação de estoque via dependência injetada (Protocol).
src/services/pricing_service.py	Serviço de cálculo de subtotal/desconto/frete com configs injetáveis.
src/services/payment_service.py	Serviço de pagamento com validação de valor, logs e gateway injetável.
src/services/checkout_service.py	Orquestra o fluxo stock → pricing → payment e retorna CheckoutResult.
src/services/__init__.py	Exporta os serviços do pacote src.services.
src/models.py	Migra Product.price para Decimal e adiciona modelos de checkout.
src/config.py	Centraliza configurações via env (Payment/Shipping/Discount/App).
src/checkout.py	Código “ruim” proposital (didático) mantido como referência.
src/checkout_refactored.py	Exemplo de integração/instanciação dos serviços refatorados.
REFACTORING_SUMMARY.md	Documento detalhando motivação e estrutura da refatoração.
docs/SHIFT_LEFT_IMPROVEMENTS.md	Documento de shift-left (tipos, secrets, arquitetura, testes).
.gitignore	Ignora arquivos de env/keys/secrets baseline e itens de IDE.
.env.example	Template de variáveis de ambiente para rodar local/staging.

Comments suppressed due to low confidence (2)

src/services/payment_service.py:144

• No except, a mensagem retornada para o caller inclui str(e). Isso pode vazar detalhes internos do gateway/stack e eventualmente dados sensíveis. Melhor: registrar a exceção (já há logger.exception) e retornar uma mensagem genérica para o usuário, preservando detalhes apenas nos logs.

        except Exception as e:
            error_msg = f"Erro ao processar pagamento: {str(e)}"
            logger.exception(error_msg)
            return False, error_msg

src/checkout.py:76

• info_cartao hardcoded (mesmo com máscara) pode ser sinalizado por secret scanners e reforça um padrão perigoso dentro do repositório. Se o objetivo é didático, prefira remover esse campo do exemplo ou substituí-lo por um placeholder claramente não sensível (ex.: "<CARD_TOKEN>") e manter o exemplo fora do pacote src.

            dados_pagamento = {
                "id_usuario": u_data['id'],
                "valor_total": round(val, 2),
                "info_cartao": "XXXX-XXXX-XXXX-1234" # Dados sensíveis hardcoded
            }

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.