Desenvolvimento da Suíte de Administração e Desenvolvedor
Esta skill ajuda você a estender o painel de administração e construir ferramentas internas seguindo os padrões estabelecidos.
PONTOS DE DECISÃO
Quando Adicionar Aba vs Modificar Endpoint vs Criar Nova Ferramenta
Adicionando Nova Funcionalidade de Admin:
├─ Usuário precisa de visualização de dados somente leitura?
│ ├─ Dados existem na API atual? → Modificar aba existente
│ ├─ Novo tipo de dado necessário? → Adicionar nova aba + novo endpoint
│ └─ Análises complexas necessárias? → Criar aba de análises dedicada
│
├─ Usuário precisa modificar dados do sistema?
│ ├─ Operações CRUD simples? → Adicionar aba de gerenciamento
│ ├─ Operações em lote necessárias? → Criar aba do console de operações
│ └─ Workflow de múltiplas etapas? → Construir componente de wizard
│
├─ Ferramentas internas para desenvolvedores?
│ ├─ Inspeção de código/documentação? → Adicionar ao portal de desenvolvimento
│ ├─ Monitoramento do sistema? → Adicionar ao console de operações
│ └─ Ferramentas de suporte ao usuário? → Adicionar ao painel de administração
│
└─ Funcionalidade para usuário externo?
→ PARE: Use a skill de desenvolvimento frontend
Estratégia de Implementação de Conteúdo da Aba
Avaliação de Complexidade da Aba:
├─ Exibição simples de estatísticas (< 5 métricas)?
│ → Usar padrão de grade StatCard
│
├─ Tabela de dados com filtragem?
│ ├─ < 1000 linhas? → Filtragem no lado do cliente
│ └─ > 1000 linhas? → Paginação e busca no lado do servidor
│
├─ Monitoramento em tempo real?
│ ├─ Atualizações a cada 30s+? → Usar SWR com intervalo de atualização
│ └─ Atualizações a cada 5s-? → Usar conexão WebSocket
│
└─ Controles interativos?
├─ Toggles/botões simples? → Ações inline
└─ Formulários complexos? → Diálogos modais + fluxos de confirmação
MODOS DE FALHA
1. Espiral da Morte de Performance de Consulta ao Banco
Sintoma: Painel de administração expira ou carrega lentamente (>5 segundos) Detecção: Monitorar tempos de resposta de /api/admin/* >3s Correção: Adicionar índices ao banco, implementar paginação, armazenar em cache estatísticas agregadas
-- RUIM: Varredura completa da tabela
SELECT COUNT(*) FROM pageViews WHERE userId = ?
-- BOM: Usar intervalos de timestamp indexados
SELECT COUNT(*) FROM pageViews WHERE createdAt > NOW() - INTERVAL 24 HOUR
2. Cache Desatualizado Mostrando Dados Errados
Sintoma: Administrador vê métricas desatualizadas que não correspondem à atividade recente Detecção: Usuário relata que as estatísticas não mudam após ações conhecidas Correção: Implementar invalidação de cache em mutações de dados, adicionar carimbos de data/hora "Última Atualização"
// Adicionar quebra de cache às mutações
await updateUserData(userId);
await revalidateTag('admin-stats'); // Limpar cache
3. Falta de Logging de Auditoria
Sintoma: Ações do administrador não são registradas na tabela auditLog Detecção: Verificar entradas de auditLog para ações de admin nas últimas 24h Correção: Adicionar chamadas logAdminAction() a TODOS os endpoints de admin
// Necessário em todo endpoint de admin
await logAdminAction(admin.id, AuditAction.USER_DATA_VIEW, 'users', userId);
4. Exposição de Dados por Violação de HIPAA
Sintoma: PHI visível em mensagens de erro, logs ou visualizações agregadas Detecção: Erro contém email/telefone/dados médicos do usuário Correção: Sanitizar todas as respostas de erro, usar identificadores hash nas visualizações de admin
// RUIM: Expõe email do usuário
{ error: "Usuário [email protected] não encontrado" }
// BOM: Usa identificadores anônimos
{ error: "ID do usuário hash_123abc não encontrado" }
5. Escalonamento de Privilégio de Admin
Sintoma: Usuários comuns podem acessar endpoints de admin Detecção: Usuário não-admin recebe dados de admin em vez de 403 Correção: Adicionar verificação requireAdmin() como primeira linha de todo endpoint de admin
export async function GET(request: Request) {
const admin = await requireAdmin(); // Deve ser a PRIMEIRA
if (!admin) return Response.json({ error: 'Proibido' }, { status: 403 });
// ... resto do manipulador
}
EXEMPLOS PRÁTICOS
Adicionando Aba de Monitoramento de Saúde da Produção
Cenário: Adicionar monitoramento de saúde da API em tempo real com métricas de latência, taxas de erro e status do serviço.
1. Navegação no Ponto de Decisão:
- Usuário precisa de monitoramento em tempo real → Usar SWR com atualização a cada 30s
- Dados do sistema, não dados do usuário → Adicionar ao painel de administração
- Novo tipo de dados (métricas da API) → Criar nova aba + endpoint
2. Passos de Implementação:
Criar endpoint com padrões necessários:
// src/app/api/admin/health/route.ts
export async function GET(request: Request) {
const admin = await requireAdmin(); // Segurança primeiro
if (!admin) return Response.json({ error: 'Proibido' }, { status: 403 });
const rateLimitResult = await rateLimiter.check(admin.id); // Rate limiting
if (!rateLimitResult.allowed) return Response.json({}, { status: 429 });
await logAdminAction(admin.id, 'HEALTH_VIEW', 'metrics', null); // Auditoria
const metrics = await getHealthMetrics(); // Busca de dados
return Response.json(metrics);
}
Criar componente da aba:
function ProductionHealthTab() {
const { data: health, error } = useSWR('/api/admin/health', fetcher, {
refreshInterval: 30000 // Atualizações em tempo real
});
return (
<div className="space-y-6">
<div className="grid grid-cols-4 gap-4">
<StatCard label="Tempo de Atividade da API" value="99.9%" status="good" />
<StatCard label="Latência Média" value="45ms" trend="down" />
<StatCard label="Taxa de Erro" value="0.1%" status="warning" />
<StatCard label="Serviços Ativos" value="12/12" status="good" />
</div>
</div>
);
}
3. Diferenças entre Especialista e Novato:
- Novato erra: Logging de auditoria, rate limiting, tratamento de erro seguro para HIPAA
- Especialista acerta: Estratégia de invalidação de cache, configuração de monitoramento de performance, limites de erro adequados
PORTÕES DE QUALIDADE
- Controle de acesso de admin: verificação requireAdmin() passa com usuário admin, falha com usuário comum
- Rate limiting: Endpoint retorna 429 quando o limite de taxa é excedido (60 req/min padrão)
- Logging de auditoria: Ação de admin registrada na tabela auditLog com tipo de ação correto
- Baseline de performance: Aba carrega em <2 segundos com volume de dados realista
- Conformidade HIPAA: Nenhum PHI exposto em mensagens de erro ou saída de debug
- Validação de dados: Requisições inválidas retornam erros 400 adequados com mensagens seguras
- Comportamento de cache: Dados atualizam em até 30 segundos após mudanças no backend
- Limites de erro: UI lida graciosamente com falhas de API sem travar
- Responsivo para mobile: Layout da aba funciona em telas de tablet (768px+)
- Atualizações em tempo real: Auto-atualização funciona sem vazamentos de memória por mais de 10 minutos
FRONTEIRAS DE NÃO USO
NÃO use esta skill para:
- Funcionalidades voltadas para usuário externo → Use
frontend-development - Fluxos de autenticação/login → Use
auth-security - Mudanças no esquema do banco de dados → Use
database-operations - Sistemas de email/notificação → Use
communications - Configuração de rate limiting de API → Use
backend-api - Configuração de conformidade HIPAA → Use
security-compliance - Otimização de performance → Use
optimization
Delegue para outras skills quando:
- Adicionando funcionalidades públicas para usuário →
frontend-development - Modificando autenticação de usuário →
auth-security - Criando novos endpoints de API para uso externo →
backend-api - Configurando infraestrutura de monitoramento →
devops-infrastructure