Padrão Admin do Covil

Objetivo

Este documento define como o backoffice deve ser mantido. Outras IAs devem tratar o admin como a fonte principal de atualização do conteúdo público.

Módulos oficiais

• /admin: visão geral e checklist operacional.
• /admin/financeiro: receita, pedidos e potencial de ingressos.
• /admin/eventos: CRUD de eventos e lotes de ingresso.
• /admin/produtos: CRUD do catálogo da loja.
• /admin/galeria: CRUD de itens visuais.
• /admin/diretoria: CRUD da equipe pública.
• /admin/conteudo: edição de blocos site_sections.
• /admin/banners: banners por página (galeria/diretoria/sobre).
• /admin/usuarios: gestão de usuários e aprovação de sócios (só super_admin).
• /admin/cupons: cupons de desconto.
• /admin/planos: planos de associação.
• /admin/parceiros: parceiros e descontos para sócios.
• /admin/pepitas: programa de fidelidade (recompensas, resgates, saldos).

Convenções obrigatórias

• Todas as páginas admin usam admin-page-frame.tsx.
• Campos devem usar admin-field.tsx com components base de input.
• Feedback pós-ação deve usar admin-status-banner.tsx.
• Ações de escrita ficam centralizadas em admin-actions.ts.
• Não duplicar lógica de upload ou parsing de FormData dentro das páginas.

Modelo de publicação

• Conteúdo público usa draft ou published.
• O site público lê apenas registros publicados.
• O admin pode criar rascunhos sem quebrar páginas públicas.

Mídia

• Bucket padrão: site-media.
• Pastas obrigatórias:
  • events/
  • products/
  • gallery/
  • board/
• O upload do arquivo tem precedência sobre a URL manual.
• Se o upload falhar, preservar o valor manual do campo de mídia.

Permissões

• Papéis: super_admin, admin, director, financeiro, marketing, eventos, esportes e member (usuário comum, não entra no admin).
• O acesso é por seção: o mapa papel→seção vive em permissions.ts e é espelhado no banco por can_admin_section(). Só super_admin acessa /admin/usuarios.
• Middleware protege /admin/*; cada página revalida com requireSectionAccess e cada Server Action revalida de novo (guarda fail-closed). A RLS é o anteparo final.
• Detalhes em seguranca.md.

Regras de manutenção

• Se um novo domínio público for criado, o backoffice deve ganhar um módulo correspondente antes de virar conteúdo editável de produção.
• Se um novo bloco institucional surgir, primeiro avaliar se ele cabe em site_sections; se não couber, documentar a nova tabela e atualizar este documento.
• Nunca espalhar upsert e delete por múltiplos arquivos quando o padrão atual já cobre o domínio.

Checklist antes de alterar o admin

• O novo formulário usa o padrão de campo e card existente.
• A ação revalida as rotas públicas impactadas.
• O status de publicação está explícito.
• A mídia segue a pasta correta do bucket.
• O comportamento foi coberto por teste ou smoke manual equivalente.