theus-cli 0.2.83 → 0.2.85

package/vendor/theus-arsenal/skills/patrones-backend/SKILL.md

@@ -1,560 +0,0 @@
----
-name: patrones-backend
-description: Patrones de arquitectura backend, diseño de APIs, optimización de bases de datos y buenas prácticas del lado del servidor para Node.js, Express y rutas de API de Next.js.
----
-
-# Patrones de desarrollo backend
-
-Patrones de arquitectura backend y buenas prácticas para aplicaciones del lado del servidor escalables.
-
-## Cuándo activarla
-
-- Al diseñar endpoints de API REST o GraphQL
-- Al implementar capas de repositorio, servicio o controlador
-- Al optimizar consultas de base de datos (N+1, índices, connection pooling)
-- Al añadir caché (Redis, en memoria, cabeceras de caché HTTP)
-- Al configurar trabajos en segundo plano o procesamiento asíncrono
-- Al estructurar el manejo de errores y la validación de APIs
-- Al construir middleware (autenticación, logging, limitación de tasa)
-
-## Patrones de diseño de APIs
-
-### Estructura de API RESTful
-
-```typescript
-// BIEN: URLs basadas en recursos
-GET    /api/markets                 # Listar recursos
-GET    /api/markets/:id             # Obtener un recurso
-POST   /api/markets                 # Crear un recurso
-PUT    /api/markets/:id             # Reemplazar un recurso
-PATCH  /api/markets/:id             # Actualizar un recurso
-DELETE /api/markets/:id             # Eliminar un recurso
-
-// BIEN: parámetros de query para filtrado, ordenamiento y paginación
-GET /api/markets?status=active&sort=volume&limit=20&offset=0
-```
-
-### Patrón Repository
-
-```typescript
-// Abstrae la lógica de acceso a datos
-interface MarketRepository {
-  findAll(filters?: MarketFilters): Promise<Market[]>
-  findById(id: string): Promise<Market | null>
-  create(data: CreateMarketDto): Promise<Market>
-  update(id: string, data: UpdateMarketDto): Promise<Market>
-  delete(id: string): Promise<void>
-}
-
-class SupabaseMarketRepository implements MarketRepository {
-  async findAll(filters?: MarketFilters): Promise<Market[]> {
-    let query = supabase.from('markets').select('*')
-
-    if (filters?.status) {
-      query = query.eq('status', filters.status)
-    }
-
-    if (filters?.limit) {
-      query = query.limit(filters.limit)
-    }
-
-    const { data, error } = await query
-
-    if (error) throw new Error(error.message)
-    return data
-  }
-
-  // Otros métodos...
-}
-```
-
-### Patrón de capa de servicio
-
-```typescript
-// Lógica de negocio separada del acceso a datos
-class MarketService {
-  constructor(private marketRepo: MarketRepository) {}
-
-  async searchMarkets(query: string, limit: number = 10): Promise<Market[]> {
-    // Lógica de negocio
-    const embedding = await generateEmbedding(query)
-    const results = await this.vectorSearch(embedding, limit)
-
-    // Obtener los datos completos
-    const markets = await this.marketRepo.findByIds(results.map(r => r.id))
-
-    // Ordenar por similitud
-    return markets.sort((a, b) => {
-      const scoreA = results.find(r => r.id === a.id)?.score || 0
-      const scoreB = results.find(r => r.id === b.id)?.score || 0
-      return scoreA - scoreB
-    })
-  }
-
-  private async vectorSearch(embedding: number[], limit: number) {
-    // Implementación de búsqueda vectorial
-  }
-}
-```
-
-### Patrón Middleware
-
-```typescript
-// Pipeline de procesamiento de solicitud/respuesta
-export function withAuth(handler: NextApiHandler): NextApiHandler {
-  return async (req, res) => {
-    const token = req.headers.authorization?.replace('Bearer ', '')
-
-    if (!token) {
-      return res.status(401).json({ error: 'No autorizado' })
-    }
-
-    try {
-      const user = await verifyToken(token)
-      req.user = user
-      return handler(req, res)
-    } catch (error) {
-      return res.status(401).json({ error: 'Token inválido' })
-    }
-  }
-}
-
-// Uso
-export default withAuth(async (req, res) => {
-  // El handler tiene acceso a req.user
-})
-```
-
-## Patrones de base de datos
-
-### Optimización de consultas
-
-```typescript
-// BIEN: selecciona solo las columnas necesarias
-const { data } = await supabase
-  .from('markets')
-  .select('id, name, status, volume')
-  .eq('status', 'active')
-  .order('volume', { ascending: false })
-  .limit(10)
-
-// MAL: seleccionar todo
-const { data } = await supabase
-  .from('markets')
-  .select('*')
-```
-
-### Prevención de consultas N+1
-
-```typescript
-// MAL: problema de consultas N+1
-const markets = await getMarkets()
-for (const market of markets) {
-  market.creator = await getUser(market.creator_id)  // N consultas
-}
-
-// BIEN: obtención por lotes
-const markets = await getMarkets()
-const creatorIds = markets.map(m => m.creator_id)
-const creators = await getUsers(creatorIds)  // 1 consulta
-const creatorMap = new Map(creators.map(c => [c.id, c]))
-
-markets.forEach(market => {
-  market.creator = creatorMap.get(market.creator_id)
-})
-```
-
-### Patrón de transacción
-
-```typescript
-async function createMarketWithPosition(
-  marketData: CreateMarketDto,
-  positionData: CreatePositionDto
-) {
-  // Usa una transacción de Supabase
-  const { data, error } = await supabase.rpc('create_market_with_position', {
-    market_data: marketData,
-    position_data: positionData
-  })
-
-  if (error) throw new Error('La transacción falló')
-  return data
-}
-
-// Función SQL en Supabase
-CREATE OR REPLACE FUNCTION create_market_with_position(
-  market_data jsonb,
-  position_data jsonb
-)
-RETURNS jsonb
-LANGUAGE plpgsql
-AS $$
-BEGIN
-  -- La transacción inicia automáticamente
-  INSERT INTO markets VALUES (market_data);
-  INSERT INTO positions VALUES (position_data);
-  RETURN jsonb_build_object('success', true);
-EXCEPTION
-  WHEN OTHERS THEN
-    -- El rollback ocurre automáticamente
-    RETURN jsonb_build_object('success', false, 'error', SQLERRM);
-END;
-$$;
-```
-
-## Estrategias de caché
-
-### Capa de caché con Redis
-
-```typescript
-class CachedMarketRepository implements MarketRepository {
-  constructor(
-    private baseRepo: MarketRepository,
-    private redis: RedisClient
-  ) {}
-
-  async findById(id: string): Promise<Market | null> {
-    // Consulta primero la caché
-    const cached = await this.redis.get(`market:${id}`)
-
-    if (cached) {
-      return JSON.parse(cached)
-    }
-
-    // Fallo de caché: consultar la base de datos
-    const market = await this.baseRepo.findById(id)
-
-    if (market) {
-      // Cachear por 5 minutos
-      await this.redis.setex(`market:${id}`, 300, JSON.stringify(market))
-    }
-
-    return market
-  }
-
-  async invalidateCache(id: string): Promise<void> {
-    await this.redis.del(`market:${id}`)
-  }
-}
-```
-
-### Patrón Cache-Aside
-
-```typescript
-async function getMarketWithCache(id: string): Promise<Market> {
-  const cacheKey = `market:${id}`
-
-  // Intentar la caché
-  const cached = await redis.get(cacheKey)
-  if (cached) return JSON.parse(cached)
-
-  // Fallo de caché: consultar la BD
-  const market = await db.markets.findUnique({ where: { id } })
-
-  if (!market) throw new Error('Mercado no encontrado')
-
-  // Actualizar la caché
-  await redis.setex(cacheKey, 300, JSON.stringify(market))
-
-  return market
-}
-```
-
-## Patrones de manejo de errores
-
-### Manejador de errores centralizado
-
-```typescript
-class ApiError extends Error {
-  constructor(
-    public statusCode: number,
-    public message: string,
-    public isOperational = true
-  ) {
-    super(message)
-    Object.setPrototypeOf(this, ApiError.prototype)
-  }
-}
-
-export function errorHandler(error: unknown, req: Request): Response {
-  if (error instanceof ApiError) {
-    return NextResponse.json({
-      success: false,
-      error: error.message
-    }, { status: error.statusCode })
-  }
-
-  if (error instanceof z.ZodError) {
-    return NextResponse.json({
-      success: false,
-      error: 'La validación falló',
-      details: error.issues
-    }, { status: 400 })
-  }
-
-  // Registrar errores inesperados
-  console.error('Error inesperado:', error)
-
-  return NextResponse.json({
-    success: false,
-    error: 'Error interno del servidor'
-  }, { status: 500 })
-}
-
-// Uso
-export async function GET(request: Request) {
-  try {
-    const data = await fetchData()
-    return NextResponse.json({ success: true, data })
-  } catch (error) {
-    return errorHandler(error, request)
-  }
-}
-```
-
-### Reintentos con backoff exponencial
-
-```typescript
-async function fetchWithRetry<T>(
-  fn: () => Promise<T>,
-  maxRetries = 3
-): Promise<T> {
-  let lastError: Error
-
-  for (let i = 0; i < maxRetries; i++) {
-    try {
-      return await fn()
-    } catch (error) {
-      lastError = error as Error
-
-      if (i < maxRetries - 1) {
-        // Backoff exponencial: 1s, 2s, 4s
-        const delay = Math.pow(2, i) * 1000
-        await new Promise(resolve => setTimeout(resolve, delay))
-      }
-    }
-  }
-
-  throw lastError!
-}
-
-// Uso
-const data = await fetchWithRetry(() => fetchFromAPI())
-```
-
-## Autenticación y autorización
-
-### Validación de tokens JWT
-
-```typescript
-import jwt from 'jsonwebtoken'
-
-interface JWTPayload {
-  userId: string
-  email: string
-  role: 'admin' | 'user'
-}
-
-export function verifyToken(token: string): JWTPayload {
-  try {
-    const payload = jwt.verify(token, process.env.JWT_SECRET!) as JWTPayload
-    return payload
-  } catch (error) {
-    throw new ApiError(401, 'Token inválido')
-  }
-}
-
-export async function requireAuth(request: Request) {
-  const token = request.headers.get('authorization')?.replace('Bearer ', '')
-
-  if (!token) {
-    throw new ApiError(401, 'Falta el token de autorización')
-  }
-
-  return verifyToken(token)
-}
-
-// Uso en una ruta de API
-export async function GET(request: Request) {
-  const user = await requireAuth(request)
-
-  const data = await getDataForUser(user.userId)
-
-  return NextResponse.json({ success: true, data })
-}
-```
-
-### Control de acceso basado en roles
-
-```typescript
-type Permission = 'read' | 'write' | 'delete' | 'admin'
-
-interface User {
-  id: string
-  role: 'admin' | 'moderator' | 'user'
-}
-
-const rolePermissions: Record<User['role'], Permission[]> = {
-  admin: ['read', 'write', 'delete', 'admin'],
-  moderator: ['read', 'write', 'delete'],
-  user: ['read', 'write']
-}
-
-export function hasPermission(user: User, permission: Permission): boolean {
-  return rolePermissions[user.role].includes(permission)
-}
-
-export function requirePermission(permission: Permission) {
-  return (handler: (request: Request, user: User) => Promise<Response>) => {
-    return async (request: Request) => {
-      const user = await requireAuth(request)
-
-      if (!hasPermission(user, permission)) {
-        throw new ApiError(403, 'Permisos insuficientes')
-      }
-
-      return handler(request, user)
-    }
-  }
-}
-
-// Uso: una HOF envuelve el handler
-export const DELETE = requirePermission('delete')(
-  async (request: Request, user: User) => {
-    // El handler recibe al usuario autenticado con el permiso verificado
-    return new Response('Eliminado', { status: 200 })
-  }
-)
-```
-
-## Limitación de tasa
-
-La limitación de tasa debe usar un almacén compartido como Redis, un gateway o
-el limitador nativo de la plataforma. No uses contadores en memoria por proceso
-para APIs en producción: se reinician con cada deploy, se fragmentan entre
-réplicas y fallan en abierto en entornos serverless o multi-instancia.
-
-Deja que la capa backend sea responsable de elegir el punto de integración y la
-forma del error; usa `diseno-api` para el contrato HTTP y `revision-seguridad`
-para revisar los casos de abuso.
-
-## Trabajos en segundo plano y colas
-
-### Patrón de cola simple
-
-```typescript
-class JobQueue<T> {
-  private queue: T[] = []
-  private processing = false
-
-  async add(job: T): Promise<void> {
-    this.queue.push(job)
-
-    if (!this.processing) {
-      this.process()
-    }
-  }
-
-  private async process(): Promise<void> {
-    this.processing = true
-
-    while (this.queue.length > 0) {
-      const job = this.queue.shift()!
-
-      try {
-        await this.execute(job)
-      } catch (error) {
-        console.error('El trabajo falló:', error)
-      }
-    }
-
-    this.processing = false
-  }
-
-  private async execute(job: T): Promise<void> {
-    // Lógica de ejecución del trabajo
-  }
-}
-
-// Uso para indexar mercados
-interface IndexJob {
-  marketId: string
-}
-
-const indexQueue = new JobQueue<IndexJob>()
-
-export async function POST(request: Request) {
-  const { marketId } = await request.json()
-
-  // Añadir a la cola en vez de bloquear
-  await indexQueue.add({ marketId })
-
-  return NextResponse.json({ success: true, message: 'Trabajo encolado' })
-}
-```
-
-## Logging y monitoreo
-
-### Logging estructurado
-
-```typescript
-interface LogContext {
-  userId?: string
-  requestId?: string
-  method?: string
-  path?: string
-  [key: string]: unknown
-}
-
-class Logger {
-  log(level: 'info' | 'warn' | 'error', message: string, context?: LogContext) {
-    const entry = {
-      timestamp: new Date().toISOString(),
-      level,
-      message,
-      ...context
-    }
-
-    console.log(JSON.stringify(entry))
-  }
-
-  info(message: string, context?: LogContext) {
-    this.log('info', message, context)
-  }
-
-  warn(message: string, context?: LogContext) {
-    this.log('warn', message, context)
-  }
-
-  error(message: string, error: Error, context?: LogContext) {
-    this.log('error', message, {
-      ...context,
-      error: error.message,
-      stack: error.stack
-    })
-  }
-}
-
-const logger = new Logger()
-
-// Uso
-export async function GET(request: Request) {
-  const requestId = crypto.randomUUID()
-
-  logger.info('Consultando mercados', {
-    requestId,
-    method: 'GET',
-    path: '/api/markets'
-  })
-
-  try {
-    const markets = await fetchMarkets()
-    return NextResponse.json({ success: true, data: markets })
-  } catch (error) {
-    logger.error('Falló la consulta de mercados', error as Error, { requestId })
-    return NextResponse.json({ error: 'Error interno' }, { status: 500 })
-  }
-}
-```
-
-**Recuerda**: los patrones backend hacen posibles aplicaciones del lado del servidor escalables y mantenibles. Elige los patrones que se ajusten a tu nivel de complejidad.