IbraClube
Clube de fidelidade que transforma compras de tinta em pontos, capacitação e trabalho para o pintor.
- 7
- perfis de acesso
- 2
- regionais isoladas
- 0
- frameworks de backend
Contexto
O desafio
A Ibratin (fabricante de tintas e texturas) queria reconhecer o pintor, o profissional que efetivamente escolhe e aplica o produto na ponta, mas que a indústria raramente enxerga.
O pedido inicial era “um programa de pontos”. O que entreguei foi uma plataforma de relacionamento: além de pontuar, ela capacita o profissional, certifica seu conhecimento e ainda gera trabalho para ele, transformando cada pintor num divulgador da marca.
O sistema nasceu como piloto (2 lojas em Maceió) e hoje roda numa arquitetura multi-regional, preparada para a expansão nacional com dezenas de franquias.
Tecnologia
Stack
- Backend
- PHP 8 puro, sem framework, com arquitetura em camadas própria (autoload PSR-4)
- Banco
- MySQL/MariaDB com modelo relacional normalizado, transações e FKs
- Frontend
- HTML5, CSS3 (design system com custom properties), JavaScript vanilla
- Infra
- cPanel/HostGator, domínio próprio, SSL, cron para rotinas
- Integrações
- Webhook de WhatsApp (n8n)
- Docs
- Geração automatizada de PDF/PPTX (Python + ReportLab)
Escolhi não usar framework de propósito: o ambiente-alvo era hospedagem compartilhada, e o projeto exigia controle total sobre performance e footprint. Isso me obrigou a implementar do zero autenticação, roteamento, camada de dados e proteções, e a entender cada decisão que um framework normalmente esconde.
Estrutura
Arquitetura
public/ → document root (única pasta exposta na web) ├─ pintor/ → app do pintor (mobile-first) ├─ master/ → painel da loja · serve também a "loja completa" ├─ detec/ → painel técnico · telas compartilhadas (pintor, evento) ├─ marketing/ → painel de marketing ├─ admin/ → painel administrativo · serve também o admin regional ├─ p/<slug> → vitrine pública do pintor └─ pintores → página pública "Encontre um Pintor" src/ → fora da raiz web (protegido) ├─ Auth/ → autenticação, sessões, CSRF ├─ Core/ → Database (PDO), Points, Logger, Session └─ Notify/ → WhatsApp config/ · views/ · scripts/ · database/
Só o public/ é exposto
Código, credenciais e configuração ficam um nível acima do document root.
Regra de escopo em vez de código duplicado
O painel do admin serve tanto o admin geral quanto o admin regional; o da loja serve a loja simples e a “loja completa”. A diferença é um escopo aplicado às queries, não uma cópia do arquivo. Evitou ~2.000 linhas duplicadas.
Telas compartilhadas multi-perfil
Gestão de pintor e de evento são um arquivo só, consumido por 5 perfis diferentes, cada um com seu retorno e seu escopo.
Motor de pontos centralizado
Points::approveInvoice é usado por todos os fluxos que creditam pontos. Garante que a regra de negócio existe em um lugar só.
Escopo
Funcionalidades
/Pintor (app mobile-first)
- Cadastro e login por telefone/CPF · recuperação e troca de senha
- Envio de nota fiscal por foto → pontos após validação da loja
- Saldo, níveis (Bronze/Prata/Ouro) com bônus progressivo e ranking
- Catálogo de prêmios e resgate online, com endereço de envio quando a regional exige
- Trilha de capacitação, inscrição em cursos e certificados digitais com código de validação
- Vitrine própria: portfólio de obras, especialidades e contato
/Vitrine & “Encontre um Pintor” (público)
- Página pública por pintor (/p/nome) com galeria, selo de Especialista e WhatsApp
- Diretório público com busca por cidade, nome e capacitação
- Curadoria: só aparece quem a equipe técnica aprovar
- As especialidades são derivadas da trilha concluída, não autodeclaradas
/Gestão (5 perfis)
- Loja: aprovação de NF, pintores, ranking, resgates, catálogo e regras próprias
- Loja completa (franquia): tudo acima + trilha, cursos, certificados e vídeos
- DETEC (técnico): capacitações, cursos, presença, certificados, selo Especialista
- Marketing: pintores, eventos, catálogo, campanhas e conteúdo
- Admin / Admin Regional: visão consolidada, relatórios com exportação CSV, unidades, usuários e auditoria
/Multi-regional
- Operação dividida em regionais (Norte/Nordeste e Sul/Sudeste/Centro-Oeste)
- Cada regional tem catálogo, trilha, cursos e regras próprios
- Isolamento garantido no servidor. Nenhuma regional enxerga ou altera dados da outra
- Conteúdo “de marca” é compartilhado por todas
Engenharia
Destaques técnicos
Compatibilidade com MySQL legado
O ranking usava RANK() OVER, mas o servidor rodava MySQL 5.7, sem window functions. Diagnostiquei pelo erro 500 em produção e reescrevi com subconsultas COUNT(*)+1 equivalentes.
Isolamento de dados multi-tenant
Ao introduzir as regionais, o risco real era vazamento entre elas. Apliquei escopo em todas as queries de leitura e guards server-side em cada ação de escrita, de forma que um ID forjado num formulário não afeta outra regional.
Concorrência no resgate
Resgate roda em transação com SELECT ... FOR UPDATE sobre saldo e estoque, evitando resgate duplicado ou estoque negativo em cliques simultâneos.
Modelagem de níveis
Separação entre saldo gastável e total acumulado: o nível é vitalício e não regride quando o pintor resgata prêmios. Uma decisão de produto que virou decisão de modelagem.
Auditoria transparente
Um logger central registra automaticamente toda ação autenticada (via hook no bootstrap), sem instrumentar tela por tela, e com try/catch que garante que a auditoria nunca derruba a aplicação.
Integridade referencial
Itens de catálogo com histórico de resgate não podem ser apagados (quebraria o vínculo): o sistema faz soft-delete automático nesses casos, preservando o histórico.
Infraestrutura
Deploy em hospedagem compartilhada, migração de domínio .com.br (Registro.br → nameservers), emissão de SSL, backup automático do banco via cron com rotação, e cache busting de assets por filemtime.
Segurança
CSRF em todos os formulários, bcrypt (cost 12), uploads validados por MIME e tamanho, e código sensível fora da raiz web.
Impacto
Resultados
- Em produção, com pintores, lojas e equipe reais operando
- De piloto regional a arquitetura multi-regional aprovada pela diretoria para expansão nacional
- 7 perfis de acesso com permissões e escopos distintos
- Documentação completa: manual de uso, guia do pintor, regulamento, apresentação executiva e plano de conteúdo
- Vitrine + diretório: recursos que geram trabalho para o pintor e marketing orgânico para a marca
Retrospectiva
O que esse projeto me ensinou
Foi um projeto end-to-end de verdade: levantamento de requisitos com a diretoria, modelagem de dados, desenvolvimento full-stack, deploy, DNS, SSL, backup, e também produto, conteúdo e apresentação para a liderança.
O aprendizado mais forte não foi técnico: foi entender que o requisito que chega quase nunca é o problema real. O pedido era “um sistema de pontos”. O que resolvia o problema era dar visibilidade e reconhecimento a um profissional invisibilizado pela indústria. As features que mais geraram valor (a vitrine, o diretório, a trilha de capacitação) nasceram dessa conversa, não do briefing inicial.