diagramas de atividades - LucasXRosas/utfprarena GitHub Wiki

Esta página apresenta os Diagramas de Atividades da API Arena UTFPR, elaborados seguindo as convenções padrão de UML (Unified Modeling Language) e a convenção de Raul Sidnei Wazlawick com a utilização de OCL (Object Constraint Language) e IFML (Interaction Flow Modeling Language) para modelagem de processos de negócio, condicionais, fluxos concorrentes e atualizações de estado do sistema.

Vídeo Descritivo

https://www.youtube.com/watch?v=W_oJuANAcuE

Atividade 1: Gestão de Atores e Vinculação

Esta atividade descreve a criação de perfis de acesso pelo Gestor da Arena, mapeando a diferenciação de fluxos entre Alunos e Professores, a obrigatoriedade da vinculação e a instanciação do contrato inicial.

Diagrama UML

flowchart TD
    subgraph Gestor["Gestor da Arena"]
        Start([ ]) ---> SolicitarCadastro[Acessar módulo de cadastro]
        MergeFormulario{ }
        PreencherFormulario[Preencher formulário: Nome, CPF, E-mail, Telefone]
        EnviarCadastro[Submeter dados cadastrais]

        SolicitarCadastro --> MergeFormulario
        MergeFormulario --> PreencherFormulario
        PreencherFormulario --> EnviarCadastro
    end

    subgraph Sistema["API / Sistema Arena"]
        ValidaFormulario{ }
        ChecarVinculoProf{ }
        ExigirVinculo[Exibir erro de vínculo obrigatório]
        
        ProcessarProf[Persistir perfil Professor]
        ProcessarAluno[Persistir perfil Aluno e associar Professor]
        
        GerarPrimeiraFatura[Criar cobrança do 1º ciclo]
        FinalizarCadastro[Definir status inicial do Usuário]
        MergeFinalizacao{ }
        
        EnviarCadastro --> ValidaFormulario
        
        ValidaFormulario -- "[perfil = Professor]" --> ProcessarProf
        ValidaFormulario -- "[perfil = Aluno]" --> ChecarVinculoProf
        
        ChecarVinculoProf -- "[sem vínculo / else]" --> ExigirVinculo
        ExigirVinculo --> MergeFormulario
        
        ChecarVinculoProf -- "[possui vínculo com professor]" --> ProcessarAluno
        
        ProcessarAluno --> ObjFaturaPendente[Fatura : PENDENTE]
        ObjFaturaPendente --> GerarPrimeiraFatura
        
        ProcessarProf --> MergeFinalizacao
        GerarPrimeiraFatura --> MergeFinalizacao
        MergeFinalizacao --> FinalizarCadastro
    end

    subgraph BD["Banco de Dados / Repositório"]
        ObjUsuarioAtivo[Usuario : ATIVO]
        SalvarRegistro[Salvar Registro no Repositório]
        EndNode([ ])
        
        FinalizarCadastro --> ObjUsuarioAtivo
        ObjUsuarioAtivo --> SalvarRegistro
        SalvarRegistro --> EndNode
    end

    style Start fill:#000,stroke:#fff
    style EndNode fill:#000,stroke:#fff,stroke-width:4px
    style ObjFaturaPendente stroke-width:2px
    style ObjUsuarioAtivo stroke-width:2px
Loading

Detalhamento Textual

  • Início: O Gestor da Arena acessa o módulo de cadastro de usuários.
  • Entrada de Dados: O Gestor preenche o formulário informando Nome, CPF, E-mail, Telefone e seleciona o perfil do usuário.
  • Validação de Formato e Regras de Perfil:
  • Decisão de Perfil (Aluno vs. Professor):
    • Caminho A (Professor): O sistema valida os dados e envia para persistência do perfil de Professor sem a criação de mensalidades recorrentes.
    • Caminho B (Aluno): O sistema verifica a indicação obrigatória de um Professor responsável. Caso o campo esteja ausente, o formulário é rejeitado com mensagem de erro.
  • Instanciação e Estado:
    • Para o Aluno, o sistema gera o primeiro ciclo financeiro [Objeto: Fatura (Status = PENDENTE)] e associa seu vínculo ao professor indicado.
    • O sistema finaliza definindo o nó objeto [Objeto: Usuario (Status = ATIVO)] e conclui o cadastro no banco de dados.

Atividade 2: Processo de Cobrança e Baixa de Mensalidade

Esta atividade mapeia o faturamento periódico, a emissão de lembretes preventivos, a escolha do meio de pagamento e a baixa sincronizada via callback de Webhook ou liberação manual pelo gestor.

Diagrama UML

flowchart TD
    subgraph Cron["Processo Agendado / Cron"]
        Start([ ]) --> VarreduraVencimentos[Executar varredura diária]
        VarreduraVencimentos --> IdentificarVencimentos[Filtrar faturas com vencimento próximo]
        
        IdentificarVencimentos --> ForkBar["━━━━ FORK ━━━━"]
        ForkBar --> DispararEmail[Disparar alerta via E-mail]
        ForkBar --> DispararPush[Disparar alerta via App/WhatsApp]
        
        DispararEmail --> JoinBar["━━━━ JOIN ━━━━"]
        DispararPush --> JoinBar
    end

    subgraph Aluno["Aluno / Cliente"]
        ReceberAlerta[Receber alerta de fatura aberta]
        EscolherPagamento{ }
        
        JoinBar --> ReceberAlerta
        ReceberAlerta --> EscolherPagamento
    end

    subgraph Gateway["Gateway de Pagamento / Adquirente"]
        GerarPayloadPIX[Criar QR Code PIX]
        ProcessarTransacao[Autorizar transação de crédito]
        MergePagamento{ }
        ConfirmarGateway{ }
        ConfirmarSucesso[Processar liquidação financeira]
        TratarFalha[Registrar recusa ou expiração]
        DispararWebhook[Disparar callback de pagamento]
        
        EscolherPagamento -- "[opção = PIX]" --> GerarPayloadPIX
        EscolherPagamento -- "[opção = Cartão de Crédito]" --> ProcessarTransacao
        
        GerarPayloadPIX --> MergePagamento
        ProcessarTransacao --> MergePagamento
        MergePagamento --> ConfirmarGateway
        
        ConfirmarGateway -- "[liquidação = Confirmada]" --> ConfirmarSucesso
        ConfirmarGateway -- "[liquidação = Recusada / Expirada]" --> TratarFalha
        
        ConfirmarSucesso --> DispararWebhook
    end

    subgraph API["API / Sistema Arena"]
        ProcessarBaixa[Validar payload do Webhook]
        ObjFaturaPago[Fatura : PAGO]
        AtualizarFatura[Alterar estado da fatura]
        RenovarCiclo[Prorrogar acesso por +30 dias]
        ObjUsuarioAtivo[Usuario : ATIVO]
        EndNode([ ])
        
        ObjFaturaRecusada[Fatura : RECUSADA/EXPIRADA]
        NotificarFalha[Notificar aluno: pagamento não efetuado]
        
        DispararWebhook --> ProcessarBaixa
        ProcessarBaixa --> ObjFaturaPago
        ObjFaturaPago --> AtualizarFatura
        AtualizarFatura --> RenovarCiclo
        RenovarCiclo --> ObjUsuarioAtivo
        ObjUsuarioAtivo --> EndNode
        
        TratarFalha --> ObjFaturaRecusada
        ObjFaturaRecusada --> NotificarFalha
        NotificarFalha -. "[tentar novamente]" .-> ReceberAlerta
    end

    style Start fill:#000,stroke:#fff
    style EndNode fill:#000,stroke:#fff,stroke-width:4px
    style ForkBar fill:#000,color:#fff,stroke:#fff,font-weight:bold
    style JoinBar fill:#000,color:#fff,stroke:#fff,font-weight:bold
    style ObjFaturaPago stroke-width:2px
    style ObjFaturaRecusada stroke-width:2px
    style ObjUsuarioAtivo stroke-width:2px
Loading

Detalhamento Textual

  • Monitoramento Continuado: Um job agendado executa diariamente a busca por faturas cujo vencimento expira em $X$ dias.
  • Disparo Concorrente de Alertas: Ao encontrar registros, o sistema executa um nó de garfo (Fork), disparando em paralelo as notificações via E-mail e Push/WhatsApp, sincronizando os fluxos em um nó de junção (Join).
  • Processamento de Pagamento:
    • O aluno seleciona a fatura e opta por PIX (com geração de QR Code dinâmico) ou Cartão de Crédito/Débito.
    • A transação é processada na adquirente/gateway parceiro.
  • Baixa e Transição de Estado:
    • O gateway dispara um Webhook para a API da Arena confirmando o recebimento.
    • O sistema executa a transição do nó objeto de [Fatura: PENDENTE] para [Fatura: PAGO], renovando a validade da assinatura do aluno por mais 30 dias com status ATIVO.

Atividade 3: Régua de Inadimplência e Bloqueio Automático

Esta atividade descreve a verificação automatizada de pendências financeiras, a régua gradual de notificações preventivas por tempo de atraso, o bloqueio do aluno ao atingir o limite tolerado e o desbloqueio instantâneo após a quitação.

Diagrama UML

flowchart TD
    subgraph Cron["Processo Agendado / Cron"]
        Start([ ])
        ChecagemInadimplencia[Executar varredura na madrugada]
        AvaliarDiasAtraso{ }
        
        Start --> ChecagemInadimplencia
        ChecagemInadimplencia --> AvaliarDiasAtraso
    end

    subgraph Sistema["API / Sistema Arena"]
        Regua7Dias[Disparar 1º Lembrete]
        Regua14Dias[Disparar 2º Lembrete]
        Regua21Dias[Disparar 3º Lembrete]
        MergeRegua{ }
        EndDiario([ ])
        
        AplicarBloqueio[Atualizar permissão de acesso]
        NotificarBloqueio[Enviar aviso de suspensão ao aluno]
        BloquearCatraca[Negar requisições no endpoint CheckAccess]
        
        AvaliarDiasAtraso -- "[dias = 7]" --> Regua7Dias
        AvaliarDiasAtraso -- "[dias = 14]" --> Regua14Dias
        AvaliarDiasAtraso -- "[dias = 21]" --> Regua21Dias
        AvaliarDiasAtraso -- "[else / sem ação hoje]" --> MergeRegua
        
        Regua7Dias --> MergeRegua
        Regua14Dias --> MergeRegua
        Regua21Dias --> MergeRegua
        MergeRegua --> EndDiario
        
        AvaliarDiasAtraso -- "[dias >= 30 ou débitos >= 2]" --> ObjUsuarioBloqueado[Usuario : BLOQUEADO]
        ObjUsuarioBloqueado --> AplicarBloqueio
        AplicarBloqueio --> NotificarBloqueio
        NotificarBloqueio --> BloquearCatraca
    end

    subgraph Reativacao["Fluxo Assíncrono de Quitação"]
        EventoPagamentoConfirmed>Evento: Pagamento Confirmado]
        DesbloqueioInstantaneo[Executar baixa automática da dívida]
        RegistrarAuditoria[Registrar log de auditoria com data/hora do desbloqueio]
        RestabelecerStatus[Restaurar permissão de acesso]
        ObjUsuarioReativo[Usuario : ATIVO]
        EndReativacao([ ])
        
        BloquearCatraca -. "Aguardando evento" .-> EventoPagamentoConfirmed
        EventoPagamentoConfirmed --> DesbloqueioInstantaneo
        DesbloqueioInstantaneo --> RegistrarAuditoria
        RegistrarAuditoria --> RestabelecerStatus
        RestabelecerStatus --> ObjUsuarioReativo
        ObjUsuarioReativo --> EndReativacao
    end

    style Start fill:#000,stroke:#fff
    style EndDiario fill:#000,stroke:#fff,stroke-width:4px
    style EndReativacao fill:#000,stroke:#fff,stroke-width:4px
    style ObjUsuarioBloqueado stroke-width:2px
    style ObjUsuarioReativo stroke-width:2px
    style EventoPagamentoConfirmed stroke-width:2px
Loading

Detalhamento Textual

  • Varredura Diária de Madrugada: A API executa uma rotina em segundo plano para contabilizar os dias de atraso das faturas abertas.
  • Régua de Cobrança Preventiva (Nó de Decisão):
    • 7 dias de atraso: Envio do 1º aviso formal de cobrança.
    • 14 dias de atraso: Envio do 2º aviso de cobrança com alerta de suspensão iminente.
    • 21 dias de atraso: Envio do 3º e último aviso preventivo.
    • Os fluxos de notificação reconvergem em um nó de mescla (Merge) finalizando a execução do job.
  • Suspensão Automatizada:
    • Ao atingir 30 dias de atraso ou acumular 2 faturas vencidas, o sistema realiza a alteração do nó objeto do aluno para [Usuario: BLOQUEADO].
    • As requisições ao endpoint de controle de acesso (CheckAccess) passam a retornar resposta negativa, impedindo a liberação de catracas ou a reserva de quadras.
  • Reativação em Tempo Real:
    • Assim que a quitação da dívida é processada pela Atividade 2, o sistema dispara a transição imediata do nó objeto do aluno de volta para [Usuario: ATIVO], liberando o acesso às instalações instantaneamente.

Uso de Inteligência Artificial

No desenvolvimento da Entrega 2, foram utilizadas ferramentas de Inteligência Artificial Generativa para validação da notação UML, refinamento da lógica de estados e conversão dos requisitos para sintaxe Mermaid.js.

Ferramentas Utilizadas

Gemini: Utilizados no apoio à estruturação dos diagramas de atividades UML, alinhamento dos nós de decisão e garantia de conformidade com a literatura de modelagem orientada a objetos.

Finalidades do Uso

  1. Modelagem Metodológica UML: Ajuste dos diagramas conceituais para atender às diretrizes do livro Análise e Design Orientados a Objetos para Sistemas de Informação (Raul Sidnei Wazlawick).
  2. Sintaxe e Renderização em Mermaid.js: Conversão de estruturas de raias (Partitions), concorrência (Fork/Join) e estados de objetos para código gráfico compatível com o GitHub Wiki.
  3. Escrita da Documentação: Estruturação dos textos explicativos e detalhamento textual correspondente a cada nó dos diagramas.

Exemplos de Prompts e Resultados

Exemplo 1: Adaptação para Raias de Divisão (Swimlanes)

  • Prompt Enviado:

"Como organizar um Diagrama de Atividades UML no Mermaid.js utilizando raias (partitions) para separar as ações executadas pelo Gestor da Arena, pela API e pelo Banco de Dados conforme a metodologia do livro do Raul Wazlawick?"

  • Resultado Obtido: A IA estruturou o diagrama utilizando blocos de estado como partições lógicas (state "API / Sistema" as Sistema), isolando as responsabilidades de cada componente e ator do sistema.

Exemplo 2: Garfo e Junção para Disparos Concorrentes

  • Prompt Enviado:

"Modele em UML uma barra de garfo (fork) e junção (join) para disparar notificações por E-mail e Push em paralelo quando uma fatura estiver próxima do vencimento."

  • Resultado Obtido:

A IA gerou a notação com os estados <> e <> para representar a concorrência assíncrona do envio de mensagens antes de retornar ao fluxo principal do usuário.

⚠️ **GitHub.com Fallback** ⚠️