| name | hidrocar-erp |
| description | Skill especializada para desenvolvimento, debug e manutenção do ERP Hidrocar Veículos (Dailabs). Use esta skill SEMPRE que o usuário mencionar: bug no financeiro, pedido de compra, pedido de venda, fluxo de caixa, comissões, estoque de veículos, patrimônio por sócio, espelho financeiro, caixa PDV, contas a pagar/receber, despesas, relatórios do sistema, ou qualquer módulo do ERP Hidrocar. Também use quando o usuário falar "quebrou o financeiro", "tá errado o saldo", "bug na venda", "não bate o patrimônio", "corretor errado", "comissão incorreta", ou qualquer correção de lógica de negócio do sistema de gestão de veículos.
|
Skill: Hidrocar ERP — Debug & Desenvolvimento
Visão Geral do Sistema
Produto: ERP para revenda de veículos
Stack: Next.js / React, Vercel (deploy), Supabase (banco de dados PostgreSQL)
Empresa cliente: Hidrocar Veículos
Desenvolvedor: Dailabs — Creative AI & Softwares
URL: hidrocar-veiculos-erp.vercel.app
Arquitetura de Módulos
ERP HIDROCAR
├── Início (Dashboard KPI)
├── Parceiros (Clientes, Fornecedores, Corretores)
├── Cadastros (Marcas, Modelos, Configurações)
├── Estoque (Inventário de veículos no pátio)
├── Pedidos Compra (Aquisição de veículos)
├── Pedidos Venda (Saída de veículos)
├── Caixa PDV → Fluxo de Caixa & Patrimônio
├── Financeiro (Dashboard financeiro completo)
├── Performance (Visão gerencial do mês)
├── Relatórios (Central de extração)
├── Editor Site
└── Ajustes
❤️ O Coração do Sistema: Fluxo Financeiro
REGRA DE OURO: Qualquer alteração no financeiro pode impactar múltiplos módulos em cascata. Sempre rastrear o fluxo completo antes de corrigir.
Fluxo Principal de Dados
PEDIDO DE COMPRA
↓ efetivado
ESTOQUE (veículo entra no pátio)
↓ custo registrado por sócio
PATRIMÔNIO POR SÓCIO (exposição de capital)
↓ venda realizada
PEDIDO DE VENDA
↓ gera
CONTAS A RECEBER + LUCRO BRUTO
↓ baixa financeira
FINANCEIRO (entradas/saídas/saldo)
↓ consolidado em
CAIXA PDV / FLUXO DE CAIXA & PATRIMÔNIO
↓ reflete em
PERFORMANCE + RELATÓRIOS
Espelhos Críticos (onde costumam aparecer bugs)
| Origem | Espelha em | Campo crítico |
|---|
| Pedido Compra | Estoque | custo_total, serviços adicionados |
| Pedido Compra | Financeiro (saídas) | valor pago, contas a pagar |
| Pedido Venda | Financeiro (entradas) | valor recebido, contas a receber |
| Pedido Venda | Lucro Bruto | receita - custo - serviços |
| Ambos | Patrimônio por Sócio | divisão % entre sócios |
| Ambos | Performance | KPIs do mês atual |
Sócios e Participação
O sistema possui 3 sócios com participação igualitária:
- Klecio Guimaraes — 33.3% do estoque/lucro
- Newton Porto Neto — 33.3% do estoque/lucro
- Yuri Porto — 33.3% do estoque/lucro
⚠️ Bugs comuns: Participação não sendo recalculada após nova compra/venda; sócio aparecer com % errado quando veículo tem múltiplos ativos.
Módulos em Detalhe
📦 Estoque
- Veículos com status:
DISPONÍVEL, EM PREPARAÇÃO, VENDIDO
- Cada veículo tem: custo de compra + serviços agregados = custo total do ativo
- Agrupamentos: por MARCA, TIPO, lista geral
- Participação por sócio é calculada sobre o total investido no estoque
🛒 Pedidos de Compra — Dossiê de Aquisição
- Status:
RASCUNHO → EFETIVADO (botão "CONCLUÍDO")
- Campos: Fornecedor (Parceiro), Intermediação (corretor), data contrato
- Composição Societária do Investimento: mostra os 3 sócios com Aporte individual (valor_total / 3), Lucro Est. e Margem Ref.
- Composição do Pagamento (seção crítica):
Custo do Veículo — valor baseTotal Lançado (Negociado) — valor acordadoTotal Pago (Real) — soma das baixas efetivasQuitação Confirmada — valor confirmado manualmente- Barra de progresso:
Cobertura do Contrato (Programado) e Quitação Financeira Real
- Tabela de parcelas: Data | Vencimento | Forma/Condição (PIX, PRAZO, etc.) | Conta (ex: CAIXA) | Valor
- ⭐ Espelho Financeiro (Títulos & Baixas): painel em tempo real do Contas a Pagar
- Mostra o título gerado: ex. "PAGAMENTO DE COMPRA - PEDIDO #60"
- Exibe
Valor Total vs Valor Pago
Histórico de Baixas: data, conta, valor de cada pagamento realizado
- Ao efetivar: veículo entra no estoque + gera título em Contas a Pagar no Financeiro
💰 Pedidos de Venda — Detalhe
- Status:
RASCUNHO → FATURADA → VENDA CONCLUÍDA
- Campos: Destino/Comprador, Responsável Venda (executivo de negócios)
- Divisão de Capital e Retorno por Investidor (3 sócios):
Capital Investido por sócio (custo proporcional do veículo)Lucro Proporcional (Bolso) por sócioMargem Real % por sócio- Cota de participação: 33.33% cada
- Composição do Recebimento (seção crítica):
Data da Venda, Forma Principal (PIX, PRAZO, etc.), Valor Total NegociadoProgresso da Quitação: barra mostrando total recebido vs total negociado- Tabela de parcelas: Data | Vencimento | Condição de Recebimento | Conta de Destino | Valor
- Parcelas podem ter: vencimento imediato (PIX) + vencimento futuro (PRAZO, "Não Vinculada")
- KPIs gerados: Faturamento Bruto (VGV), Custo Total dos Ativos, Lucro Bruto, Margem %
- Participação por sócio: divisão real do lucro bruto no período
- Ao concluir: gera título em Contas a Receber no Financeiro
🏦 Financeiro — Abas Detalhadas
Dashboard — Saldo disponível, Compra de Veículos, Despesas Fixas, Despesas Variáveis, Outras Receitas, Retiradas. Seções: Disponibilidade por Carteira, Atenção Prioritária (contas atrasadas/vencendo hoje).
Contas a Pagar — Agenda de Compromissos Financeiros e Liquidação de Pedidos
- KPIs: Total a Liquidar, Vencendo Hoje, Total em Atraso
- Filtros: Período de Vencimento, Plano de Contas, Situação
- Cards: status (PENDENTE/PAGO), Vencimento, Veículo vinculado, Favorecido/Descrição, Ref. Pedido (ex: "Ref: PED #57"), Valor do Título
- ⚠️ Origem: gerado automaticamente ao efetivar Pedido de Compra
Contas a Receber — Gestão de Fluxo de Caixa e Entradas de Faturamento
- KPIs: Total a Receber, Recebendo Hoje, Total em Atraso
- Filtros: Período de Vencimento, Categoria
- Cards: status (PENDENTE), Vencimento, Veículo vinculado, Cliente
- ⚠️ Origem: gerado automaticamente ao concluir Pedido de Venda (cada parcela = 1 título)
Despesas Variáveis — Gestão de Gastos Operacionais e Eventuais
- KPIs: Total a Pagar, Vencendo Hoje, Total em Atraso
- Filtros: Categoria, Agrupar por (Lista/Mês/Categoria)
- Ação: "+ Lançar Despesa"
Despesas Fixas — Custos Recorrentes e Manutenção Estrutural
- KPIs: Total a Pagar, Vencendo Hoje, Total em Atraso
- Filtros: Plano de Contas, Organizar por (Lista/Mês/Categoria)
- Ação: "+ Lançar Custo Fixo"
Outros Créditos — Aportes, Rendimentos e Entradas Extraordinárias
- KPIs: Total Creditado, Previsto (em aberto), Atrasados
- ⚠️ Importante: veículos com parcelas de venda a prazo "Não Vinculada" podem aparecer aqui como PENDENTE — ex: Comander, Cronos, Ford Ka, Onix com vencimento futuro e "Conta a Definir"
- Ação: "+ Lançar Crédito"
Retiradas — Pro-labore dos sócios
Transferências entre Contas — Movimentações internas entre carteiras bancárias
Histórico Geral — Todos os lançamentos consolidados
📊 Caixa PDV — Fluxo de Caixa & Patrimônio
Consolidação máxima do sistema:
- Patrimônio Líquido = Saldo + Ativos (Estoque) + Contas a Receber - Contas a Pagar
- Vendas (valor recebido) = Outras Receitas no financeiro
- Exposição & Retorno por Sócio: capital no pátio vs lucro realizado no mês
- Saldos Individuais por conta bancária
📈 Performance
- Visão do mês atual vs outros meses
- KPIs: Vendas, Compras, Lucro Bruto, Ticket Médio, Entradas, Saídas, A Receber, A Pagar
- Saldo Total Contas, Despesas Veículos, Retiradas Sócios
- Detalhamento: Vendas Realizadas, Compras Realizadas
📋 Relatórios
Categorias:
- Comercial & Vendas: Vendas Detalhadas, Relatório de Comissões
- Operacional & Estoque: Posição de Estoque, Gastos com Serviços
⭐ Espelho Financeiro — Como Funciona
Este é o mecanismo central que causa a maioria dos bugs. Entender este fluxo é essencial.
Pedido de Compra → Financeiro
PEDIDO COMPRA efetivado
↓ cria automaticamente
TÍTULO em Contas a Pagar
- Descrição: "PAGAMENTO DE COMPRA - PEDIDO #XX"
- Valor: Total Lançado (Negociado)
- Vencimento: conforme parcelas da Composição do Pagamento
- Status inicial: PENDENTE
↓ ao baixar o título
HISTÓRICO DE BAIXAS no pedido
- Data da baixa, conta bancária usada, valor
- Atualiza "Total Pago (Real)" e "Quitação Confirmada"
- Saldo da conta bancária é debitado
Pedido de Venda → Financeiro
PEDIDO VENDA concluído (Venda Concluída)
↓ cada parcela da Composição do Recebimento cria
TÍTULO em Contas a Receber (se conta vinculada)
OU
TÍTULO em Outros Créditos (se "Não Vinculada" / conta a definir)
- Valor: valor da parcela
- Vencimento: data de vencimento da parcela
- Status inicial: PENDENTE
↓ ao receber/baixar o título
Saldo da conta bancária é creditado
Progresso da Quitação é atualizado no pedido
Problemas Críticos do Espelho
| Sintoma | Causa provável | Onde verificar |
|---|
| Contas a Pagar zerada mas compras foram feitas | Títulos não gerados ao efetivar pedido | Trigger de criação de título no POST do pedido |
| Saldo conta não bate | Baixa registrada sem debitar/creditar conta | Função de baixa financeira |
| "Total Pago" diverge do Histórico de Baixas | Cálculo usando campo errado | Soma do histórico vs campo cached |
| Parcela PRAZO não aparece em Contas a Receber | Conta "Não Vinculada" indo para Outros Créditos | Lógica de roteamento por tipo de parcela |
| Quitação 100% mas Contas a Receber ainda mostra pendente | Título não sendo marcado como PAGO após baixa total | Trigger de atualização de status |
| Valor errado no Contas a Pagar | Usando custo do veículo em vez do valor negociado | Campo fonte do título gerado |
Antes de qualquer correção:
- Identificar o ponto de origem do dado incorreto (qual tabela/função cria o valor?)
- Mapear todos os consumidores desse dado (quais componentes/páginas o leem?)
- Verificar se há cache ou estado local que pode estar desatualizado
- Testar isoladamente antes de integrar
Checklist de impacto por módulo:
Alterou lógica de Pedido Compra?
✓ Verificar Estoque (custo do ativo)
✓ Verificar Financeiro (saídas/contas a pagar)
✓ Verificar Patrimônio por Sócio
✓ Verificar Performance (compras do mês)
✓ Verificar Caixa PDV (patrimônio líquido)
Alterou lógica de Pedido Venda?
✓ Verificar Financeiro (entradas/contas a receber)
✓ Verificar Lucro Bruto e Margem
✓ Verificar Participação por Sócio
✓ Verificar Performance (vendas do mês)
✓ Verificar Relatório de Comissões
✓ Verificar Caixa PDV (vendas realizadas)
Alterou lógica de Saldo/Contas?
✓ Verificar Dashboard Financeiro
✓ Verificar Caixa PDV (saldo disponível)
✓ Verificar Performance (entradas/saídas)
✓ Verificar Atenção Prioritária (vencidos/hoje)
Armadilhas conhecidas
- Dupla contabilização: Um pagamento pode ser registrado tanto como "baixa de conta a pagar" quanto como "saída direta" — verificar se existe deduplicação
- Status de pedido: Rascunhos NÃO devem entrar nos cálculos financeiros — sempre filtrar por status =
EFETIVADO / CONCLUÍDO / FATURADA
- Data de referência: Verificar se filtros de mês usam data de criação vs data de vencimento vs data de baixa
- Participação societária: Capital investido por sócio =
valor_total_ativo / 3 — recalcular após qualquer CRUD
- Serviços adicionados: Custo do ativo = compra + soma de serviços — nunca usar só o valor de compra
- Corretor vs Responsável Venda: Corretor = intermediário externo (campo "Intermediação"); Responsável Venda = executivo/funcionário interno
- Parcelas "Não Vinculada": Venda a prazo sem conta destino definida vai para "Outros Créditos" com status PENDENTE — não some em Contas a Receber padrão
- Quitação Confirmada ≠ Total Pago: São campos distintos — um é confirmação manual, outro é soma do histórico de baixas
- Espelho não atualiza: Quando o título é criado mas o pedido não reflete a baixa, verificar se o update é bidirecional (título → pedido)
- "Outros Créditos" inflado: Veículos com parcelas futuras aparecem como créditos previstos — não devem ser somados ao saldo disponível atual
Padrão de Resposta para Bugs
Ao receber um relato de bug, sempre:
- Perguntar: Em qual módulo aparece o sintoma? Qual o valor esperado vs o que está aparecendo?
- Rastrear: Seguir o fluxo financeiro de ponta a ponta para o caso
- Propor: A correção mais cirúrgica possível (menor surface area de mudança)
- Alertar: Quais outros pontos podem ser afetados pela correção
- Sugerir teste: Como validar que a correção funcionou sem quebrar o restante
Contexto Técnico
- Framework: Next.js (App Router ou Pages — confirmar com o dev)
- Deploy: Vercel (produção em
hidrocar-veiculos-erp.vercel.app)
- Banco: Supabase (PostgreSQL) — consultas via Supabase client
- UI: Componentes customizados com tema dark/light, ícones Lucide
- Autenticação: Sistema de acesso com roles (ADMIN, GESTOR, etc.)
- Moeda: BRL (Real Brasileiro), formato
R$ X.XXX,XX
💡 Quando o usuário enviar código, sempre verificar se as queries ao banco estão filtrando corretamente por: empresa/tenant, status do pedido, período de referência, e se joins estão trazendo dados de serviços agregados.
Referências Adicionais
references/financeiro-queries.md — Padrões de query para módulo financeiroreferences/fluxo-dados.md — Diagrama detalhado de relacionamento entre tabelas
