ERP TPH
Evolução do Projeto
Um registro de tudo que está sendo construído, em ordem cronológica, para acompanhar a evolução do sistema.
Página inicial, briefing e manuais com a identidade da TPH
Novo- Página inicial pública do sistema, com a identidade visual da TPH Consultoria
- Briefing público (sem login) que entrega o lead ao CRM da TPH
- Área de Documentação com quatro manuais (Administrador, Usuário, PDV e Financeiro), passo a passo e imagens das telas reais
- Ambiente de homologação separado da produção, com o mesmo código e banco próprio
Design- Paleta, tipografia (Sora e DM Sans), logo e símbolo do Guia de Marca aplicados às páginas públicas
- Tela de Marca: campos de logo e favicon não se sobrepõem mais
Infraestrutura- Prints dos manuais gerados por script a partir da homologação, com dados fictícios removidos ao final
Fiscal — preparação da arquitetura (NF-e/NFC-e/NFS-e)
Novo- Configurações fiscais do tenant: regime tributário, inscrição estadual, inscrição municipal, CNAE e ambiente (homologação/produção)
- Dados fiscais por produto: NCM, CEST, CFOP padrão, CST de ICMS, CSOSN e alíquotas de ICMS/PIS/COFINS/ISS
- Solicitação de emissão de NF-e/NFC-e/NFS-e a partir da tela de venda, com histórico de documentos fiscais por venda
Infraestrutura- FiscalAdapter: porta de integração com provedor fiscal externo, seguindo o mesmo padrão do CrmAdapter/PaymentAdapter já previstos na arquitetura
- Nenhum provedor fiscal está contratado — a implementação ativa (NullFiscalAdapter) sempre retorna 'provedor não configurado', nunca simula uma emissão bem-sucedida
Banco de Dados- Novas tabelas tenant_fiscal_settings e fiscal_documents, e novos campos fiscais em products — mantidos separados das regras comerciais
- Novas permissões fiscal.manage e fiscal.emit
Relatórios e dashboard gerencial
Novo- Dashboard com indicadores dos últimos 30 dias: vendas, ticket médio, clientes ativos e produtos abaixo do estoque mínimo
- Ranking dos 5 produtos mais vendidos no período
- Fluxo de caixa exibido no dashboard para quem também tem permissão financeira
- Endpoint GET /api/v1/reports/dashboard para consumo externo (API key)
Seguranca- Indicadores só ficam visíveis para quem tem a permissão reports.view (proprietário, administrador, gerente por padrão)
- Isolamento multi-tenant testado: dados de outro tenant nunca aparecem no resumo
Banco de Dados- Nova permissão reports.view associada aos papéis proprietário, administrador e gerente
White Label completo
Novo- Configurações de marca por tenant: nome fantasia, logo, favicon, cores primária/secundária, contatos de suporte, WhatsApp
- Upload de logo e favicon (bucket próprio no Storage, público — necessário para aparecer na interface)
- Domínio próprio: campo para o tenant registrar o domínio desejado (ativação de DNS/certificado é manual pela TPH)
- Módulos habilitáveis por tenant (PDV, Estoque, Financeiro, Integração CRM, API pública, Relatórios, Fiscal) — o menu se adapta automaticamente
Design- Logo e nome fantasia substituem "ERP TPH" no cabeçalho do app
- Cor primária do tenant aplicada de verdade na interface (nome da marca e borda do cabeçalho)
Seguranca- Configurações de marca só editáveis por quem tem a permissão tenant.settings.manage; leitura liberada a qualquer usuário do tenant (necessária para renderizar a marca)
- Isolamento multi-tenant testado: configurações de um tenant nunca vazam nem são alteráveis por outro
Integração CRM TPH — decisão de arquitetura
Integracao- Alinhado com a sessão responsável pelo CRM TPH: sem tabela de vínculo organization_id ↔ tenant_id — a API key da Fase 9 já resolve o tenant sozinha, e essa chave é o vínculo do lado do CRM
- Nenhuma sincronização de dado real implementada ainda (nem clientes, nem vendas, nem produtos) — fica para quando surgir o primeiro caso de uso concreto
- A base técnica da Fase 10 já estava coberta pela Fase 9 (chaves de API com escopo); nenhum código adicional foi necessário
API pública v1
Novo- Chaves de API para integrações externas, com escopos granulares (ver produtos, ver/criar clientes, ver vendas, ver estoque)
- Gestão de chaves em Configurações → API — gerar, listar, revogar
- Documentação da API pública em /docs/api, com especificação OpenAPI em /api/v1/openapi.json
- Endpoints de produtos e clientes já aceitam autenticação por API key, além da sessão do app
Seguranca- Chave em texto puro é exibida uma única vez na criação — só o hash fica no banco
- Requisições autenticadas por API key usam o client administrativo com tenant_id filtrado manualmente em toda consulta (RLS não se aplica sem sessão do Supabase Auth) — testado o isolamento multi-tenant nesse caminho também
- Rate limit de 60 requisições por minuto por chave, testado de verdade (60 passam, a 61ª é bloqueada)
- Chave revogada, expirada ou malformada é rejeitada
API- GET /api/v1/products e GET /api/v1/customers aceitam Bearer token
- Demais endpoints internos seguem só por sessão por ora — expansão incremental, documentada em /docs/api
Banco de Dados- Tabelas api_keys, api_logs
- Permissão api_keys.manage
Financeiro
Novo- Contas a pagar e a receber, com categorias financeiras
- Fluxo de caixa: resumo de valores recebidos/pagos (realizado) e a receber/a pagar (projetado)
- Venda sem pagamento no ato (fiado) gera conta a receber automaticamente, vinculada ao cliente e à venda
- Cancelar uma venda fiado cancela a conta a receber pendente correspondente
Integracao- Vendas e Financeiro agora conversam automaticamente — nenhuma etapa manual para registrar uma venda a prazo
Banco de Dados- Tabelas financial_categories, accounts_payable, accounts_receivable
- Permissões finance.view, finance.manage
PDV e Caixa
Novo- PDV rápido: busca por nome/SKU/código de barras, atalhos de teclado F2-F9 (cliente, desconto, pagamento, suspender, recuperar, cancelar item, cancelar venda, finalizar)
- Pagamento múltiplo (dividir entre dinheiro, débito, crédito, Pix), com cálculo de troco
- Suspender e recuperar venda — atender outro cliente sem perder o carrinho
- Abertura e fechamento de caixa, com cálculo automático de saldo esperado e diferença
- Sangria e suprimento de caixa
Seguranca- Pagamento em dinheiro só é aceito com um caixa aberto vinculado
- Corrigida falha encontrada nos testes: faltava política de exclusão (DELETE) em vendas, então recuperar uma venda suspensa falhava silenciosamente sem apagar o rascunho; corrigido e restrito a vendas suspensas do próprio tenant
Banco de Dados- Tabelas cash_registers, cash_sessions, cash_movements, payment_methods, payments
- Vendas passam a suportar status "suspensa", além de concluída/cancelada
- Permissões cash.manage, pdv.use
Vendas
Novo- Registro de venda com múltiplos itens e cliente opcional
- Baixa automática de estoque ao concluir a venda
- Cancelamento de venda com estorno automático do estoque
- Verificação de estoque disponível antes de confirmar a venda
Seguranca- Isolamento por tenant em vendas e itens de venda
- Cancelar venda exige permissão específica (sales.cancel)
Banco de Dados- Tabelas sales e sale_items
- Permissões sales.view/create/cancel
Estoque
Novo- Depósitos (múltiplos locais de estoque por empresa)
- Entrada e saída manual de estoque
- Ajuste por inventário: usuário informa a contagem física, sistema calcula a diferença automaticamente
- Transferência de estoque entre depósitos
- Histórico completo de movimentações por produto/depósito
Seguranca- Saldo de estoque nunca é alterado diretamente — só através de uma movimentação auditável (trigger no banco)
- Corrigida uma falha encontrada durante o desenvolvimento: a política de isolamento por tenant não impedia usar um depósito ou produto de outro tenant numa movimentação; adicionada validação explícita no banco (testado: tentativa é rejeitada e o saldo do outro tenant não é afetado)
Banco de Dados- Tabelas warehouses, stock_balances, stock_movements
- Função transfer_stock() para transferências atômicas entre depósitos
- Permissões stock.view, stock.move, warehouses.manage
Produtos e imagens
Novo- Cadastro de produtos (SKU, código de barras, custo, preço, categoria, marca)
- Múltiplas imagens por produto, com imagem principal escolhida pelo usuário (não é automática)
- Upload, exclusão e reordenação de imagens
- Categorias e marcas cadastráveis direto no formulário de produto
- Histórico de preço/custo registrado a cada alteração
Seguranca- Bucket de imagens privado no Supabase Storage — sem URL pública direta
- URLs de imagem são assinadas (expiram em 1h), geradas só após checar tenant/permissão
- Teste crítico de imagens (seção 45): confirmado que Tenant B não visualiza, não exclui e não baixa o arquivo do Tenant A manipulando o storage_path
- Validação de tipo, extensão e tamanho de arquivo (máx. 5MB; JPEG/PNG/WebP)
Banco de Dados- Tabelas products, product_images, product_prices, categories, brands
- Permissões products.view/create/edit/delete
Cadastro de clientes
Novo- Cadastro de clientes (Pessoa Física e Pessoa Jurídica)
- Validação de CPF e CNPJ (dígitos verificadores)
- Listagem de clientes com busca por nome, documento e e-mail
- API /api/v1/customers (listar, criar, editar, excluir)
Seguranca- RLS isolando clientes por tenant (testado: Tenant B não acessa clientes do Tenant A)
- RBAC: criar/editar/excluir clientes exige permissão específica, checada no servidor
- Exclusão de cliente é lógica (soft delete), preservando histórico para auditoria/LGPD
Banco de Dados- Tabelas customers e customer_addresses
- Permissões customers.view/create/edit/delete
Correção: site fora do ar após deploy
Correcao- middleware.ts estava na raiz do projeto; como a aplicação usa src/app, o Next.js só reconhece src/middleware.ts — a proteção de sessão nunca esteve realmente ativa via middleware (o redirect de login ainda funcionava por uma checagem redundante no layout)
- Next.js 16.3.6 (versão mais recente disponível) tinha um bug de empacotamento do middleware que quebrava em produção; feito downgrade para next@15.5.26 (última estável da série 15)
- O projeto na Vercel foi criado antes de existir código Next.js e ficou com Framework Preset = "Other"; corrigido para "Next.js", resolvendo 404 no domínio de produção
Infraestrutura- eslint.config.mjs reescrito com FlatCompat para compatibilidade com eslint-config-next 15.x
Usuários e RBAC
Novo- Cadastro de empresa (cria tenant + usuário Proprietário)
- Login e logout
- Gestão de usuários: listar e convidar novos usuários do tenant
- Papéis com permissões (RBAC): Proprietário, Administrador, Gerente, Vendedor, Operador de PDV, Financeiro, Estoquista, Consulta
Seguranca- Middleware de sessão protege as áreas logadas
- Convite de usuário exige a permissão users.invite, checada no servidor (testado: usuário sem permissão recebe 403 mesmo chamando a API diretamente)
- Função bootstrap_tenant protegida contra reexecução
Banco de Dados- Catálogo de permissões e mapeamento por papel
- Função bootstrap_tenant() para provisionar o primeiro usuário/tenant
Fundação da plataforma
Novo- Arquitetura em camadas (UI, Application, Domain, Infrastructure)
- Projeto Next.js + TypeScript + Tailwind CSS
- Estrutura multi-tenant no banco (tenants, tenant_settings)
- RBAC inicial (roles, permissions, user_roles)
- Página de Evolução do Projeto
Seguranca- Row Level Security habilitado em todas as tabelas do núcleo
- Função current_tenant_id() para isolamento por tenant
Banco de Dados- Migration inicial: tenants, users, roles, permissions, audit_logs
Infraestrutura- Projeto Supabase dedicado (erp-pdv-whitelabel)
- Deploy configurado na Vercel