🎭 CAPÍTULO 10: DIAGRAMA DE CASOS DE USO (CONCEITOS)

🎯 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 finalidade do Diagrama de Casos de Uso na captura de requisitos funcionais sob a perspectiva do usuário (Ivar Jacobson / UML).
• 🔹 Identificar Atores Primários, Atores Secundários (Sistemas Externos/APIs) e o Limite do Sistema (System Boundary).
• 🔹 Modelar diagramas de casos de uso profissionais com sintaxe declarativa Mermaid e Draw.io.
• 🔹 Evitar o anti-pattern de desenhar sequências temporais e fluxogramas dentro do diagrama de casos de uso.

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

Na TecProExpress, a diretoria executiva solicitou uma visão consolidada de todas as operações do novo Módulo de Gestão de Fretes e Frotas. Eles não desejam ver tabelas de banco de dados ou detalhes de infraestrutura, mas precisam entender com clareza quais ações podem ser executadas pelo Motorista, pelo Operador de Logística e pelo Gateway Bancário.

O Desafio: Seu objetivo como Analista de Sistemas é construir a "foto panorâmica" de escopo funcional do sistema através do Diagrama de Casos de Uso, estabelecendo com precisão o que está dentro do escopo do software (System Boundary) e quais entidades externas interagem com ele.

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

3.1. A Tríade do Diagrama de Casos de Uso

O diagrama organiza-se em torno de 3 elementos gráficos padronizados pela UML:

1. Atores (Actors): Entidades externas que interagem com o sistema (usuários, sensores ou sistemas legados).
2. Casos de Uso (Use Cases - Elipses): Conjuntos de ações realizadas pelo sistema que geram um resultado de valor observável para o ator.
3. Limite do Sistema (Subject Boundary - Retângulo): Delimita o que pertence ao software que será construído versus o que é externo.

flowchart LR
    subgraph SIS ["🏢 SISTEMA TECPROEXPRESS (SYSTEM BOUNDARY)"]
        direction TB
        UC1(["📦 Registrar Pacote"])
        UC2(["🗺️ Rastrear Entrega"])
        UC3(["💳 Processar Pagamento"])
    end
    
    A1["👤 Operador Logístico"] --> UC1
    A2["👤 Cliente Final"] --> UC2
    UC3 --> S1["🏛️ Gateway de Pagamento (API)"]
    
    style SIS fill:#f8fafc,stroke:#475569
    style UC1 fill:#e0f2fe,stroke:#0284c7
    style UC2 fill:#e0f2fe,stroke:#0284c7
    style UC3 fill:#e0f2fe,stroke:#0284c7
    style A1 fill:#dcfce7,stroke:#16a34a
    style A2 fill:#dcfce7,stroke:#16a34a
    style S1 fill:#ede7f6,stroke:#5e35b1

3.2. Atores Primários vs. Atores Secundários

• Ator Primário: Inicia a interação com o sistema para atingir uma meta pessoal de negócio (ex: o Cliente buscando rastrear seu pacote).
• Ator Secundário (Ator de Suporte): É acionado pelo sistema para fornecer serviços auxiliares (ex: a API de Envio de SMS ou o Serviço de Cobrança Bancária).

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

Mapeamento de casos de uso para controladores REST com Flask 3.x em Python 3.11+.

📋 Pré-requisitos e Instalação

No terminal do seu ambiente virtual, instale o microframework Flask:

pip install flask

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

Crie o arquivo rotas_casos_uso.py e insira o código abaixo integralmente:

"""
Módulo: rotas_casos_uso.py
Domínio: Transposição de casos de uso UML para endpoints REST com Flask 3.x.
Stack: Python 3.11+ | Flask 3.x
"""
from flask import Flask, request, jsonify

app = Flask(__name__)

# Base de dados em memória para simulação operacional
PACOTES_DB = {
    "BR123456": {"codigo": "BR123456", "status": "EM TRANSITO", "localizacao": "Hub São Paulo"}
}

# Caso de Uso 1: Registrar Pacote (Ator: Operador Logístico)
@app.post("/api/pacotes/")
def uc_registrar_pacote():
    """UC01: Permite ao Operador Logístico cadastrar um novo pacote no sistema."""
    dados = request.get_json()
    if not dados or "codigo" not in dados or "peso_kg" not in dados:
        return jsonify({"status": "ERRO", "mensagem": "Campos 'codigo' e 'peso_kg' são obrigatórios."}), 400

    PACOTES_DB[dados["codigo"]] = {
        "codigo": dados["codigo"],
        "peso_kg": dados["peso_kg"],
        "destino": dados.get("destino", "NÃO INFORMADO"),
        "status": "REGISTRADO"
    }
    return jsonify({"status": "SUCESSO", "mensagem": f"Pacote {dados['codigo']} registrado com sucesso."}), 201

# Caso de Uso 2: Rastrear Entrega (Ator: Cliente Final)
@app.get("/api/pacotes/<codigo>/rastreio")
def uc_rastrear_entrega(codigo: str):
    """UC02: Permite ao Cliente Final consultar o status em tempo real do pacote."""
    pacote = PACOTES_DB.get(codigo)
    if not pacote:
        return jsonify({"status": "ERRO", "detalhe": f"Pacote '{codigo}' não localizado."}), 404
    return jsonify(pacote), 200

# Ponto de Entrada Executável
if __name__ == "__main__":
    print("🚀 TESTE DE CONTROLADORES REST FLASK (CASOS DE USO UML)")
    print("=" * 65)

    # Execução de testes de integração automáticos via Flask Test Client nativo
    client = app.test_client()

    # 1. Simulação do Caso de Uso 1 (Operador cadastra pacote)
    print("1. [UC01 - Operador] Registrando pacote:")
    resp_post = client.post("/api/pacotes/", json={"codigo": "BR999888", "peso_kg": 3.5, "destino": "Curitiba/PR"})
    print(f"   Status HTTP: {resp_post.status_code}")
    print(f"   Resposta: {resp_post.get_json()}\n")

    # 2. Simulação do Caso de Uso 2 (Cliente rastreia pacote)
    print("2. [UC02 - Cliente] Rastreando entrega cadastrada:")
    resp_get = client.get("/api/pacotes/BR123456/rastreio")
    print(f"   Status HTTP: {resp_get.status_code}")
    print(f"   Resposta: {resp_get.get_json()}\n")

    # 3. Cenário de Falha (Pacote não encontrado)
    print("3. [UC02 - Exceção] Consultando código inexistente:")
    resp_404 = client.get("/api/pacotes/XX000000/rastreio")
    print(f"   Status HTTP: {resp_404.status_code}")
    print(f"   Resposta: {resp_404.get_json()}")
    print("=" * 65)
    print("💡 Dica: Para iniciar o servidor HTTP interativo na porta 5000, descomente: # app.run(port=5000, debug=True)")
    # app.run(port=5000, debug=True)

🚀 Como Executar

Execute o script no terminal:

python rotas_casos_uso.py

🖥️ Saída Esperada no Terminal

🚀 TESTE DE CONTROLADORES REST FLASK (CASOS DE USO UML)
=================================================================
1. [UC01 - Operador] Registrando pacote:
   Status HTTP: 201
   Resposta: {'mensagem': 'Pacote BR999888 registrado com sucesso.', 'status': 'SUCESSO'}

2. [UC02 - Cliente] Rastreando entrega cadastrada:
   Status HTTP: 200
   Resposta: {'codigo': 'BR123456', 'localizacao': 'Hub São Paulo', 'status': 'EM TRANSITO'}

3. [UC02 - Exceção] Consultando código inexistente:
   Status HTTP: 404
   Resposta: {'detalhe': "Pacote 'XX000000' não localizado.", 'status': 'ERRO'}
=================================================================
💡 Dica: Para iniciar o servidor HTTP interativo na porta 5000, descomente: # app.run(port=5000, debug=True)

💡 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 de Escopo: O Diagrama de Casos de Uso apresenta as capacidades do sistema sob a ótica do usuário e de sistemas externos.
• Atores: Papéis que interagem com o sistema (não confunda com pessoas individuais).
• Fronteira do Sistema: Delimita a responsabilidade da equipe técnica de desenvolvimento.
• Nomenclatura Semântica: Sempre use [Verbo no Infinitivo] + [Objeto] expressando uma meta real de negócio.