Pular para conteúdo

MVP 2 - Painel Admin

Atualizado: 2026-05-18 Status: canonico para planejamento MVP2 Issue raiz: auraxis-platform#697

Visao executiva

O painel admin sera a superficie operacional do Auraxis em app.auraxis.com.br/admin. Ele deve permitir que pessoas autorizadas entendam usuarios, assinaturas, entitlements, insights de IA, auditoria, feature flags e saude operacional sem depender de acesso direto ao banco ou ferramentas internas.

O painel admin nao e um atalho para burlar seguranca. Toda acao sensivel deve ser protegida por RBAC, exigir motivo quando houver mutacao e gerar trilha de auditoria. O backend alvo e sempre auraxis-api-v2.

Objetivos

  • Dar visibilidade operacional sobre usuarios, assinatura e entitlements.
  • Investigar geracao de insights de IA, custos, tokens, modelo e consentimento.
  • Expor auditoria de acoes sensiveis.
  • Centralizar feature flags existentes e sinais operacionais seguros.
  • Permitir impersonacao read-only para suporte, sem mutacoes.
  • Reduzir necessidade de acesso manual ao banco em operacao diaria.

Nao objetivos

  • Criar um CRM completo.
  • Substituir Grafana Cloud, Sentry ou logs tecnicos.
  • Permitir impersonacao com escrita.
  • Criar endpoints novos no auraxis-api v1.
  • Expor prompts completos, segredos, tokens de provedor ou PII desnecessaria.

Principios de seguranca

  1. API v2 como autoridade. O front apenas reflete permissoes retornadas pela API v2.
  2. Negar por padrao. Usuario sem role admin nao deve ver rota, dados ou acoes admin.
  3. Motivo obrigatorio para mutacoes. Grant/revoke, flags e impersonacao exigem motivo humano.
  4. Auditoria sempre ligada. Toda mutacao admin deve registrar ator, alvo, acao, motivo, origem, timestamp e resultado.
  5. Read-only de verdade. Impersonacao de suporte deve bloquear mutacoes no front e na API.
  6. Minimizacao de dados. Insights IA e logs mostram evidencias redigidas, nao payloads sensiveis crus.

Roles iniciais

Role Uso Permissoes esperadas
owner Operacao maxima e governanca. Todas as permissoes admin, incluindo grants sensiveis.
admin Operacao de plataforma. Usuarios, assinaturas, flags, auditoria e operacao.
support Atendimento e diagnostico. Consulta de usuario e impersonacao read-only.
ai_auditor Auditoria de IA/LGPD. Insights IA, custos, consentimentos e eventos relacionados.

As permissoes devem ser granulares. Roles sao agrupadores; guards devem checar permissoes quando a acao for sensivel.

Claims e sessao

A API v2 deve expor as permissoes administrativas por JWT claim ou endpoint de sessao autenticada. A escolha final deve priorizar revogacao rapida e baixo risco de claim obsoleta.

Minimo esperado para o Web:

  • is_admin ou equivalente booleano.
  • Lista de permissoes granulares.
  • Identificador do ator admin.
  • Expiracao do token/sessao.
  • Sinal de step-up auth quando uma acao exigir reforco.

Modulos do painel

Overview

Resumo inicial com:

  • usuarios ativos/recentes;
  • assinaturas ativas, free, trial e canceladas quando disponivel;
  • insights IA gerados, falhos e custo agregado;
  • alertas operacionais resumidos;
  • links para Grafana Cloud, Sentry ou runbooks.

Usuarios, assinaturas e entitlements

Funcionalidades esperadas:

  • busca por email, id e nome quando disponivel;
  • detalhe de usuario com perfil, assinatura, plano, status, entitlements e metadados de conta;
  • grant/revoke de entitlement com confirmacao e motivo;
  • historico resumido de alteracoes;
  • bloqueio claro quando o admin nao tiver permissao de mutacao.

Insights IA e auditoria

Funcionalidades esperadas:

  • lista de insights gerados, pendentes, falhos e bloqueados por consentimento;
  • filtros por usuario, periodo, status e modelo;
  • custo, tokens, modelo, latencia e provider;
  • consentimento de IA vigente no momento da geracao;
  • evidencias redigidas e logs operacionais sem PII desnecessaria;
  • ligacao com eventos de auditoria.

Feature flags e operacoes

Funcionalidades esperadas:

  • lista de flags existentes por ambiente;
  • descricao, dono, estado atual e impacto esperado;
  • alteracao com confirmacao, motivo e auditoria quando o backend permitir;
  • resumo operacional seguro via API;
  • link externo para Grafana Cloud.

Grafana Cloud nao deve ser embedado em iframe. O admin deve mostrar um resumo proprio, retornado pela API, e abrir Grafana em link externo autenticado pelo servico.

Auditoria

Funcionalidades esperadas:

  • busca por ator, alvo, acao, periodo e resultado;
  • visualizacao de motivo, IP/origem quando permitido, timestamp e request id;
  • redacao de campos sensiveis;
  • exportacao futura somente se aprovada em tarefa propria.

Impersonacao read-only

Funcionalidades esperadas:

  • iniciar "visualizar como usuario" a partir do detalhe do usuario;
  • exigir motivo e permissao especifica;
  • mostrar banner persistente com usuario alvo, ator admin e botao para sair;
  • bloquear todas as mutacoes no front;
  • API rejeitar qualquer mutacao com sessao/token de impersonacao;
  • expirar em janela curta;
  • registrar auditoria de inicio, encerramento/expiracao e tentativas bloqueadas.

Regras de UX

  • Admin e ferramenta de trabalho, nao landing page. Deve ser denso, escaneavel e previsivel.
  • Modulos devem usar tabelas, filtros, detalhes laterais e estados vazios objetivos.
  • Toda acao perigosa deve explicar consequencia antes de confirmar.
  • Mensagens devem usar linguagem direta: "Revogar Premium" e nao "Atualizar entitlement".
  • Quando uma acao estiver indisponivel, a UI deve dizer se e falta de permissao, feature flag ou API indisponivel.

Regras LGPD e IA

  • Dados pessoais exibidos devem ser os minimos necessarios ao caso operacional.
  • Insights IA devem mostrar consentimento e base operacional sem expor prompt completo com PII.
  • Exclusao ou anonimizacao de usuario deve refletir no admin.
  • Eventos de auditoria devem ter retencao definida na matriz LGPD.
  • O admin nao deve sugerir que dados de usuarios sao usados para treinar modelos.

Dependencias principais

  1. auraxis-api-v2#41 - RBAC, roles e JWT claims.
  2. auraxis-api-v2#44 - Auditoria e acoes sensiveis.
  3. auraxis-web#888 - Shell /admin e guard.
  4. Modulos de usuarios, insights, flags e impersonacao em API/Web.

Ordem sugerida

  1. API v2 RBAC e auditoria.
  2. Web admin shell e guard.
  3. API/Web usuarios, assinaturas e entitlements.
  4. API/Web insights IA e auditoria.
  5. API/Web operacoes e Grafana Cloud.
  6. API/Web impersonacao read-only.

Criterios globais de aceite

  • Usuario comum nao acessa /admin.
  • Admin autorizado acessa shell e modulos conforme permissoes.
  • Toda mutacao admin exige motivo e gera auditoria.
  • Impersonacao e read-only no front e na API.
  • Insights IA exibem custo, tokens, modelo, status e consentimento com redaction.
  • Grafana Cloud e acessado por link externo, nao por embed.
  • Nenhum endpoint novo e criado no auraxis-api v1.

Referencias