Diagrama de Transição de Estados — KOLOS

Máquinas de estados (UML): estados possíveis, eventos que disparam transições e estados finais. Complementa wireflow.md, user-flow.md e activity-diagram.md.

Nota: sintaxe Mermaid (stateDiagram-v2). Estados com nomes alinhados a middlewares (auth, actor_context, role:*) e ao Actor Switcher.

1. Ciclo de vida da sessão (autenticação)

Estados do utilizador relativamente à aplicação web.

stateDiagram-v2
    [*] --> Visitante: primeira visita / sessão expirada

    Visitante --> Autenticando: abrir /login
    Autenticando --> Visitante: credenciais inválidas
    Autenticando --> Autenticado: login OK

    Visitante --> Registando: abrir /cadastro
    Registando --> Visitante: abandonar / erro bloqueante
    Registando --> Autenticado: cadastro OK + sessão

    Autenticado --> Visitante: logout / POST /logout
    Autenticado --> Visitante: sessão invalidada / timeout

2. Contexto de ator (ActorContext)

Após login, o utilizador pode alternar quem está a “agir” na UI (jogador vs dono de arena), quando aplicável.

stateDiagram-v2
    [*] --> Indefinido: sem utilizador

    Indefinido --> PlayerAtivo: ator = player\n(switch / default)
    Indefinido --> VenueOwnerAtivo: ator = venue_owner

    PlayerAtivo --> VenueOwnerAtivo: switch actor\n(Actor Switcher)
    VenueOwnerAtivo --> PlayerAtivo: switch actor

    PlayerAtivo --> Indefinido: logout
    VenueOwnerAtivo --> Indefinido: logout

Efeito nas rotas: com PlayerAtivo, rotas de arena podem estar inacessíveis (403); com VenueOwnerAtivo, rotas só player (ex.: /booking) podem estar inacessíveis.

3. Estados de navegação na área autenticada (macro)

Visão grosso grão da “zona” da app (não substitui a lista de rotas).

stateDiagram-v2
    [*] --> Dashboard: entrada pós-login

    state "Área autenticada" as Auth {
        Dashboard --> Social: torneios / comunidade / card
        Dashboard --> Jogo: booking\n(só player + ator player)
        Dashboard --> Operacional: arenas / quadras / manutenção\n(só venue + permissões)
        Dashboard --> DocsHub: /docs
        Social --> Dashboard
        Jogo --> Dashboard
        Operacional --> Dashboard
        DocsHub --> Dashboard
    }

    Auth --> [*]: logout

4. Cadastro de jogador (formulário)

Estados do fluxo de UI do registo (conceitual).

stateDiagram-v2
    [*] --> EmEdicao: abrir /cadastro

    EmEdicao --> Validando: submeter
    Validando --> EmEdicao: erros de validação
    Validando --> Submetendo: dados OK
    Submetendo --> ContaCriada: persistência OK
    Submetendo --> EmEdicao: falha servidor

    ContaCriada --> [*]: redirecionamento / sessão
    EmEdicao --> [*]: abandonar

5. Dono de arena — contexto de gestão de uma arena

Passar de lista para detalhe de uma arena (quadras / manutenção).

stateDiagram-v2
    [*] --> ListaArenas: /venues

    ListaArenas --> ListaArenas: filtrar / atualizar lista
    ListaArenas --> ArenaSelecionada: escolher arena

    ArenaSelecionada --> GestaoQuadras: ir a courts
    ArenaSelecionada --> GestaoManutencao: ir a maintenance
    ArenaSelecionada --> ListaArenas: voltar

    GestaoQuadras --> ArenaSelecionada: concluir edição
    GestaoManutencao --> ArenaSelecionada: concluir registo

    ListaArenas --> [*]: logout / sair da área

6. Documentação (modo de leitura)

stateDiagram-v2
    [*] --> IndiceDocs: /docs

    IndiceDocs --> LeituraMarkdown: abrir architecture / changes / read
    LeituraMarkdown --> IndiceDocs: voltar ao índice
    LeituraMarkdown --> LeituraMarkdown: seguir link interno .md

    IndiceDocs --> [*]: fechar / navegar para app
    LeituraMarkdown --> [*]: idem

7. Ambiente de desenvolvimento — Reverb (ligação WebSocket)

Estado da ligação Echo ↔ Reverb no browser (conceitual).

stateDiagram-v2
    [*] --> Desligado: Echo não inicializado\nou VITE_REVERB_ENABLED=false

    Desligado --> AConectar: app carrega + Echo ativo
    AConectar --> Ligado: WebSocket OK
    AConectar --> Erro: falha de rede / Reverb parado
    Erro --> AConectar: retry / Reverb disponível
    Ligado --> Desligado: sair da página / tab background

8. Índice de documentação relacionada

Atualizar quando novos estados de domínio (ex.: reserva confirmada, pagamento) forem modelados no código.