Diagrama de Atividades — KOLOS

Visão UML (atividades): ações, decisões, bifurcações e conclusões. Complementa wireflow.md (rotas) e user-flow.md (jornadas). Estados e transições: state-transition-diagram.md.

Nota: os diagramas usam sintaxe Mermaid (flowchart). Em ferramentas UML puras, podes redesenhar a partir destes nós e decisões.

1. Atividade: Autenticação (login)

Participante: utilizador registado. Objetivo: obter sessão e entrar na área autenticada.

flowchart TD
    Start([Início]) --> A[Abrir /login]
    A --> B[Preencher email e senha]
    B --> C[Submeter formulário]
    C --> D{Credenciais válidas?}
    D -->|Não| E[Mostrar erros de validação]
    E --> B
    D -->|Sim| F[Registar sessão]
    F --> G[Resolver actor_context]
    G --> H[Redirecionar para /dashboard]
    H --> End([Fim — sessão ativa])

2. Atividade: Cadastro de jogador

Participante: visitante. Objetivo: criar conta com dados pessoais e endereço (CEP opcional via API).

flowchart TD
    Start([Início]) --> A[Abrir /cadastro]
    A --> B[Preencher identidade e senha]
    B --> C[Preencher CEP — opcional]
    C --> D{Consultar CEP?}
    D -->|Sim| E[GET /api/cep/{cep}]
    E --> F{CEP encontrado?}
    F -->|Sim| G[Preencher rua, bairro, cidade, UF]
    F -->|Não| H[Manter campos manuais / mensagem]
    D -->|Não| I[Validar formulário]
    G --> I
    H --> I
    I --> J{Dados válidos?}
    J -->|Não| K[Exibir erros]
    K --> B
    J -->|Sim| L[Persistir utilizador + perfil]
    L --> M[Autenticar ou redirecionar login]
    M --> End([Fim — conta criada])

3. Atividade: Seleção de contexto de ator

Participante: utilizador com mais de um perfil. Objetivo: definir ator ativo (player vs venue_owner).

flowchart TD
    Start([Início]) --> A[Abrir menu do utilizador]
    A --> B{Existem vários atores?}
    B -->|Não| C[Usar ator por defeito]
    B -->|Sim| D[Mostrar Actor Switcher]
    D --> E[Utilizador escolhe ator]
    E --> F[Persistir contexto de ator]
    C --> G[Atualizar navegação visível]
    F --> G
    G --> End([Fim — UI alinhada ao ator])

4. Atividade: Jogador — aceder a “Jogar” (booking)

Pré-condição: sessão autenticada, role:player, ator player. Objetivo: consultar e interagir com o fluxo de jogos.

flowchart TD
    Start([Início]) --> A{Navegação permitida\nplayer + ator player?}
    A -->|Não| X([Fim — 403 ou item oculto])
    A -->|Sim| B[Carregar /booking]
    B --> C[Exibir listas / placeholders UI]
    C --> D{Ação do utilizador}
    D -->|Explorar| C
    D -->|Ir a torneios| E[/tournaments/]
    D -->|Sair| End([Fim])

5. Atividade: Dono de arena — gerir quadras

Pré-condição: role:venue_owner|super_admin, ator venue_owner, permissões de arena.

flowchart TD
    Start([Início]) --> A{Acesso a Arenas?}
    A -->|Não| X([Fim — 403])
    A -->|Sim| B[Carregar /venues]
    B --> C[Listar arenas]
    C --> D[Selecionar arena]
    D --> E[Abrir /venues/{id}/courts]
    E --> F[Listar / editar quadras]
    F --> G{Guardar alterações?}
    G -->|Sim| H[Persistir + feedback]
    H --> F
    G -->|Voltar| C

6. Atividade: Declarar manutenção (arena)

flowchart TD
    Start([Início]) --> A[Em /venues — selecionar arena]
    A --> B[Abrir /venues/{id}/maintenance]
    B --> C[Preencher dados de manutenção]
    C --> D[Submeter]
    D --> E{Sucesso?}
    E -->|Não| F[Mostrar erros]
    F --> C
    E -->|Sim| G[Confirmar registo]
    G --> End([Fim])

7. Atividade: Consultar documentação

Participante: qualquer visitante autenticado ou não (rotas públicas).

flowchart TD
    Start([Início]) --> A[Abrir /docs]
    A --> B{Destino?}
    B -->|Arquitetura| C[/docs/architecture/]
    B -->|Mudanças| D[/docs/changes/]
    B -->|Ficheiro .md| E[/docs/read/{path}/]
    C --> F[Renderizar Markdown]
    D --> F
    E --> F
    F --> G[Seguir links internos — se existirem]
    G --> End([Fim])

8. Atividade: Terminar sessão (logout)

flowchart TD
    Start([Início]) --> A[Menu do utilizador]
    A --> B[Clicar Sair]
    B --> C[POST /logout + CSRF]
    C --> D[Invalidar sessão]
    D --> E[Redirecionar — home ou login]
    E --> End([Fim — sessão terminada])

9. Atividade paralela (dev): assets e tempo real

Fluxo conceitual do ambiente de desenvolvimento (não é uma rota única).

flowchart LR
    subgraph dev["Ambiente dev"]
        V[Vite — HMR]
        P[PHP / Sail — app]
        R[Reverb — WS :8080]
    end
    U[Browser] --> V
    U --> P
    U --> R

10. Índice de documentação relacionada

Atualizar quando novas ações (pagamentos, notificações push, etc.) forem implementadas.