Identidade ancorada em SaaS multi-tenant: quando uma pessoa veste muitos papéis

Estudo de caso · engenharia de plataformas. Metodologia Meta Dados (Genba · Kanso · Omotenashi).

Resumo. Em SaaS multi-tenant do domínio de serviços, o mesmo ser humano aparece como cliente, funcionário e dono — às vezes em vários estabelecimentos. Modelamos esse problema como um grafo de identidade ancorada: uma entidade global (a pessoa, ancorada pelo CPF) para a qual convergem vínculos denormalizados por tenant. Um experimento controlado, executado no banco de produção sob transação com ROLLBACK, mostra que a identidade unifica corretamente pelo CPF, mas que o dado denormalizado diverge silenciosamente entre tabelas e que uma classe de portas que cria login "inline" com CPF nulo parte um humano em duas identidades. Descrevemos duas intervenções verificadas e derivamos princípios reutilizáveis.

Plataformas de agendamento tratam três entidades como cidadãs de primeira classe — cliente, funcionário e estabelecimento — cada uma com sua chave natural: o cliente é reconhecido pelo telefone; o funcionário exige CPF; o estabelecimento identifica-se por CNPJ + e-mail (ou CPF, no autônomo). O problema surge porque essas três não são disjuntas: um cliente pode ser contratado e virar funcionário; um cliente pode abrir o próprio negócio; um dono pode agendar como cliente em outro salão. O sistema precisa que a informação trafegue entre as tabelas e se mantenha coerente, sem dado vital divergente em cadastros diferentes.

Tratamos a plataforma Marcaê como estudo de caso, mas o modelo e os achados são gerais: valem para qualquer SaaS onde um indivíduo assume papéis heterogêneos ao longo do tempo e entre inquilinos.

A ideia central é separar identidade de papel. A pessoa é uma entidade global — sem tenant, ancorada por uma chave forte (o CPF normalizado). Cada vínculo (cliente, funcionário, usuário) carrega uma cópia denormalizada dos campos vitais e uma chave estrangeira person_id apontando para a pessoa. Um gatilho de banco (vincular_pessoa_por_cpf) faz o find-or-create: ao gravar um vínculo com CPF válido, ele associa (ou cria) a pessoa daquele CPF e fixa o person_id. Sem CPF válido, a identidade é local ao tenant.

O modelo deve garantir dois invariantes. O primeiro é a unificação de identidade (I1): dois vínculos com o mesmo CPF válido apontam para a mesma pessoa. O segundo é a completude de papéis (I2): a pessoa conhece todos os papéis (tenant + papel) derivados de seus vínculos.

Para medir a coerência dos dados vitais (nome, e-mail, telefone), definimos uma taxa de divergência δ: a fração de pessoas em que algum campo vital tem mais de um valor não-vazio entre a âncora e seus vínculos. δ = 0 é o alvo — a pessoa é a fonte única da verdade.

Uma classe de portas cria a conta de login "inline" (junto com o cliente) usando uma ancoragem que ignora o CPF — na prática, cria uma pessoa nova, sempre. Se um humano passa por uma porta que ancora e por uma porta que não ancora, ele passa a ser representado por duas pessoas — violando I1. A taxa de partição σ cresce proporcionalmente ao uso das portas que não ancoram. É o defeito de maior severidade, porque, uma vez partida, a identidade só se reconcilia por operação manual/SQL.

Adotamos Genba — ir ao chão de fábrica: em vez de raciocinar sobre o modelo pretendido, exercitamos o modelo real. Duas técnicas: (1) leitura exaustiva das 15 portas onde nasce ou se transforma um cliente/funcionário/usuário/dono, registrando o que cada uma escreve e se ancora no CPF; (2) simulação transacional — instanciamos jornadas de identidade direto no banco de produção, dentro de BEGIN … ROLLBACK: o gatilho de ancoragem dispara de verdade, mas nada persiste.

Os resultados confirmaram o modelo e flagraram onde ele falha:

• I1 vale onde há ancoragem — uma pessoa percorrendo 5 papéis em 2 tenants gravou o mesmo person_id.
• O dado vital diverge — a âncora retém apenas o que viu primeiro: o e-mail que o funcionário recebeu depois nunca subiu para a pessoa; nomes divergiram entre as tabelas.
• σ = 0,5 no cenário controlado — 1 de 2 humanos foi partido em duas identidades pela porta que cria login inline.

Deduplicação como relação de equivalência. A regra antiga colapsava dois cadastros só pelo telefone; a nova exige telefone E nome normalizados. Assim, dois humanos distintos que compartilham um telefone (a mãe que agenda pelo próprio celular para o filho) deixam de ser fundidos por engano.

Mesclagem como fold campo-a-campo. Quando dois cadastros são de fato a mesma pessoa, a fusão deixa de ser "escolha um e descarte o outro" e passa a ser resolução por campo: uma tabela de diferenças apresenta cada campo divergente lado a lado, e o operador escolhe o valor que fica no sobrevivente. A ordem importa — religar as referências e arquivar os removidos antes de aplicar a escolha — senão o índice único parcial colide. Fusão que perde dado é regressão; fusão campo-a-campo preserva o melhor de cada cadastro.

O caso ilustra um trade-off recorrente: denormalizar campos vitais nos vínculos torna cada tela rápida e autônoma, ao custo de coerência; manter a pessoa como fonte única da verdade elimina a divergência, ao custo de acoplamento na leitura. Princípios reutilizáveis para qualquer plataforma multi-tenant com identidade compartilhada:

• Uma âncora, uma chave. Escolha uma entidade global e uma chave forte (CPF/CNPJ) e faça toda porta ancorar por ela. Uma única porta que ancora com nulo quebra a garantia.
• Ancoragem é invariante de estado, não de papel. Modele papéis como estados; a transição cliente→funcionário→dono deve preservar o person_id. "Transformar" um papel é adicionar um vínculo, nunca criar uma nova identidade.
• Decida coerência por campo. E-mail e telefone pedem fonte única; observações locais podem viver no vínculo. A métrica δ mede o custo de cada decisão.
• Deduplicação é uma relação de equivalência — escolha-a explicitamente. "Mesmo telefone" e "mesmo telefone e nome" produzem partições diferentes.
• Reconciliação é fold, não descarte.

A identidade do Marcaê unifica corretamente quando há CPF — a âncora funciona e é robusta a transições de papel. A classe de portas que partia a identidade foi fechada por gatilho no banco (a reconciliação garante que a conta siga a pessoa do CPF, a mesclagem deixou de gerar login órfão, e a âncora passou a aprender os vitais que lhe faltavam). Resta apenas a fonte-única-da-verdade plena — decisão de projeto, não defeito. O ganho não é só técnico: é a garantia de que um cliente que vira funcionário, ou um dono que vira cliente, continua sendo a mesma pessoa em todo o sistema.