Empresas e unidades: separar os dados de cada cliente

Três palavras aparecem em toda esta página. Vale fixar o sentido de cada uma antes de ligar qualquer opção:

Separar por empresa e separar por unidade são opções independentes. Um app pode usar só uma delas, as duas juntas ou nenhuma. Empresas e unidades são cadastradas dentro do app publicado, em Administração › Empresas e Administração › Unidades; o passo a passo dessas telas está em Login, usuários e unidades, seção 06.

Responda pela situação dos seus clientes. A primeira coluna é o que você tem; as outras dizem o que ligar.

Toda a configuração fica num painel do projeto, no MadBuilder. Há três caminhos para abri-lo:

• No menu lateral do Studio, grupo Geração & ferramentas, item Tenancy & Banco.
• Em Propriedades do projeto, seção Tenancy & Banco, botão Abrir configuração.
• Na tela de Modelos de dados, pelo selo Tenancy: … no alto. Ele mostra o modo atual e as colunas que o painel acrescenta (tenant_id, unit_id).

MadBuilder › Tenancy & Banco

O painel grava sozinho a cada alteração: no alto aparece Salvando… e depois Salvo, sem botão de salvar. São quatro blocos:

O bloco Tenancy (cliente) tem três cartões. Eles mudam onde os dados de cada empresa ficam guardados:

Pool: um banco, registros marcados com a empresa

O Pool pede dois passos no bloco 2. Só escolher o cartão não separa nada:

1. Clique no cartão Pool.
2. Ligue Isolar por linha (tenant_id): "Liga o filtro automático por tenant nos models data-plane".
3. Em Conexões isoladas por tenant, marque os modelos de dados cujas tabelas devem ser separadas por empresa. Os selos iam e log aparecem travados.

MadBuilder › Tenancy & Banco › Tenancy (cliente)

O que acontece nos modelos marcados:

• Toda tabela ganha a coluna tenant_id, inclusive as que já existiam. As tabelas criadas depois já nascem com ela.
• Nas telas do app, cada listagem, campo de seleção, filtro e dashboard mostra só os registros da empresa de quem está logado. Vale também para quem é administrador.
• Todo registro novo é gravado com a empresa de quem está logado. A coluna não aparece nos formulários e nas listagens geradas, e o formulário não consegue escolher outra empresa: um valor de tenant_id enviado por ele é ignorado. Para cadastrar em outra empresa, a pessoa troca de empresa no topo do app (pergunta frequente).
• Coluna marcada como única passa a ser única dentro da empresa: duas empresas podem usar o mesmo código.

Dedicado (Bridge): um banco por empresa

No Dedicado, cada empresa tem um banco próprio. O app escolhe o banco no login, pela empresa da pessoa, e passa a ler e gravar só nele. Usuários, permissões e auditoria continuam num banco compartilhado.

1. Clique no cartão Dedicado (Bridge). No bloco 2b, Banco próprio por empresa aparece ligado e travado: o cartão já liga essa opção.
2. Em Conexões de tenant (allowlist), adicione uma linha por banco de empresa. O Nome lógico segue o formato tenant_<nome>, só com letras minúsculas, números e _ (ex.: tenant_bemviver). Na coluna Banco, informe o nome do banco dessa empresa.
3. Crie os bancos. Em Comandos, o painel lista um comando por linha para rodar no app instalado. Pelo próprio app, a lista Administração › Empresas ganha a ação Provisionar banco para as empresas que ainda não têm banco.

MadBuilder › Tenancy & Banco › Tenancy (cliente)

No app, o cadastro da empresa ganha o campo Conexão, preenchido sozinho ao provisionar ("Deixe em branco para empresas em banco único"), e a linha Modo de tenancy acima da lista de empresas passa a dizer Bridge (banco por empresa).

A unidade é uma camada dentro da empresa. Com ela ligada, cada registro guarda a unidade dona, e cada pessoa trabalha numa unidade por vez. O bloco Unidade (filial) tem quatro opções:

MadBuilder › Tenancy & Banco › Unidade (filial)

O que muda com Multi-unidade ligado

• Nas tabelas. Todas as tabelas dos modelos de dados do projeto ganham a coluna unit_id, inclusive as que já existiam. Ela não aparece nos formulários e nas listagens geradas: o app preenche sozinho.
• No login. Quem tem vínculo com mais de uma unidade escolhe em qual entrar, na janela Escolha a unidade. Quem tem uma só entra direto.
• No topo do app. Um seletor mostra a unidade ativa e troca para outra sem sair. Com mais de uma empresa, o seletor é de empresa e o nome da unidade fica ao lado, clicável. No menu do perfil há também Trocar Unidade. As telas estão em Login, usuários e unidades, seção 04.
• Nas telas. Listagem, campo de seleção (combo, busca, rádio, lista de marcação), combo dependente, filtro de coluna, filtro avançado e dashboard mostram só os registros da unidade ativa. Com Ver todas as unidades do usuário, mostram os de todas as unidades da pessoa.
• No cadastro. O registro novo vai para a unidade ativa. A edição mantém a unidade que o registro já tinha, mesmo que a pessoa esteja em outra unidade.
• Nos códigos únicos. Uma coluna única passa a ser única dentro da unidade: duas filiais podem ter o pedido PED-0001.

Por padrão, a pessoa vê só os registros da unidade ativa. Para consultar outra filial, ela troca de unidade no topo. Em muitos negócios isso atrapalha: a gerente regional quer ver os atendimentos das duas filiais na mesma lista. É para isso que existe Ver todas as unidades do usuário, no bloco 2b.

Regras do modo "todas as unidades"

Algumas partes do app continuam na unidade ativa nos dois modos: os filtros salvos da listagem, os painéis de conciliação, o PDV, o acesso do agente de IA e as telas em que o próprio desenvolvedor pediu o filtro da unidade ativa (por exemplo, o calendário com filtro de unidade ligado).

As regras abaixo valem sem nenhuma configuração extra, em qualquer tela gerada:

• Ninguém grava na unidade dos outros. Se um formulário tentar gravar um registro numa unidade de que a pessoa não participa, o app recusa com a mensagem "Você não tem acesso à unidade escolhida", no campo da unidade ou num aviso no canto da tela.
• O formulário não escolhe a empresa. No Pool, o registro é sempre gravado na empresa de quem está logado.
• Validações enxergam o mesmo que a tela. "Este código já está sendo utilizado" só considera os registros que a pessoa enxerga, e um campo de seleção só aceita um registro que ela poderia escolher. Nenhuma mensagem revela que um código existe em outro cliente.
• Administrador também é separado. Quem tem perfil de administrador vê os dados da empresa e da unidade em que entrou, como todo mundo. Para ver outra empresa ou unidade, troca no topo.
• Usuários e permissões são do app inteiro. Cadastro de pessoa, perfis e auditoria nunca são separados por empresa: é o que permite a mesma pessoa ter vínculo em vários clientes.

O painel grava a configuração no projeto; o app só muda depois de publicado.

1. Republique o projeto. É a publicação que cria as colunas novas no banco, ajusta os índices únicos e atualiza as regras das telas.
2. No MadCloud, se a Hospedagem mostrar "O app está com variáveis da plataforma desatualizadas", clique em Sincronizar agora.
3. Em servidor próprio ou pelo download do projeto, as variáveis vêm no .env gerado, num bloco "Multi-tenancy & Banco". Quando há banco externo, comandos ou avisos, o pacote traz também um SETUP-INSTALL.md com o passo a passo. Ver Instalação em servidor próprio.

Telas geradas já respeitam empresa e unidade. Esta seção é para quem escreve código PHP próprio no projeto (códigos, serviços, relatórios com SQL).

• Os models das tabelas com unit_id ou tenant_id já filtram sozinhos, no modo configurado. Não acrescente um filtro pela unidade ativa num model desses: no modo "todas as unidades", ele esconderia registros que a pessoa deveria ver.
• Em consulta direta ao banco (sem model), use a lista de unidades que a leitura enxerga.

// Unidade ativa (onde os cadastros novos entram)
$unidade = \Mad\Database\UnitContext::id();

// Unidades que a leitura enxerga: a ativa, ou todas as da pessoa
$unidades = \Mad\Database\UnitContext::readIds();   // null = sem filtro

$total = DB::table('atendimento')
    ->when($unidades !== null, fn ($q) => $q->whereIn('unit_id', $unidades))
    ->count();

// Empresa de quem está logado
$empresa = \Mad\Database\TenantContext::id();

No PDF exportado, os campos {UNIT_NAME} e {TENANT_NAME} trazem o nome da unidade e da empresa: ver Cabeçalho e rodapé do PDF.