Gestão de Acessos

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

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.