theus-cli-darwin-x64 0.2.84

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

@@ -0,0 +1,560 @@
+---
+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.