KOLOS — Estratégia: dono da arena, quadras, agenda e ligação às aulas (Academy)

Versão: 1.0
Público: produto, engenharia e operações da arena.
Relaciona com: Onda 3.1 Booking, Academy — horários e vínculos, Mudança court picker + holds.

1. Objetivo

Dar ao dono da arena uma visão e controlo claros sobre:

• Catálogo de quadras (recursos físicos agendáveis).
• Agenda por quadra (o que está ocupado, porquê e por quem).
• Horários “estáticos” das turmas (padrão semanal do professor) e a sua projeção na agenda como ocupação recorrente.

Sem duplicar verdades: o tempo na quadra continua centralizado em bookings (com tipos distintos) e, para turmas, complementado por academy_class_schedule_slots (padrão semanal + court_id) e sincronização de holds.

2. O que sistemas maduros costumam fazer (referência, não prescrição)

Plataformas de clubes e reservas desportivas (ex.: gestão por recurso estilo CourtReserve / Playtomic Business / conceitos de facility management) convergem em padrões úteis:

No KOLOS, Academy já gera ACADEMY_CLASS_HOLD a partir de slots com quadra; o dono precisa de ver isso na mesma agenda que BOOKING (jogador) e MAINTENANCE.

3. Estado atual no código (baseline)

4. Modelo mental: três camadas

1. Catálogo — courts: identidade da quadra, atributos, is_active.
2. Padrão semanal (Academy) — academy_class_schedule_slots (weekday, horas, court_id) + academy_classes.sync_court_holds → gera N semanas de bookings tipo ACADEMY_CLASS_HOLD com academy_class_id.
3. Eventos no tempo — bookings: intervalo [starts_at, ends_at) por court_id, type, opcionalmente academy_class_id.

Regra de ouro: qualquer UI de “agenda do dono” deve ler principalmente de bookings por court_id, enriquecendo labels com joins (turma, utilizador criador). Slots Academy são a fonte do padrão; holds são a materialização para conflito com jogadores e manutenção.

5. Arquitetura de produto: “Hub da arena”

Sugestão de navegação (uma arena selecionada):

Isto alinha o mental model do dono com operações diárias (agenda) e configuração (quadras, turmas).

6. Roadmap recomendado (fases)

Fase A — Agenda do dono (leitura), alto valor

• Rota protegida: venue_owner + policy na arena (ex.: manageCourts ou permissão nova tipo VenueViewSchedule).
• Vista semanal (e opcionalmente “dia”): colunas = quadras da arena, linhas = tempo; células = blocos de bookings.
• Legenda: BOOKING, MAINTENANCE, ACADEMY_CLASS_HOLD (ex.: “Turma: {nome}”).
• Clique no bloco ACADEMY_CLASS_HOLD → link para roster/sessões da turma (rotas já existentes).
• Sem criar reserva nesta fase — só visibilidade e confiança operacional.

Critério de pronto: dono consegue responder “o que está na Quadra 2 na próxima terça?” em < 30 s.

Fase B — Quadras: edição e segurança operacional

• Editar quadra inline ou modal (nome, superfície, cobertura, iluminação, ativo).
• Ao desativar quadra: aviso se existirem bookings futuros ou slots Academy ativos com essa quadra; fluxo guiado (migrar turma, cancelar holds, etc.) — pode ser MVP com mensagem + lista de bloqueios.

Fase C — Agenda com escrita (staff)

• Criar reserva manual (em nome de cliente / telefonema) → BOOKING com created_by_user_id = dono/staff.
• Criar bloqueio rápido → reutilizar manutenção ou tipo dedicado no futuro.
• Cancelamento com política (soft delete / CANCELLED quando existir no enum).

Fase D — Horário de funcionamento e regras

• Janela global da arena (abre/fecha) para esmaecer horas no picker (complementa court_picker_* em config).
• Preços por franja (ligação à Onda 3.2 / finanças, fora do âmbito imediato).

7. Ligação explícita com aulas dos professores

• Professor define slot com court_id + opcionalmente sync_court_holds (UI já orientada no treinador e no dono em Turmas).
• Sistema gera ACADEMY_CLASS_HOLD para as próximas N semanas; conflitos com BOOKING e outros holds são validados nas actions existentes.
• Dono na Agenda deve ver holds como ocupação atribuível à turma, não como “caixa preta”.
• Mudanças: alterar horário/quadra da turma → resync dos holds (já previsto no backend); a UI da Agenda deve refletir após refresh ou push.

Documentar para suporte: “Se desligares reserva recorrente na turma, os holds futuros são removidos; a quadra fica livre para jogadores.”

8. Permissões e ACL (alinhamento)

• Reutilizar VenueManageCourts para quadras e, se necessário, introduzir VenueViewBookings ou VenueManageSchedule para separar “vê agenda” de “cria reserva manual”.
• Manter escopo sempre por venue_id (dono só vê as suas arenas), coerente com matriz ACL.

9. Riscos e mitigação

10. Validação e próximos passos de engenharia

1. Fase A (MVP leitura) — implementada: GET /venues/{venue}/schedule (App\Livewire\Venue\VenueSchedule), policy manageCourts, vista semanal por quadra, legenda por BookingType, link para roster quando ACADEMY_CLASS_HOLD + AcademyClassPolicy::view. Atalhos em «Minhas arenas» e «Quadras».
2. Testes Pest: tests/Feature/Venue/VenueScheduleTest.php + rota em VenueUiAuthorizationTest.
3. Registro de rotas atualizado.
4. Entregue (B parcial + C parcial + horário arena): edição de quadras em ManageCourts; horário diário daily_opens_at / daily_closes_at na mesma página (picker Academy usa estes limites); reserva manual na página VenueSchedule. Seguinte: desativar quadra com aviso de conflitos; dashboard dedicado.

11. Resumo executivo

A melhor estratégia para o KOLOS é tratar a agenda multi-quadra baseada em bookings como centro operacional do dono, com quadras e turmas Academy como fontes de configuração que alimentam essa agenda. Referências de mercado reforçam vista por recurso, tipos visíveis e drill-down — já compatíveis com BookingType e academy_class_id. Entregar primeiro leitura (Fase A) maximiza confiança e reduz suporte; edição de quadras e ações na agenda seguem em ondas claras.