KOLOS — Matriz de Atores e Acesso (ACL)

Versão: 1.0 (Definitiva)

Tecnologia: Spatie Laravel Permission (RBAC)

Escopo: Definição de papéis (Roles), permissões e regras de escopo (Tenancy/Policies).

🎯 Objetivo

Garantir que cada usuário tenha acesso apenas ao que é pertinente à sua função, mantendo segurança e integridade dos dados em ambiente SaaS multi-tenant.

1) Definição dos Atores (Roles)

O sistema possui 6 níveis hierárquicos de usuários.

Ícone	Ator (Role)	Chave do Sistema	Interface Principal	Descrição
👑	Super Admin	`super_admin`	Painel Filament	Dono da plataforma (SaaS). Acesso irrestrito, gestão global.
🏟️	Venue Owner	`venue_owner`	App Principal (Flux)	Dono da arena (cliente). Gere negócio, quadras, staff, financeiro local.
🏆	Organizer	`organizer`	App Principal (Flux)	Produtor de torneios. Gestão desportiva (chaves, horários, resultados).
🎓	Coach	`coach`	App Principal (Flux)	Professor. Turmas, presenças e avaliações técnicas (Play Card).
🛡️	Staff	`staff`	App Principal (Flux)	Operacional. Portaria (check-in), bar e manutenção rápida.
🏃	Player	`player`	App Principal (Flux)	Usuário final. Reserva quadras, inscreve-se e vê estatísticas.

2) Matriz de Permissões (Capabilities)

A) Módulo Venue (Espaço Físico)

Ação	👑 Admin	🏟️ Owner	🛡️ Staff	🏃 Player
Criar Arena	✅	❌	❌	❌
Editar Configs da Arena	✅	✅	❌	❌
Gerir Quadras (Ativos)	✅	✅	❌	❌
Declarar Manutenção	✅	✅	✅	❌
Ver Relatórios Financeiros	✅	✅	❌	❌

B) Módulo Booking (Agenda)

Ação	🏟️ Owner	🛡️ Staff	🏃 Player
Criar Bloqueio (Torneio)	✅	❌	❌
Cancelar Reservas de Terceiros	✅	✅	❌
Reservar Quadra (Booking)	✅	✅	✅
Fazer Check-in (QR Code)	❌	✅	❌
Ver Disponibilidade	✅	✅	✅

C) Módulo Competition (Torneios)

Ação	🏟️ Owner	🏆 Organizer	🏃 Player
Criar Torneio	✅	✅	❌
Editar Chaves/Tabela	✅	✅	❌
Lançar Resultados (Live Desk)	✅	✅	❌
Inscrever-se	❌	❌	✅
Validar Resultado (Amistoso)	❌	❌	✅

D) Módulo Academy (Aulas)

Ação	🏟️ Owner	🎓 Coach	🏃 Player
Criar Turma	✅	❌	❌
Editar Turma (nome, horário, treinador)	✅	❌	❌
Arquivar / reativar turma	✅	❌	❌
Gerir Alunos da Turma	✅	✅	❌
Lançar Presença	❌	✅	❌
Avaliar Nível (Play Card)	❌	✅	❌
Ver turmas em que está inscrito	❌	❌	✅
Sair da turma (remover própria inscrição)	❌	❌	✅
Ver Própria Evolução	❌	❌	✅

3) Regras de Escopo (Tenancy & Policies)

Apenas ter a permissão “X” não é suficiente: é necessário garantir o isolamento de dados por contexto (arena, autoria, vínculo). Essas regras devem ser implementadas via Policies do Laravel e/ou constraints de query.

🔒 Regra 1: Propriedade de Venue

Ator: venue_owner
Lógica: owner_user_id da Arena deve corresponder ao id do utilizador.
Restrição: um dono jamais pode ver dados financeiros de outra arena.

🎯 Regra 2: Autoria de Evento

Ator: organizer
Lógica: pode editar/apagar apenas torneios onde creator_id é ele mesmo.
Exceção: o venue_owner da arena onde o torneio ocorre tem permissão superior (“supervisão”) para cancelar o evento se necessário.

🛡️ Regra 3: Vínculo de Staff

Ator: staff
Lógica: o staff só pode operar (check-in, venda) dentro do contexto da arena à qual está vinculado (ex.: staff_contracts).

🎓 Regra 4: Certificação Técnica

Ator: coach
Lógica: apenas treinadores com role coach e permissão Spatie academy.coach.credentialed (atribuída pontualmente, ex. por super_admin) podem alterar atributos técnicos oficiais (saque, smash, etc.) no Play Card de um aluno. Método de conveniência: User::isAcademyCredentialedCoach().

📌 Notas de Implementação (quando formos codar)

Roles já existem como enum em Kolos\Modules\Identity\Domain\Enums\RoleName.
Permissões devem ser granularizadas por módulo (ex.: venue.manage, booking.create, booking.cancel_others) e aplicadas com permission/role_or_permission + Policies.
Tenancy deve ser aplicado sempre no nível de query (evitar vazamento) e validado em testes (Pest).

Guardas e painéis

A base é o guard web (padrão). Roles/permissões devem ser criadas com o guard_name correto.
O Filament usa painel separado, mas o usuário pode continuar sendo o mesmo App\Models\User com RBAC; o acesso ao painel deve exigir role super_admin.