Sistema de Gestão de Carregamento Documentação Técnica – Agosto/2026

📋 Visão Geral

Este projeto consiste em um sistema web completo para gestão e visualização dos registros de carregamento da empresa Brado, baseado em dados reais do mês de Agosto de 2026. O sistema foi desenvolvido sob demanda para oferecer um dashboard administrativo interativo, com filtros dinâmicos, indicadores de performance (KPIs), gráficos de barras e pizza, e uma tabela de registros com funcionalidades de CRUD (criar, ler, atualizar, excluir). Além disso, permite a geração de relatórios em PDF e PNG com o resumo do período selecionado.

O projeto foi executado seguindo uma metodologia ágil baseada em sprints, com entregas incrementais e revisão constante do cliente. O resultado final é uma aplicação responsiva, minimalista e de alto padrão profissional, alinhada à identidade visual da marca Brado.

⚙️ Stack Tecnológico

A escolha das ferramentas foi orientada por produtividade, escalabilidade e facilidade de manutenção. Abaixo estão as principais tecnologias utilizadas:

🏗️ Arquitetura do Sistema

O sistema segue uma arquitetura Full‑Stack baseada em Next.js com separação clara entre frontend e backend através de API Routes. O acesso ao banco de dados é realizado via Prisma ORM, que oferece segurança tipada e facilidade de migração. O frontend é composto por componentes reutilizáveis, organizados em uma estrutura de pastas modular.

Estrutura de Pastas

sistema-brado-2026/
├── app/                    # Next.js App Router
│   ├── api/                # Endpoints da API
│   │   ├── registros/      # CRUD de carregamentos
│   │   ├── stats/          # Estatísticas para KPIs e gráficos
│   │   ├── filtros/        # Opções dinâmicas para os filtros
│   │   └── relatorio/      # Dados completos para relatórios
│   ├── layout.tsx          # Layout global
│   └── page.tsx            # Página principal (dashboard)
├── components/             # Componentes reutilizáveis
│   ├── Header.tsx
│   ├── Filters.tsx
│   ├── KpiCards.tsx
│   ├── Charts.tsx
│   ├── DataTable.tsx
│   ├── CrudModal.tsx
│   └── RelatorioPreview.tsx
├── lib/                    # Utilitários
│   └── prisma.ts           # Singleton do PrismaClient
├── prisma/                 # Configuração do Prisma
│   ├── schema.prisma       # Definição do modelo de dados
│   ├── migrations/         # Histórico de migrações
│   └── seed.ts             # Script para popular o banco
├── .env                    # Variáveis de ambiente (local)
├── .env.local              # (gerado pelo Vercel CLI)
├── .env.development.local  # (gerado pelo Vercel CLI)
└── package.json            # Dependências e scripts
            

🗄️ Modelo de Dados

O esquema do banco de dados foi definido no arquivo schema.prisma e contempla as 10 colunas da planilha original, além de três campos adicionais (linha, trem, prefixo_chegada) que foram solicitados posteriormente para os filtros.

Schema Prisma

model Carregamento {
  id                String   @id @default(cuid())
  n_veiculo         Int      @map("n_veiculo")
  data_carregamento DateTime @map("data_carregamento")
  nome_motorista    String   @map("nome_motorista")
  destino           String
  conjunto          String
  placa_cavalo      String   @map("placa_cavalo")
  placa_carreta     String   @map("placa_carreta")
  container         String
  data_entrega      DateTime @map("data_entrega")
  dias_carregado    Int      @map("dias_carregado")
  linha             String
  trem              String
  prefixo_chegada   String   @map("prefixo_chegada")

  @@map("carregamentos")
}
            

O banco de dados utilizado em desenvolvimento foi SQLite (arquivo dev.db), e em produção foi migrado para Vercel Postgres (PostgreSQL), mantendo a compatibilidade através do Prisma.

🚀 Desenvolvimento – Sprints

O projeto foi desenvolvido em 4 sprints, cada um com entregas funcionais e validadas pelo cliente. Abaixo, o detalhamento de cada etapa.

✨ Funcionalidades Entregues

• Dashboard Interativo: Exibe KPIs, gráficos e tabela com dados filtrados em tempo real.
• Filtros Avançados: Mês, Ano, Linha, Prefixo, Trem e intervalo de datas (De/Até).
• KPIs Dinâmicos: Total de Carregamentos, Veículos LS, Veículos RODOTREM, Média de Dias Antecipados.
• Gráficos: Barras agrupadas, barras empilhadas com percentuais, pizza com média por conjunto e linha de evolução.
• Tabela Interativa: 10 colunas, ordenação, paginação, edição e exclusão de registros.
• CRUD Completo: Adicionar, editar e excluir registros (protegido por senha mestra).
• Relatórios: Download de relatórios em PNG e PDF com todo o conteúdo do período selecionado.
• Design Responsivo: Adapta-se a desktops, tablets e smartphones.
• Autenticação: Controle de acesso para operações de escrita via senha mestra.
• Pop‑up de Detalhes: Ao clicar em um KPI, um diálogo exibe explicações detalhadas sobre a métrica.

🌐 Implantação (Deploy)

O sistema foi implantado na Vercel utilizando o plano gratuito. O processo de deploy é automatizado através da integração com o GitHub: cada push para a branch main dispara um novo build e deployment.

Etapas do Deploy

1. Preparação: O repositório foi enviado para o GitHub com o código completo.
2. Criação do projeto na Vercel: Utilizou-se o CLI da Vercel (vercel link) para vincular o repositório e criar o projeto sistema-brado-2026.
3. Configuração da base de dados: Foi criada uma instância Prisma Postgres na Vercel, que forneceu a DATABASE_URL.
4. Variáveis de ambiente: As variáveis DATABASE_URL e ADMIN_SECRET foram adicionadas no painel da Vercel (Settings → Environment Variables).
5. Deploy: Executou-se vercel deploy --prod para o primeiro deploy.
6. Migração e Seed: Localmente, com a DATABASE_URL apontando para o banco da Vercel, foram executados npx prisma migrate dev e npx tsx prisma/seed.ts para criar a tabela e popular os dados.
7. Redeploy: Após a migração, um novo deploy foi realizado para garantir que a aplicação utilizasse a nova base de dados.

🔄 Como Reproduzir o Projeto

Para replicar este sistema em seu próprio ambiente, siga os passos abaixo. Este guia assume que você tem Node.js (versão 18 ou superior) e Git instalados.

1. Clonar o repositório

git clone https://github.com/FrankE2021/full_brado.git
cd full_brado
            

2. Instalar as dependências

npm install
            

3. Configurar o ambiente local

Crie um arquivo .env na raiz com o seguinte conteúdo:

DATABASE_URL="file:./dev.db"
ADMIN_SECRET="sua_senha_mestra"
            

4. Inicializar o banco de dados (SQLite)

npx prisma migrate dev --name init_carregamentos
            

5. Executar o seed (popula com dados de exemplo)

npx tsx prisma/seed.ts
            

Nota: Para usar o seed com os dados atualizados, certifique-se de que o arquivo prisma/seed.ts contenha os 67 registros.

6. Executar o servidor de desenvolvimento

npm run dev
            

Acesse http://localhost:3000 para visualizar o dashboard.

7. (Opcional) Deploy na Vercel

• Instale o Vercel CLI: npm i -g vercel
• Execute vercel link para vincular o projeto.
• Crie uma base de dados Prisma Postgres no painel da Vercel.
• Adicione as variáveis de ambiente (DATABASE_URL e ADMIN_SECRET) no projeto.
• Execute vercel deploy --prod.
• Após o deploy, execute as migrações e o seed apontando para a base de dados remota (altere o .env local com a DATABASE_URL da Vercel e execute npx prisma migrate dev e npx tsx prisma/seed.ts).

8. Estrutura adicional

Certifique-se de que os componentes da UI (Header, Filters, KpiCards, Charts, DataTable, CrudModal, RelatorioPreview) estejam presentes na pasta components/, e que as APIs estejam em app/api/.

✅ Considerações Finais

O sistema entregue atende a todos os requisitos iniciais: visualização, filtragem, CRUD, geração de relatórios e design responsivo. A combinação de Next.js, Prisma, PostgreSQL e um frontend moderno com Shadcn UI e Recharts resultou em uma ferramenta robusta, escalável e de fácil manutenção.

A documentação aqui presente serve como guia para futuras manutenções ou para a replicação do sistema em outros ambientes. Todo o código-fonte está disponível no GitHub e o sistema está em produção na Vercel.