arckode-framework 1.3.2 → 1.4.0

package/skills/realtime/SKILL.md

@@ -1,307 +1,32 @@
-# SKILL: Arckode Realtime — EventBus, Queue y WebSockets
+# Realtime — WebSockets, SSE, Event Bus
 
-> Activar cuando: comunicación entre módulos broadcast, jobs en background, WebSockets, tiempo real, notificaciones push.
+## Stack
 
----
+- WebSockets nativos (`ws`) o Socket.IO
+- SSE para unidireccional server→client
+- Event Bus interno (`EventEmitter`) para módulos
 
-## 1. EVENTBUS (pub-sub broadcast)
-
-**Cuándo usar EventBus vs Conectores:**
-- **Conector directo** → 2 módulos específicos, flujo claro y predecible
-- **EventBus** → 1 evento, N módulos reaccionan independientemente entre sí
-
-### Setup en composition-root.ts
-
-```ts
-import { EventBus } from 'arckode-framework/events'
-
-const events = new EventBus()
-
-// Pasar a los módulos que lo necesiten
-const system = new System({ ..., events })
-```
-
-### Emitir eventos (en el service)
-
-```ts
-// El service emite — no sabe quién escucha
-class PedidosService {
-  constructor(private events: EventBus, ...) {}
-
-  async confirmar(id: string): Promise<PedidoDTO> {
-    const pedido = await this.repo.update(id, { estado: 'confirmado' })
-    await this.events.emit('pedido.confirmado', pedido, 'pedidos')
-    return pedido!
-  }
-}
-```
-
-### Suscribirse (en composition-root, no en módulos)
+## Event Bus
 
 ```ts
-// Los suscriptores van en composition-root — no en los módulos
-events.on('pedido.confirmado', async (event) => {
-  const pedido = event.data as PedidoDTO
-  await inventario.descontarStock(pedido.productoId, pedido.cantidad)
-})
-
-events.on('pedido.confirmado', async (event) => {
-  const pedido = event.data as PedidoDTO
-  await notificaciones.enviar(pedido.usuarioId, 'Pedido confirmado')
-})
-
-// Suscribirse una sola vez
-events.once('sistema.iniciado', async (event) => {
-  await seeds.cargar()
-})
-
-// Cancelar suscripción
-const handler = async (event: EventMessage) => { ... }
-events.on('pedido.cancelado', handler)
-events.off('pedido.cancelado', handler)
-```
-
-### Inspeccionar (debug)
-
-```ts
-// Historial de los últimos 100 eventos
-const todos = events.getHistory()
-const soloConfirmados = events.getHistory('pedido.confirmado')
-
-// Cuántos listeners hay por evento
-console.log(events.listeners)  // { 'pedido.confirmado': 2, 'pedido.cancelado': 1 }
-
-// Limpiar historial
-events.clearHistory()
-```
-
-### Nomenclatura de eventos
-
-```
-{módulo}.{acción}            → pedido.confirmado, usuario.registrado
-{módulo}.{entidad}.{acción}  → inventario.stock.agotado
-sistema.{acción}             → sistema.iniciado, sistema.detenido
-```
-
----
-
-## 2. QUEUE SERVICE (jobs en background)
-
-**Cuándo usar Queue:**
-- Tareas que no deben bloquear la response HTTP (enviar email, generar PDF, procesar imagen)
-- Tareas que pueden fallar y necesitan reintentos automáticos
-- Tareas que deben ejecutarse con delay
-
-### Setup en composition-root.ts
-
-```ts
-import { QueueService, MemoryQueueAdapter } from 'arckode-framework/modules/queue'
-
-const queue = new QueueService(new MemoryQueueAdapter())
-```
-
-### Registrar handlers (antes de dispatch)
-
-```ts
-// Registrar los handlers ANTES de empezar a despachar
-queue.register('enviar-email', async (job) => {
-  const { to, subject, html } = job.data as { to: string; subject: string; html: string }
-  await mail.send({ to: { address: to }, subject, html })
-})
-
-queue.register('generar-reporte', async (job) => {
-  const { userId, periodo } = job.data as { userId: string; periodo: string }
-  const pdf = await generarPDF(userId, periodo)
-  await storage.upload({ ...pdf, fieldName: 'reporte' }, 'reportes')
-})
-
-queue.register('procesar-imagen', async (job) => {
-  const { imagePath, userId } = job.data as { imagePath: string; userId: string }
-  await redimensionarYOptimizar(imagePath)
-})
-```
-
-### Despachar jobs (desde el service)
-
-```ts
-// Fire-and-forget: no espera que el job termine
-async registrar(dto: RegisterDTO): Promise<UserDTO> {
-  const user = await this.repo.create(...)
-
-  // El email no bloquea — se procesa en background
-  await this.queue.dispatch('enviar-email', {
-    to: user.email,
-    subject: 'Bienvenido',
-    html: `<h1>Hola ${user.nombre}!</h1>`,
-  })
-
-  return user
-}
-
-// Con delay (30 segundos)
-await queue.dispatch('recordatorio-carrito', { userId }, { delay: 30_000 })
-
-// Con reintentos personalizados
-await queue.dispatch('procesar-pago', { monto, userId }, { maxAttempts: 5 })
-```
-
-### Manejo de errores y reintentos
-
-```ts
-// MemoryQueueAdapter reintenta automáticamente con backoff exponencial:
-// intento 1 → falla → espera 1s → intento 2 → falla → espera 2s → intento 3
-// maxAttempts default: 3
-
-// El handler recibe el job con metadatos
-queue.register('procesar-pago', async (job) => {
-  console.log(`Intento ${job.attempts}/${job.maxAttempts}`)
-  if (job.error) console.log('Error anterior:', job.error)
-
-  const { monto } = job.data as { monto: number }
-  await procesarPago(monto)
-})
-```
-
-**Nota:** `MemoryQueueAdapter` es solo para desarrollo — los jobs se pierden al reiniciar. Para producción → implementar `QueueAdapter` con Redis o una tabla en BD.
-
----
-
-## 3. WEBSOCKETS (tiempo real)
-
-### Setup en composition-root.ts
-
-```ts
-import { WSServer } from 'arckode-framework/ws'
-
-const ws = new WSServer()
-
-// Adjuntar al servidor HTTP ANTES de iniciar
-ws.attach(http.server)
-
-await system.start()
-```
-
-### Broadcast a todos los clientes
-
-```ts
-// Desde cualquier service inyectado con ws
-ws.broadcast('pedido.nuevo', {
-  id: pedido.id,
-  total: pedido.total,
-  estado: 'pendiente',
-})
-
-ws.broadcast('stock.actualizado', { productoId, stockActual })
-```
-
-### Enviar a un cliente específico
-
-```ts
-ws.sendTo(clientId, 'notificacion', {
-  tipo: 'success',
-  mensaje: 'Tu pedido fue confirmado',
-})
-```
-
-### Gestionar clientes
-
-```ts
-// Obtener todos los clientes conectados
-const clientes = ws.getClients()
-console.log(`${clientes.length} clientes conectados`)
-```
-
-### Inyectar WebSocket en un módulo
-
-```ts
-// En index.ts del módulo
-create({ logger, orm, router, ws }: ModuleDependencies) {
-  const service = new PedidosService(repo, ws, logger.child('pedidos'))
-  ...
-}
-
-// En service.ts (al root del módulo)
-class PedidosService {
-  constructor(
-    private repo: RepositoryAdapter<PedidoDTO>,
-    private ws: WSServer,
-    private logger: Logger,
-  ) {}
-
-  async confirmar(id: string): Promise<PedidoDTO> {
-    const pedido = await this.repo.update(id, { estado: 'confirmado' })
-    this.ws.broadcast('pedido.confirmado', { id, estado: 'confirmado' })
-    return pedido!
-  }
-}
-```
-
-### SSE como alternativa (Server-Sent Events)
-
-Para notificaciones unidireccionales servidor → cliente sin WebSocket:
-
-```ts
-// En el controller — SSE es más simple para notificaciones push
-router.get('/eventos', [auth.authenticate()], async (req) => {
-  return {
-    status: 200,
-    stream: async function* () {
-      // Enviar evento inicial
-      yield `data: ${JSON.stringify({ tipo: 'conectado' })}\n\n`
-
-      // Mantener conexión abierta — enviar heartbeat cada 30s
-      while (true) {
-        await new Promise(r => setTimeout(r, 30_000))
-        yield `data: ${JSON.stringify({ tipo: 'heartbeat' })}\n\n`
-      }
-    },
-    headers: {
-      'Content-Type': 'text/event-stream',
-      'Cache-Control': 'no-cache',
-      'Connection': 'keep-alive',
-    },
-  }
-})
-```
-
----
-
-## 4. COMBINACIONES COMUNES
-
-### EventBus + Queue (decoupled async pipeline)
-
-```ts
-// Módulo emite → EventBus → Queue despacha en background
-events.on('usuario.registrado', async (event) => {
-  const user = event.data as UserDTO
-  await queue.dispatch('enviar-bienvenida', { email: user.email, nombre: user.nombre })
-  await queue.dispatch('configurar-defaults', { userId: user.id })
-})
-```
-
-### Queue + WebSocket (progreso en tiempo real)
-
-```ts
-queue.register('exportar-reporte', async (job) => {
-  const { userId } = job.data as { userId: string }
-
-  ws.sendTo(userId, 'reporte.progreso', { paso: 1, total: 3, mensaje: 'Generando...' })
-  const datos = await obtenerDatos(userId)
-
-  ws.sendTo(userId, 'reporte.progreso', { paso: 2, total: 3, mensaje: 'Formateando...' })
-  const pdf = await generarPDF(datos)
+import { EventBus } from 'arckode'
+const bus: EventBus
 
-  ws.sendTo(userId, 'reporte.listo', { url: pdf.url })
-})
+bus.on('pedido:creado', (pedido) => { /* ... */ }) // callback catch
+bus.emit('pedido:creado', pedido) // dispatch
 ```
 
----
+| Clave | `on()` | `once()` | `emit()` |
+|-------|--------|----------|----------|
+| Persiste | ✅ hasta `off()` | ❌ tras 1er fire | — |
+| Async | ✅ callbacks | ✅ callbacks | ✅ await emit |
+| Error | atrapa y log | atrapa y log | lanza a caller |
 
-## 5. CHECKLIST REALTIME
+## Errores silenciosos
 
-- [ ] EventBus: suscriptores en composition-root, NO dentro de módulos
-- [ ] Queue: handlers registrados ANTES del primer dispatch
-- [ ] `MemoryQueueAdapter` solo para dev — jobs se pierden al reiniciar
-- [ ] WebSocket: `ws.attach(http.server)` ANTES de `system.start()`
-- [ ] Eventos nombrados en `{módulo}.{acción}` — no strings aleatorios
-- [ ] Handlers de queue con try/catch si el error debe notificarse al usuario
+| Error | Señal | Fix |
+|-------|-------|-----|
+| Memory leak en `on()` | Eventos acumulan listeners sin `off()` | `bus.once()` || cleanup en `dispose()` |
+| Socket sin heartbeat | Conexión muerta invisible | `ws.ping()` / `socket.io pingInterval` |
+| Evento sin tipo | `bus.emit('order:paid', whatever)` | Tipar payload con `interface OrderPaidPayload` |
+| Broadcast a todos | Socket envía a todos sin filtro | Room/channel por usuario o grupo |

package/skills/services/SKILL.md

@@ -1,206 +1,63 @@
-# SKILL: Arckode Services — Mail y Storage
+# Services — Lógica de Negocio
 
-> Activar cuando: enviar emails, subir archivos, gestionar attachments, servir uploads.
+## Regla cardinal
 
----
-
-## 1. MAIL SERVICE
-
-### Setup en composition-root.ts
-
-```ts
-import { MailService } from 'arckode-framework/modules/mail'
-import { SmtpAdapter } from 'arckode-framework/modules/mail/smtp-adapter'
-
-const mail = new MailService(
-  new SmtpAdapter({
-    host:   config.get('SMTP_HOST'),
-    port:   config.get<number>('SMTP_PORT'),
-    user:   config.get('SMTP_USER'),
-    pass:   config.get('SMTP_PASS'),
-    secure: config.get<number>('SMTP_PORT') === 465,
-  }),
-  { address: 'noreply@mi-app.com', name: 'Mi App' },  // from por defecto
-)
-```
-
-**Config requerida en .env:**
-```env
-SMTP_HOST=smtp.gmail.com
-SMTP_PORT=587
-SMTP_USER=mi@gmail.com
-SMTP_PASS=app-password-aqui
-```
-
----
-
-### API del MailService
+Service recibe `RepositoryAdapter<T>`, NUNCA el ORM.
 
 ```ts
-// Email simple
-await mail.send({
-  to:      { address: 'user@example.com', name: 'Juan' },
-  subject: 'Bienvenido',
-  html:    '<h1>Hola Juan!</h1>',
-  text:    'Hola Juan!',           // fallback plain text (recomendado)
-})
-
-// Múltiples destinatarios
-await mail.send({
-  to:      [{ address: 'a@x.com' }, { address: 'b@x.com' }],
-  cc:      { address: 'cc@x.com' },
-  bcc:     { address: 'bcc@x.com' },
-  subject: 'Notificación',
-  html:    '<p>Mensaje masivo</p>',
-})
-
-// Con adjunto
-await mail.send({
-  to:      { address: 'user@example.com' },
-  subject: 'Tu factura',
-  html:    '<p>Adjunto tu factura</p>',
-  attachments: [{
-    filename:    'factura.pdf',
-    content:     pdfBuffer,           // Buffer
-    contentType: 'application/pdf',
-  }],
-})
-
-// Helpers pre-construidos
-await mail.sendWelcome('user@example.com', 'Juan')
-await mail.sendPasswordReset('user@example.com', resetToken)
-```
-
----
-
-### Inyectar MailService en un módulo
-
-```ts
-// En index.ts del módulo
-create({ logger, orm, cache, router, auth, mail }: ModuleDependencies) {
-  const service = new AuthService(repo, auth, mail, logger.child('auth'))
-  ...
-}
-
-// En service.ts (al root del módulo)
-class AuthService {
-  constructor(
-    private repo: RepositoryAdapter<UserDTO>,
-    private auth: Auth,
-    private mail: MailService,
-    private logger: Logger,
-  ) {}
-
-  async registrar(dto: RegisterDTO) {
-    const user = await this.repo.create(...)
-    await this.mail.sendWelcome(user.email, user.nombre)  // no bloquear si falla
-    return user
+// ✅ bien
+class WalletsService {
+  constructor(private repo: RepositoryAdapter<WalletDTO>) {}
+  async credit(userId: string, amount: number) {
+    return this.repo.update(userId, { balance: { increment: amount } })
   }
 }
-```
-
-**Importante:** Envolver `mail.send()` en try/catch si el email no es crítico — el registro no debería fallar si el correo de bienvenida no llega.
-
----
-
-### Testear con mock
 
-```ts
-const mockMail = { send: mock(() => Promise.resolve()), sendWelcome: mock(() => Promise.resolve()) }
-const service = new AuthService(repo, auth, mockMail as any, logger)
-
-test('registrar envía email de bienvenida', async () => {
-  await service.registrar({ email: 'a@b.com', password: '12345678', nombre: 'Juan' })
-  expect(mockMail.sendWelcome).toHaveBeenCalledWith('a@b.com', 'Juan')
-})
-```
-
----
-
-## 2. STORAGE SERVICE
-
-### Setup en composition-root.ts
-
-```ts
-import { StorageService } from 'arckode-framework/modules/storage'
-import { LocalStorageAdapter } from 'arckode-framework/modules/storage/local-adapter'
-
-const storage = new StorageService(
-  new LocalStorageAdapter(
-    './uploads',    // directorio en disco
-    '/uploads',     // URL base pública
-  )
-)
-```
-
-**Para servir los archivos subidos**, agregar el static server:
-```ts
-import { serveStatic } from 'arckode-framework/static'
-serveStatic(router, './uploads', { prefix: '/uploads' })
+// ❌ mal — service acoplado al ORM
+class WalletsService {
+  constructor(private orm: ORM) {} // ← swap DB requiere cambiar esto
+}
 ```
 
----
-
-### API del StorageService
+## Patrones
 
 ```ts
-// Subir archivo
-const stored = await storage.upload(fileUpload, 'avatars')
-// → { url: '/uploads/avatars/1234-abc.png', path: 'avatars/1234-abc.png', ... }
-
-// Eliminar archivo
-await storage.delete('avatars/1234-abc.png')
-
-// Obtener URL pública
-const url = storage.getUrl('avatars/1234-abc.png')
-```
-
----
-
-### Recibir archivo desde HTTP request
+class PedidosService {
+  constructor(
+    private repo: RepositoryAdapter<PedidoDTO>,
+    private wallets: WalletsService, // otro service (no ORM)
+    private bus: EventBus,
+  ) {}
 
-```ts
-// En el controller — el framework parsea multipart/form-data automáticamente
-async uploadAvatar(req: HttpRequest): Promise<HttpResponse> {
-  const file = req.files?.['avatar']  // FileUpload
-  if (!file) throw new ValidationError('Archivo requerido', { avatar: 'requerido' })
-  if (!file.mimeType.startsWith('image/')) {
-    throw new ValidationError('Formato inválido', { avatar: 'debe ser una imagen' })
-  }
-  if (file.size > 5 * 1024 * 1024) {
-    throw new ValidationError('Archivo muy grande', { avatar: 'máximo 5MB' })
+  async create(data: CreatePedidoDTO): Promise<PedidoDTO> {
+    // validación de dominio
+    if (data.total <= 0) throw new Error('Total debe ser > 0')
+    // delegar persistencia
+    const pedido = await this.repo.create(data)
+    // emitir evento
+    this.bus.emit('pedido:creado', pedido)
+    return pedido
   }
-
-  const stored = await this.service.subirAvatar(req.user!.id, file)
-  return { status: 200, body: { url: stored.url } }
-}
-
-// En el service
-async subirAvatar(userId: string, file: FileUpload): Promise<StoredFile> {
-  const stored = await this.storage.upload(file, `avatars/${userId}`)
-  await this.repo.update(userId, { avatarUrl: stored.url })
-  return stored
 }
 ```
 
----
+## Inyección
 
-### Inyectar StorageService en un módulo
+Composition root (ej. `index.ts` del módulo):
 
 ```ts
-// ModuleDependencies incluye storage si fue pasado al System
-create({ logger, orm, router, storage }: ModuleDependencies) {
-  const service = new UsuariosService(repo, storage, logger.child('usuarios'))
-  ...
+create({ orm, bus }) {
+  const repo = new OrmRepository<PedidoDTO>(orm, 'Pedido')
+  const walletsService = new WalletsService(new OrmRepository<WalletDTO>(orm, 'Wallet'))
+  return new PedidosService(repo, walletsService, bus)
 }
 ```
 
----
-
-### Checklist Mail + Storage
+## Errores silenciosos
 
-- [ ] `SMTP_*` variables en .env (nunca hardcodeadas)
-- [ ] `mail.send()` con try/catch si el email no es crítico para la operación
-- [ ] Validar `mimeType` y `size` antes de `storage.upload()`
-- [ ] `serveStatic()` configurado si se necesita acceso público a los archivos
-- [ ] Mockear ambos servicios en tests (no enviar emails reales en tests)
+| Error | Señal | Fix |
+|-------|-------|-----|
+| Service recibe ORM directo | `constructor(private orm: ORM)` | Cambiar a `RepositoryAdapter<T>` |
+| Service con lógica HTTP | Validación de request en service | Mover a controller/validateSchema |
+| Lógica repetida en services | Mismo filtro en 3 services | Domain repository |
+| Service sin interface | Acoplamiento directo | Usar `RepositoryAdapter<T>` |