🔀 CAPÍTULO 14: DIAGRAMA DE SEQUÊNCIA E APIS REST

🎯 1. Objetivos de Aprendizagem & Competências

Estimativa de Dedicação: 2 horas de estudo autoguiado.
Ao final deste capítulo, você será capaz de:

• 🔹 Compreender a representação temporal de troca de mensagens entre objetos no Diagrama de Sequência da UML 2.5.
• 🔹 Dominar a sintaxe visual de Linhas de Vida (Lifelines), Barras de Ativação (Execution Occurrences), Mensagens Síncronas (->>), Assíncronas (-)) e Retornos (-->>).
• 🔹 Modelar fluxos completos de requisições HTTP REST (Request-Response Cycle) conectando Cliente, Gateway, Serviços e Banco de Dados.
• 🔹 Implementar rotas Flask integradas com serviços de domínio espelhando rigorosamente a ordem do diagrama de sequência.

🏢 2. Cenário Corporativo & Estudo de Caso (TecProExpress)

Na TecProExpress, a equipe de engenharia identificou uma latência excessiva durante o processo de Checkout e Emissão de Etiqueta. O time de frontend culpava o banco de dados, o DBA culpava a rede e a equipe backend culpava a API externa de CEP.

O Desafio: Como Arquiteto de Software, você deve desenhar o Diagrama de Sequência da UML para rastrear a linha do tempo exata das chamadas de rede e processamento síncrono/assíncrono, identificando gargalos e estabelecendo contratos REST claros e determinísticos em Flask.

🧠 3. Fundamentação Teórica & Modelos Visuais

3.1. Anatomia do Diagrama de Sequência da UML

O tempo flui verticalmente de cima para baixo. Cada participante possui uma linha de vida vertical com barras que indicam períodos em que o objeto está executando operações ativas:

sequenceDiagram
    autonumber
    actor C as 📱 App do Motorista
    participant API as 🌐 Flask (Gateway)
    participant SVC as 🧠 FreteService
    participant DB as 🛢️ PostgreSQL
    
    C->>+API: POST /api/fretes/calcular (distancia_km, peso_kg, expresso)
    API->>+SVC: processar_calculo(distancia, peso, expresso)
    SVC->>+DB: SELECT taxa_km FROM tabelas_frete...
    DB-->>-SVC: taxa_km = 2.50
    SVC-->>-API: { valor_total: 316.25, prazo_horas: 24 }
    API-->>-C: 200 OK { valor_total: 316.25, prazo_horas: 24 }

3.2. Notação de Mensagens na UML 2.5

💻 4. Aplicação Prática & Código Executável (Python 3.11+)

📋 Pré-requisitos e Instalação

Instale o micro-framework Flask no seu ambiente virtual:

pip install flask

💻 Código Completo e Autocontido (sequence_api_frete.py)

Implementação do fluxo síncrono de cálculo de frete com Flask 3.x, refletindo a interação modelada no Diagrama de Sequência:

"""
Módulo: sequence_api_frete.py
Domínio: Endpoint REST Flask refletindo a sequência síncrona de cálculo de frete.
"""
from decimal import Decimal
import sys
from flask import Flask, request, jsonify

app = Flask(__name__)

# 1. Camada de Serviço (Service Layer)
class FreteService:
    @staticmethod
    def processar_calculo(distancia_km: Decimal, peso_kg: Decimal, expresso: bool = False) -> dict:
        taxa_base_km = Decimal("2.50")
        valor = (distancia_km * taxa_base_km) + (peso_kg * Decimal("3.00"))
        prazo = 24
        
        if expresso:
            valor *= Decimal("1.25")
            prazo = 8
            
        return {
            "valor_total": float(valor.quantize(Decimal("0.01"))),
            "prazo_horas": prazo,
            "status": "CALCULADO_COM_SUCESSO"
        }

# 2. Rota REST (Controller / Gateway)
@app.post("/api/fretes/calcular")
def endpoint_calcular_frete():
    """Reflete o Passo 1 do Diagrama de Sequência: POST /api/fretes/calcular."""
    dados = request.get_json()
    if not dados:
        return jsonify({"erro": "Payload JSON ausente ou inválido"}), 400

    try:
        distancia = Decimal(str(dados.get("distancia_km", 0)))
        peso = Decimal(str(dados.get("peso_kg", 0)))
        expresso = bool(dados.get("expresso", False))

        if distancia <= Decimal("0.00") or peso <= Decimal("0.00"):
            return jsonify({"erro": "distancia_km e peso_kg devem ser maiores que zero"}), 400

        resultado = FreteService.processar_calculo(distancia, peso, expresso)
        return jsonify(resultado), 200

    except Exception as ex:
        return jsonify({"erro": f"Falha no processamento: {str(ex)}"}), 400

if __name__ == "__main__":
    if "--server" in sys.argv:
        print("🚀 Iniciando servidor Flask em http://127.0.0.1:5000...")
        app.run(port=5000, debug=True)
    else:
        print("--- Simulação de Requisições HTTP com Flask test_client() ---")
        with app.test_client() as client:
            # Cenário 1: Frete Padrão (120.5 km, 5 kg) -> (120.5*2.50) + (5*3.00) = 301.25 + 15 = 316.25
            res1 = client.post("/api/fretes/calcular", json={
                "distancia_km": 120.5,
                "peso_kg": 5.0,
                "expresso": False
            })
            print(f"Cenário 1 (Frete Padrão) [Status {res1.status_code}]: {res1.get_json()}")

            # Cenário 2: Frete Expresso (120.5 km, 5 kg, expresso) -> 316.25 * 1.25 = 395.31
            res2 = client.post("/api/fretes/calcular", json={
                "distancia_km": 120.5,
                "peso_kg": 5.0,
                "expresso": True
            })
            print(f"Cenário 2 (Frete Expresso) [Status {res2.status_code}]: {res2.get_json()}")

            # Cenário 3: Validação de Payload com Erro
            res3 = client.post("/api/fretes/calcular", json={
                "distancia_km": -10.0,
                "peso_kg": 5.0
            })
            print(f"Cenário 3 (Validação Defensiva) [Status {res3.status_code}]: {res3.get_json()}")

🚀 Como Executar

Execute o script de teste automatizado diretamente no terminal:

python sequence_api_frete.py

Para iniciar o servidor HTTP e testar com ferramentas como Postman, cURL ou VS Code REST Client:

python sequence_api_frete.py --server

🖥️ Saída Esperada no Terminal

--- Simulação de Requisições HTTP com Flask test_client() ---
Cenário 1 (Frete Padrão) [Status 200]: {'prazo_horas': 24, 'status': 'CALCULADO_COM_SUCESSO', 'valor_total': 316.25}
Cenário 2 (Frete Expresso) [Status 200]: {'prazo_horas': 8, 'status': 'CALCULADO_COM_SUCESSO', 'valor_total': 395.31}
Cenário 3 (Validação Defensiva) [Status 400]: {'erro': 'distancia_km e peso_kg devem ser maiores que zero'}

💡 5. Checkpoint de Engenharia & Boas Práticas

🔗 6. Conexão com os Projetos Integradores

🧪 7. Quiz de Fixação e Autoavaliação (Formative Assessment)

🛠️ 8. Ponte para a Ação: Laboratório Prático

📌 9. Resumo Executivo & Key Takeaways

• Visão Temporal: O Diagrama de Sequência é o modelo comportamental mais utilizado para mapear a ordem cronológica de APIs REST e microsserviços.
• Linhas de Vida & Barras de Ativação: Indicam os participantes e os momentos exatos de processamento ativo.
• Mensagens Síncronas vs Assíncronas: Diferenciam chamadas diretas de eventos desacoplados em filas e mensageria.
• Endpoints em Flask: Implementam de forma limpa e síncrona as transições modeladas no diagrama de sequência, facilitando testes com test_client().