Sistema ERP - Verde Pack Cantoneiras - Documentação Completa

📋 Visão Geral do Projeto

Objetivo

Desenvolver um sistema ERP completo para gerenciar a fabricação de cantoneiras de papel sob encomenda e a revenda de produtos de embalagem.

Principais Características

✅ Dual Operating Model

Fabricação sob encomenda: Cantoneiras personalizadas sem estoque final
Revenda: Produtos de embalagem com controle de estoque tradicional

📏 Unidade Padrão: Milímetros

Todo o sistema trabalha com milímetros (mm) como unidade base para comprimento, com conversões automáticas para metros e quilogramas conforme necessário.

🔄 Conversões Automáticas

O sistema realiza conversões inteligentes:

Venda (mm) → Metros → Kg de Matéria-Prima

Exemplo: 10 peças × 2.500mm = 25.000mm = 25 metros = 2,8kg de papel

🏢 Modelo de Negócio

1. Fabricação de Cantoneiras (Sob Encomenda)

Características

Produção apenas após venda confirmada
Não mantém estoque de produto acabado
Controla apenas estoque de matéria-prima
Dimensões personalizadas por pedido

Matéria-Prima: Bobinas de Papel

Especificação	Descrição	Exemplo
Gramatura	Peso por metro quadrado	400 g/m²
Largura	Largura da bobina em mm	70 mm
Peso por Metro	Calculado automaticamente	28 g/m
Controle de Estoque	Por peso total	150 kg

Composição de uma Cantoneira

Exemplo: Cantoneira 50x50x3mm

Componente	Especificação	Camadas	Consumo/Metro
Miolo	Bobina 400g - 70mm	4 camadas	112g
Capa	Bobina 130g - 160mm	1 camada	20,8g
Adesivo	Cola PVA	-	15g
Total por Metro			147,8g

2. Revenda de Produtos de Embalagem

Características

Compra produtos prontos de fornecedores
Mantém estoque físico dos produtos
Controle tradicional de entrada/saída
Alertas de estoque mínimo

Exemplos de Produtos de Revenda

Caixas de papelão padronizadas
Fita adesiva (diversos tamanhos)
Stretch film
Papel kraft em folhas
Cantoneiras padrão de outros fornecedores

Venda de Produtos

Produtos Fabricados: Unidade Composta

O vendedor informa dois valores:

Quantidade de peças: 10 unidades
Comprimento de cada: 2.500mm

Total = 10 peças × 2.500mm = 25.000mm = 25 metros

Precificação: R$ 8,00/metro × 25m = R$ 200,00

Produtos de Revenda: Unidade Simples

O vendedor informa apenas a quantidade:

Quantidade: 10 rolos

Precificação: R$ 15,00/rolo × 10 = R$ 150,00

🗄️ Estrutura do Banco de Dados

Tabelas Principais

1. categorias

Campo	Tipo	Descrição
id	INTEGER	Chave primária
nome	VARCHAR(100)	Nome da categoria
tipo	ENUM	'fabricado' ou 'revenda'
ativo	BOOLEAN	Status da categoria

2. fornecedores

Campo	Tipo	Descrição
id	INTEGER	Chave primária
razao_social	VARCHAR(255)	Nome legal da empresa
nome_fantasia	VARCHAR(255)	Nome comercial
cnpj	VARCHAR(18)	CNPJ do fornecedor
email	VARCHAR(255)	E-mail de contato
telefone	VARCHAR(20)	Telefone
condicoes_pagamento	TEXT	Condições negociadas
prazo_entrega_dias	INTEGER	Lead time padrão

3. materias_primas

Campo	Tipo	Descrição
id	INTEGER	Chave primária
nome	VARCHAR(255)	Ex: "Bobina Kraft 400g - 70mm"
tipo	VARCHAR(50)	papel_kraft, cola_pva, tinta, etc
gramatura	DECIMAL(10,2)	g/m² (só para papel)
largura_mm	DECIMAL(10,2)	Largura em milímetros
peso_por_metro_g	DECIMAL(10,3)	Calculado: (gramatura × largura_mm) / 1000
unidade_estoque	VARCHAR(20)	kg, litro, unidade
estoque_atual	DECIMAL(10,3)	Quantidade em estoque
estoque_minimo	DECIMAL(10,3)	Nível de alerta
custo_por_unidade	DECIMAL(10,2)	Preço de compra

4. produtos

⚠️ Tabela Híbrida: Armazena tanto produtos fabricados quanto de revenda

Campo	Tipo	Uso	Descrição
id	INTEGER	Ambos	Chave primária
nome	VARCHAR(255)	Ambos	Nome do produto
tipo	ENUM	Ambos	fabricado ou revenda
categoria_id	INTEGER	Ambos	FK para categorias
altura_mm	DECIMAL(10,2)	Fabricado	Dimensões em mm
largura_mm	DECIMAL(10,2)	Fabricado	Dimensões em mm
espessura_mm	DECIMAL(10,2)	Fabricado	Dimensões em mm
unidade_venda	VARCHAR(20)	Ambos	metro, kg, unidade, rolo
permite_medida_composta	BOOLEAN	Ambos	TRUE para cantoneiras
preco_venda_unitario	DECIMAL(10,2)	Ambos	Preço por unidade
estoque_atual	DECIMAL(10,2)	Revenda	NULL para fabricados
estoque_minimo	DECIMAL(10,2)	Revenda	Alerta de reposição
custo_compra	DECIMAL(10,2)	Revenda	Preço de compra
fornecedor_id	INTEGER	Revenda	FK para fornecedores
tempo_producao_metros_hora	DECIMAL(10,2)	Fabricado	Capacidade produtiva
lead_time_dias	INTEGER	Fabricado	Prazo de produção

5. receitas (Composição de Produtos Fabricados)

Campo	Tipo	Descrição
id	INTEGER	Chave primária
produto_id	INTEGER	FK para produtos (tipo fabricado)
materia_prima_id	INTEGER	FK para materias_primas
numero_camadas	INTEGER	Quantas camadas/folhas
consumo_por_metro_g	DECIMAL(10,3)	Peso em gramas por metro
custo_por_metro	DECIMAL(10,2)	Custo calculado automaticamente

6. clientes

Campo	Tipo	Descrição
id	INTEGER	Chave primária
tipo_pessoa	ENUM	'fisica' ou 'juridica'
razao_social	VARCHAR(255)	Nome completo ou razão social
nome_fantasia	VARCHAR(255)	Nome comercial
cnpj_cpf	VARCHAR(18)	Documento
email	VARCHAR(255)	E-mail
telefone	VARCHAR(20)	Telefone principal
limite_credito	DECIMAL(10,2)	Limite aprovado

7. pedidos

Campo	Tipo	Descrição
id	INTEGER	Chave primária
numero_pedido	VARCHAR(20)	Número sequencial automático
cliente_id	INTEGER	FK para clientes
data_pedido	DATE	Data de criação
tipo	ENUM	'orcamento' ou 'pedido_confirmado'
status	ENUM	orcamento, aprovado, producao, finalizado, entregue, cancelado
valor_produtos	DECIMAL(10,2)	Soma dos itens
valor_frete	DECIMAL(10,2)	Custo de entrega
valor_desconto	DECIMAL(10,2)	Desconto aplicado
valor_total	DECIMAL(10,2)	Valor final
prazo_entrega_dias	INTEGER	Prazo combinado
data_entrega_prevista	DATE	Data calculada

8. pedidos_itens

💡 Chave do Sistema: Esta tabela permite venda composta para produtos fabricados

Campo	Tipo	Descrição
id	INTEGER	Chave primária
pedido_id	INTEGER	FK para pedidos
produto_id	INTEGER	FK para produtos
tipo_produto	ENUM	'fabricado' ou 'revenda'
quantidade_pecas	INTEGER	Número de peças (para compostos)
comprimento_cada_mm	DECIMAL(10,2)	Comprimento em mm (NULL para simples)
total_calculado	DECIMAL(10,3)	quantidade × comprimento / 1000 = metros
quantidade_simples	DECIMAL(10,2)	Para produtos de revenda
unidade_medida	VARCHAR(20)	metro, kg, unidade, rolo
preco_unitario	DECIMAL(10,2)	Preço por unidade
subtotal	DECIMAL(10,2)	Valor do item

9. ordens_producao

Campo	Tipo	Descrição
id	INTEGER	Chave primária
numero_op	VARCHAR(20)	Número sequencial (OP-0001)
pedido_id	INTEGER	FK para pedidos
pedido_item_id	INTEGER	FK para pedidos_itens
produto_id	INTEGER	FK para produtos
quantidade_produzir_metros	DECIMAL(10,2)	Total a produzir
data_programada	DATE	Data planejada
data_inicio_producao	DATETIME	Quando iniciou
data_conclusao	DATETIME	Quando finalizou
status	ENUM	aguardando, em_producao, concluido, cancelado

10. ordens_producao_consumo

Campo	Tipo	Descrição
id	INTEGER	Chave primária
ordem_producao_id	INTEGER	FK para ordens_producao
materia_prima_id	INTEGER	FK para materias_primas
quantidade_prevista_kg	DECIMAL(10,3)	Consumo calculado
quantidade_consumida_kg	DECIMAL(10,3)	Consumo real (após produção)
diferenca_kg	DECIMAL(10,3)	Desperdício/economia

11. movimentacoes_estoque

Campo	Tipo	Descrição
id	INTEGER	Chave primária
tipo	ENUM	entrada, saida, ajuste, producao
tipo_item	ENUM	'materia_prima' ou 'produto_revenda'
item_id	INTEGER	ID da matéria-prima ou produto
quantidade_anterior	DECIMAL(10,3)	Estoque antes
quantidade_movimentada	DECIMAL(10,3)	+ ou -
quantidade_atual	DECIMAL(10,3)	Estoque depois
motivo	VARCHAR(50)	compra, venda, producao, ajuste
documento_referencia	VARCHAR(50)	Pedido, OP, NF

🗂️ Estrutura de Menus

🏠 Dashboard

Resumo de vendas do período
Pedidos em aberto
Ordens de produção pendentes
Alertas de estoque baixo
Gráficos de performance

📋 Vendas

Clientes: Cadastro e gestão
Orçamentos: Propostas em análise
Pedidos: Pedidos confirmados
Relatórios: Análise de vendas

🏭 Produção

Ordens de Produção: Gestão de OPs
Programação: Planejamento de produção
Controle de Qualidade: Inspeções
Relatórios: Produtividade e eficiência

📦 Estoque

Produtos (Revenda): Controle de estoque
Matérias-Primas: Controle de insumos
Movimentações: Histórico completo
Inventário: Contagem física
Alertas: Estoque baixo/crítico

⚙️ Cadastros

Produtos
- Listar Todos
- Produtos Fabricados
- Produtos de Revenda
Matérias-Primas: Bobinas e insumos
Fornecedores: Cadastro de fornecedores
Clientes: Cadastro de clientes
Categorias: Organização de produtos

💰 Financeiro

Contas a Receber: Clientes
Contas a Pagar: Fornecedores
Fluxo de Caixa: Movimentações
Análise de Lucratividade: Por produto

📊 Relatórios

Vendas por Período
Produtividade
Giro de Estoque
Margem por Produto
Análise de Custos

🔄 Fluxos Operacionais

Fluxo 1: Cadastro de Matéria-Prima (Bobina)

Passo 1: Acessar Menu Cadastros → Matérias-Primas → [+ Nova]

⬇️

Passo 2: Preencher dados básicos

Nome: "Bobina Kraft 400g - Largura 70mm"
Tipo: Papel Kraft
Gramatura: 400 g/m²
Largura: 70 mm

⬇️

Passo 3: Sistema calcula automaticamente

peso_por_metro_g = (400 × 70) / 1000 = 28g/m

⬇️

Passo 4: Informar controle de estoque

Estoque Atual: 150 kg
Estoque Mínimo: 50 kg
Custo: R$ 12,00/kg

⬇️

Passo 5: Salvar e bobina fica disponível para composição

Fluxo 2: Cadastro de Produto Fabricado (Cantoneira)

Passo 1: Acessar Cadastros → Produtos → [+ Novo]

⬇️

Passo 2: Aba Informações Básicas

Nome: "Cantoneira 50x50x3mm"
Tipo: Fabricado
Dimensões: 50×50×3mm
Unidade: Metro
✅ Permite medida composta

⬇️

Passo 3: Aba Precificação

Preço de Venda: R$ 8,00/metro
Margem: (calculada após composição)

⬇️

Passo 4: Aba Composição/Receita
[+ Adicionar Matéria-Prima]

Matéria-Prima	Camadas	Consumo/Metro
Bobina 400g-70mm	4	112g
Bobina 130g-160mm	1	20,8g
Cola PVA	-	15g

⬇️

Passo 5: Sistema calcula custo automaticamente

Custo Total: R$ 2,00/metro
Preço Venda: R$ 8,00/metro
Margem: 300% (R$ 6,00)

⬇️

Passo 6: Salvar produto completo

Fluxo 3: Criar Pedido de Venda

Passo 1: Vendas → Pedidos → [+ Novo Pedido]

⬇️

Passo 2: Selecionar Cliente e Data

⬇️

Passo 3: Adicionar Item Fabricado

Produto: Cantoneira 50x50x3mm
Quantidade: 10 peças
Comprimento: 2.500mm cada

⬇️

Sistema Calcula:

10 × 2.500mm = 25.000mm = 25 metros
25m × R$ 8,00 = R$ 200,00

⬇️

Sistema Verifica Matéria-Prima:

Bobina 400g: Necessário 2,8kg | Disponível: 150kg ✅
Bobina 130g: Necessário 0,52kg | Disponível: 80kg ✅
Cola: Necessário 375g | Disponível: 5kg ✅

⬇️

Passo 4: Adicionar Item de Revenda

Produto: Fita Adesiva 48mm
Quantidade: 10 rolos
Sistema verifica estoque: 150 rolos ✅

⬇️

Passo 5: Revisar totais

Valor Produtos: R$ 350,00
Frete: R$ 50,00
Total: R$ 400,00

⬇️

Passo 6: Confirmar Pedido

⬇️

Sistema Executa:

✅ Gera Ordem de Produção para cantoneiras
✅ Reserva estoque de fita adesiva
✅ Status: "Aprovado"

Fluxo 4: Ordem de Produção

Geração Automática: Ao confirmar pedido com item fabricado

⬇️

OP Criada: OP-0123

Produto: Cantoneira 50x50x3mm
Quantidade: 25 metros
Prazo: 3 dias úteis
Status: ⏳ Aguardando

⬇️

Operador: [Iniciar Produção]

Sistema reserva matéria-prima
Status: 🏭 Em Produção

⬇️

Durante Produção: Operador registra consumo real

⬇️

Finalização: [Finalizar Produção]

✅ Baixa real no estoque de matéria-prima
✅ Status OP: Concluído
✅ Status Pedido: Finalizado
✅ Registra movimentações
✅ Produto pronto para entrega

🧮 Cálculos Automáticos

1. Peso por Metro de Bobina

Objetivo: Calcular quanto pesa 1 metro linear de bobina

peso_por_metro_g = (gramatura × largura_mm) / 1000

Exemplo:

Gramatura: 400 g/m²
Largura: 70 mm = 0,07 m
Peso: (400 × 70) / 1000 = 28g por metro

2. Consumo de Matéria-Prima por Metro de Produto

Objetivo: Calcular quanto de cada material é necessário para fabricar 1 metro de cantoneira

consumo_por_metro_g = numero_camadas × peso_por_metro_bobina_g

Exemplo:

Bobina 400g-70mm: peso = 28g/m
Número de camadas: 4
Consumo: 4 × 28 = 112g por metro

3. Custo de Matéria-Prima por Metro

Objetivo: Calcular o custo de material para 1 metro de produto

custo_por_metro = (consumo_por_metro_g / 1000) × custo_por_kg

Exemplo:

Consumo: 112g = 0,112 kg
Custo da bobina: R$ 12,00/kg
Custo: 0,112 × 12 = R$ 1,34 por metro

4. Conversão de Venda Composta

Objetivo: Converter quantidade de peças + comprimento em metros totais

total_metros = (quantidade_pecas × comprimento_cada_mm) / 1000

Exemplo:

Quantidade: 10 peças
Comprimento: 2.500mm cada
Total: (10 × 2.500) / 1000 = 25 metros

5. Consumo Total de Matéria-Prima

Objetivo: Calcular quantos kg de matéria-prima serão consumidos na produção

consumo_kg = (total_metros × consumo_por_metro_g) / 1000

Exemplo:

Total: 25 metros
Consumo por metro: 112g (bobina 400g)
Consumo total: (25 × 112) / 1000 = 2,8 kg

6. Valor Total do Pedido

Para Produtos Fabricados:

valor = total_metros × preco_por_metro

Exemplo: 25m × R$ 8,00 = R$ 200,00

Para Produtos de Revenda:

valor = quantidade × preco_unitario

Exemplo: 10 rolos × R$ 15,00 = R$ 150,00

7. Verificação de Disponibilidade

Para Produto Fabricado: Verificar cada matéria-prima

para cada materia_prima na receita:
    consumo_necessario = (total_metros × consumo_por_metro_g) / 1000
    
    se materia_prima.estoque_atual < consumo_necessario:
        material_insuficiente = true
        alertar_usuario()
        break
    
se todos_materiais_disponiveis:
    permitir_confirmacao_pedido()

Para Produto Revenda: Verificar estoque direto

se produto.estoque_atual >= quantidade_pedida:
    permitir_venda()
senao:
    alertar_estoque_insuficiente()

8. Cálculo de Margem de Lucro

margem_percentual = ((preco_venda - custo_total) / custo_total) × 100

Exemplo:

Custo Total: R$ 2,00/metro
Preço de Venda: R$ 8,00/metro
Margem: ((8 - 2) / 2) × 100 = 300%
Lucro por Metro: R$ 6,00

💻 Tecnologias Sugeridas

Frontend

Tecnologia	Versão	Finalidade
React	18+	Framework principal
TypeScript	5+	Tipagem estática
Tailwind CSS	3+	Estilização
React Hook Form	7+	Gerenciamento de formulários
TanStack Query	5+	Gerenciamento de estado server
Zustand	4+	Estado global
Recharts	2+	Gráficos e visualizações

Backend

Opção 1: Node.js

Tecnologia	Finalidade
Node.js + Express	Runtime e framework
TypeScript	Linguagem
Prisma ORM	Acesso ao banco
Zod	Validação de schemas

Opção 2: Python

Tecnologia	Finalidade
FastAPI	Framework web
SQLAlchemy	ORM
Pydantic	Validação de dados

Banco de Dados

Tecnologia	Motivo
PostgreSQL	Robusto, ACID compliant, excelente para dados relacionais complexos

Integrações

API	Finalidade
ReceitaWS	Consulta de CNPJ
ViaCEP	Consulta de endereços por CEP
APIs de Nota Fiscal	Emissão de NFe

DevOps

Versionamento: Git + GitHub/GitLab
CI/CD: GitHub Actions
Containerização: Docker
Deploy: AWS, DigitalOcean ou Heroku

🎯 Próximos Passos

Fase 1: Planejamento e Estrutura

✅ Definir modelo de negócio (CONCLUÍDO)
✅ Estruturar banco de dados (CONCLUÍDO)
✅ Definir fluxos operacionais (CONCLUÍDO)
⏳ Escolher stack tecnológica
⏳ Criar repositório Git

Fase 2: Setup Inicial

Configurar ambiente de desenvolvimento
Criar estrutura de pastas do projeto
Configurar banco de dados PostgreSQL
Implementar migrations/schema inicial
Setup do frontend React + TypeScript

Fase 3: Módulo de Cadastros

Cadastro de Fornecedores
Cadastro de Matérias-Primas (com cálculo automático)
Cadastro de Categorias
Cadastro de Clientes
Cadastro de Produtos (fabricados + revenda)
Composição de Produtos (receitas)

Fase 4: Módulo de Vendas

Criar Orçamento
Converter Orçamento em Pedido
Pedido com itens compostos
Verificação de disponibilidade
Cálculos automáticos de conversão
Impressão de pedidos

Fase 5: Módulo de Produção

Geração automática de OPs
Programação de produção
Controle de consumo de matéria-prima
Finalização e baixa de estoque
Relatórios de produtividade

Fase 6: Módulo de Estoque

Controle de matérias-primas
Controle de produtos de revenda
Movimentações de estoque
Alertas de estoque baixo
Inventário físico

Fase 7: Dashboard e Relatórios

Dashboard principal
Relatórios de vendas
Relatórios de produção
Análise de custos
Análise de margem por produto

Fase 8: Módulo Financeiro

Contas a receber
Contas a pagar
Fluxo de caixa
Integração bancária (opcional)

Fase 9: Melhorias e Integrações

Emissão de notas fiscais
Integração com APIs brasileiras
Sistema de permissões
Logs e auditoria
Backup automático

Fase 10: Deploy e Manutenção

Testes completos
Deploy em produção
Treinamento de usuários
Documentação técnica
Suporte e melhorias contínuas

✅ Validações Críticas do Sistema

⚠️ Ao Confirmar Pedido

Produtos Fabricados: Verificar estoque de TODAS as matérias-primas necessárias
Produtos Revenda: Verificar estoque do produto final
Cliente: Verificar limite de crédito (se aplicável)
Prazo: Calcular prazo realista baseado em capacidade produtiva

Alertas de Estoque

🟡 Alerta: Quando estoque <= estoque_minimo
🔴 Crítico: Quando estoque <= ponto_reposicao
⛔ Bloqueio: Não aceitar pedidos se não houver material suficiente

Consistência de Dados

Impedir exclusão de matéria-prima usada em produtos ativos
Impedir exclusão de produto com pedidos em aberto
Validar CNPJ/CPF na entrada
Garantir integridade referencial no banco