🔄 CAPÍTULO 15: DIAGRAMAS DINÂMICOS (ESTADOS E ATIVIDADES)

🎯 1. Objetivos de Aprendizagem & Competências

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

• 🔹 Modelar o ciclo de vida completo de entidades reativas utilizando o Diagrama de Máquina de Estados da UML (David Harel).
• 🔹 Dominar a sintaxe formal de transições: Evento [Condição de Guarda] / Ação Executada.
• 🔹 Construir Diagramas de Atividades com particionamento em Raias (Swimlanes), bifurcações de decisão e nós de sincronização paralela (Fork e Join).
• 🔹 Implementar o padrão comportamental State Pattern e máquinas de estados finitos (FSM) em Python 3.11+.

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

Na TecProExpress, os motoristas estavam conseguindo alterar o status de um pacote diretamente de "Aguardando Coleta" para "Entregue ao Destinatário", pulando a etapa obrigatória de "Em Rota de Entrega" e sem coletar a assinatura digital do cliente.

O Desafio: Como Engenheiro de Software, você deve modelar formalmente a Máquina de Estados Finita do pacote e o Diagrama de Atividades com Raias do processo de entrega, garantindo que o backend bloqueie qualquer transição de status ilegal ou desordenada.

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

3.1. Diagrama de Máquina de Estados da UML

Mapeia os estados discretos pelos quais um objeto passa durante sua existência em resposta a eventos:

stateDiagram-v2
    [*] --> CRIADO : Criação do Pacote
    CRIADO --> COLETADO : Motorista Coleta no Hub
    COLETADO --> EM_TRANSITO : Saída para Entrega [Veículo Alocado]
    EM_TRANSITO --> TENTATIVA_FALHA : Cliente Ausente / Notificar SAC
    TENTATIVA_FALHA --> EM_TRANSITO : Nova Tentativa [Tentativas < 3]
    TENTATIVA_FALHA --> DEVOLVIDO_HUB : Excedeu Limite [Tentativas >= 3]
    EM_TRANSITO --> ENTREGUE : Assinatura Coletada / Enviar Recibo
    ENTREGUE --> [*]
    DEVOLVIDO_HUB --> [*]

3.2. Diagrama de Atividades com Raias (Swimlanes) e Fork / Join

Organiza o fluxo de trabalho distribuindo as responsabilidades entre os diferentes departamentos/atores:

flowchart TD
    subgraph CLIENTE ["👤 Cliente"]
        A1["Fazer Pedido"] --> A2["Efetuar Pagamento"]
    end
    
    subgraph GATEWAY ["🏛️ Gateway Pagamento"]
        A2 --> B1{"Pagamento Aprovado?"}
    end
    
    subgraph LOGISTICA ["🚚 Centro Logístico"]
        B1 -- Sim --> FORK["Barra Fork (Paralelo)"]
        FORK --> C1["Separar Estoque"]
        FORK --> C2["Emitir Nota Fiscal"]
        C1 --> JOIN["Barra Join (Sincronização)"]
        C2 --> JOIN
        JOIN --> C3["Despachar Encomenda"]
    end
    
    B1 -- Não --> A3["Notificar Erro Pagamento"]
    
    style FORK fill:#fef3c7,stroke:#d97706
    style JOIN fill:#fef3c7,stroke:#d97706
    style C3 fill:#dcfce7,stroke:#16a34a

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

📋 Pré-requisitos e Instalação

Este exemplo utiliza os módulos padrão enum do Python, sem necessidade de pacotes externos:

python --version  # Requer Python 3.11 ou superior

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

Implementação de uma Máquina de Estados Finitos (FSM) com validação estrita de transições de ciclo de vida:

"""
Módulo: maquina_estados_pacote.py
Domínio: Validação de transições de ciclo de vida de encomendas com FSM.
"""
from enum import Enum, auto

class EstadoPacote(Enum):
    CRIADO = auto()
    COLETADO = auto()
    EM_TRANSITO = auto()
    ENTREGUE = auto()
    CANCELADO = auto()

class PacoteFSM:
    # Tabela de transições permitidas: EstadoAtual -> Lista de Próximos Estados Legais
    TRANSIÇÕES_VALIDAS = {
        EstadoPacote.CRIADO: {EstadoPacote.COLETADO, EstadoPacote.CANCELADO},
        EstadoPacote.COLETADO: {EstadoPacote.EM_TRANSITO, EstadoPacote.CANCELADO},
        EstadoPacote.EM_TRANSITO: {EstadoPacote.ENTREGUE, EstadoPacote.COLETADO},
        EstadoPacote.ENTREGUE: set(), # Estado Final
        EstadoPacote.CANCELADO: set()  # Estado Final
    }

    def __init__(self, codigo_rastreio: str):
        self.codigo_rastreio = codigo_rastreio
        self.estado_atual = EstadoPacote.CRIADO

    def transicionar_para(self, novo_estado: EstadoPacote):
        permitidos = self.TRANSIÇÕES_VALIDAS.get(self.estado_atual, set())
        if novo_estado not in permitidos:
            raise ValueError(
                f"❌ Transição Ilegal: Não é permitido mudar de {self.estado_atual.name} para {novo_estado.name}."
            )
        self.estado_atual = novo_estado
        print(f"📦 Pacote [{self.codigo_rastreio}] transicionou com sucesso para: {self.estado_atual.name}")

if __name__ == "__main__":
    print("--- Simulação da Máquina de Estados (FSM) de Logística ---")
    pacote = PacoteFSM("BR-2026-99")
    pacote.transicionar_para(EstadoPacote.COLETADO)
    pacote.transicionar_para(EstadoPacote.EM_TRANSITO)
    pacote.transicionar_para(EstadoPacote.ENTREGUE)
    
    # Tentativa ilegal de transição a partir de um estado final
    try:
        pacote.transicionar_para(EstadoPacote.CRIADO)
    except ValueError as err:
        print(err)

🚀 Como Executar

Execute o script diretamente no terminal:

python maquina_estados_pacote.py

🖥️ Saída Esperada no Terminal

--- Simulação da Máquina de Estados (FSM) de Logística ---
📦 Pacote [BR-2026-99] transicionou com sucesso para: COLETADO
📦 Pacote [BR-2026-99] transicionou com sucesso para: EM_TRANSITO
📦 Pacote [BR-2026-99] transicionou com sucesso para: ENTREGUE
❌ Transição Ilegal: Não é permitido mudar de ENTREGUE para CRIADO.

💡 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

• Diagrama de Estados: Foca nas mudanças de situação interna de uma única entidade ao longo do tempo.
• Sintaxe de Transição: Evento [Guarda Booleana] / Ação Executada.
• Diagrama de Atividades: Modela o fluxo de trabalho global, decisões lógicas e sincronização paralela (Fork/Join).
• Raias (Swimlanes): Atribuem responsabilidades claras para cada etapa do processo corporativo.