User Flow — KOLOS

Documento de jornadas de utilizador: objetivos, decisões e passos do ponto de vista de UX. O mapa técnico de rotas e ecrãs está em wireflow.md. Diagramas de atividades (ações e decisões) em activity-diagram.md. Estados e transições em state-transition-diagram.md.

Personas (resumo)

1. Descoberta e entrada (visitante)

Objetivo: entender o KOLOS e decidir entre cadastro, login ou só documentação.

flowchart TD
    A[Landing — Home] --> B{Próximo passo?}
    B -->|Quero experimentar| C[Cadastro jogador]
    B -->|Já tenho conta| D[Login]
    B -->|Sou técnico / curioso| E[Docs índice]
    B -->|Sair| F[Fim visita]
    C --> G[Formulário + CEP opcional]
    G --> H[Conta criada → área autenticada]
    D --> H
    E --> I[Architecture / Changes / .md]

Momentos de fricção a monitorizar

• Erros de validação no cadastro (email, CEP, endereço).
• Redirecionamento pós-login vs primeira visita.

2. Primeira sessão após login

Objetivo: orientar o utilizador no contexto de ator (jogador vs dono de arena) e no dashboard.

flowchart LR
    A[Login bem-sucedido] --> B[Dashboard]
    B --> C{Tem mais de um perfil?}
    C -->|Sim| D[Actor switcher\nmenu utilizador]
    C -->|Não| E[Explora sidebar / bottom nav]
    D --> F[Ator ativo: player ou venue_owner]
    F --> E
    E --> G[Escolhe área: Torneios, Jogar, Arenas…]

Microcopy sugerido (produto)

• Deixar claro qual perfil está ativo antes de ações críticas (reservar, editar arena).

3. Jornada jogador — “Quero jogar hoje”

Objetivo: ir de intenção a ação de jogo (booking / lobby).

flowchart TD
    A[Dashboard] --> B[⚔️ Jogar / Booking]
    B --> C[Ver partidas / vagas — UI atual]
    C --> D{Ação}
    D -->|Entrar num jogo| E[Confirmar / check-in — placeholder]
    D -->|Voltar| A

Extensões naturais

• Torneios para competição estruturada.
• Comunidade para convívio e redes.
• Meu Card para identidade e nível.

4. Jornada jogador — “Onde estou / perto de mim”

Objetivo: usar localização para descoberta de arenas ou contexto de matchmaking.

flowchart LR
    A[Menu utilizador\nou atalho] --> B[📍 Localização atual]
    B --> C[Permissões do browser]
    C --> D[Mapa / lista — conforme UI]
    D --> E[Refinar busca / voltar]

5. Jornada dono de arena — “Gerir o meu espaço”

Objetivo: listar arenas → gerir quadras e manutenção.

flowchart TD
    A[Dashboard] --> B[🏟️ Arenas]
    B --> C[Lista de venues]
    C --> D[Arena específica]
    D --> E[Quadras — ManageCourts]
    D --> F[Manutenção — DeclareMaintenance]
    E --> G[Guardar / voltar]
    F --> G

Pré-requisitos de produto

• Papel venue_owner (ou super_admin) + permissões e ator ativo arena.

6. Torneios e comunidade (jogador)

Objetivo: participação social e competitiva contínua.

flowchart LR
    subgraph social["Social + competição"]
        T[Torneios]
        C[Comunidade]
        K[Meu Card]
    end
    D[Dashboard] --> T
    D --> C
    D --> K

7. Documentação e suporte técnico

Objetivo: aprender arquitetura, histórico de mudanças ou ler .md do repositório.

flowchart TD
    A[Sidebar 📚 Docs] --> B[Índice /docs]
    B --> C[Architecture]
    B --> D[Changes]
    B --> E[Leitura dinâmica wireflow / user-flow / outros .md]

8. Sair e voltar ao site público

Objetivo: terminar sessão ou regressar à Home sem perder contexto mental.

flowchart LR
    A[Menu utilizador] --> B[Sair — POST logout]
    A --> C[Voltar ao início — Home pública]
    B --> D[Home ou login — política atual]

9. Relação com o Wireflow

10. Melhorias de UX alinhadas ao código (backlog sugerido)

1. Sidebar vs permissões: itens visíveis para rotas só player devem esconder-se ou mostrar estado desativado para outros papéis (evitar cliques que levam a 403).
2. Pós-cadastro: mensagem de sucesso explícita antes do dashboard.
3. Actor switcher: tooltip “Estás a agir como: …” na primeira utilização.

Atualizar este ficheiro quando novas jornadas (ex.: pagamentos, notificações) forem definidas.