Papéis, Permissões e Rotas

Esta documentação serve de referência técnica (inclusive para IA) sobre os níveis de acesso na plataforma Flowi Agentic.

A plataforma possui uma arquitetura SaaS Multi-tenant. O controle de acesso baseia-se primordialmente na existência (ou ausência) da flag de SUPER_ADMIN no Keycloak/Store e no papel (role) do usuário no contexto de um Tenant.

---

1. Perfis e Níveis de Acesso

A. Super Admin (Admin Global)

• Identificação Frontend: roles.includes('SUPER_ADMIN')
• Identificação Backend: Verificação da role global (via token Keycloak) ou ausência do header X-Tenant-ID em endpoints restritos /admin/*.
• Escopo: Todo o sistema. Não está amarrado a um tenant específico na interface de administração global.
• Responsabilidades: Cadastrar tenants, gerenciar definições de processos globais (BPMN/CMMN), templates DMN, gerenciar configurações de IA e todos os usuários.

B. Tenant Admin (Administrador do Tenant)

• Identificação Frontend: !isSuperAdmin && currentTenant?.role === 'ADMIN'
• Identificação Backend: Acesso a recursos via /a/* com permissão de manipulação de metadados do tenant, além do CRUD de usuários daquele tenant (/admin/tenants/{tenantId}/* que internamente valida as roles).
• Escopo: Restrito aos dados do seu próprio Tenant.
• Responsabilidades: Configurar o Business Key padrão do tenant, habilitar/desabilitar processos publicados no seu catálogo, gerenciar membros do seu próprio tenant (convites/remoções), gerenciar robôs (AI Agents), API Keys e Webhooks do tenant.

C. Tenant User (Usuário Padrão)

• Identificação Frontend: currentTenant?.role === 'USER'
• Identificação Backend: Acesso restrito via endpoints operacionais (/a/*) com header X-Tenant-ID.
• Escopo: Restrito à operação do próprio Tenant.
• Responsabilidades: Iniciar instâncias de processo, executar tarefas (/tasks), preencher formulários e visualizar dashboards operacionais.

---

2. Rotas do Frontend (React / TanStack Router)

A tabela abaixo cruza as rotas do frontend com a visibilidade de cada perfil:

Rota / Path	Módulo / Função	Super Admin	Tenant Admin	Tenant User
/dashboard	Visão geral, gráficos e contadores.	❌ (Usa admin panel)	✅	✅
/admin/tenants	Listagem e criação global de tenants.	✅	❌	❌
/admin/users	Listagem global de usuários.	✅	❌	❌
/admin/ai-config	Configuração do provider de IA.	✅	❌	❌
/admin/rag-config	Configuração de Retrieval-Augmented Generation.	✅	❌	❌
/definitions	Definições Locais (Catálogo de Processos) - Para TA: Visualiza processos publicados, permite ligar/desligar e configurar instâncias e tipos locais.	❌	✅	❌
/admin/global-templates	Templates Globais - Para SA: Lista tudo, permite criar BPMN/CMMN/DMN e configurar Tipos Documentais, Variáveis e Anexos globais.	✅	❌	❌
/admin/process-roles	Catálogo centralizado de Papéis de Processo.	✅	❌	❌
/admin/global-templates/$key	Detalhes do template e abas de configuração avançada.	✅	❌	❌
/instances	Listagem de instâncias ativas, histórico e erros.	❌ (Gestão global por API apenas)	✅	✅
/instances/start/*	Formulário para iniciar instâncias.	❌ (Restrito para evitar instâncias sem tenant)	✅	✅
/tasks	Caixa de entrada e execução de tarefas humanas.	❌	✅	✅
/cms	Gerenciamento de conteúdo dinâmico do tenant.	❌	✅	✅
/decisions	Tabela de Decisões e instâncias DMN executadas.	❌	✅	✅
/robots	Automação e bots vinculados ao tenant.	❌	✅	❌
/admin/api-keys	Chaves de API programáticas por tenant.	❌	✅	❌
/admin/webhooks	Callbacks configurados por tenant.	❌	✅	❌
/admin/tenants/$id	Gestão de membros do tenant.	✅	✅	❌

---

3. Endpoints de Backend e Permissões (REST API)

As APIs no Spring Boot são divididas por convenção de URL e filtros de segurança.

Prefixos Principais

1. /admin/**: Endpoints de gestão global.
   • Requerem role SUPER_ADMIN ou escopo equivalente.
   • Não requerem obrigatoriamente X-Tenant-ID, operando cross-tenant onde aplicável.
2. /a/**: Endpoints operacionais multi-tenant.
   • Requerem obrigatoriamente o header X-Tenant-ID.
   • O backend valida se o usuário autenticado possui o tenant listado em suas permissões.

Endpoints Chave de Controle de Processo

Endpoint	Método	Contexto	Acesso	Descrição
/admin/definitions	GET, POST	Global	SA	Consulta geral, deploy de arquivos XML para a plataforma.
/a/definitions	GET	Tenant	TA, User	Retorna o catálogo de processos ativos para o tenant.
/a/definitions/{key}/config	PUT	Tenant	TA	Configuração específica do processo no tenant (ex: Business Key Template).
/a/definitions/{key}/toggle	PATCH	Tenant	TA	Habilita/Desabilita o processo no tenant.
/a/instances	POST	Tenant	TA, User	Inicia uma instância de workflow em nome do tenant logado. Gera o Business Key de acordo com fallback hierarchy.
/a/instances/search	GET	Tenant	TA, User	Busca instâncias baseando-se em variáveis atreladas ao tenant logado.

---

4. Hierarchy Resolution para Business Keys (Nota para IA)

O backend resolve variáveis de inicialização como o Business Key numa ordem hierárquica (Implementado em WorkflowDefinitionService):

1. Configuração de Tenant (TenantProcessCatalog): O Tenant Admin sobrepõe a configuração global usando /a/definitions/{key}/config.
2. Configuração Global (WorkflowDefinition): O Super Admin configura o padrão do processo via /definitions/$key.
3. Padrão do Sistema: Fallback hardcoded para DOC-${date:yyyyMMdd}-${random:4}.

Esta arquitetura impede que o SA e o Tenant enviem hardcoded Business Keys, gerando consistência arquitetural na camada do Java (Flowable).