🎭 CAPÍTULO 11: CASOS DE USO (PRÁTICA E RELAÇÕES)

🎯 1. Objetivos de Aprendizagem & Competências

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

• 🔹 Distinguir e aplicar com precisão os três relacionamentos da UML entre casos de uso: «include» (inclusão obrigatória), «extend» (extensão condicional) e Generalização/Especialização.
• 🔹 Estruturar especificações textuais completas de casos de uso contendo Fluxo Principal (Caminho Feliz), Fluxos Alternativos e Fluxos de Exceção.
• 🔹 Modelar diagramas com pontos de extensão (Extension Points) claros no Mermaid e Draw.io.
• 🔹 Implementar o padrão de handlers condicionais e exceções em Python 3.11+ refletindo os fluxos modelados.

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

Na TecProExpress, a equipe de desenvolvimento modelou um caso de uso para "Emitir Frete". No entanto, quando o cliente solicita entrega expressa aos domingos, uma taxa especial de seguro adicional precisa ser contratada condicionalmente. Além disso, toda emissão de frete exige obrigatoriamente a validação do token JWT de autenticação.

O Desafio: Você deve modelar corretamente esses comportamentos utilizando as relações «include» para a autenticação obrigatória e «extend» com ponto de extensão condicional para o seguro especial de domingo, evitando duplicação de lógica e garantindo clareza técnica.

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

3.1. As Relações entre Casos de Uso na UML

flowchart TD
    subgraph RELACOES_UC ["RELAÇÕES NA UML ENTRE CASOS DE USO"]
        direction TB
        UC_BASE(["📦 Emitir Frete (Base)"])
        
        UC_INC(["🔐 Validar Token JWT<br>(Obrigatório)"])
        UC_EXT(["🛡️ Contratar Seguro Especial<br>(Opcional / Condicional)"])
        
        UC_BASE -.->|"«include»"| UC_INC
        UC_EXT -.->|"«extend» [Se for Domingo]"| UC_BASE
    end
    
    style UC_BASE fill:#e0f2fe,stroke:#0284c7
    style UC_INC fill:#ede7f6,stroke:#5e35b1
    style UC_EXT fill:#fef3c7,stroke:#d97706

3.2. Comparativo: «include» vs. «extend» vs. Generalização

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

Implementação dos fluxos principal, de extensão («extend») e de inclusão obrigatória («include») em Python 3.11+.

📋 Pré-requisitos e Instalação

Este módulo utiliza exclusivamente recursos nativos do Python 3.11+ (dataclasses e decimal). Nenhuma instalação externa é necessária:

# Ambiente padrão Python 3.11+ (sem dependências externas)

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

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

"""
Módulo: emissoes_frete_regras.py
Domínio: Aplicação das relações de caso de uso (Include, Extend e Exceções).
Stack: Python 3.11+
"""
from dataclasses import dataclass
from decimal import Decimal

class TokenInvalidoException(Exception):
    pass

@dataclass
class SolicitacaoFrete:
    token_jwt: str
    peso_kg: Decimal
    entrega_domingo: bool

# Caso de Uso Incluído («include» obrigatório)
def validar_token_jwt(token: str):
    if not token or token != "TOKEN_SEGURO_2026":
        raise TokenInvalidoException("❌ Acesso negado: Token JWT ausente ou inválido.")

# Caso de Uso Extensor («extend» condicional)
def aplicar_seguro_domingo(valor_base: Decimal) -> Decimal:
    print(" 🛡️ [«extend»] Ponto de Extensão Ativado: Adicionando Seguro Especial de Domingo (+15%)")
    return valor_base * Decimal("1.15")

# Caso de Uso Base
def emitir_frete(solicitacao: SolicitacaoFrete) -> Decimal:
    # 1. Executa o «include» obrigatório
    validar_token_jwt(solicitacao.token_jwt)

    # 2. Fluxo Principal
    valor_base = solicitacao.peso_kg * Decimal("12.00")

    # 3. Ponto de Extensão («extend»)
    if solicitacao.entrega_domingo:
        valor_base = aplicar_seguro_domingo(valor_base)

    return valor_base

if __name__ == "__main__":
    try:
        sol = SolicitacaoFrete("TOKEN_SEGURO_2026", Decimal("5.0"), entrega_domingo=True)
        valor_final = emitir_frete(sol)
        print(f"✅ Frete emitido com sucesso: R$ {valor_final:.2f}")
    except TokenInvalidoException as erro:
        print(erro)

🚀 Como Executar

Execute o script no terminal:

python emissoes_frete_regras.py

🖥️ Saída Esperada no Terminal

 🛡️ [«extend»] Ponto de Extensão Ativado: Adicionando Seguro Especial de Domingo (+15%)
✅ Frete emitido com sucesso: R$ 69.00

💡 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

• «include»: Comportamento compartilhado e obrigatório para o término do caso base.
• «extend»: Comportamento modular e condicional acionado em pontos de extensão pré-definidos.
• Direção das Setas: Base ➔ «include» ➔ Compartilhado | Extensor ➔ «extend» ➔ Base.
• Especificação Textual: Caminho Feliz (Principal), Alternativos e Exceções devem ser detalhados para guiar o time de testes e desenvolvimento.