KOLOS — Módulo Treinador & Alunos (MVP para divulgação)
Documentação KOLOS
← Índice docs Início

KOLOS — Módulo Treinador & Alunos (MVP para divulgação)

Versão: 1.0
Stack de referência: Laravel 13, Livewire 4, Flux Pro, PostgreSQL, Redis, Spatie Permission, Policies, Pest, Laravel Reverb (broadcast opcional), Sail, Laravel Boost.

Objetivo deste documento

Consolidar o estado atual do produto (estruturas e vistas), alinhar com a matriz ACL já definida (módulo Academy) e definir um plano enxuto em fases para o primeiro ciclo voltado à divulgação (valor percebido, narrativa, demos), sem depender ainda de todo o escopo operacional (presenças, Play Card credenciado, etc.).

1) Inventário — o que já existe no código

1.1 Módulos em src/Modules/

Módulo Conteúdo principal
Identity RoleName, PermissionName, seeds de roles/permissões
Venue Venue, Court, actions de criação
Booking Booking, enums, actions, conflitos
Player Player (perfil atleta, localização, nível em schema)

Não existe ainda módulo Academy / Training no código — apenas a especificação na ACL.

1.2 Papéis (RBAC)

  • Enum: Kolos\Modules\Identity\Domain\Enums\RoleName — inclui Coach (coach).
  • Permissões atuais em PermissionName: somente venue (venue.create, venue.update, …). Nenhuma permissão granular para treinador/turmas foi criada ainda.
  • Contexto multi-ator: App\Support\ActorContext — o treinador aparece no switcher como «🎓 Treinador», mas não há rotas nem itens de navegação específicos para coach.

1.3 Rotas relevantes (routes/web.php)

Área Rotas Middleware
Público /, /login, /cadastro guest onde aplicável
App autenticado /dashboard, /tournaments, POST /logout auth, actor_context
Player /booking, /community, /my-card, /my-location auth + role:player
Venue owner /venues, /venues/{venue}/courts, .../maintenance auth + role:venue_owner|super_admin

Treinador (coach): sem rotas dedicadas.

1.4 Vistas Livewire e papel na experiência «aluno» vs «professor»

Ficheiros em resources/views/livewire/:

Vista Componente Papel / notas
home.blade.php Home Marketing / entrada
auth/login.blade.php Login Autenticação
onboarding/register-player.blade.php RegisterPlayer Onboarding atleta (cadastro + endereço/CEP)
dashboard.blade.php Dashboard Hub genérico; conteúdo majoritariamente placeholder; links úteis sob @role('player') e @canany venue
booking.blade.php Booking Atleta — reservas
tournaments.blade.php Tournaments Acessível a qualquer user autenticado na rota (sem role:player no middleware)
community.blade.php Community Comunidade (UI placeholder)
my-card.blade.php MyCard Card do atleta (stats placeholder — alinhado a «Play Card» futuro)
my-location.blade.php MyLocation Atleta — localização
venue/my-venues.blade.php MyVenues Dono de arena
venue/manage-courts.blade.php ManageCourts Dono de arena
venue/declare-maintenance.blade.php DeclareMaintenance Dono de arena
actor-switcher.blade.php ActorSwitcher Troca de contexto (inclui Treinador se tiver role)

Shell de navegação (resources/views/components/app-shell.blade.php):

  • Itens condicionais claros para player (ex.: «Jogar») e venue_owner (Arenas).
  • Torneios, Comunidade e Meu Card aparecem na sidebar sem condicionar ao ator ativo — útil para demo, mas para o módulo treinador/alunos será preciso rever visibilidade (evitar que um coach veja fluxos de atleta sem querer, ou segmentar por activeActor).

Conclusão: a experiência «aluno» no app corresponde ao role player + onboarding + booking/card/localização. A experiência «professor / treinador» está só na documentação ACL; não há ecrãs Livewire dedicados ao coach.

2) Alinhamento com a ACL existente (Academy)

Trecho já definido em kolos_acl-matriz-atores-e-acesso.md — módulo Academy (Aulas):

  • Dono de arena cria turma; coach gere alunos da turma; coach lança presença e avalia nível (Play Card); player vê evolução.
  • Regra Regra 4 — Certificação técnica: apenas coach com is_credentialed = true altera atributos técnicos no Play Card.

MVP divulgação pode cortar presenças e credenciação técnica, desde que o plano deixe explícito o debt e a ordem em que isso entra.

3) Princípios do MVP «divulgação»

  1. Demonstrar valor em minutos: página(s) que mostram «como o KOLOS liga treinador ↔ alunos ↔ evolução».
  2. Reutilizar stack: Livewire + Flux, ActorContext, Spatie + Policies quando houver mutação de dados.
  3. Não bloquear o roadmap Academy completo: modelos e nomes devem conversar com a ACL (turmas, vínculos, venue).
  4. Testes: cada permissão ou rota nova → Pest (allow/deny).

4) Plano por fases

Fase A — Organização e contrato do módulo (curta)

  • Namespace sugerido: Kolos\Modules\Academy\ em src/Modules/Academy/ (ver README na pasta).
  • Documentar e depois implementar:
    • Permissões novas (exemplos): academy.class.view, academy.class.manage_students, academy.roster.invite — nomes finais a cravar com o mesmo padrão de PermissionName.
    • Atribuição: coach recebe subset; venue_owner mantém capacidades de «criar turma» conforme matriz.

Fase B — MVP visual / divulgação (sem ou com persistência mínima)

Objetivo: screenshots, demo ao vivo, landing interna.

Entrega Descrição Tecnologias
B1 Rota(s) sob role:coach + activeActor === coach: «Minhas turmas» (lista mock ou 1 turma fixa) Livewire, Flux, middleware role, ActorContext
B2 Vista «Alunos da turma» (tabela placeholder com nomes fictícios ou seed) Flux table/cards
B3 Ajuste de navegação: quando ator = coach, sidebar / bottom nav mostram Academy e escondem ou despriorizam fluxos puramente atleta app-shell, @if ($activeActor === $roleCoach)
B4 Dashboard: bloco condicional «Modo treinador» com CTA para turmas dashboard.blade.php + opcional lógica no componente

Persistência opcional nesta fase: se quiserem URL estável para demo, uma migration academy_classes + academy_class_members mínima (UUID, venue_id, coach_user_id, name) já justifica Policies.

Fase C — Dados reais e convites (primeiro ciclo «produto»)

  • Migrations: turmas, membros (FK para users / players), opcional convite por token.
  • Policies: escopo por venue e por coach atribuído.
  • Actions + DTOs: criar turma (owner), adicionar aluno (coach), listar turmas do coach.
  • Aluno: notificação ou fila (opcional) quando integrar mail — Mailpit em dev.

Fase D — Operacional (pós-divulgação)

  • Presenças, histórico, integração com Meu Card / Play Card.
  • Flag is_credentialed no coach (ou tabela coach_profiles) + enforcement na Policy de atualização técnica.
  • Eventos Reverb (ex.: «nova avaliação disponível») — opcional.

5) Uso das tecnologias do projeto

Tecnologia Uso no módulo
Livewire 4 Páginas turmas, lista alunos, formulários
Flux Pro Cards, tabelas, badges, modais
Spatie Permission Permissões Academy; roles coach, venue_owner, player
Policies Turma pertence à arena; coach só edita turmas onde é responsável
PostgreSQL Tabelas normalizadas + índices por venue_id, coach_user_id
Redis Filas (convites, notificações) quando existirem jobs
Pest Feature tests por rota e Policy
Reverb + Echo Fase D ou notificações live
Filament Apenas se houver necessidade de back-office global (não é foco do MVP divulgação)
Sail Comandos padrão vendor/bin/sail artisan test, migrate, etc.

6) Lacunas a decidir (para ficar «perfeito»)

  1. Modelo de vínculo aluno–turma: só User ou obrigar Player existente? (Recomendação: FK para users; perfil desportivo continua em players quando existir.)
  2. Multi-venue: um coach pode lecionar em várias arenas? (Impacta queries e active_venue_id — hoje ligado a venue_owner; pode precisar de «arena ativa» também para coach.)
  3. Convite: link mágico vs e-mail vs código curto.
  4. i18n: copy pública em PT apenas no MVP ou chaves desde já.

Documentar decisões em docs/changes/ quando fechadas.

7) Critérios de pronto (MVP divulgação)

  • Documento lido e pastas Academy referenciadas no código.
  • Rotas coach + permissão academy.class.view + middleware active_actor:coach.
  • Navegação coerente com ActorContext (shell mobile/desktop por $showPlayerShell / $showCoachShell / $showVenueShell).
  • Registro em kolos_registro-de-rotas.md atualizado.
  • Testes Pest: tests/Feature/Academy/AcademyCoachRoutesTest.php.

8) Referências cruzadas