Módulo de Franchising, Comissões e Dashboards Interativas

Uma comissão não é um número. É uma pilha de números.

A percentagem de um colaborador vive dentro da percentagem de um franchising. Um team leader leva uma fatia do que a sua equipa produz. Um pagamento é prometido num momento mas só se torna devido quando um processo atinge um estado que o negócio define – às vezes meses depois.

Quando essa pilha se torna real, duas coisas partem. Ninguém consegue dizer com certeza que percentagem se aplicou a um negócio concreto depois de as tabelas terem mudado. E ninguém consegue dizer que negócios tecnicamente ganhos foram de facto pagos.

As folhas de cálculo sobrevivem aos primeiros escritórios. Não sobrevivem ao quinto franchising, à terceira revisão de percentagens, nem à primeira discussão sobre uma comissão que devia ter sido liquidada há três meses.

O que foi construído

Quatro áreas ligadas entre si, entregues por fases sobre o site do cliente já em produção – e não como reconstrução de raiz. Sem paragem de serviço.

• Rede e perfis. Registo de franchisings, página de angariação, dashboard por franchising. Perfis – Admin, Master, Team Leader, Colaborador – com permissões próprias. Objetivos mensais por colaborador e por franchising.
• Motor de comissões. Uma tabela mestre mais uma tabela configurável de forma independente por cada franchising. Percentagens por colaborador e por banco. Uma fatia de team leader sobreposta. Cálculo em tempo real visível em cada processo.
• Pipeline e liquidação. Banco, estado interno e campos de detalhe específicos do estado em cada processo. Comissão congelada automaticamente quando um processo atinge um estado que desencadeia pagamento. Um indicador de pago/pendente independente, com histórico próprio de alterações.
• Relatórios e supervisão. Filtráveis por franchising, colaborador e período, com exportação para Excel. Pipeline versus valores fechados. Evolução do financiamento mês a mês. Volume por tipologia de crédito e por banco parceiro. Ranking de colaboradores face ao objetivo. Vista imediata de tudo o que está por liquidar.

Arquitetura

A rede já tinha o site público e o portal de franchisados em WordPress, e reconstruir não estava em cima da mesa. O motor foi por isso construído como seis módulos que cooperam, e não como um monólito: uma API em PHP e uma base de dados MySQL dedicadas, por trás da instalação WordPress existente, com uma aplicação React feita à medida montada nela e a comunicar com a API através do proxy REST do WordPress.

A divisão mantém cada área testável e substituível isoladamente. A matemática das comissões e as regras de auditoria vivem inteiramente na API e na base de dados, independentes do WordPress; o plugin e a aplicação React apenas veem o resultado da API. Nada no motor de comissões depende do CMS por baixo.

Decisões de engenharia

1. Resolução sem fallback silencioso

A percentagem efetiva resolve-se colaborador → franchising, e para aí. Uma percentagem de franchising em falta ou a 0% nunca é preenchida a partir da tabela mestre – significa que a comissão não se aplica.

Uma lacuna de configuração aparece como um N/A visível, nunca como um número adivinhado. Um sistema que adivinha produz pagamentos errados que ninguém deteta.

2. Cristalização no momento do pagamento

A comissão é calculada e congelada no instante em que um processo entra num estado que desencadeia pagamento – fatias da empresa, do master, do team leader e do colaborador, mais as percentagens exatas e as identidades por trás delas.

Uma alteração de percentagens no mês seguinte nunca reescreve o que foi prometido num negócio já comprometido. É esta decisão que torna possível responder, meses depois, à pergunta «que percentagem se aplicou a este processo?».

3. Dois padrões de auditoria, conforme o que é versionado

As tabelas de percentagens usam versionamento completo por soft-delete e reinserção, porque a linha inteira é aquilo que tem história.

Um único indicador de liquidação recebe em vez disso um registo append-only mais leve – quem o mudou, para que valor, quando. Voltar a versionar um snapshot de comissão já congelado porque um booleano mudou seria desperdício e ruído no histórico.

4. Unicidade garantida pela base de dados

O MySQL não tem índices únicos parciais. A regra «uma linha ativa por chave, as antigas ficam para histórico» é imposta com uma coluna gerada e armazenada que resolve para a chave apenas enquanto a linha está viva.

A base de dados recusa uma linha ativa duplicada. A alternativa seria código de aplicação que se pode esquecer de verificar – e que, um dia, esquece-se.

5. Disciplina de esquema sem paragens

Em produção desde a terceira fase. Cada alteração é entregue como a sua própria migração datada e segura para reaplicação – nunca uma edição manual, nunca uma reconstrução. A história completa do esquema é revisível uma migração de cada vez.

Para quem é que isto serve

Nada disto é específico da intermediação de crédito. A forma é estrutural: vender através de escritórios franchisados, mediadores ou agentes; percentagens que variam por escritório, pessoa, produto ou parceiro e que mudam ao longo do tempo; a necessidade de responder meses depois sobre que percentagem se aplicou a um negócio concreto; pagamentos faseados que acabam por exigir que alguém pergunte se um deles foi mesmo pago.

Setores adjacentes onde a mesma forma aparece: mediação de crédito habitação, agentes de seguros, redes de franchising imobiliário, redes de distribuidores de equipamento e de energia solar, e programas de referência e afiliação por escalões.