Pular para o conteúdo principal

ADR 0002 — Uso do Laravel Backpack para painel administrativo

Introdução ao documento​

Este ADR registra a decisão de utilizar o Laravel Backpack como solução de painel administrativo.

Versionamento​

  • Versão do documento: 1.0.0
  • Última atualização: 2026-03-04
  • Responsável: Time Dhedalos

Referencial teórico​

Contexto​

  • O projeto precisa de uma interface administrativa para gerenciar submissões, usuários, roles, permissions, chaves Novu e arquivos modelo de atividades.
  • A equipe busca produtividade e padronização, evitando construir painéis admin do zero.
  • Evidência: composer.json — backpack/crud ^6.8, backpack/pro ^2.2, backpack/permissionmanager ^7.2

Decisão​

  1. Adotar Laravel Backpack 6.8 (com Backpack Pro) como painel admin CRUD.
  2. Utilizar Backpack Permission Manager para gerenciamento visual de roles e permissions (integrado com Spatie Permission).
  3. Implementar CRUDs para: DeliverableSubmission, User, Role, Permission, NovuKey, ActivityTemplateFile.
  4. Integrar Swagger UI e Log Viewer como páginas embarcadas no painel admin.

Consequências​

Positivas​

  • Geração rápida de interfaces CRUD com validação, filtros, upload de arquivos e paginação.
  • Integração nativa com Spatie Permission para controle de acesso granular.
  • Redução significativa de tempo de desenvolvimento para funcionalidades admin.
  • Padrão visual consistente e responsivo.

Negativas​

  • Dependência de pacote proprietário (Backpack Pro requer licença — auth.json).
  • Customização avançada de UI limitada pelo framework do Backpack.
  • Testes de CI precisam de composer.ci.json alternativo para evitar pacotes privados.
    • Evidência: .github/workflows/test.yaml — usa composer.ci.json

Alternativas consideradas​

  • Filament PHP — alternativa moderna, mas exigiria reescrita de toda a camada admin.
  • Nova (Laravel) — excelente, mas custo de licença e lock-in mais forte.
  • Admin customizado — flexibilidade total, mas custo de desenvolvimento e manutenção elevado.

Pendências​

  • ⚠️ PENDÊNCIA: Documentar processo de renovação/gestão da licença Backpack Pro.