Cadastro de Funções

Gestão centralizada de funções (papéis ou cargos) do Portal EasyPAC, com vinculação a empresas e controle de visibilidade para usuários.

▶ Tutorial em vídeo: ainda não disponível para esta rotina.

ℹ️ Informações importantes

• Não é obrigatório vincular empresa nenhuma: uma função pode ser salva sem nenhuma empresa selecionada, tornando-se uma função “geral”.
• Rotina é pré-requisito de outra: o cadastro de uma função aqui é pré-requisito para que ela possa ser vinculada a um usuário em outra tela do sistema; sem a função estar cadastrada nesta tela, ela não aparece disponível para vínculo em nenhum outro lugar.
• Consultas sem exigência de permissão: dois pontos de consulta usados internamente pelo sistema (um que devolve o identificador e o nome de uma função a partir do seu identificador, e outro que lista as funções vinculáveis a um usuário) não exigem permissão nem autenticação para serem acionados, diferente de todas as demais operações desta tela. Esse comportamento é uma característica identificada na análise técnica de origem e está sinalizado ali como um ponto a ser observado pela equipe responsável; não é algo que o usuário final precise agir a respeito, mas explica por que essas duas consultas específicas não dependem de permissão.

Identificador (coluna da grade de listagem de Funções)

Descrição: número que identifica cada função de forma única dentro do sistema.

Comportamento: a grade de funções vem, por padrão, ordenada por esta coluna em ordem decrescente; o usuário pode clicar no cabeçalho desta coluna para alternar a ordenação. Quando o texto digitado no campo de busca da grade é um número inteiro, o sistema usa esse número para localizar a função pelo Identificador exato.

Impacto: é o valor usado por outras telas do sistema para localizar e vincular a função a um usuário; também aparece nas mensagens de confirmação de exclusão, junto com o Nome.

Nome (coluna da grade de listagem de Funções)

Descrição: nome dado à função, como aparece para quem está consultando a listagem.

Comportamento: o usuário pode clicar no cabeçalho desta coluna para ordenar a grade por nome. Quando o texto digitado no campo de busca da grade não é um número inteiro, o sistema busca as funções cujo nome contenha o texto digitado.

Impacto: é o nome usado em todas as telas do sistema que exibem ou permitem selecionar uma função, inclusive nas mensagens de sucesso e erro desta própria tela.

Campo de busca da grade de Funções

Descrição: campo usado para localizar rapidamente uma função já cadastrada, digitando parte do nome ou o identificador exato. (Nota: texto exato do rótulo não informado na documentação de origem, validar com analista responsável)

Comportamento: se o texto digitado for um número inteiro, o sistema procura a função com aquele Identificador exato; caso contrário, procura as funções cujo Nome contenha o texto digitado. A busca só é enviada ao servidor a partir do terceiro caractere digitado, ao pressionar Enter ou ao limpar o campo, com uma espera de meio segundo depois que o usuário para de digitar (para evitar disparar uma busca a cada tecla pressionada).

Impacto: define quais funções aparecem na grade de listagem, mas não altera nenhum dado gravado no cadastro das funções.

Empresa (campo do painel de filtros da listagem de Funções)

Descrição: campo usado para restringir a listagem de funções às que estão vinculadas a uma ou mais empresas específicas. A lista de opções mostra as empresas vinculadas ao usuário logado, mais a opção “Geral” no início.

Comportamento: a busca dentro da lista de opções ignora acentuação e diferença entre maiúsculas e minúsculas. A alteração deste campo só passa a valer, recarregando a grade, depois que o usuário clica no botão “Filtrar”; apenas mudar a seleção sem clicar em “Filtrar” não altera a listagem exibida. Quando a opção “Geral” está marcada (ou o campo está vazio), nenhuma restrição adicional por empresa é aplicada além do recorte automático de visibilidade do usuário logado (ver seção “Regras de Negócio e Restrições das Funções”). O painel de filtros inicia recolhido, e o valor escolhido aqui fica guardado no navegador durante a sessão, sendo restaurado automaticamente quando o usuário volta para a listagem depois de abrir um cadastro ou uma edição.

Impacto: define quais funções aparecem na grade de listagem; não altera nenhum dado gravado no cadastro das funções.

Nome (campo do formulário de cadastro/edição de função)

Descrição: nome dado à função que está sendo cadastrada ou editada; é o nome pelo qual essa função vai aparecer em toda a listagem e em qualquer outra tela do sistema que exiba ou permita selecionar funções.

Comportamento: o sistema valida o preenchimento e o limite de 50 caracteres diretamente na tela, antes de enviar ao servidor; se o campo estiver vazio ou ultrapassar o limite, ele é destacado visualmente e o envio é cancelado. Depois de enviado, o servidor também verifica se já existe outra função com o mesmo nome, considerando todas as funções do sistema, de qualquer empresa; se existir, a gravação é recusada com a mensagem “Já existe uma função cadastrada com o nome {nome}”.

Impacto: aparece na coluna Nome da grade de listagem, nas mensagens de sucesso e erro do sistema, e é o nome pelo qual a função fica disponível para vínculo com usuários em outras telas.

Empresas (campo do formulário de cadastro/edição de função)

Descrição: define a quais empresas a função está vinculada. Se nenhuma empresa for selecionada, a função é salva como “geral” e passa a ficar visível para todos os usuários do sistema, independentemente da empresa de cada um.

Comportamento: a lista de opções mostra sempre as empresas vinculadas ao usuário logado (sem a opção “Geral”, que existe apenas no filtro da listagem, não no formulário). No cadastro de uma função nova, essa lista já vem carregada assim que o formulário é aberto. Na edição de uma função existente, atenção: depois que o sistema busca a função a ser editada, ele recarrega a lista de empresas do campo a partir do usuário logado e marca como pré-selecionada a empresa padrão desse usuário, e não necessariamente a(s) empresa(s) que já estão de fato vinculadas à função. Por isso, ao editar uma função, é importante conferir manualmente e reselecionar as empresas corretas antes de salvar, em vez de confiar na marcação que aparece ao abrir a tela (ver seção “Regras de Negócio e Restrições das Funções”).

Impacto: determina para quais usuários a função fica visível na listagem e disponível para vínculo (ver “Escopo de visibilidade por empresa” na seção de regras de negócio).

ℹ️ Observação sobre campo de situação

A tela de Funções não possui nenhum campo de situação (ativo/inativo) para a função; esse tipo de valor nunca é definido a partir desta tela, nem no cadastro nem na edição.

ℹ️ Persistência de filtros

Os valores de filtro aplicados ficam guardados durante a sessão do navegador e são restaurados automaticamente quando o usuário retorna à listagem depois de abrir um cadastro ou uma edição. Independentemente da busca e do filtro aplicados, a listagem só exibe as funções que o usuário logado tem permissão de enxergar, segundo a regra de visibilidade por empresa descrita na seção “Regras de Negócio e Restrições das Funções”.

⚠️ Atenção ao editar uma função

Ao abrir a edição, o campo Empresas do formulário aparece com uma pré-seleção baseada na empresa padrão do usuário que está editando, e não necessariamente com as empresas que já estão de fato vinculadas à função. Antes de salvar uma edição, é recomendável conferir e reselecionar manualmente as empresas corretas para aquela função, para evitar alterar por engano o vínculo de empresas já existente.

🔒 Condições que impedem a edição

Se a função que está sendo editada foi excluída ou alterada por outra sessão antes do usuário salvar, o servidor recusa a gravação com a mensagem “401 >> função não encontrada.”, e o formulário permanece aberto com os dados digitados, sem gravar nada. Também é recusada a gravação se o novo nome escolhido já estiver em uso por outra função do sistema (ver seção “Regras de Negócio e Restrições das Funções”).

ℹ️ Histórico de alterações

A documentação de origem não menciona nenhuma tela ou recurso de histórico/log de alterações para o cadastro de funções [informação não disponível na documentação de origem, validar com analista responsável].

Não é permitido cadastrar ou renomear uma função para um nome já usado por outra função, mesmo que essa outra função pertença a uma empresa diferente. Essa verificação considera todas as funções do sistema, de todas as empresas, e não apenas as da empresa selecionada no momento. Se o nome já existir, o sistema recusa a gravação com a mensagem “Já existe uma função cadastrada com o nome {nome}”, e o usuário precisa escolher outro nome para conseguir salvar.

Uma função pode ficar vinculada a nenhuma, uma ou várias empresas. Quando não há nenhuma empresa vinculada, a função é considerada “geral” e aparece na listagem e nas consultas de vínculo para qualquer usuário do sistema, independentemente das empresas às quais esse usuário tem acesso.

Quando uma função tem uma ou mais empresas vinculadas, ela só aparece na listagem principal para um usuário quando TODAS as empresas vinculadas a ela estiverem entre as empresas às quais esse usuário tem acesso. Se apenas uma das empresas vinculadas estiver fora do acesso do usuário, a função inteira deixa de aparecer para ele. Na consulta de funções vinculáveis a um usuário específico, essa mesma regra vale quando o identificador desse usuário é informado; quando não é informado (ou é igual a zero), a comparação passa a considerar a empresa ativa da sessão no momento, e nesse caso basta que uma das empresas vinculadas à função esteja entre as consideradas para que a função apareça.

A cada gravação de uma função (cadastro ou edição), o sistema sempre redefine automaticamente o usuário responsável e a empresa de origem da função, substituindo qualquer valor que porventura tenha vindo do formulário. A data de inclusão só é redefinida de fato no cadastro de uma função nova; ao editar uma função já existente, o sistema preserva a data de inclusão original gravada desde o cadastro, e qualquer nova data enviada durante a edição é descartada. Na prática, isso significa que, ao editar uma função, apenas o Nome e as Empresas vinculadas são realmente atualizados no registro.

Na grade de listagem de funções, somente um clique nos cabeçalhos das colunas Identificador ou Nome altera a ordenação exibida. Clicar em qualquer outra área não muda a ordenação atual, e quando nenhuma coluna de ordenação é informada ao sistema, a listagem é exibida sem nenhuma ordenação explícita aplicada.

No campo de busca da grade de listagem, se o texto digitado for um número inteiro, o sistema interpreta como uma busca pelo Identificador exato daquele número; se o texto digitado não for um número inteiro, o sistema busca pelas funções cujo Nome contenha o texto digitado.

O filtro de Empresa do painel de filtros só aplica uma restrição adicional à listagem quando uma empresa específica (diferente da opção “Geral”) é selecionada e o botão “Filtrar” é acionado. Com o filtro vazio ou com a opção “Geral” selecionada, nenhuma restrição adicional por empresa é aplicada além do recorte automático de visibilidade do usuário logado (ver Regra 3).

Antes de excluir uma função, o sistema verifica se ela está vinculada a outros registros do sistema (por exemplo, usuários que já a utilizam). Se houver qualquer vínculo, a exclusão é bloqueada com a mensagem “Não é possível deletar esta função devido a ligação com outros registros…”, e a função permanece na listagem sem nenhuma alteração.

Se, no momento de salvar uma edição ou de confirmar uma exclusão, a função em questão não for mais localizada pelo sistema (por exemplo, por ter sido removida ou alterada por outra sessão enquanto o usuário trabalhava nela), a operação é interrompida sem alterar nada: na edição, com a mensagem “401 >> função não encontrada.”; na exclusão, com a mensagem “401 >> função não encontrada, ou dados inválidos para esta operação.”.

O cadastro de Funções não possui campo de situação (ativo/inativo); esse tipo de valor nunca é definido a partir desta tela, nem no cadastro nem na edição de uma função.

Cada ação da tela de Funções exige uma permissão específica atribuída ao perfil de acesso do usuário: visualizar função (para ver a listagem), nova função (para cadastrar), editar função (para alterar um registro existente) e excluir função (para remover um registro). Usuários com perfil fiscal não têm acesso a nenhuma dessas ações na tela de Funções.