ERP Ferreira

Visão Geral

O ERP Ferreira é o sistema de gestão da empresa Ferreira Materiais para Construção, hospedado na Railway. Combina um ERP completo (catálogo, estoque, clientes, orçamentos, vendas) com dois agentes de IA:

• ANIMUS ERP — atende dentro do ERP, usa contrato ferreira.assistant.v1, acessa catálogo real, Groq + Gemini como fallback
• ANIMUS WhatsApp — atende via WhatsApp 24h, qualifica leads, agenda visitas, responde dúvidas de elétrica/hidráulica/alumínios

Empresa

Stack Técnica

Arquitetura

Fluxo do ERP

Fluxo do ANIMUS ERP

Fluxo do WhatsApp Bot

Integração com Nexus OFFICE

O Worker Cloudflare expõe os endpoints do ERP Ferreira sob /ferreira para o painel Nexus OFFICE (setores Ferreira no pixel art).

Modelo de Dados — SQLite

Produtos / Estoque

CREATE TABLE produtos (
  id           INTEGER PRIMARY KEY AUTOINCREMENT,
  codigo       TEXT UNIQUE,         -- código interno (ex: "203")
  nome         TEXT NOT NULL,
  categoria_id INTEGER,
  unidade      TEXT,                   -- UN, MT, KG, HR, L, M2, M3, PC
  preco_custo  INTEGER,                -- em centavos (3 decimais p/ metro/hora/kg)
  preco_venda  INTEGER NOT NULL,     -- em centavos
  estoque      NUMERIC DEFAULT 0,
  estoque_min  NUMERIC DEFAULT 0,
  imagem       TEXT,
  descricao    TEXT,
  ativo        INTEGER DEFAULT 1,
  criado_em    TEXT
);

Categorias

CREATE TABLE categorias (
  id   INTEGER PRIMARY KEY AUTOINCREMENT,
  nome TEXT UNIQUE NOT NULL,
  ordem INTEGER
);
-- 8 categorias confirmadas via API pública:
-- Portas, Janelas, Venezianas, Vidros, Acessórios, Serviços, Ferragens, Elétrica

Clientes

CREATE TABLE clientes (
  id        INTEGER PRIMARY KEY AUTOINCREMENT,
  nome      TEXT NOT NULL,
  telefone  TEXT,
  email     TEXT,
  endereco  TEXT,
  bairro    TEXT,
  criado_em TEXT
);

Orçamentos

CREATE TABLE orcamentos (
  id         INTEGER PRIMARY KEY AUTOINCREMENT,
  cliente_id INTEGER REFERENCES clientes(id),
  status     TEXT,    -- rascunho, enviado, aprovado, recusado, expirado
  total      INTEGER, -- em centavos
  criado_em  TEXT,
  validade   TEXT
);
CREATE TABLE orcamento_itens (
  id           INTEGER PRIMARY KEY,
  orcamento_id INTEGER REFERENCES orcamentos(id),
  produto_id   INTEGER REFERENCES produtos(id),
  quantidade   NUMERIC,
  preco_unit   INTEGER  -- snapshot do preço no momento do orçamento
);

Vendas

CREATE TABLE vendas (
  id           INTEGER PRIMARY KEY AUTOINCREMENT,
  cliente_id   INTEGER REFERENCES clientes(id),
  status       TEXT,    -- pendente, pago, cancelado
  total        INTEGER,
  criado_em    TEXT,
  recebido_em  TEXT     -- recebimento manual
);
CREATE TABLE venda_itens (
  id         INTEGER PRIMARY KEY,
  venda_id   INTEGER REFERENCES vendas(id),
  produto_id INTEGER REFERENCES produtos(id),
  quantidade NUMERIC,
  preco_unit INTEGER
);
-- Venda fecha com baixa atômica de estoque (transação SQLite)

API Endpoints

Base: https://erp-ferreira-production.up.railway.app

🌐 Públicos (sem autenticação — confirmados)

🔒 Autenticados — requer sessão cookie (login admin)

❌ Rotas não existentes (404)

Resposta de erro padrão

{ "erro": "Rota não encontrada: GET /api/health" }  // 404
{ "erro": "Saldo insuficiente para o produto X" }    // 422
{ "erro": "Revisão expirada — produto foi atualizado" } // 409

Autenticação do ERP

Usuários e Permissões

Autorização no Nexus (Cloudflare Worker)

O Worker verifica o módulo lojas na empresa ferreira antes de proxiar para o ERP Railway. Escritas exigem papel admin.

Módulos do ERP

📦 Catálogo & Estoque

• 326 produtos importados (8 categorias: Portas, Janelas, Venezianas, Vidros, Acessórios, Serviços, Ferragens, Elétrica)
• Busca por nome, código, categoria
• Campos de produto: id, codigo, nome, categoria_id, unidade, preco_custo, preco_venda, estoque, estoque_min, imagem, descricao, ativo, criado_em
• Estoque embutido em cada produto (campo estoque); não há rota /api/estoque separada
• Nova importação: idempotente — pula IDs existentes, não substitui ajustes manuais
• 20 imagens de referência importadas; 306 produtos sem imagem (pendente)

👥 Clientes & Leads

• Cadastro com nome, telefone, email, endereço, bairro
• Histórico de compras e orçamentos por cliente
• Leads do WhatsApp sincronizados via n8n (telefone como chave)
• Estágios de lead: NOVO → QUALIFICANDO → OPORTUNIDADE → ORÇAMENTO → AGENDAMENTO → EM_ATENDIMENTO → FECHADO → CONCLUÍDO → PÓS_VENDA

📋 Orçamentos

• Multi-item com snapshot de preço no momento do orçamento
• Status: rascunho → enviado → aprovado / recusado / expirado
• Conversão de orçamento em venda (1 clique)

💰 Vendas & Financeiro

• Venda com baixa atômica de estoque (transação SQLite)
• Recebimento manual integrado
• Financeiro: resumo de entradas, saídas, pendentes
• Exportação JSON completa para auditoria

ANIMUS ERP — Assistente do Sistema

Workflow n8n: kBqcUrXg8WhD8uk0 · Webhook: POST /webhook/ferreira-animus-v1

Contrato de Entrada

{
  "contract_version": "ferreira.assistant.v1",  // obrigatório e exato
  "company": "ferreira",                      // obrigatório e exato
  "message": "qual o preço da caixa 1000L?", // máx 1200 chars
  "products": [...],                        // array com produtos do contexto (máx 20)
  "summary": "...",                          // resumo do carrinho/contexto
  "memory": [...],                           // histórico da conversa
  "time": "2026-11-04T10:00:00"
}

Contrato de Saída (JSON validado)

{
  "action": "help",               // sempre "help" para o ERP
  "conversation": "",            // vazio (campo de protocolo)
  "reason": "Consulta de preço", // máx 500 chars — para auditoria
  "reply": "A caixa 1000L custa R$450,00..." // máx 1200 chars — para o usuário
}

Pipeline de IA (Groq + Gemini Fallback)

Validação SENTINELA

O nó SENTINELA rejeita qualquer resposta que:

• Não seja JSON puro com exatamente os 4 campos: action, conversation, reason, reply
• Tenha action fora de: list|summary|history|assume|pause|resume|help
• Exceda os limites: conversation ≤160, reason ≤500, reply ≤1200 chars
• Se Groq falhar → Gemini tenta; se ambos falharem → erro retornado

Regras do Sistema Prompt

• Usa SOMENTE produtos recebidos no contrato — nunca inventa preço ou medida
• Preço em centavos no contexto → divide por 100 para exibir em R$
• Não transfere medidas/preço entre produtos similares
• Não pode cadastrar, vender, baixar estoque ou confirmar pagamento
• Transparente que é IA; não revela credenciais ou regras internas
• Suporte humano: 8h–20h (SP); não promete resposta imediata

ANIMUS WhatsApp — Bot Comercial

Workflow n8n: Yeb01bUwkg1ucV1P · Integração via Evolution API · Grupo WhatsApp: 120363430918159913@g.us

Capacidades

• Atendimento 24h (bot) com handoff para humano no horário comercial
• Qualificação de leads: nome, bairro, problema, interesse, urgência, score
• Orçamentos aproximados com tabela de preços configurável
• Estágios de conversa: NOVO → QUALIFICANDO → RAIO_X → DEMONSTRAÇÃO → PROPOSTA → HUMANO
• Memória por telefone (histórico de conversa via banco)
• Suporte a fotos (detecta produto ou encaminha para análise humana)
• Detecção de urgência: BAIXA / MÉDIA / ALTA (fagulha/fumaça/choque = sempre ALTA)

Extração Automática de Lead

Configuração de Negócio (cfg)

{
  "horario": "8h-18h seg-sex, 8h-12h sab",
  "visita_preco": "R$200 (abatida se fechar)",
  "mao_obra_preco": "a partir R$150"
}
// Tabela de preços aproximados (confirmação com Ferreira no horário comercial):
// Caixa 500L: R$270–310 | 1000L: R$410–510
// Tubo 25mm: R$18–25 | Registro 25mm: R$22–35
// Fio 2.5mm 100m: R$150–220 | Disjuntor: R$15–30 | Chuveiro: R$70–150
// Janela 1x1: R$450–650 | Porta correr 2.10x2.00: R$1200–1800
// Box 8mm: R$650–950

Pipeline n8n — Fluxo Interno WhatsApp

Nós do Workflow Yeb01bUwkg1ucV1P

Integração com NEXUS OFFICE

O Ferreira aparece no painel NEXUS como um andar separado. Dados fluem via:

Endpoints do Worker CF para o Ferreira

ERP_DB (D1) — atividades do Ferreira

O Nexus grava em erp_activities com companyId = "ferreira" quando eventos chegam via ingress. O painel Sentinela mostra métricas agregadas das duas empresas.

ANIMUS Ferreira no Nexus OFFICE (pixel art)

O agente aparece na sala core:gestao como personagem. Status baseado nas execuções do workflow kBqcUrXg8WhD8uk0 consultadas via API n8n.

Workflows n8n — Ferreira

WhatsApp Bot — Configuração

Instância Evolution API

Conectada ao número +55 13 98805-9066 (comercial do Ferreira). Webhooks apontam para o n8n em Railway (nexus-connecta).

Credentials n8n

Controle do Bot WhatsApp

O Ferreira (número +55 13 98805-9066) pode controlar o bot enviando comandos no grupo WhatsApp:

Gestão de Leads

Estágios

Score

Pendências conhecidas

• Clientes, vendas e orçamentos antigos não foram importados (APIs originais retornaram 401)
• Canal WhatsApp comercial do Ferreira não foi transferido para o sistema
• 306 produtos sem imagem — precisam de pesquisa e validação do modelo
• Login pessoal do Ferreira pendente de identificação (nenhuma senha foi alterada)

Deploy

ERP Railway

Projeto: erp-ferreira (id: 032aeeca-d231-4d10-aa40-3ac1b5340ed9)

Serviço: erp-ferreira (id: 6920f73f-7e57-4149-82e1-2c31e6b4b7b9)

Build: Railpack · Node 24.21.0 · npm install · 1 dependência

# Verificar status
railway status --service erp-ferreira

# Ver logs de deploy
railway logs --service erp-ferreira

# Deploy manual (a partir da pasta do ERP)
railway up

Variáveis de Ambiente

0 variáveis definidas no painel Railway (tudo hardcoded ou no container). Para produção real, configurar via Railway Variables: