🎭 ATIVIDADE 05: CASOS DE USO (UML)

Bem-vindo a mais uma etapa da sua jornada no curso de Gestão de TI / Desenvolvimento de Sistemas. Hoje vamos mergulhar em conceitos que conectam a teoria técnica diretamente com o padrão de excelência da indústria visual, transformando requisitos em diagramas universais. 🛡️🧩

🎯 Objetivos de Aprendizagem do Laboratório

Ao final deste laboratório prático (estimativa: 4 horas presenciais / autoguiadas), você será capaz de:

• Identificar Atores (pessoas ou sistemas externos que interagem com o seu software).
• Mapear Casos de Uso (funcionalidades entregues ao ator).
• Aplicar os relacionamentos de dependência <<include>> e <<extend>> corretamente, segundo as normas UML.
• Descrever textualmente o "Caminho Feliz" de um Caso de Uso.

🏢 O Cenário Prático (Seu Desafio)

Na TecProExpress, você escreveu um Backlog incrível (Atividade 04). Mas quando levou os Post-its para a diretoria, o CEO disse: "Não consigo ler isso, são muitos textos soltos. Quero um desenho que me mostre de forma macro o que o Motorista pode fazer e o que o Administrador pode fazer".

"Seu desafio é desenhar o primeiro diagrama oficial da Engenharia de Software: O Diagrama de Casos de Uso. Ele será a 'Planta Baixa' do seu aplicativo, estabelecendo a Fronteira do Sistema (o que está dentro e o que está fora)."

🧠 Fundamentos: A Teoria Traduzida

A UML (Linguagem de Modelagem Unificada) é o idioma mundial da engenharia. Um desenvolvedor japonês que não fala português consegue entender seu projeto se você desenhar em UML.

Elementos Chaves

• Ator (Boneco de Palito): É quem provoca o sistema. (Ex: O Cliente, O Motorista, ou até a API do Banco Central).
• Caso de Uso (Oval): Sempre no infinitivo (Ex: Atualizar Rastreio, Realizar Login).
• Fronteira (Retângulo): A caixa do seu software. Atores ficam de fora, Casos de Uso ficam dentro.

📊 Visualizando a Lógica

📖 Exemplo Guiado

Abaixo, veja como estruturar o cenário do aplicativo de logística da TecProExpress.

📊 Relações de Include e Extend da TecProExpress

flowchart LR
    M(("Motorista")) --> UC1(["Finalizar Entrega"])
    UC1 -. "<< include >>" .-> UC2(["Registrar Geolocalização"])
    UC3(["Registrar Foto do Comprovante"]) -. "<< extend >> (Se falhar GPS)" .-> UC1

    style M fill:#eceff1,stroke:#607d8b,stroke-width:2px
    style UC1 fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
    style UC2 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
    style UC3 fill:#fffde7,stroke:#fbc02d,stroke-width:2px

🛠️ Especificação Textual do Caso de Uso

Todo oval desenhado precisa de um "Manual de Instruções" por trás dele. Exemplo do Caso "Reportar Atraso":

• Ator Principal: Motorista.
• Pré-condição: O motorista deve estar logado no aplicativo.
• Fluxo Principal (Caminho Feliz):
  1. O motorista seleciona a entrega em andamento.
  2. Clica no botão "Reportar Atraso".
  3. O sistema pede o motivo (Trânsito, Veículo Quebrado, etc).
  4. O motorista seleciona o motivo e confirma.
  5. O sistema atualiza o status e notifica o SAC.
• Pós-condição: O status da entrega muda para "Atrasado".

🔍 Detalhamento da Documentação:

• O Caminho Feliz é a rota perfeita, sem erros. É essencial escrever isso para que o testador de software saiba o que esperar quando tudo dá certo.

🛠️ Prática Obrigatória 1: O Diagrama

Cenário: O projeto semestral da sua equipe.

1. Acesse o draw.io (ou Lucidchart, Astah) e crie um Diagrama de Casos de Uso.
2. Desenhe a Fronteira do Sistema (O retângulo com o nome do App no topo).
3. Insira pelo menos 2 Atores diferentes (do lado de fora).
4. Insira pelo menos 6 Casos de Uso (dentro da fronteira), derivados das suas User Stories.
5. Crie pelo menos uma relação de <<include>> e uma de <<extend>>.

🏁 Resultado Esperado (Para sua Referência)

Um arquivo de imagem (PNG/JPG) com o diagrama organizado, onde as linhas não se cruzam loucamente, provando que você sabe abstrair o macro do sistema.

💻 Simulador de Casos de Uso (Fluxo Principal & Exceções) em Python

Para validar a execução programática do caso de uso "Atualizar Status de Entrega" (incluindo a extensão de atraso), execute o script:

# simulador_caso_uso.py
from datetime import datetime, timezone

class EntregaService:
    def __init__(self, id_entrega: str) -> None:
        self.id_entrega = id_entrega
        self.status = "EM_TRANSITO"
        self.historico = []

    def executar_fluxo_principal_concluir(self) -> None:
        """UC01 - Fluxo Principal: Confirmar Entrega."""
        self.status = "ENTREGUE"
        self.historico.append({"evento": "CONFIRMACAO_ENTREGA", "data": datetime.now(timezone.utc).isoformat()})
        print(f"✅ [UC01 - Fluxo Principal] Entrega {self.id_entrega} concluída com sucesso!")

    def executar_extensao_reportar_atraso(self, motivo: str) -> None:
        """UC01 <<extend>> UC02: Reportar Atraso na Rota."""
        self.status = "ATRASADO"
        self.historico.append({"evento": "REPORTE_ATRASO", "motivo": motivo, "data": datetime.now(timezone.utc).isoformat()})
        print(f"⚠️  [UC02 - Extend] Entrega {self.id_entrega} marcada como ATRASADA. Motivo: '{motivo}'. SAC notificado!")

if __name__ == "__main__":
    print("=" * 65)
    print("🎭 SIMULADOR DE CASOS DE USO & FLUXOS UML - TECPROEXPRESS")
    print("=" * 65)

    entrega1 = EntregaService("PKG-9901")
    entrega2 = EntregaService("PKG-9902")

    # 1. Executando Caminho Feliz (Fluxo Principal)
    entrega1.executar_fluxo_principal_concluir()

    # 2. Executando Fluxo Alternativo/Extensão
    entrega2.executar_extensao_reportar_atraso("Pneu furado na Rodovia Anhanguera")

    print("-" * 65)
    print(f"Status Final PKG-9901: {entrega1.status}")
    print(f"Status Final PKG-9902: {entrega2.status}")
    print("=" * 65)

🖥️ Saída Esperada no Terminal:

=================================================================
🎭 SIMULADOR DE CASOS DE USO & FLUXOS UML - TECPROEXPRESS
=================================================================
✅ [UC01 - Fluxo Principal] Entrega PKG-9901 concluída com sucesso!
⚠️  [UC02 - Extend] Entrega PKG-9902 marcada como ATRASADA. Motivo: 'Pneu furado na Rodovia Anhanguera'. SAC notificado!
-----------------------------------------------------------------
Status Final PKG-9901: ENTREGUE
Status Final PKG-9902: ATRASADO
=================================================================

🌐 Exemplo de Payload JSON para Extensão de Caso de Uso (Swagger /docs)

{
  "id_entrega": "PKG-9902",
  "acao": "REPORTAR_ATRASO",
  "motivo": "Pneu furado na Rodovia Anhanguera",
  "geolocalizacao": {
    "latitude": -23.55052,
    "longitude": -46.633308
  },
  "notificar_cliente_sms": true
}

📤 Instruções de Entrega (Microsoft Teams)

Após validar suas documentações técnicas:

1. Salve o arquivo de documentação com o nome Atividade_05.md e a imagem do seu diagrama com o nome Atividade_05.png na pasta es-atv-05-casos-uso/ do seu repositório GitHub.
2. Certifique-se de fazer o commit e push para o repositório público.
3. Submeta o link do seu repositório no Microsoft Teams para avaliação do professor.

💡 Checkpoint de Lógica

📊 Rubrica Formativa de Avaliação