Funções & Permissões

Visão Geral

Sistema de controle de acesso baseado em papéis (RBAC) com 11 permissões granulares. Roles podem ser globais (system) ou criadas por tenant. O AdminLayout filtra os itens de navegação visíveis com base nas permissões do JWT.

Localização

• Module/Service: backend/src/roles/
• View: frontend-react/src/views/superadmin/RolesView.tsx
• Controller superadmin: backend/src/superadmin/superadmin-roles.controller.ts
• Controller tenant: backend/src/roles/roles.controller.ts
• Guard: backend/src/common/guards/permissions.guard.ts
• Decorator: backend/src/common/decorators/require-permissions.decorator.ts
• Enum: backend/src/common/enums/permissions.enum.ts

Permissões (Enum)

enum Permission {
  manage_menu          = 'manage_menu',
  view_orders          = 'view_orders',
  manage_orders        = 'manage_orders',
  manage_tables        = 'manage_tables',
  manage_reservations  = 'manage_reservations',
  manage_users         = 'manage_users',
  manage_settings      = 'manage_settings',
  view_reports         = 'view_reports',
  use_pdv              = 'use_pdv',
  manage_inventory     = 'manage_inventory',
  manage_fiscal        = 'manage_fiscal',
}

Mapeamento Permissão → Nav Item

Permissão	Item de Nav no AdminLayout
view_orders / manage_orders	Pedidos
manage_menu	Cardápio
manage_tables	Mesas
manage_reservations	Reservas
manage_inventory	Estoque
manage_users	Usuários
manage_settings	Configurações
view_reports	Relatórios
use_pdv	Filial (PDV)
manage_fiscal	Fiscal

Roles do Sistema (Imutáveis)

Geradas pelo seeder — não podem ser excluídas.

Role	Permissões
admin	Todas as 11 permissões
staff	view_orders, manage_orders, use_pdv
kitchen	view_orders, manage_orders
cashier	use_pdv, view_orders, manage_orders
customer	(sem permissões admin)

Seed Endpoint

POST /api/superadmin/roles/seed

Cria as roles do sistema se não existirem (idempotente). Execute após primeiro deploy.

API Tenant-Scoped

Método	Rota	Descrição
GET	/api/t/:slug/roles	Lista roles do tenant
POST	/api/t/:slug/roles	Cria role customizada
PUT	/api/t/:slug/roles/:id	Atualiza role
DELETE	/api/t/:slug/roles/:id	Remove role (não system)

RolesView — UI

Interface split-screen:

• Painel esquerdo: Lista de roles do tenant. Botão "+ Nova Função".
• Painel direito: Ao selecionar uma role, exibe permissões disponíveis e atribuídas. Interação por clique (toggle) para mover permissões.

UserRole Junction

Entidade que associa usuário + role + tenant (+ PDV opcional):

interface UserRole {
  user: ObjectId;
  role: ObjectId;
  tenant: ObjectId;
  pdv?: ObjectId;
}

PermissionsGuard

@UseGuards(JwtAuthGuard, PermissionsGuard)
@RequirePermissions(Permission.manage_menu)
async createItem() { ... }

• Lê @RequirePermissions() do handler
• Superadmins e admins bypass automático
• Para staff: verifica permissions[] no JWT payload

Nav Filtering no Frontend

AdminLayout.tsx lê permissions do authStore. Cada item de nav tem uma lista de permissões requeridas. O item só aparece se o usuário tiver ao menos uma das permissões listadas (ou for admin/superadmin).

Relacionados

• Usuários Superadmin
• Staff Role
• authStore