ADR-002 — E-mail único global, usuário local
Data: 2026-08-09 (virada multi-tenant) · Situação: vigente
Contexto
Com um banco por organização, a tabela users passou a viver dentro de
cada app_<org>. Isso preserva todas as chaves estrangeiras e telas existentes — mas cria um
problema no login: quando alguém digita o e-mail, ainda não se sabe em qual banco procurar.
Mover users inteira para o plano de controle resolveria o login e quebraria dezenas de FKs
(perfis, ofertas, widgets, auditoria) em ~100 arquivos.
Decisão
A users continua por organização. Para o plano de controle vai apenas um diretório fino:
ent-user-directory — email → (org_id, user_id), com e-mail único em toda a plataforma.
O login vira: e-mail → diretório → organização → app_<org>.users → verificação local (bcrypt) →
JWT com org_id e org. Ver flx-resolucao-tenant.
Por quê
- Custo de migração próximo de zero. Nenhuma FK quebrou.
- O diretório é minúsculo — três colunas úteis. Consulta de login é uma leitura indexada.
- O caminho para multi-org já está aberto: um usuário em duas organizações seriam duas linhas no diretório. Nada precisa mudar de forma.
Consequências
Boas:
- Login por e-mail funciona sem o usuário saber o que é uma organização.
- A unicidade global impede o cenário confuso de duas contas com o mesmo e-mail em clientes diferentes.
Ruins, e são reais:
- Sincronia manual. Criar, editar ou excluir usuário no portal precisa manter o diretório em dia. Não há FK entre bancos para garantir isso — é responsabilidade de código. É o ponto de falha mais provável de toda esta decisão.
- Um e-mail, uma organização. Um consultor que atenda dois clientes não consegue ter a mesma conta nos dois. O desenho suporta; o login não sabe escolher.
- Login por username depende da organização. Sem
@não há o que procurar no diretório, então cai no slug informado — e a tela-login não tem esse campo, o que amarra username à organização padrão.
O que isso substituiu
No sistema de origem havia credencial externa por usuário e um botão “Unificar” para reconciliar a mesma pessoa entre dois sistemas. Nada disso existe mais: a autenticação é sempre local e a identidade é única por construção. Ver adr-003-erp-nunca-ao-vivo.