Grupos: listar e editar o perfil
Tela onde você localiza um grupo (tenant) já cadastrado, abre o perfil administrativo completo e vê as unidades que pertencem a ele. "Grupo" é o nome que a interface usa para o que a API chama de tenant — a organização/cliente dona de uma ou mais unidades.
Antes de começar
- Componentes:
TenantComponent(lista,@pages/administration/tenant),GroupGeneralComponent(perfil,@pages/group-detail) eGroupUnitsComponent(unidades do grupo,@pages/group-detail). - Rotas:
/admin/tenant(lista),/admin/tenant/:id/general(perfil),/admin/tenant/:id/units(unidades do grupo). - Para criar um grupo novo, veja Cadastrar um grupo (wizard).
Permissões e acesso
A lista (/admin/tenant) não tem nenhum guard de rota no frontend — qualquer pessoa
autenticada abre a URL. O que decide o que aparece na tabela é o próprio backend: um administrador
de plataforma vê todos os grupos ativos; qualquer outra pessoa só vê os grupos em que tem
permissão direta, ou dos quais é dono de alguma unidade em que ela tem acesso (ver
Tenants — API, regra RN-09). É por isso
que, neste levantamento, os quatro perfis de teste (administrator, manager, financial,
doctor — todos vinculados só à "Unidade Central Docs") viram a linha do grupo "Clínica Docs
Portal 2" na lista, mesmo sem nenhuma permissão de grupo: a visibilidade veio da unidade a que
pertencem, não de uma permissão de tenant.
O botão Cadastrar Grupo só aparece para administrador de plataforma (ver Cadastrar um grupo).
Já o Detalhe do grupo (/admin/tenant/:id/*) tem um guard de rota real:
permissionGuard('unit:read', 'route') — a pessoa precisa ter unit:read no próprio grupo
(não basta ter unit:read numa unidade dele). Uma tentativa sem essa permissão é redirecionada
silenciosamente para /admin/tenant, sem toast nem página de erro — confirmamos isso com os
quatro perfis testados: nenhum deles abre o detalhe do grupo, porque nenhum tem unit:read
concedido no escopo do tenant (só na unidade).
| Ação | Onde | Permissão exigida |
|---|---|---|
| Ver a linha do grupo na lista | /admin/tenant | Nenhuma no frontend — filtrado pelo backend por acesso direto ou por unidade |
| Botão Cadastrar Grupo | /admin/tenant | Administrador de plataforma |
| Abrir Detalhes / Unidades do grupo | /admin/tenant/:id/* | unit:read no grupo |
| Editar o perfil (botão Salvar) | /admin/tenant/:id/general | Sem checagem própria no componente — protegido só pelo guard de rota acima. A confirmar — responsável: time de frontend; data: 24/09/2026. se o backend aceita a gravação sem permission:manage |
| Inativar o grupo (menu "Mais ações") | /admin/tenant | permission:manage no grupo (iamSession.hasPermission(g.id, 'permission:manage')) — controla só a visibilidade do botão; a validação real é do backend |
Lista de grupos
A tabela mostra Nome, Apelido, Documento e E-mail Root, com filtro por qualquer um desses campos. Cada linha tem até três ações:
| Ação | Ícone | Condição de visibilidade |
|---|---|---|
| Detalhes | olho | Sempre visível — mas a rota de destino tem o guard de unit:read no grupo descrito acima |
| Histórico de auditoria | relógio | *appHasPermission="'audit:read'; scope: g.id" |
| Mais ações (menu "...") | reticências | Sempre visível; o conteúdo do menu varia |
O menu Mais ações sempre oferece Empresas (abre a lista de Unidades já filtrada por este
grupo) e Usuários (abre a lista de Usuários filtrada por este grupo) e Preferências. A
opção Inativar só aparece com permission:manage no grupo, e pede confirmação num diálogo
antes de chamar a inativação (soft-delete, sem cascata sobre unidades — ver
Tenants — API, RN-10).
Aba Detalhes: perfil do grupo
Formulário completo do perfil administrativo, reaproveitado do componente app-tenant-edit
também usado no wizard de criação:
| Campo | Obrigatório | Validação |
|---|---|---|
| Nome do grupo | Sim | até 255 caracteres |
| Apelido (slug) | Sim | minúsculo, alfanumérico com hífens; mensagem de erro genérica ("apelido inválido"), sem verificação de duplicidade em tempo real como no wizard |
| Tipo de Documento | — | CNPJ / CPF / estrangeiro |
| CNPJ/CPF | Sim | dígito verificador conforme o tipo |
| E-mail Root | Sim | formato de e-mail |
| Telefone | Não | máscara (99) 9 9999-9999 |
| Fuso Horário | Não | lista fixa de 11 fusos brasileiros comuns + UTC — não busca do catálogo de timezones como o wizard |
| Descrição | Não | texto livre |
No rodapé: Histórico (leva para a auditoria do grupo), Cancelar (repopula o formulário com os dados originais, descartando a edição sem pedir confirmação) e Salvar (desabilitado enquanto o formulário for inválido). Ao salvar com sucesso, aparece um toast de confirmação e a tela recarrega os dados do grupo.
Aba Unidades: as unidades deste grupo
Lista somente leitura das unidades do grupo — não é possível criar ou remover uma unidade a partir daqui. Mostra nome fantasia, documento e status (Ativo/Inativo), com o mesmo filtro reutilizável usado na lista global de Unidades.
O botão Editar de cada linha leva para /admin/company/:unitId/general — o detalhe completo da
unidade, documentado em Unidades. Para criar
uma unidade neste grupo, use o botão Incluir Unidade na tela de
Unidades (selecionando este grupo no campo Grupo) ou o
passo Unidades do wizard de criação do grupo.
Validações
Frontend
Ver a tabela de campos da aba Detalhes acima — a validação de formato roda no cliente antes de habilitar o botão Salvar.
Backend
A gravação usa o mesmo PATCH .../tenants/:id/profile documentado em
Tenants — API, seção Body e Erros; em particular, o
backend aceita atualização parcial com versionamento otimista (expectedVersion), mas o
formulário desta tela não expõe esse campo — toda gravação por aqui é "o último que salvar,
vale" (ver Tenants — API, RN-02).
Caminhos alternativos e falhas
| Situação | O que acontece | Como se recupera |
|---|---|---|
Sem unit:read no grupo | Redirecionamento silencioso para /admin/tenant, sem toast | Pedir a permissão a quem administra o grupo, ou usar a unidade diretamente |
| Slug ou documento já usado por outro grupo ativo, ao salvar | A confirmar — responsável: time de frontend; data: 24/09/2026. — não testado neste levantamento; a API responde 409 (ver Tenants — API), mas não confirmamos como a tela exibe esse erro | |
| Cancelar com edições não salvas | O formulário volta aos dados originais imediatamente, sem confirmação | Reabrir a aba e editar de novo, se foi engano |