Aspectos Técnicos do Permissionamento

Tabelas envolvidas

Tabelas core

Tabela	Responsabilidade
functionality	Funcionalidades do sistema (79 registros)
operation	Possíveis operações: VIEW(1), CREATE(2), EDIT(3), DELETE(4), EXPORT(5)
operation_functionality	Relação entre funcionalidades e operações disponíveis
user_type	Tipos de usuário: SMARTNX(1), ADMIN(2), GESTOR(3), SUPERVISOR(4), OPERADOR(5)
user_type_operation	Permissões padrão por tipo de usuário — usado no Contexto 1
permission_group	Grupos de permissão — vinculados a um client_id e user_type_id
permission_group_operation	Permissões efetivas do grupo — usado no Contexto 2
user_operation	Permissões customizadas individuais do usuário — usado exclusivamente no Contexto 3
users	Colunas relevantes: permission_group_id, has_custom_permissions

Tabelas de filas

Tabela	Responsabilidade
permission_group_queue	Filas associadas ao grupo de permissão

info

A tabela user_operation é populada exclusivamente para usuários com has_custom_permissions = true. Usuários do Contexto 1 e 2 não geram registros nela.

---

Diagrama de relacionamento

---

Resolução de permissões em runtime

Fluxo completo por requisição

Estrutura do cache Redis

Contexto 1 — sem grupo:

{
  "user_permission_default": {
    "functionalities": [
      { "id": 6, "name": "Usuários", "operations": [1, 2, 3] }
    ]
  }
}

Contexto 2 e 3 — com grupo:

{
  "user_group": {
    "id": 42,
    "name": "Supervisores Turno Manhã",
    "description": "...",
    "functionalities": [
      { "id": 6, "name": "Usuários", "operations": [1] }
    ]
  }
}

---

Middlewares

api/middleware/commonjs/authPermissions.js

Usado por APIs CommonJS. Instancia os componentes no nível do módulo (singleton por processo).

checkPermissions(req, res, next, functionalityId, operationId)

api/middleware/ecs/authPermissions.mjs

Versão ESM equivalente. Usada por: journey-api, contact-internal-api, webchat-mobile-renderer-api.

Uso nas rotas

const checkPermissionsMiddleware = {
    view:   (req, res, next) => checkPermissions(req, res, next, FunctionalitiesId.USERS, OperationId.VIEW),
    create: (req, res, next) => checkPermissions(req, res, next, FunctionalitiesId.USERS, OperationId.CREATE),
    edit:   (req, res, next) => checkPermissions(req, res, next, FunctionalitiesId.USERS, OperationId.EDIT),
    delete: (req, res, next) => checkPermissions(req, res, next, FunctionalitiesId.USERS, OperationId.DELETE),
};

router.get('/:userId', authenticateToken, checkPermissionsMiddleware.view, async (req, res) => { ... });

---

Componentes envolvidos

component/user-authorization

user-authorization.js

• permissionValidation(functionalityId, operationId, user) — resolve o contexto e verifica a permissão
• #checkUserPermission(serializedPermissions, functionalityId, operationId, resultValidation) — verifica se funcionalidade+operação estão presentes nas permissões serializadas
• authorizeCognito(token, selectedClientId) — valida o token e popula req.user com permission_group_id e has_custom_permissions
• selectClient(...) — carrega permissões e filas do usuário para a sessão após escolha de empresa

data/user-repository.js

• findCustomPermissionsByUserAndClient(userId, clientId) — busca permissões de user_operation com filtro de cliente (Contexto 3 no selectClient)
• findGroupPermissionsByUserAndClient(userId, clientId) — busca permissões de permission_group_operation com filtro de cliente (Contexto 2 no selectClient)
• findDefaultPermissionsByUserType(userTypeId) — busca permissões padrão de user_type_operation (Contexto 1 no selectClient)

component/permission-group-maintenance

permission-group-maintenance.js

• createPermissionGroup(...) — cria grupo, associa usuários e popula user_operation apenas para usuários com has_custom_permissions = true
• updatePermissionGroup(...) — recria permissões do grupo; ao trocar usuário de grupo (changeFounded) reseta has_custom_permissions = false
• deletePermissionGroupsById(...) — remove grupo e invalida cache dos usuários afetados
• findPermissionsByGroupId(permissionGroupId) — Contexto 2 no permissionValidation
• findCustomPermissionsByUserId(userId) — Contexto 3 no permissionValidation
• #invalidateUsersPermissionsCache(userIds) — invalida user_permissions:{userId} no Redis para os usuários afetados

data/permission-repository.js

• findPermissionsByGroupId(permissionGroupId) — lê permission_group_operation
• findCustomPermissionsByUserId(userId) — lê user_operation
• findPermissionsDefaultByUserTypeId(userTypeId) — lê user_type_operation, retorna { user_permission_default: {...} }
• findPermissionsByUserTypeId(userTypeId) — lê user_type_operation, retorna dados sem envelope (usado em listagens)
• findUserIdsByPermissionGroupId(permissionGroupId) — retorna IDs dos usuários do grupo para invalidação de cache

---

Cache de permissões (Redis)

Propriedade	Valor
Chave	user_permissions:{userId}
TTL	300 segundos
Invalidação	No logout do usuário; ao atualizar ou deletar o grupo

Quando o cache é invalidado

• Logout (logoutUserById, massiveLogoutUsersById, #logoutByEmail) — invalida a chave do usuário deslogado
• Atualização de grupo (updatePermissionGroup) — invalida as chaves de todos os usuários do grupo
• Deleção de grupo (deletePermissionGroupsById) — invalida as chaves de todos os usuários do grupo antes da deleção

---

Carregamento no selectClient

Ao selecionar a empresa (/selectclient/:clientId), o sistema carrega as permissões completas para a sessão:

---

Filas — detalhe técnico

Hierarquia de roles (rolesHierarchy)

Controla quem pode criar e gerenciar grupos para quais tipos de usuário:

SMARTNX  → [ADMIN, GESTOR, SUPERVISOR, OPERADOR]
ADMIN    → [GESTOR, SUPERVISOR, OPERADOR]
GESTOR   → [GESTOR, SUPERVISOR, OPERADOR]
SUPERVISOR → [SUPERVISOR, OPERADOR]

---

Enum de funcionalidades (FunctionalitiesId)

Referência completa dos IDs de funcionalidades usados ao registrar o middleware checkPermissions nas rotas:

ID	Constante	ID	Constante
1	QUEUES	40	BOT_MONITORING
2	TABULATIONS	41	QUEUE_MONITORING
3	PAUSES	42	VOICE_MONITORING
4	MACROS	48	EXPORT_BOARD_MONITORING
5	USER_GROUPS	60	EXTERNAL_API_KEY
6	USERS	61	CUSTOMIZATION
7	CONTACTS	62	TEMPLATE_FLOWS
8	LEADS	63	JOURNEY_DASHBOARD
9	CUSTOM_FIELDS	64	EMAIL
10	CONTACT_IMPORT	65	ATTENDANCE_HISTORY
11	LGPD	66	HSM_MANUAL_FIRING
12	FLOWS	67	MANUAL_CALL
13	TAGS	68	MASSIVE_ATTENDANCE_TRANSFER
14	SATISFACTION_SURVEY	69	TICKETS
15	HSM	70	INTERNAL_CHAT
16	SMS	71	OPERATOR_DASHBOARD
17	REALTIME_DASHBOARD	72	CHANGE_PASSWORD
18	ATTENDANCE_DASHBOARD	73	CHANGE_AUDIO_SETTINGS
19	ANALYTICAL_REPORT	74	ATTENDACE_DATA
20	CHANNELS	75	NOTIFICATION_SOUNDS
21	INTEGRATIONS	76	ATTENDANCE_SCREEN
22	MATCHSCRIPT	77	ATTENDANCE
24	ENTITIES_AND_INTENTS_GROUP	78	INTEGRATION_TICKET
25	SUBSCRIPTION	79	TICKET_ATTENDANCE
26	CONSUMPTION
27	CONSOLIDATED_BY_CHANNEL
28	HOLIDAYS_AND_RECESS
29	BLACKLIST
30	BILLING
31	SITUATION
32	META_PANEL_NUMBERS
33	INTEGRATION_CLASSIFICATION
34	EXPORTS_REPORT
35	JOURNEYS
37	SECTOR
38	HSM_DASHBOARD
39	TICKETS_DASHBOARD