Gestão de Acessos

Agências, tenants, tipos de usuário e perfis de permissão — como o sistema controla quem acessa o quê.

Visão Geral

O sistema possui uma hierarquia de 4 níveis que define o acesso e a organização dos sites:

Hierarquia do Sistema


      Master (super-admin)

        └── Agência (revenda white-label)

            └── Tenant (site/empresa do cliente)

                └── Usuário (quem opera o painel)

Entidade	O que é	Quem gerencia
Master	Administrador da plataforma. Acesso total a tudo.	—
Agência	Revenda/agência digital. Tem branding próprio no painel (logo, nome). Gerencia vários tenants.	Master
Tenant	Um site/empresa. Tem domínios, configurações, conteúdo e template próprios.	Master ou Agência
Usuário	Pessoa que acessa o painel. Pode ser master, membro de agência ou cliente final.	Master, Agência ou Admin do Tenant

Um tenant pode existir sem agência — nesse caso é gerenciado diretamente pelo Master. A agência é uma camada opcional de intermediação.

Agências

Agências são revendas white-label que gerenciam vários tenants. Cada agência tem branding próprio que substitui o padrão da plataforma quando os usuários da agência acessam o painel.

Campos da Agência

Campo	Descrição
Nome	Nome interno da agência (ex: "Agência Digital XYZ")
Slug	Gerado automaticamente a partir do nome
E-mail de contato	E-mail da agência para referência interna
Telefone	Telefone da agência para referência interna
Notas	Observações internas (visível apenas para master)
Nome no Painel	Nome exibido no cabeçalho do painel para tenants desta agência. Se vazio, usa o nome da agência.
Logo do Painel	Logo exibido no cabeçalho do painel no lugar do logo padrão da plataforma
Desenvolvido por	Nome e URL do desenvolvedor para créditos no rodapé do front. Sobrescreve o padrão de `config/panel.php`

Status da Agência

Status	Badge	O que acontece
Liberada (`is_active = true`)	Liberada	Funcionamento normal. Pode criar novos tenants, editar, gerenciar tudo.
Bloqueada (`is_active = false`)	Bloqueada	Membros da agência não podem criar ou editar tenants/domínios. O painel exibe mensagem de erro. Sites existentes continuam funcionando normalmente no front.

Bloquear uma agência não desativa os sites dos clientes. Apenas impede a equipe da agência de fazer alterações no painel. Para desativar um site, altere o status do tenant para "Inativo".

Dashboard da Agência

A agência pode ter um dashboard próprio com métricas dos seus tenants. Para funcionar, dois gates precisam estar ativos:

Na agência: campo dashboard_enabled deve estar ativo
No usuário: campo can_view_dashboard deve estar ativo

Se qualquer um estiver desativado, o usuário vê uma tela de boas-vindas genérica no lugar do dashboard.

Transferência de Tenants

Na página de edição de uma agência, o master pode transferir todos os tenants para outra agência (ou para gestão direta do master).

Cuidado: A transferência move todos os tenants de uma vez. Membros da agência de origem perdem acesso aos tenants transferidos (permissões são limpas automaticamente). Clientes finais vinculados diretamente aos tenants mantêm o acesso.

Exclusão de Agência

Uma agência só pode ser excluída quando possui 0 tenants. Se houver tenants vinculados, primeiro é necessário transferi-los ou desvinculá-los individualmente.

Rotas da Agência

Rota	Ação	Acesso
`/panel/agencies`	Listar agências	Master only
`/panel/agencies/create`	Criar agência	Master only
`/panel/agencies/{id}/edit`	Editar agência + transferência	Master only
`/panel/agencies/{id}` (DELETE)	Excluir agência	Master only

Tenants

Cada tenant é um site independente com seu próprio conteúdo, configurações, domínios e template. Tenants podem pertencer a uma agência ou ser gerenciados diretamente pelo master.

Criando um Tenant

A criação de tenants segue regras diferentes dependendo de quem está criando:

Quem cria	Agência	Segmento	Pós-criação
Master	Pode escolher uma agência ou deixar "direto do Master"	Pode selecionar segmento + Starter Kit	Redireciona para edição (configurar domínios)
Membro de agência	Vinculado automaticamente à agência do usuário	Pode selecionar segmento + Starter Kit	Redireciona para edição (configurar domínios)
Usuário normal	Sem agência	Pode selecionar segmento + Starter Kit	Auto-vinculado como admin do tenant

Campos do Tenant

Campo	Descrição
Nome	Nome do site/empresa (obrigatório)
Slug	Gerado automaticamente. Usado como identificador único.
Status	`active` (site funciona) ou `suspended` (front retorna 503)
Agência	Agência proprietária (opcional). Determina branding e acesso da equipe.
Segmento	Tipo de site (Imobiliária, Loja, etc.). Define módulos e template via Starter Kit.

Starter Kit

Ao selecionar um segmento na criação, o sistema pode aplicar automaticamente o Starter Kit do segmento, que inclui:

Template — visual padrão do site
Módulos — funcionalidades ativadas automaticamente
Páginas iniciais — home, contato, sobre, etc.

O checkbox "Aplicar Starter Kit automaticamente" vem marcado por padrão. Se desmarcado, o tenant é criado vazio (sem template, módulos ou páginas).

Domínios

Após criar o tenant, o passo seguinte é configurar os domínios na tela de edição. Cada tenant pode ter múltiplos domínios.

Opção	Descrição
Principal	Domínio canônico do site. Apenas um pode ser principal.
Redirecionar	Quando marcado, visitantes são enviados para o domínio principal.
Tipo (301/302)	301 = permanente (SEO), 302 = temporário.
SSL	Indica se o domínio usa HTTPS.

www.meusite.com.br e meusite.com.br são domínios diferentes. Cadastre ambos e configure um para redirecionar ao outro.

Vínculo com Agência (edição)

Na tela de edição do tenant:

Master: pode vincular tenant órfão a uma agência, ou desvincular (botão )
Membro de agência: vê o nome da agência como informação (não pode alterar)

Tipos de Usuário

Existem 3 tipos de usuário no sistema, definidos pela combinação de dois campos: is_master e agency_id.

Tipo	`is_master`	`agency_id`	Acesso a Tenants	Permissões
Master	`true`	`null`	Todos os tenants automaticamente	Bypassa todas as verificações
Membro de Agência	`false`	ID da agência	Todos os tenants da agência automaticamente	Controladas por perfil de permissão
Cliente / Normal	`false`	`null`	Apenas tenants vinculados manualmente (pivot `user_tenant`)	Controladas por perfil de permissão

Membros de agência não precisam de vínculo na tabela user_tenant. O acesso é automático via agency_id. Já clientes normais precisam ser vinculados manualmente a cada tenant.

Usuário Master

O Master é o super-administrador da plataforma. Ele tem acesso irrestrito a todas as funcionalidades.

Características

Vê todos os tenants no seletor e na listagem
Bypassa todas as verificações de permissão (middleware PanelRouteAccess)
Pode criar/editar/excluir agências, tenants, usuários e perfis de permissão
Pode atribuir qualquer perfil a qualquer usuário (incluindo perfis master-only)
Pode transformar outros usuários em master
Não precisa de agency_id nem vínculo user_tenant

Criando um Usuário Master

Acesse Usuários → Novo Usuário
Preencha nome, e-mail e senha
No campo Tipo, selecione Master
Salve

Apenas um usuário Master pode criar outro Master. Ao marcar como Master, todos os vínculos de tenant e agência são removidos automaticamente (não são necessários).

Membro de Agência

Membros de agência são a equipe da revenda. Eles têm acesso automático a todos os tenants da agência, sem precisar de vínculo individual.

Características

Acesso automático a todos os tenants da agência
Não precisa de vínculo user_tenant
Vê o branding da agência no painel (logo e nome)
Pode criar novos tenants (vinculados automaticamente à agência)
Pode criar outros membros de agência e clientes finais
Permissões controladas por perfil (pode receber perfis agency e client)
Pode receber acesso a rotas de plataforma (ex: gestão de tenants) via perfis platform

Criando um Membro de Agência

Existem duas formas de criar um membro de agência:

Forma 1: Master cria o membro

Acesse Usuários → Novo Usuário
Preencha nome, e-mail e senha
No campo Agência, selecione a agência desejada
Opcionalmente marque "Pode ver Dashboard"
Salve
Acesse Permissões do usuário para atribuir um perfil

Forma 2: Outro membro da agência cria

Logado como membro de agência, acesse Usuários → Novo Usuário
Selecione o tipo "Membro da Agência"
Preencha nome, e-mail e senha
Opcionalmente marque "Pode ver Dashboard"
Opcionalmente selecione um perfil de permissão inicial
Salve

O campo "Pode ver Dashboard" só habilita o dashboard se a agência também tiver o dashboard habilitado (dashboard_enabled). Ambos os gates precisam estar ativos.

Usuário Cliente

Clientes (ou usuários normais) são os donos/operadores dos sites. Eles só acessam os tenants aos quais foram vinculados manualmente.

Características

Acesso apenas aos tenants vinculados via tabela user_tenant
Cada vínculo tem um papel (role): admin, editor ou viewer (informativo)
Permissões efetivas controladas pelo perfil de permissão atribuído
Pode gerenciar outros usuários do mesmo tenant (se tiver permissão)
Pode receber perfis marcados como assignable_by: client
Não tem acesso a rotas de plataforma (fábrica, gestão de tenants/agências)

Criando um Usuário Cliente

Forma 1: Master cria o cliente

Acesse Usuários → Novo Usuário
Preencha nome, e-mail e senha
Deixe Agência vazia e Tipo como "Padrão"
Selecione os tenants aos quais o usuário terá acesso (checkboxes)
Opcionalmente selecione um perfil de permissão para definir o que o usuário pode acessar
Salve

Forma 2: Membro de agência cria o cliente

Logado como membro de agência, acesse Usuários → Novo Usuário
Selecione o tipo "Cliente do Tenant"
Selecione o tenant da agência ao qual vincular
Preencha nome, e-mail e senha
Opcionalmente selecione um perfil de permissão inicial
Salve

Forma 3: Outro usuário do tenant cria

Logado no contexto do tenant, acesse Usuários → Novo Usuário
O tenant já vem fixo (o atual)
Preencha nome, e-mail e senha
Salve e depois configure permissões

As permissões efetivas de um usuário são determinadas exclusivamente pelo perfil de permissão atribuído. Sem um perfil (ou permissões customizadas), o usuário terá acesso apenas às rotas definidas como always_allowed.

Perfis de Permissão

Perfis de permissão definem quais rotas do painel um usuário pode acessar. Um perfil é um conjunto nomeado de rotas que pode ser reutilizado em vários usuários.

Conceitos Principais

Conceito	Descrição
Scope	`tenant` — rotas de conteúdo (blog, páginas, produtos, configurações, etc.) `platform` — rotas de gestão (fábrica de templates, gestão de tenants, agências, etc.)
Assignable By	Quem pode atribuir este perfil a um usuário: `master` — apenas master pode atribuir `agency` — master ou membro de agência pode atribuir `client` — qualquer usuário com permissão de gerenciar usuários pode atribuir
Sistema	Perfis criados automaticamente na instalação. Não podem ser excluídos.

Perfis de Sistema

Perfil	Scope	Descrição
Acesso Fábrica	`platform`	Rotas da fábrica (templates master, segmentos, páginas modelo)
Gestor de Tenants	`platform`	Rotas de gestão (tenants, domínios, agências)
Admin Completo	`tenant`	Todas as rotas de conteúdo do tenant
Editor de Conteúdo	`tenant`	Páginas, blog, produtos, imóveis, veículos, portfólio, etc.
Visualizador	`tenant`	Apenas visualização (index/show) em todos os módulos
Atendimento	`tenant`	Mensagens de contato, orçamentos e comentários

Modos de Permissão

Ao atribuir permissões a um usuário, existem 3 modos:

Modo	Como funciona
Perfil	Seleciona um perfil pré-definido. O usuário herda todas as rotas do perfil. Se o perfil for atualizado, todos os usuários refletem a mudança.
Customizado	Seleciona rotas individualmente (checkboxes agrupados por funcionalidade). Mais flexível, mas mais trabalhoso de manter.
Nenhum	Remove todas as permissões. O usuário pode logar mas não acessa nenhuma funcionalidade.

Permissões de tenant são globais — o mesmo conjunto de rotas vale para todos os tenants que o usuário pode acessar. Se precisar de permissões diferentes por tenant, crie usuários separados.

Cadeia de Verificação

Quando um usuário acessa qualquer rota do painel, a verificação segue esta ordem:


    1. Usuário é master? → PERMITIDO (bypassa tudo)

    2. Rota está em always_allowed (33 rotas)? → PERMITIDO

    3. Rota está em master_only? → BLOQUEADO

    4. Rota é scope platform?

        → Verifica perfil platform (tenant_id = NULL)

    5. Rota é scope tenant?

        → Usuário tem acesso ao tenant? (agency_id ou pivot)

        → Verifica perfil tenant (apply_to_all_tenants = true)

        → Rota está no perfil ou nas rotas customizadas? → PERMITIDO / BLOQUEADO

Rotas Sempre Permitidas (always_allowed)

Estas 33 rotas são acessíveis por qualquer usuário autenticado, independente de permissões:

Dashboard e refresh
Logout
Listar/trocar tenants
Editar próprio perfil
Notificações
Categorias (autorização no controller)
Mídia (popup, browse, upload, TinyMCE)
Galeria de imagens de entidades

Criando um Perfil de Permissão

Acesse Perfis de Permissão (em Gestão, na sidebar)
Clique em Novo Perfil
Opcionalmente, use um template como ponto de partida (Editor, Atendimento ou Gerenciador)
Defina nome, descrição, scope (tenant ou platform) e assignable_by
Marque as rotas desejadas (organizadas por grupos)
Salve

Atribuindo Permissões a um Usuário

Na listagem de Usuários, clique no ícone de chave () do usuário
Escolha o modo: Perfil, Customizado ou Nenhum
Se perfil: selecione o perfil desejado no grid de cards
Se customizado: marque as rotas individualmente
Para master: opcionalmente atribua perfis de plataforma (seção separada na mesma tela)
Salve

Todas as alterações de permissão ficam registradas no log de auditoria (permission_audit_log), incluindo quem fez a alteração e quando.

Guia Prático

Passo a passo completo para configurar uma agência funcional do zero.

Passo 1: Criar a Agência

Logado como Master, acesse Agências → Nova Agência
Preencha: nome, e-mail de contato, telefone
Configure o branding do painel: nome no painel e logo (aparecem para a equipe da agência)
Opcionalmente configure "Desenvolvido por" (créditos no rodapé dos sites)
Ative "Dashboard" se quiser que a equipe tenha acesso ao dashboard de métricas
Salve

Passo 2: Criar o Primeiro Membro da Agência

Acesse Usuários → Novo Usuário
Preencha nome, e-mail e senha
No campo Agência, selecione a agência criada no passo 1
Marque "Pode ver Dashboard" se a agência tem dashboard ativo
Salve

Passo 3: Atribuir Permissões ao Membro

Na listagem de Usuários, clique no ícone do membro criado
Na seção Permissões do Tenant: selecione modo Perfil e escolha "Admin Completo" (ou outro perfil)
Na seção Permissões da Plataforma (abaixo): marque "Gestor de Tenants" se quiser que ele gerencie tenants e domínios
Salve

Passo 4: Criar um Tenant (Site)

Pode ser feito pelo Master ou pelo membro da agência:

Acesse Tenants → Novo Tenant
Preencha o nome do site
Se logado como Master: selecione a agência
Se logado como membro de agência: a vinculação é automática
Selecione o segmento e mantenha "Aplicar Starter Kit" marcado
Salve → será redirecionado para configurar domínios

Passo 5: Configurar Domínios

Na tela de edição do tenant, clique em "Adicionar Domínio"
Digite o domínio (ex: meucliente.com.br)
Marque como Principal
Se necessário, adicione www.meucliente.com.br e configure para redirecionar ao principal
Marque SSL se o domínio usa HTTPS
Salve

Passo 6: Criar Usuário Cliente Final (Opcional)

Se o dono do site precisa de acesso ao painel:

Logado como membro de agência, acesse Usuários → Novo Usuário
Selecione tipo "Cliente do Tenant"
Selecione o tenant criado no passo 4
Preencha nome, e-mail e senha do cliente
Selecione um perfil de permissão inicial (ex: "Editor de Conteúdo")
Salve

Passo 7: Verificar Acessos

Teste os acessos fazendo login com cada tipo de usuário:

Usuário	Deve ver	Não deve ver
Master	Tudo: agências, todos os tenants, fábrica, gestão	—
Membro da agência	Tenants da agência, branding da agência no painel, funcionalidades do perfil atribuído	Tenants de outras agências, agências (a menos que tenha perfil platform)
Cliente final	Apenas o(s) tenant(s) vinculado(s), funcionalidades do perfil atribuído	Outros tenants, gestão, fábrica, agências

Dica: Use o navegador em modo privado (ou outro navegador) para testar logins diferentes simultaneamente sem precisar deslogar.