curiositech/windags-skills

Desarrollo de Suite de Administración y Desarrollador

Este skill te ayuda a extender el panel de administración y construir herramientas internas siguiendo los patrones establecidos.

PUNTOS DE DECISIÓN

Cuándo Agregar una Pestaña vs Modificar un Endpoint vs Crear una Nueva Herramienta

Agregar Nueva Funcionalidad de Administración:
├─ ¿El usuario necesita una vista de datos de solo lectura?
│  ├─ ¿Los datos existen en la API actual? → Modificar pestaña existente
│  ├─ ¿Se necesita un nuevo tipo de datos? → Agregar nueva pestaña + nuevo endpoint
│  └─ ¿Se requieren análisis complejos? → Crear pestaña de análisis dedicada
│
├─ ¿El usuario necesita modificar datos del sistema?
│  ├─ ¿Operaciones CRUD simples? → Agregar pestaña de gestión
│  ├─ ¿Se necesitan operaciones por lotes? → Crear pestaña de consola de operaciones
│  └─ ¿Flujo de trabajo de varios pasos? → Construir componente de asistente
│
├─ ¿Herramientas internas para desarrolladores?
│  ├─ ¿Inspección de código/documentación? → Agregar al portal /dev
│  ├─ ¿Monitoreo del sistema? → Agregar a la consola /ops
│  └─ ¿Herramientas de soporte al usuario? → Agregar al panel de administración
│
└─ ¿Funcionalidad para usuarios externos?
   → DETENER: Usar el skill de desarrollo de frontend

Estrategia de Implementación de Contenido de Pestañas

Evaluación de Complejidad de Pestaña:
├─ ¿Visualización simple de estadísticas (< 5 métricas)?
│  → Usar patrón de cuadrícula StatCard
│
├─ ¿Tabla de datos con filtrado?
│  ├─ ¿Menos de 1000 filas? → Filtrado del lado del cliente
│  └─ ¿Más de 1000 filas? → Paginación del lado del servidor + búsqueda
│
├─ ¿Monitoreo en tiempo real?
│  ├─ ¿Actualizaciones cada 30s o más? → Usar SWR con intervalo de actualización
│  └─ ¿Actualizaciones cada 5s o menos? → Usar conexión WebSocket
│
└─ ¿Controles interactivos?
   ├─ ¿Alternancias/botones simples? → Acciones en línea
   └─ ¿Formularios complejos? → Diálogos modales + flujos de confirmación

MODOS DE FALLO

1. Espiral de Muerte de Rendimiento de Consultas de Base de Datos

Síntoma: El panel de administración se agota el tiempo de espera o carga lentamente (>5 segundos) Detección: Monitorear tiempos de respuesta /api/admin/* >3s Solución: Agregar índices de base de datos, implementar paginación, almacenar en caché estadísticas agregadas

-- MALO: Escaneo completo de tabla
SELECT COUNT(*) FROM pageViews WHERE userId = ?

-- BUENO: Usar rangos de tiempo indexados
SELECT COUNT(*) FROM pageViews WHERE createdAt > NOW() - INTERVAL 24 HOUR

2. Caché Obsoleto que Muestra Datos Incorrectos

Síntoma: El administrador ve métricas desactualizadas que no coinciden con la actividad reciente Detección: El usuario informa que las estadísticas no cambian después de acciones conocidas Solución: Implementar invalidación de caché en mutaciones de datos, agregar marcas de tiempo de "Última actualización"

// Agregar ruptura de caché a las mutaciones
await updateUserData(userId);
await revalidateTag('admin-stats'); // Limpiar caché

3. Falta de Registro de Auditoría

Síntoma: Las acciones de los administradores no se registran en la tabla auditLog Detección: Revisar entradas de auditLog para acciones de administración en las últimas 24h Solución: Agregar llamadas logAdminAction() a TODOS los endpoints de administración

// Requerido en cada endpoint de administración
await logAdminAction(admin.id, AuditAction.USER_DATA_VIEW, 'users', userId);

4. Exposición de Datos por Violación de HIPAA

Síntoma: PHI visible en mensajes de error, registros o vistas agregadas Detección: El error contiene correo electrónico/teléfono/datos médicos del usuario Solución: Sanitizar todas las respuestas de error, usar identificadores hash en las vistas de administración

// MALO: Expone el correo del usuario
{ error: "Usuario [email protected] no encontrado" }

// BUENO: Usa identificadores anónimos
{ error: "ID de usuario hash_123abc no encontrado" }

5. Escalada de Privilegios de Administración

Síntoma: Usuarios regulares pueden acceder a endpoints de administración Detección: Un usuario no administrador recibe datos de administración en lugar de un 403 Solución: Agregar verificación requireAdmin() como primera línea de cada endpoint de administración

export async function GET(request: Request) {
  const admin = await requireAdmin(); // Debe ser PRIMERO
  if (!admin) return Response.json({ error: 'Prohibido' }, { status: 403 });
  // ... resto del manejador
}

EJEMPLOS PRÁCTICOS

Agregar Pestaña de Monitoreo de Salud de Producción

Escenario: Agregar monitoreo de salud de API en tiempo real con métricas de latencia, tasas de error y estado del servicio.

1. Navegación de Puntos de Decisión:

• El usuario necesita monitoreo en tiempo real → Usar SWR con actualización cada 30s
• Datos del sistema, no datos de usuario → Agregar al panel de administración
• Nuevo tipo de datos (métricas de API) → Crear nueva pestaña + endpoint

2. Pasos de Implementación:

Crear endpoint con patrones requeridos:

// src/app/api/admin/health/route.ts
export async function GET(request: Request) {
  const admin = await requireAdmin(); // Seguridad primero
  if (!admin) return Response.json({ error: 'Prohibido' }, { status: 403 });
  
  const rateLimitResult = await rateLimiter.check(admin.id); // Límite de tasa
  if (!rateLimitResult.allowed) return Response.json({}, { status: 429 });
  
  await logAdminAction(admin.id, 'HEALTH_VIEW', 'metrics', null); // Auditoría
  
  const metrics = await getHealthMetrics(); // Obtención de datos
  return Response.json(metrics);
}

Crear componente de pestaña:

function ProductionHealthTab() {
  const { data: health, error } = useSWR('/api/admin/health', fetcher, {
    refreshInterval: 30000 // Actualizaciones en tiempo real
  });
  
  return (
    <div className="space-y-6">
      <div className="grid grid-cols-4 gap-4">
        <StatCard label="Tiempo de actividad de API" value="99.9%" status="bueno" />
        <StatCard label="Latencia promedio" value="45ms" trend="baja" />
        <StatCard label="Tasa de error" value="0.1%" status="advertencia" />
        <StatCard label="Servicios activos" value="12/12" status="bueno" />
      </div>
    </div>
  );
}

3. Diferencias entre Experto y Principiante:

• Lo que el principiante olvida: Registro de auditoría, limitación de tasa, manejo de errores seguro para HIPAA
• Lo que el experto capta: Estrategia de invalidación de caché, configuración de monitoreo de rendimiento, límites de error adecuados

PUERTAS DE CALIDAD

• Control de acceso de administración: la verificación requireAdmin() pasa con usuario administrador, falla con usuario regular
• Limitación de tasa: el endpoint devuelve 429 cuando se excede el límite de tasa (60 req/min por defecto)
• Registro de auditoría: la acción de administración se registra en la tabla auditLog con el tipo de acción correcto
• Línea base de rendimiento: la pestaña carga en <2 segundos con un volumen de datos realista
• Cumplimiento HIPAA: no se expone PHI en mensajes de error o salida de depuración
• Validación de datos: las solicitudes no válidas devuelven errores 400 adecuados con mensajes seguros
• Comportamiento de caché: los datos se actualizan dentro de los 30 segundos posteriores a cambios en el backend
• Límites de error: la UI maneja fallos de API de forma elegante sin fallar
• Adaptable a móviles: el diseño de la pestaña funciona en pantallas de tamaño tablet (768px+)
• Actualizaciones en tiempo real: la actualización automática funciona sin pérdidas de memoria durante más de 10 minutos

LÍMITES (NO PARA)

NO usar este skill para:

• Funcionalidades orientadas al usuario externo → Usar frontend-development en su lugar
• Flujos de autenticación/inicio de sesión → Usar auth-security en su lugar
• Cambios en el esquema de base de datos → Usar database-operations en su lugar
• Sistemas de correo electrónico/notificaciones → Usar communications en su lugar
• Configuración de limitación de tasa de API → Usar backend-api en su lugar
• Configuración de cumplimiento HIPAA → Usar security-compliance en su lugar
• Optimización de rendimiento → Usar optimization en su lugar

Delegar a otros skills cuando:

• Agregar funciones de usuario público → frontend-development
• Modificar autenticación de usuario → auth-security
• Crear nuevos endpoints de API para uso externo → backend-api
• Configurar infraestructura de monitoreo → devops-infrastructure