📄 Cópia local — fonte de verdade no GitHub. Origem: felipeluissalgueiro/cadencia-app / master / src/app/(app)/app/admin/CLAUDE.md/app/admin/CLAUDE.md) Sincronizar via /documentar-software ou sync_to_framework.py.

frontend-admin — painel administrativo¶

TL;DR¶

Área super_admin em /app/admin. 14 sub-rotas cobrindo gestão de tenants, billing, custos LLM, roteamento de modelos, feature flags e impersonação.

Identidade¶

• Tipo: Next.js 15 App Router
• Path: src/app/(app)/app/admin/
• Status: ativo
• Deps: Supabase (role super_admin), Workers Coolify VPS Master, VPS

Rotas e funcionalidades¶

Feature flags expostas no Admin¶

Operação multi-conta¶

O botão Nova subconta em /app/admin/tenants fica disponível somente ao super_admin. A tela lista raízes ativas com a flag multi-conta habilitada e envia uma requisição idempotente ao backend.

A operação cria tenant filho, configuração mínima, onboarding pendente, carteira com saldo zero, ledger privado e auditoria. Não cria usuário, membership, bônus ou conteúdo. Hierarquia não concede acesso implícito.

Veja Hierarquia multi-conta.

CostsDashboard¶

Rastreia todas as chamadas LLM por tenant (tabela api_call_logs). Permite identificar tenants de alto custo e otimizar modelo routing.

ModelRouter¶

Configura qual LLM usar por tipo de conteúdo e por tenant. Overrides de prompt por agente. API: POST /api/app/admin/model-routing + POST /api/app/admin/agent-prompts.

Don'ts¶

• Acesso super_admin verificado no backend — nunca confiar em check só no frontend
• Export CSV (GET /api/app/admin/export) tem dados sensíveis — não expor publicamente
• Não reutilizar provisioning de signup para criar subconta operacional
• Não criar membership de cliente implicitamente pela hierarquia

Quando usar¶

• Operação interna PD: gerenciar tenants, criar subcontas operacionais, monitorar custos LLM, configurar model routing, toggle feature flags globais e impersonar tenant para suporte.

Quando NÃO usar¶

• ❌ Por usuários tenant — role super_admin obrigatório, RLS bloqueia.
• ❌ Para exportar dados de outro tenant para uso externo — auditoria + LGPD.
• ❌ Sem 2FA habilitado (boa prática, ainda que técnico não exija hoje).

Por que funciona assim¶

• Custos LLM agregados em api_call_logs — visibilidade granular por tenant para otimizar prompts/modelos.
• Model routing configurável por tenant — permite testar Opus vs Sonnet sem deploy.
• Impersonate: sessão temporária mascarada como o tenant para diagnosticar sem login do usuário.

🚫 Don'ts¶

• Não alterar maintenance_mode=true sem avisar Felipe — quebra app de todos os tenants.
• Não sair de uma sessão impersonate sem logar audit log explícito.
• Não dar créditos manuais sem registro em billing/credits audit.
• Não mudar feature flag global em produção sem testar staging.

🪦 Já tentamos¶

• Feature flag rollout sem staging → bug em produção visível para todos. Razão de manter maintenance_mode como gate.

🔥 Troubleshooting¶

📚 Referências cruzadas¶

• frontend-app — App tenant
• api-routes — Endpoints /api/app/admin/*
• supabase-schema — Tabelas api_call_logs, audit_logs