Funcionalidades do app · Dados

Empresas e unidades: separar os dados de cada cliente

Um app feito no MadBuilder pode atender vários clientes ao mesmo tempo sem que um veja os dados do outro. Esta página explica os dois jeitos de separar, por empresa e por unidade, como escolher entre eles no painel Tenancy & Banco e o que muda nas telas do app depois de publicar.

Dono do app MadBuilder › Tenancy & Banco Plano Advanced, Pro e Pro IA
01

Empresa, unidade e usuário

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

TermoO que éExemplo
Empresa tenantO cliente que contrata o seu sistema. É o limite mais forte: os dados de uma empresa nunca aparecem para outra.Rede Bem Viver, Clínica Vida Plena.
Unidade filialUma filial dentro de uma empresa. Toda unidade pertence a uma empresa só.Bem Viver — Centro e Bem Viver — Norte, as duas da Rede Bem Viver.
UsuárioUma pessoa com login. Ela é vinculada a uma ou mais unidades e trabalha em uma de cada vez, a unidade ativa.Letícia, que atende nas duas unidades da Rede Bem Viver.
Empresa Rede Bem Viver Unidade Bem Viver — Centro Unidade Bem Viver — Norte Empresa Clínica Vida Plena Unidade Vida Plena — Sede Letícia vínculo nas duas unidades; trabalha em uma de cada vez
A empresa contém as unidades, e o usuário se vincula a unidades. A empresa de uma pessoa é a empresa das unidades dela.

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.

Cadastro não é isolamento. Um app recém-criado já tem as telas de Empresas e Unidades, com uma empresa e uma unidade chamadas Default. Mas, enquanto nada for ligado no painel Tenancy & Banco, todos os usuários enxergam todos os registros das suas tabelas. É o painel que manda o app separar os dados.
02

Qual configuração escolher

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

SituaçãoTenancy (cliente)Multi-unidade
Sistema interno de uma organização só, sem filiais.Cliente únicoDesligado
Uma organização com filiais que não devem ver os registros umas das outras.Cliente únicoLigado
Sistema vendido para muitos clientes (SaaS), cada cliente com uma equipe só.Cliente único (cada cliente é uma unidade) ou PoolLigado (com Cliente único)
Sistema vendido para redes com filiais: a rede não pode ver outra rede, e as filiais separam os próprios registros.PoolLigado
Cliente que exige os dados num banco separado (contrato, volume, exigência legal).Dedicado (Bridge)Conforme as filiais
Começando um SaaS? O caminho mais simples é Cliente único + Multi-unidade: cada cliente vira uma unidade, e o Licenciamento dá a cada unidade um plano. Passe para Pool quando um cliente tiver filiais que precisam ficar agrupadas numa empresa.
03

O painel Tenancy & Banco

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
Painel Tenancy & Banco com os blocos 1 Banco, 2 Tenancy (cliente), 2b Unidade (filial) e 3 IA · acesso, e à direita a coluna O que isto gera com o .env
O painel aberto num projeto novo: banco SQLite, Cliente único e nenhuma separação ligada. À direita, O que isto gera mostra as variáveis do app, os comandos e os avisos, e se atualiza a cada mudança.

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

BlocoO que defineNesta página
1 · BancoOnde as tabelas ficam: SQLite, MySQL, MariaDB ou PostgreSQL, os dados de acesso ao servidor, conexão segura (SSL/TLS) e um nome de banco por modelo de dados.Não é assunto desta página.
2 · Tenancy (cliente)Como as empresas são separadas: Cliente único, Pool ou Dedicado (Bridge).Seção 04
2b · Unidade (filial)Separação por unidade, o modo de leitura (só a ativa ou todas), o banco por empresa e o licenciamento.Seções 05, 06 e 07
3 · IA · acessoSó um atalho para o painel MCP Server, onde se define o que o agente de IA pode ler e alterar.—
Plano. O painel faz parte dos planos Advanced, Pro e Pro IA. Nos outros ele aparece com cadeado e a mensagem "Disponível no plano Advanced", com o botão Ver planos.
Os identificadores iam e log ficam travados. O bloco 2 mostra "Control-plane (travado)" com os selos iam e log: usuários, permissões e auditoria são sempre compartilhados pelo app inteiro. É isso que permite a mesma pessoa ter vínculo em várias empresas.
04

Separar por empresa (bloco 2 · Tenancy)

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

Cliente único um banco todos veem tudo Pool um banco cada registro leva a empresa dona tenant_id Dedicado (Bridge) banco da Bem Viver banco da Vida Plena compartilhado: usuários e auditoria um banco por empresa
Os três cartões do bloco 2. Em azul e laranja, os dados de duas empresas diferentes.
CartãoComo guardaQuando usar
Cliente único padrãoUm banco, sem separação por empresa.App interno, ou SaaS em que cada cliente é uma unidade (seção 05).
PoolUm banco para todas as empresas. Cada registro guarda a empresa dona, e o app só mostra os da empresa de quem está logado.Muitos clientes, custo baixo, um banco só para administrar.
Dedicado (Bridge)Um banco separado para cada empresa. Usuários, permissões e auditoria continuam num banco compartilhado.Cliente que exige isolamento físico, ou muito volume por cliente.

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)
Bloco Tenancy (cliente) com o cartão Pool selecionado, Isolar por linha ligado e o modelo clinica marcado em Conexões isoladas por tenant; à direita o .env com MAD_TENANT_ROW_SCOPE_ENABLED=true
Pool configurado: cartão Pool, Isolar por linha ligado e o modelo clinica marcado. Em O que isto gera, a linha MAD_TENANT_ROW_SCOPE_ENABLED=true é o filtro por empresa ligado no app.

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, a menos que a opção Administrador vê todas as empresas esteja ligada (seção 08).
  • 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 escolhe outra empresa: um valor de tenant_id enviado por ele é ignorado (o painel de propriedades do Studio avisa ao selecionar um campo assim). Para cadastrar em outra empresa, a pessoa troca de empresa no topo do app, ou o código do Salvar escolhe por ela (pergunta frequente).
  • Coluna marcada como única passa a ser única dentro da empresa: duas empresas podem usar o mesmo código.
Sem modelo marcado, nada é separado. Com Isolar por linha ligado e nenhum modelo em Conexões isoladas por tenant, nenhuma tabela recebe a coluna. A coluna Avisos do painel avisa: "Pool sem nenhum modelo marcado em "Conexões isoladas por tenant": nenhuma tabela recebe tenant_id e os dados NÃO ficam separados por empresa — marque ao menos um modelo."

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)
Bloco Tenancy (cliente) com o cartão Dedicado (Bridge) selecionado e a allowlist com tenant_bemviver e tenant_vidaplena; à direita o .env com MAD_MULTI_DATABASE=1 e os comandos de provisionamento
Dedicado com duas empresas na allowlist. Em Comandos, um php artisan mad:tenant:provision … por empresa, com o nome do banco informado na linha.
Mesmo servidor do banco principal. Da linha da allowlist vale só o nome do banco: o banco da empresa é criado no mesmo servidor e com a mesma engine do bloco 1 · Banco. Se a linha informar outro host ou outra engine, o painel avisa que esses campos não são usados.

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).

05

Separar por unidade (bloco 2b · Unidade)

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 cinco opções:

MadBuilder › Tenancy & Banco › Unidade (filial)
Bloco Unidade (filial) com Multi-unidade e Ver todas as unidades do usuário ligados, Banco próprio por empresa e Licenciamento desligados
O bloco 2b com Multi-unidade e Ver todas as unidades do usuário ligados. As outras opções só ficam disponíveis com Multi-unidade ligado (o licenciamento também aceita Pool ou Dedicado). A exceção é Administrador vê todas as empresas, que só fica travada com o Licenciamento ligado.
OpçãoO que faz
Multi-unidadeLiga a separação por unidade: coluna unit_id nas tabelas, escolha da unidade no login e troca de unidade no topo do app.
Ver todas as unidades do usuárioListagens, campos de seleção e filtros mostram os registros de todas as unidades da pessoa, sem trocar de unidade. Detalhes na seção 07.
Administrador vê todas as empresasO administrador do app vê nas listagens os registros de todas as empresas e unidades, sem trocar no topo. Desligada por padrão; fica travada com o Licenciamento ligado. Detalhes na seção 08.
Banco próprio por empresaCada empresa, com as filiais dela, usa um banco separado. É o mesmo efeito do cartão Dedicado, que já liga esta opção.
LicenciamentoTransforma cada unidade ou empresa num cliente com plano, módulos, validade e limite de usuários. Ver Licenciamento.

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, exceto as marcadas como compartilhadas (veja abaixo) ou como tabelas da empresa (idem). 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.
Ligando num app que já tem registros. Os registros que existiam antes ficam com a unidade vazia e deixam de aparecer nas telas, porque nenhuma unidade é dona deles. Antes de ligar num app em uso, planeje preencher a coluna unit_id desses registros com o código da unidade dona (por exemplo, com um UPDATE no banco do app). O mesmo vale para tenant_id ao ligar o Pool.
Empresa e unidade juntas Com Pool e Multi-unidade ligados, a empresa separa os clientes e a unidade separa as filiais de cada cliente. A pessoa só vê unidades da empresa em que entrou.

Tabelas de apoio compartilhadas

Algumas tabelas são iguais para todo mundo: estados, cidades, status de uma ordem de serviço, formas de pagamento. Separá-las por unidade ou por empresa só atrapalha: cada filial teria de cadastrar os mesmos estados, e os registros que já existiam ficariam sem dono e sumiriam dos campos de seleção. Marque essas tabelas como compartilhadas: elas ficam sem separação por unidade e por empresa, e todos veem os mesmos registros.

  1. Abra o painel Tenancy & Banco. Com Multi-unidade ligado, ou com o cartão Pool ou Dedicado escolhido, aparece o bloco Tabelas compartilhadas.
  2. Clique no nome de cada tabela de apoio. A tabela marcada fica destacada e a mudança é salva na hora; clique de novo para voltar a separar. Com muitas tabelas, use a caixa Filtrar tabelas….
  3. Confira a coluna O que isto gera: a linha MAD_TENANT_SHARED_TABLES lista as tabelas marcadas. Depois, republique o projeto (seção 09).
ModoO que acontece com a tabela compartilhada
Multi-unidade e PoolA tabela não recebe as colunas unit_id e tenant_id (se já tinha, elas saem na próxima publicação). Todas as unidades e empresas leem e gravam os mesmos registros, e um código único, como a sigla do estado, vale para o app inteiro.
DedicadoCada empresa continua com o banco dela. Ao Provisionar banco de uma empresa, os registros das tabelas compartilhadas são copiados para o banco novo, para que os campos de seleção já nasçam preenchidos.
Só tabelas de apoio. Uma tabela compartilhada não deve apontar para uma tabela separada por unidade ou empresa (por exemplo, uma cidade ligada a um cliente): todos veriam a cidade, mas o vínculo levaria a um registro que as outras unidades não enxergam. O painel avisa quando isso acontece. Cadastros do negócio, como clientes, pedidos e ordens de serviço, continuam separados. Para um cadastro único da empresa, use as tabelas da empresa.

Tabelas da empresa: um cadastro para todas as filiais

Alguns cadastros são da empresa, não da filial: o catálogo de produtos, os clientes, os fornecedores. Com Multi-unidade ligado, cada filial teria a sua lista, e o produto cadastrado na matriz não apareceria na filial. Marque essas tabelas como tabelas da empresa: elas ficam sem a coluna unit_id e todas as unidades da mesma empresa veem e gravam os mesmos registros. A separação entre empresas continua: no Pool a tabela mantém o tenant_id, e no Dedicado cada empresa segue com o banco dela.

  1. Abra o painel Tenancy & Banco. Com Multi-unidade ligado, aparece o bloco Tabelas da empresa, acima de Tabelas compartilhadas.
  2. Clique no nome de cada cadastro da empresa, por exemplo produto. A mudança é salva na hora; clique de novo para voltar a separar por unidade. Uma tabela fica em um bloco só: as tracejadas estão marcadas no outro bloco, e clicar nelas as traz para este.
  3. Republique o projeto (seção 09). A coluna unit_id sai da tabela na publicação.
Marcação da tabelaUnidades da mesma empresaOutras empresasExemplos
Nenhuma (padrão)Cada unidade vê só os seusNão veempedido, venda, estoque, ordem de serviço
Tabela da empresaTodas veem os mesmosNão veemproduto, cliente, fornecedor
CompartilhadaTodas veem os mesmosVeem os mesmosestado, cidade, status
Não apague a coluna à mão. Tirar o unit_id direto no modelo de dados não dura: a plataforma o recoloca na próxima alteração do painel. Use o bloco Tabelas da empresa. Se a tabela da empresa apontar para uma tabela que segue separada por unidade (um produto ligado a uma categoria da filial, por exemplo), o painel avisa: na unidade que não cadastrou a categoria, o produto aparece sem ela. Marque a outra tabela também como da empresa, ou como compartilhada.
06

Dados da unidade: CNPJ, endereço e certificado de cada filial

A unidade do app guarda só o nome, a empresa, a situação e o tema. O que muda de uma filial para outra, como CNPJ, inscrição estadual, endereço e certificado digital para nota fiscal, fica numa tabela do seu modelo de dados, com uma linha por unidade. Você aponta essa tabela no painel e o app passa a abri-la pela tela Unidades. Não é preciso mudar a tela Unidades nem recriar as filiais numa tabela própria.

  1. No modelo de dados, crie a tabela com o que cada filial precisa, por exemplo dados_filial com cnpj, inscricao_estadual, endereco, cidade, certificado e senha_certificado, e gere o formulário dela.
  2. Abra o painel Tenancy & Banco e o bloco 2b · Unidade (filial), com Multi-unidade ligado. No fim do bloco fica Dados da unidade.
  3. Em Tabela, escolha a tabela. Em Coluna que liga à unidade, deixe Criar unidade_id, ou escolha uma coluna de número inteiro que já guarde o código da unidade. Em Formulário, escolha o formulário da tabela.
  4. Clique em Aplicar. Uma janela lista o que vai mudar no modelo de dados; confira e confirme. Depois, republique o projeto (seção 09).

O que a plataforma faz ao aplicar

MudançaPara quê
Coluna unidade_idCriada na tabela (número inteiro, rótulo Unidade) e ligada à unidade do app. Na listagem, mostra o nome da unidade. Se a tabela já tem uma unidade_id inteira, ela é aproveitada.
Índice únicoNa coluna de ligação: uma linha por unidade.
Tabela da empresaA tabela vira tabela da empresa e perde a coluna unit_id: a tela Unidades precisa achar os dados de todas as filiais, não só os da unidade ativa. Enquanto ela for a tabela de Dados da unidade, a marca fica travada nos blocos Tabelas da empresa e Tabelas compartilhadas.
Quando a confirmação vem em vermelho. Ou a tabela tinha a coluna unit_id e ela vai sair (o registro deixa de guardar a unidade que o criou), ou os dados iniciais da tabela têm valores repetidos na coluna escolhida e o índice único recusaria essas linhas na carga. Leia a janela antes de confirmar. Se uma página do projeto usa o unit_id da tabela, ele fica, e o painel avisa até você tirá-lo da página.

Abaixo das três escolhas, o bloco mostra o que está aplicado e os avisos: tabela, coluna ou formulário que sumiu, tabela que deixou de ser da empresa, versão do Mad Framework. O formulário não precisa do campo unidade_id: o registro aberto pela ação Dados já nasce ligado à unidade. Trocar só o formulário não mexe no modelo de dados. Remover desfaz a escolha; a tabela, a coluna e os registros continuam no modelo.

Onde aparece no app

  • Administração › Unidades. Cada linha ganha a ação Dados. Na primeira vez, ela abre o cadastro novo já ligado à unidade, mesmo que o formulário não mostre o campo unidade_id; depois, abre a edição.
  • Formulário da unidade. Ao lado de Salvar, o botão Dados da unidade abre os mesmos dados. Com alteração não salva na unidade, ele pergunta antes de descartar.
  • Várias empresas. Quando os dados são de cada empresa (banco próprio por empresa, ou Pool com a tabela separada por empresa), só aparecem as unidades da empresa em que se está.
Versão do Mad Framework. O recurso precisa do Mad Framework 5.201.0 ou mais novo no app. Com versão anterior, o app ignora a configuração, e o bloco do painel avisa.

Usar os dados em regra, relatório ou PDF

use Mad\Database\UnitProfile;

$dados = UnitProfile::current();      // dados da unidade ativa, ou null
$cnpj  = $dados?->cnpj;               // por exemplo, 12.345.678/0001-90
$outra = UnitProfile::for($unitId);   // dados de uma unidade qualquer

current() devolve null quando a unidade ainda não tem dados ou o recurso está desligado: trate o vazio antes de emitir uma nota ou montar um cabeçalho.

Certificado digital A1

  • Arquivo. Use um campo de arquivo com Tipo de gravação em Armazenar caminho do arquivo na coluna e uma pasta própria, como certificados. O arquivo fica na área privada do servidor e só sai pelo download do app, para quem está logado (Upload de arquivos).
  • Senha. Guarde-a cifrada: coluna de texto longo e, no código do Model da tabela, o tipo encrypted. O banco guarda o texto cifrado com a chave do app, e o código lê a senha aberta.
protected $casts = [
    'senha_certificado' => 'encrypted',
];
Cuidados com a senha. Com $casts declarado por você, a plataforma deixa de declarar o dela: inclua no mesmo bloco as colunas Sim/Não da tabela, como 'ativo' => 'boolean'. Não mostre a senha em listagem nem em PDF. Trocar a chave do app (APP_KEY) torna as senhas já gravadas ilegíveis: cadastre-as de novo.
07

Ver só a unidade ativa ou todas as do usuário

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.

Só a unidade ativa (padrão) Todas as unidades do usuário Letícia, ativa em Bem Viver — Centro Letícia, ativa em Bem Viver — Centro ATD-101Bem Viver — Centro ATD-102Bem Viver — Norte ATD-103Bem Viver — Norte ATD-104Bem Viver — Sul ATD-101Bem Viver — Centro ATD-102Bem Viver — Norte ATD-103Bem Viver — Norte ATD-104Bem Viver — Sul Letícia tem vínculo com Centro e Norte. A unidade Sul não é dela: nunca aparece.
A mesma listagem nos dois modos. Em destaque, o que aparece para Letícia.

Regras do modo "todas as unidades"

SituaçãoSó a unidade ativaTodas as unidades do usuário
Listagem, campo de seleção, combo dependente, filtros, dashboardsRegistros da unidade ativa.Registros de todas as unidades da pessoa.
Cadastrar um registro novoVai para a unidade ativa, a que está no seletor do topo.
Editar um registro de outra unidadeNão acontece: o registro não aparece.O registro continua na unidade dele.
Escolher um registro de outra filial num campo de seleção (ex.: o cliente atendido no Norte)Não aparece na lista.Aparece e é aceito ao salvar.
Código único (ex.: número do atendimento)Pode repetir em outra unidade.É recusado se já existe em qualquer unidade da pessoa. Em unidade de que ela não participa, pode repetir.

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).

O seletor do topo continua valendo. No modo "todas as unidades", a unidade ativa define onde os cadastros novos entram, o menu, o perfil e a licença daquela unidade. Trocar de unidade não muda o que a lista mostra, só para onde vai o próximo cadastro.
08

O que o app garante

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, por padrão. Quem tem perfil de administrador vê os dados da empresa e da unidade em que entrou, como todo mundo: é o que protege um cliente do outro. Para ver outra empresa ou unidade, troca no topo, ou o dono do app liga Administrador vê todas as empresas (abaixo).
  • 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.

Administrador vê todas as empresas

No bloco Unidade (filial), a opção Administrador vê todas as empresas deixa o administrador do app consultar os dados de todos os clientes de uma vez. Ela vem desligada.

SituaçãoDesligada (padrão)Ligada
Listagens, campos de seleção, filtros e dashboards do administradorSó a empresa e a unidade ativas.Todas as empresas e unidades.
Cadastro novo feito pelo administradorVai para a empresa e a unidade ativas, as do seletor do topo.
Editar um registro de outra empresaNão acontece: o registro não aparece.O registro continua na empresa e na unidade dele; não dá para mudá-lo de empresa.
Demais usuários, inclusive o administrador de uma unidadeContinuam vendo só a empresa e a unidade ativas.
  • Quem é o administrador. O usuário admin que pertence ao grupo Administrador, o dono do app. O administrador de uma unidade (o administrador de cada cliente) nunca ganha essa visão.
  • Com o Licenciamento ligado a opção fica desligada. Num app vendido como SaaS, os clientes cadastram e administram os próprios usuários, e o app não tem como garantir com segurança quem é o dono. O painel avisa e trava a opção.
  • Continuam na empresa ativa: o agente de IA (chat, assistente e Central de Comando), a API, o PDV, os filtros salvos da listagem, os painéis de conciliação e as telas em que o desenvolvedor pediu o filtro da unidade ativa.
  • O seletor do topo continua valendo. Ele define onde entram os cadastros novos, o menu e o perfil.
Cuidado ao escolher em campos de seleção. Com a opção ligada, o administrador vê nos campos de seleção os registros de todas as empresas (por exemplo, clientes com o mesmo nome em empresas diferentes). Confira a empresa antes de salvar um cadastro novo.
09

Aplicar as mudanças no app

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.
Teste Online. O ambiente de teste recebe as opções de comportamento (Pool, Multi-unidade, todas as unidades, visão do administrador, licenciamento), mas roda com o banco dele. Os dados de acesso ao seu servidor e os bancos por empresa do Dedicado não são usados no teste.
Desligar não apaga colunas. Voltar para Cliente único ou desligar Multi-unidade não remove tenant_id e unit_id das tabelas nem os dados delas. Elas passam a ser colunas comuns: voltam a aparecer nos formulários e nas listagens gerados, e o app deixa de preenchê-las sozinho.
10

Em código 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 e a empresa que a leitura enxerga (readIds() e readId()): elas já consideram o modo "todas as unidades" e a visão do administrador.
// 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 (onde os cadastros novos entram)
$empresa = \Mad\Database\TenantContext::id();

// Empresa que a leitura filtra: null na visão de todas as empresas do administrador
$empresaLeitura = \Mad\Database\TenantContext::readId();

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.

11

Perguntas frequentes

Coloquei um campo de empresa no formulário, escolhi outra empresa e o registro foi gravado na minha.

É proposital. No Pool, o registro é sempre gravado na empresa de quem está logado, mesmo para o administrador: se o formulário pudesse escolher, qualquer pessoa gravaria dados no cliente de outra. E, mesmo que gravasse, o registro sumiria da sua lista, porque a leitura também é da sua empresa. Para cadastrar em outra empresa, troque de empresa no seletor do topo (a pessoa precisa ter vínculo com uma unidade dela) e cadastre de lá.

Para o administrador do app escolher a empresa no próprio formulário, troque no onSave da página (aba PHP) a linha $this->form->save($registro); por:

$empresa = [];
if (!$registro->exists && \Mad\Security\OwnerAdmin::session()) {
    $tenantId = (int) $this->form->get('tenant_id');
    if ($tenantId > 0 && \App\Models\Iam\Tenant::query()->whereKey($tenantId)->exists()) {
        $empresa['tenant_id'] = $tenantId;
    }
}
$this->form->save($registro, $empresa);

Use o nome da variável que já está no onSave no lugar de $registro. Só o administrador do app (login admin no grupo Administrador) escolhe a empresa, e só ao cadastrar: os outros usuários continuam gravando na empresa ativa, mesmo que mandem outro valor, e na edição o registro mantém a empresa dele. Sem a opção Administrador vê todas as empresas (seção 08), o registro gravado em outra empresa não aparece na lista dele.

Liguei o Pool e cada empresa continua vendo tudo.

Confira os três pontos: o cartão Pool selecionado, Isolar por linha (tenant_id) ligado e pelo menos um modelo marcado em Conexões isoladas por tenant. A coluna Avisos do painel aponta quando falta o último. Depois, republique o projeto (seção 09).

Liguei Multi-unidade e os registros antigos sumiram.

Eles continuam no banco, mas estão com a unidade vazia e nenhuma unidade é dona deles. Preencha a coluna unit_id desses registros com o código da unidade dona. Veja o aviso da seção 05.

Liguei Multi-unidade e os combos de estado/status ficaram vazios.

As tabelas de apoio ganharam a coluna de unidade, e os estados e status que já existiam ficaram sem unidade dona, por isso não aparecem para ninguém. Marque essas tabelas em Tabelas compartilhadas no painel Tenancy & Banco e republique o projeto: elas deixam de ser separadas e os registros voltam para todas as unidades (seção 05).

Quero que o cadastro de produtos seja um só para todas as filiais da empresa.

Marque a tabela em Tabelas da empresa no painel Tenancy & Banco e republique o projeto: ela perde a coluna unit_id e todas as unidades da empresa passam a ver os mesmos produtos, sem que uma empresa veja os da outra (seção 05). Não apague a coluna à mão: ela volta na próxima alteração do painel. Produtos já cadastrados em várias filiais passam a aparecer juntos; se havia o mesmo produto em duas filiais, ele aparece duas vezes até você excluir a cópia.

Sou administrador e não vejo os dados das outras empresas ou filiais.

Por padrão a separação vale para todos, inclusive para o administrador: é a proteção entre clientes. Troque de empresa ou de unidade no topo. Para o administrador do app ver todas as empresas e unidades de uma vez, ligue Administrador vê todas as empresas no painel Tenancy & Banco e republique (seção 08). Se a sua equipe precisa consultar várias filiais ao mesmo tempo, ligue Ver todas as unidades do usuário e vincule essas pessoas às unidades que devem ver (seção 07).

No modo "todas as unidades", o app diz que um código já está em uso, mas ele é de outra filial.

Nesse modo, a verificação de código único considera todas as unidades que a pessoa enxerga, porque ela vê os registros de todas na mesma lista. Use outro código, ou cadastre pela filial que não tem esse código com o modo "só a unidade ativa".

Posso mudar de Pool para Dedicado depois?

A configuração muda no painel, mas os dados já gravados não mudam de banco sozinhos: os registros do Pool ficam no banco principal. Trocar de modo com o app em uso exige migrar os dados de cada empresa para o banco dela. Escolha o modo antes de colocar clientes no app sempre que possível.

O agente de IA respeita empresa e unidade?

Nas telas, sim: o que ele consulta pelas telas do app segue as mesmas regras. O acesso direto aos dados pelo servidor MCP tem configuração própria, no painel MCP Server (bloco 3 · IA · acesso leva até lá). Mesmo com Administrador vê todas as empresas ligado, o agente continua só na empresa e na unidade ativas.

Preciso de CNPJ, endereço e certificado por filial. Onde ponho?

Numa tabela do seu modelo de dados, com uma linha por unidade, escolhida em Dados da unidade no painel Tenancy & Banco (seção 06). A tela Unidades do app ganha a ação Dados, que abre o formulário dessa tabela, e o código do projeto lê os dados da unidade ativa com UnitProfile::current(). Não copie a tela Unidades nem crie uma tabela de filiais separada das unidades: a troca de unidade, os vínculos dos usuários e a separação dos dados já vêm das unidades do app.

Onde cadastro as empresas e as unidades?

No app publicado, em Administração › Empresas e Administração › Unidades. Os vínculos de cada pessoa ficam na aba Unidades do cadastro do usuário. Passo a passo em Login, usuários e unidades.