Wireflow — KOLOS

Mapa de ecrãs, rotas e fluxos derivado de routes/web.php, app-shell e middlewares (auth, actor_context, role:*).

Jornadas de utilizador (UX): ver user-flow.md.

Diagramas de atividades (UML): ver activity-diagram.md.

Transição de estados (UML): ver state-transition-diagram.md.

Legenda

1. Visão geral (entrada no produto)

flowchart TB
    subgraph public["🔓 Público"]
        HOME["/ — Home\nLivewire: Home"]
        LOGIN["/login — Entrar"]
        CAD["/cadastro — Cadastro jogador"]
        DOCS["/docs — Índice docs"]
        DOCS_MD["/docs/architecture, /docs/changes\n/docs/read/{path}"]
        API_CEP["GET /api/cep/{cep}"]
    end

    subgraph auth["🔐 Autenticado + actor_context"]
        DASH["/dashboard — Dashboard"]
        TOUR["/tournaments — Torneios"]
        LOGOUT["POST /logout"]
    end

    subgraph player["👤 role: player"]
        BOOK["/booking — Jogar"]
        COMM["/community — Comunidade"]
        CARD["/my-card — Meu Card"]
        LOC["/my-location — Localização"]
    end

    subgraph venue["🏟️ role: venue_owner | super_admin"]
        VEN["/venues — Arenas"]
        COURTS["/venues/{venue}/courts — Quadras"]
        MAINT["/venues/{venue}/maintenance — Manutenção"]
    end

    HOME --> LOGIN
    HOME --> CAD
    LOGIN --> DASH
    CAD --> DASH
    DASH --> TOUR
    DASH --> BOOK
    DASH --> COMM
    DASH --> CARD
    DASH --> LOC
    DASH --> VEN
    VEN --> COURTS
    VEN --> MAINT
    DASH --> LOGOUT
    HOME --> DOCS
    DOCS --> DOCS_MD

2. Fluxo de autenticação e onboarding

flowchart LR
    A["Visitante"] --> B["Home /"]
    B --> C{"Tem conta?"}
    C -->|Não| D["/cadastro\nRegisterPlayer"]
    C -->|Sim| E["/login\nLogin"]
    D --> F["Conta criada → login implícito / sessão"]
    E --> G["/dashboard"]
    F --> G
    G --> H["Actor context\n(player vs venue_owner)"]

3. Shell da app (área autenticada)

Layout principal: <x-app-shell> — sidebar (desktop), header, conteúdo, navbar inferior (mobile).

flowchart TB
    subgraph shell["App shell (autenticado)"]
        SB["Sidebar\nKOLOS → Dashboard"]
        HD["Header\ntítulo + subtítulo"]
        MN["Nav móvel\n🏠 ⚔️ 🏆 👥 🪪 (+ 🏟️ / 📚 conforme papel)"]
        PROF["Dropdown utilizador\nperfil, actor switcher, sair"]
    end

    SB --> DASH
    SB --> TOUR
    SB --> DOCS_L["Docs"]
    PROF --> HOME_PUB["Voltar ao início /\n(home pública)"]

Nota: Na sidebar, Comunidade, Meu Card e Torneios aparecem para utilizadores autenticados; o acesso HTTP a /community e /my-card está limitado a role:player em web.php. Quem não for player pode ver o item mas receber 403 ao abrir a rota — alinhar UI com políticas se necessário.

4. Fluxo por papel (ator ativo)

O Actor Switcher (livewire:actor-switcher) altera o contexto player ↔ venue_owner quando aplicável.

stateDiagram-v2
    [*] --> Dashboard: login ok
    Dashboard --> PlayerMode: ator = player
    Dashboard --> VenueMode: ator = venue_owner

    state PlayerMode {
        [*] --> Booking
        [*] --> Tournaments
        [*] --> Community
        [*] --> MyCard
        [*] --> MyLocation
    }

    state VenueMode {
        [*] --> MyVenues
        MyVenues --> ManageCourts: venue selecionado
        MyVenues --> DeclareMaintenance: venue selecionado
    }

5. Mapa de rotas (referência rápida)

6. APIs auxiliares

• GET /api/cep/{cep} — lookup de CEP (ex.: formulário de cadastro).

Gerado a partir do código; atualizar este ficheiro quando novas rotas ou fluxos forem adicionados.