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, arquitetura em camadas própria (autoload PSR-4)
- Banco
- MySQL/MariaDB — 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 — 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.