A tela de Grupos, no módulo de Cadastros, mantém o cadastro de grupos de usuários, cada um podendo ficar vinculado a uma ou mais empresas ou permanecer sem nenhum vínculo (grupo “Geral”, visível a todos os usuários independentemente da empresa). A partir do cadastro salvo aqui, o próprio formulário de um grupo já existente permite vincular e desvincular usuários àquele grupo. Um grupo também pode estar associado à planos de ação do módulo de Melhoria Contínua. Cadastrar corretamente o vínculo de empresas de cada grupo é o que garante que apenas os usuários certos o enxerguem na listagem e possam vinculá-lo a si mesmos.

Para que a tela de Grupos funcione plenamente, as seguintes condições precisam estar atendidas:

• Vincular um grupo a uma empresa exige que essa empresa já esteja cadastrada e vinculada ao usuário logado: a lista de empresas do filtro e do formulário vem desse vínculo; sem nenhuma empresa vinculada ao usuário logado, essas listas aparecem vazias.
• Não é obrigatório vincular o grupo a nenhuma empresa: um grupo pode ser salvo sem nenhum vínculo, tornando-se um grupo “Geral”, visível a todos os usuários.
• Vincular um usuário a um grupo (feito dentro do próprio formulário de edição do grupo) exige que o grupo já esteja salvo — o vínculo só fica disponível depois que o grupo existe — e que o usuário buscado pertença a pelo menos uma das empresas vinculadas ao grupo (ou a qualquer empresa, se o grupo for “Geral”).
• Excluir um grupo exige que não existam usuários vinculados a ele; havendo vínculo de usuário, a exclusão é bloqueada.

A tela de Grupos não depende de nenhum módulo contratado opcional identificado na análise: ela integra o cadastro básico do sistema, liberado a todos os clientes, dependendo apenas das permissões de papel descritas a seguir.

Papel: visualizar a listagem de grupos exige a permissão de visualizar grupo; abrir o formulário de cadastro de um grupo novo exige a permissão de novo grupo; abrir e salvar a edição de um grupo existente exige a permissão de editar grupo; excluir um grupo exige a permissão de excluir grupo.

Perfil fiscal: não tem acesso à tela, ou seja, não pode adicionar novo, editar e nem excluir.

Recorte de dados: a listagem só mostra um grupo quando ele é “Geral” (sem nenhuma empresa vinculada) ou quando TODAS as empresas vinculadas a ele estão entre as empresas às quais o usuário logado tem acesso; um grupo com pelo menos uma empresa vinculada fora do conjunto de empresas do usuário não aparece na listagem dele. O filtro de Empresa do painel só restringe ainda mais a listagem quando uma opção específica é selecionada.

O usuário chega à tela de Grupos pelo menu Cadastro > Grupos. Ao abrir, o portal monta a lista de empresas do filtro (empresas do usuário logado, mais a opção “Geral” no início, representando os grupos sem empresa) e carrega a grade, que busca os dados por uma chamada própria ao servidor. A partir daí o usuário pode:

1. Pesquisar por empresa no painel de filtros (clicando em “Filtrar”), ou navegar pelas páginas da grade.
2. Clicar em Novo para abrir o formulário de cadastro de um grupo novo, informar nome e descrição e, opcionalmente, vincular uma ou mais empresas, e salvar.
3. Clicar em Editar (ou dar duplo clique na linha) para abrir um grupo existente, alterar nome, descrição e/ou as empresas vinculadas, e salvar.
4. Dentro da edição de um grupo já existente, clicar em “Usuários” para abrir o modal de vínculo, buscar um usuário e vinculá-lo ao grupo, ou remover um vínculo já existente.
5. Clicar em Excluir para remover um grupo, confirmando a exclusão quando solicitado.
6. Clicar em Cancelar a qualquer momento, no formulário, para voltar à listagem sem gravar nada, preservando os filtros que estavam aplicados antes de abrir o formulário.

Listagem de grupos — grade, filtro e ações

A grade de grupos desta tela exibe as colunas ID, Nome e Descrição, com 20 registros por página e ordenação inicial pela coluna ID em ordem decrescente; a coluna Empresa não é exibida nesta grade. O painel de filtros (recolhido por padrão) tem apenas o campo Empresa, de seleção múltipla e sem busca por texto dentro da própria lista; as opções são todas as empresas do usuário logado, mais a opção “Geral” (representando os grupos sem empresa vinculada) inserida no início da lista. O filtro só passa a valer, recarregando a grade, quando o usuário clica no botão “Filtrar”.

A grade oferece os botões Novo (abre o cadastro de um grupo novo) e Editar (abre o grupo selecionado); o duplo clique em uma linha também abre a edição. Antes de excluir um grupo pela grade, é exibido o diálogo de confirmação “Você está prestes a remover o grupo: {id} – {nome}”; a exclusão só é enviada ao servidor se o usuário confirmar. Após a exclusão bem-sucedida, a grade é recarregada e é exibida a notificação “Operação efetuada com sucesso.”; em caso de falha, é exibido o texto de erro devolvido pelo servidor ou, se esse texto não vier no formato esperado, o texto puro da resposta de erro.

Formulário de cadastro e edição de grupo

O mesmo formulário de Grupos atende tanto o cadastro de um grupo novo quanto a edição de um existente: se um identificador for informado na rota, o portal busca o grupo no servidor e preenche nome, descrição e empresas vinculadas; se não for informado, o formulário abre vazio. Os campos Nome (até 200 caracteres) e Descrição são de preenchimento obrigatório, validados no navegador antes do envio — o formulário não é enviado se a validação falhar.

No cadastro de um grupo novo, a lista de empresas oferecida é a lista de empresas vinculadas ao usuário logado, com a empresa que é o contexto atual (padrão) desse usuário já marcada como pré-selecionada. Na edição de um grupo existente, essa mesma lista de empresas é recalculada, mas ignorando a pré-seleção da empresa padrão do usuário logado: a marcação exibida reflete apenas as empresas já vinculadas ao próprio grupo buscado, não o contexto de quem está editando.

O cabeçalho do formulário muda conforme o grupo já exista ou não: se o grupo já existe, é exibida uma barra de navegação com o botão “Usuários”, que abre o modal de vínculo de usuários ao grupo; se é um grupo novo, é exibido apenas um título estático, sem esse botão nem o modal. Ao salvar (cadastro ou edição), o portal envia o mesmo conjunto de dados — identificador, nome, descrição e lista de empresas — em ambos os casos; o servidor decide entre inserir e atualizar apenas pelo identificador recebido. Se o servidor aceitar a gravação, é exibida a notificação “Operação efetuada com sucesso.” e, ao fechá-la, o usuário é redirecionado para a listagem, com os filtros anteriores preservados; se o servidor recusar a gravação, é exibido o texto do erro devolvido por ele, e o formulário permanece aberto com os dados digitados. O botão Cancelar sempre volta para a listagem sem gravar nada, preservando os filtros que estavam aplicados antes de abrir o formulário.

Modal de vínculo de usuários ao grupo

O modal aberto pelo botão “Usuários” (disponível apenas quando o grupo já existe) mostra uma grade com as colunas Id Usuário e Nome do Usuário; a ordenação padrão é pela coluna Id Usuário, decrescente, e a paginação desta grade acontece inteiramente no navegador, sem nova busca ao servidor por página. A busca de usuário para vincular ao grupo é feita por um campo de lookup, que pesquisa por Id ou por Nome (conforme o texto de ajuda da própria tela), restrito às empresas vinculadas ao grupo em edição.

Ao selecionar um usuário no campo de lookup, o vínculo é criado automaticamente, sem nenhuma confirmação prévia; em caso de sucesso, a grade do modal é recarregada, o campo de busca é limpo e é exibida a notificação “Operação efetuada com sucesso.”. Para remover um vínculo de usuário já existente, é exibido o diálogo de confirmação “Você está prestes a remover um relacionamento entre Usuário e Grupo.”; ao confirmar e a remoção ser bem-sucedida, a grade do modal é recarregada e o campo de busca é limpo.

Feedbacks — listagem e exclusão de grupo

Feedbacks — formulário de cadastro e edição de grupo

Feedbacks — vínculo de usuários no modal do grupo

Ao carregar a listagem de grupos, o servidor recebe o texto de busca, a empresa selecionada no filtro, a ordenação e a paginação como parâmetros enviados pela grade sem alteração pelo Portal. Aplica a busca textual (identificador exato quando o texto digitado é numérico, ou nome contendo o texto em qualquer posição, caso contrário), restringe o resultado pelo escopo de visibilidade por empresa (ver Regras de Negócio) e, se o filtro de Empresa indicar uma opção específica, aplica também essa restrição adicional. Em seguida ordena pela coluna pedida — respeitando o limite de colunas ordenáveis — ou não aplica ordenação se a coluna informada não for reconhecida, pagina em memória sobre o total já filtrado e reempacota a resposta no formato esperado pela grade (recordsTotal e recordsFiltered recebem sempre o mesmo valor).

Ao abrir a edição de um grupo, o portal busca o grupo diretamente pelo identificador informado na rota e, em seguida, recalcula a lista de empresas do formulário a partir do usuário logado, mas pedindo explicitamente para ignorar a pré-seleção da empresa padrão — a marcação final reflete as empresas já vinculadas ao grupo buscado.

Ao salvar (cadastro ou edição), o portal envia os dados ao mesmo ponto de gravação em ambos os casos; o servidor decide entre inserir e atualizar exclusivamente pelo identificador recebido (ver Regras de Negócio). Antes de gravar, se a empresa enviada representar a opção “Geral”, o servidor a converte para “sem empresa vinculada”; em seguida valida a unicidade do nome do grupo e, na edição, confirma que o grupo ainda existe. Se alguma dessas verificações falhar, a operação é interrompida com a mensagem correspondente e o registro não é alterado; caso contrário, grava nome, descrição e lista de empresas do grupo.

Ao excluir um grupo, o servidor carrega o grupo junto com seus vínculos de usuário e seus vínculos a planos de ação corretiva; se o grupo não for encontrado, ou se a exclusão violar alguma restrição de integridade por existirem vínculos que a impeçam, a operação é interrompida sem remover nada. Concluída com sucesso, a resposta traz o identificador do usuário que executou a exclusão e a data e hora da operação.

Ao vincular um usuário a um grupo pelo modal, o servidor verifica antes se o mesmo vínculo (mesmo usuário e mesmo grupo) já existe; se existir, rejeita a operação. Ao remover um vínculo, verifica se ele ainda existe; se não existir mais, rejeita a operação. Além do vínculo individual usado por esta tela, existe uma funcionalidade de vínculo de um usuário a vários grupos de uma só vez, consumida por outra tela do sistema (não pela tela de Grupos): nela, cada grupo da lista informada é checado individualmente contra vínculos já existentes, e os que já existem são ignorados silenciosamente, gravando-se em lote apenas os vínculos novos. Também existe um ponto de consulta que lista todos os grupos vinculados a um usuário específico, igualmente não utilizado pela tela de Grupos — é consumido por outra tela do sistema, como o cadastro de usuário.

A busca de usuários oferecida no lookup do modal considera apenas usuários ativos que não sejam do tipo “perfil”; quando a lista de empresas do grupo é a opção “Geral”, a busca não filtra por empresa e considera usuários de todas as empresas, caso contrário considera apenas usuários vinculados a pelo menos uma das empresas do grupo. O texto digitado filtra por identificador (se numérico) ou por nome contendo o texto; quando o tamanho de página não é informado, são usados 48 registros por página, ordenados por nome.

Grupo sem empresa vinculada (grupo “Geral”)

Quando o formulário envia a opção “Geral” (representada internamente pelo valor -1) como empresa do grupo, o servidor grava o grupo sem nenhuma empresa vinculada. Um grupo “Geral” é visível a qualquer usuário do sistema, independentemente das empresas dele.

Escopo de visibilidade por empresa

Na listagem principal e na variante de listagem por usuário-empresa, um grupo com empresas vinculadas só aparece para um usuário quando TODAS as empresas vinculadas a ele estão entre as empresas às quais esse usuário tem acesso; grupos “Gerais” aparecem sempre. Quando o filtro de Empresa da tela indica uma empresa específica, a listagem só mostra grupos que tenham aquela empresa entre as vinculadas; quando o filtro indica a opção “Geral”, mostra apenas os grupos sem nenhuma empresa vinculada. Existe ainda uma variante desta listagem restrita às empresas de um usuário-empresa específico, que segue a mesma regra de visibilidade e a mesma exigência de permissão de visualizar grupo, mas não é usada pela tela padrão de Grupos — está exposta para consumo por outras integrações internas; nela, a lista de empresas do usuário considerado vem diretamente do vínculo entre usuário e empresa, sem nenhum outro filtro, a busca textual segue o mesmo critério da listagem principal (identificador exato ou nome contendo o texto), e a coluna Empresa do grupo é exibida como “Geral” quando o grupo não tem empresa vinculada, ou com a razão social da empresa vinculada, caso contrário.

Unicidade do nome do grupo

Ao cadastrar um grupo, o servidor rejeita a operação com a mensagem “Já existe um Grupo com o nome {nome informado}” quando já existir qualquer outro grupo com o mesmo nome. Ao editar um grupo, a mesma verificação se aplica, comparando apenas contra grupos com identificador diferente do que está sendo editado; se o grupo que está sendo editado não for mais encontrado, o servidor rejeita a operação com “401 >> Grupo não encontrado.” antes mesmo de checar o nome.

Decisão entre cadastrar e editar

O servidor decide entre cadastrar e editar um grupo exclusivamente pelo identificador recebido: identificador igual a 0 significa novo grupo; qualquer outro valor significa edição do grupo com aquele identificador. O Portal chama o mesmo ponto de gravação tanto para o cadastro quanto para a edição, cabendo ao servidor essa decisão.

Exclusão de grupo e seus vínculos

Ao excluir um grupo, o sistema carrega junto os vínculos de usuário ligados a ele. A exclusão é bloqueada com “401 >> grupo não encontrado, ou dados inválidos para esta operação.” se o grupo não existir mais, e bloqueada com “Não é possível excluir este grupo, pois existem usuários vinculados a ele.” quando existirem vínculos de usuário que impeçam a remoção. Concluída com sucesso, o registro da exclusão traz o identificador do usuário que a executou e a data e hora da operação.

Busca textual, ordenação e paginação da listagem principal de grupos

A busca livre da listagem principal de grupos filtra por identificador exato quando o texto digitado é numérico, ou por nome contendo o texto em qualquer posição, caso contrário. As únicas colunas ordenáveis são ID (valor 0), Nome (valor 1, comparado após remover espaços das pontas) e Descrição (valor 2, idem); qualquer outro valor de coluna não altera a ordenação atual. A paginação é aplicada em memória, depois de todos os filtros, sobre o total já filtrado.

Lookup de grupo por texto e por lista de empresas

No lookup de grupo por texto (usado por outras telas para localizar um grupo), a busca filtra por identificador exato quando o texto é numérico, ou por nome que COMECE com o texto digitado, caso contrário — diferente da listagem principal, que aceita o texto em qualquer posição do nome. No lookup paginado por lista de empresas, se o primeiro elemento da lista informada for o valor 0, a busca considera todos os grupos, sem filtrar por empresa; caso contrário, mostra apenas grupos que tenham ao menos uma empresa em comum com a lista informada, com a comparação das listas feita em memória. Este lookup aceita ordenação pela coluna 0 (ID) ou pela coluna 1 (Nome, usada como padrão para qualquer outro valor de coluna).

Vínculo entre usuário e grupo

Um mesmo usuário não pode ser vinculado duas vezes ao mesmo grupo: a tentativa é rejeitada com “400 >> Grupo já cadastrado neste usuário.”. A remoção de um vínculo exige que ele ainda exista: se não existir mais, é rejeitada com “401 >> Relação usuário x grupo não encontrada.”. No vínculo em lote de um usuário a vários grupos (recurso não usado pela tela de Grupos), vínculos já existentes são ignorados silenciosamente, sem aviso de quais foram ignorados, e apenas os vínculos novos são gravados.

Seleção de empresas nos combos de Grupos

A lista de empresas oferecida nos combos de Grupos (filtro da listagem e formulário) é sempre montada a partir das empresas vinculadas ao usuário logado. Por padrão, cada opção é marcada como pré-selecionada quando corresponde à empresa que é o contexto atual do usuário logado — exceto quando o chamador pede explicitamente para ignorar essa pré-seleção, como acontece ao editar um grupo já existente, caso em que a marcação exibida passa a refletir as empresas efetivamente vinculadas ao grupo. A consulta que monta essa lista também aceita um texto de busca opcional para filtrar pelo nome da empresa, ainda que os combos desta tela não exponham um campo de busca dentro da lista.

Registro de auditoria das operações de grupo

A inclusão de grupo, a edição de grupo, a exclusão de grupo e a criação individual de um vínculo entre usuário e grupo sempre registram o e-mail do usuário responsável pela alteração. A remoção de um vínculo entre usuário e grupo e o vínculo em lote de múltiplos grupos NÃO registram esse e-mail na auditoria.

T-01 — A opção Grupos não aparece no menu Cadastro ou a listagem não carrega

Mensagem exibida: Nenhuma — a opção simplesmente não aparece, ou a tela não carrega a grade.

O que fazer: se não for possível visualizar a grade confirmar se o usuário tem a permissão de visualizar grupo atribuída ao seu perfil de acesso, e se for possível visualizar a grade mas não o cadastro de um grupo específico, o usuário não tem acesso a todas as empresas do grupo.

T-02 — O botão Novo não aparece ou não abre o cadastro de grupo

Mensagem exibida: Nenhuma — o botão simplesmente não aparece, ou a ação não responde.

O que fazer: confirmar se o usuário tem a permissão de novo grupo atribuída ao seu perfil de acesso.

T-03 — Não é possível abrir ou salvar a edição de um grupo existente

Mensagem exibida: Nenhuma — a ação de abrir o formulário ou de salvar não responde ou é bloqueada.

O que fazer: confirmar se o usuário tem a permissão de editar grupo atribuída ao seu perfil de acesso.

T-04 — O botão Excluir não remove o grupo selecionado

Mensagem exibida: Nenhuma — a ação não responde, ou o diálogo de confirmação não avança.

O que fazer: confirmar se o usuário tem a permissão de excluir grupo atribuída ao seu perfil de acesso.

T-05 — A listagem de Grupos aparece vazia ou incompleta mesmo havendo grupos cadastrados

Cenário: o usuário espera ver um grupo específico na listagem, mas ele não aparece.

Mensagem exibida: Nenhuma — a grade simplesmente não traz o registro esperado.

O que fazer: confirmar se todas as empresas vinculadas ao grupo esperado estão entre as empresas do usuário logado; um grupo com qualquer empresa vinculada fora do acesso do usuário não aparece na listagem dele — apenas grupos “Gerais” (sem nenhuma empresa vinculada) aparecem sempre. Confirmar também se o filtro de Empresa do painel não está restringindo além do esperado (por exemplo, com a opção “Geral” selecionada, apenas grupos sem empresa aparecem).

T-06 — Erro ao salvar um grupo com nome já usado: “Já existe um Grupo com o nome {nome informado}”

Cenário: o usuário cadastra ou renomeia um grupo para um nome já utilizado por outro grupo, mesmo de outra empresa.

Mensagem exibida: “Já existe um Grupo com o nome {nome informado}”

O que fazer: escolher outro nome; a verificação de nome duplicado considera todos os grupos do sistema, não apenas os da empresa selecionada.

T-07 — Erro ao salvar a edição de um grupo: “401 >> Grupo não encontrado.”

Cenário: o usuário edita um grupo que foi excluído por outra sessão antes de salvar.

Mensagem exibida: “401 >> Grupo não encontrado.”

O que fazer: atualizar a listagem e confirmar se o grupo ainda existe antes de tentar salvar novamente.

T-08 — Erro ao excluir um grupo que não existe mais

Cenário: o usuário tenta excluir um grupo já removido por outra sessão.

Mensagem exibida: “401 >> grupo não encontrado, ou dados inválidos para esta operação.”

O que fazer: atualizar a listagem antes de tentar excluir novamente.

T-09 — Erro ao excluir um grupo com usuários vinculados

Mensagem exibida: “Não é possível excluir este grupo, pois existem usuários vinculados a ele.”

O que fazer: informar ao usuário que o grupo está em uso e não pode ser excluído; se a exclusão for realmente necessária, desvincular antes todos os usuários pelo modal “Usuários” do próprio grupo.

T-10 — Erro ao vincular um usuário já vinculado ao mesmo grupo

Mensagem exibida: “400 >> Grupo já cadastrado neste usuário.”

O que fazer: confirmar na grade do modal se o usuário já não está na lista de vinculados antes de buscá-lo novamente pelo lookup.

T-11 — Erro ao remover um vínculo de usuário que já não existe mais

Mensagem exibida: “401 >> Relação usuário x grupo não encontrada.”

O que fazer: atualizar a grade do modal antes de tentar remover o vínculo novamente.

T-12 — A busca de usuário no modal de vínculo não retorna resultados para um grupo “Geral”

Cenário: o usuário abre o modal “Usuários” de um grupo sem nenhuma empresa vinculada (grupo “Geral”) e tenta buscar alguém para vincular.

Mensagem exibida: Nenhuma — a busca simplesmente não retorna nenhum usuário.

O que fazer: registrar o comportamento e encaminhar ao responsável técnico; trata-se de uma situação conhecida (ver registro técnico de bugs desta feature) em que a busca de usuário não se comporta como esperado para grupos sem empresa vinculada.

Caso 1 — Cadastro de um grupo “Geral” e vínculo de usuários a ele

Um usuário com permissão de novo grupo abre a listagem de Grupos, clica em Novo, informa o nome “Auditores Internos” e a descrição “Grupo de acesso a auditorias”, não seleciona nenhuma empresa e salva. O portal exibe “Operação efetuada com sucesso.” e retorna para a listagem. Ao reabrir o grupo salvo, o usuário clica em “Usuários”, busca um colaborador pelo nome e o vincula ao grupo automaticamente, sem confirmação.

Caso 2 — Cadastro de um grupo vinculado a uma empresa específica

Um usuário com permissão de novo grupo cadastra o grupo “Qualidade Unidade Sul”, vinculando a empresa “Frigorífico Modelo Ltda”. O portal exibe “Operação efetuada com sucesso.”. Apenas usuários com acesso a essa empresa (ou a administradores com acesso a ela) conseguem ver esse grupo na listagem.

Caso 3 — Tentativa de excluir um grupo com usuários vinculados

Um usuário tenta excluir o grupo “Auditores Internos”, que já possui usuários vinculados. O portal exibe “Não é possível excluir este grupo, pois existem usuários vinculados a ele.” e o grupo permanece na listagem.

Caso 4 — Filtrar a listagem pela opção “Geral”

Um usuário abre o painel de filtros, seleciona a opção “Geral” no campo Empresa e clica em “Filtrar”. A grade recarrega mostrando apenas os grupos sem nenhuma empresa vinculada, mesmo que o usuário tenha acesso a várias empresas com grupos próprios cadastrados.