El equipo se entera donde ya está.

El API ya tiene un sistema de notificaciones completo: el modelo Notification, veintinueve tipos en NotificationTypeEnum y un atajo notifyAdmins() llamado desde dieciocho sitios distintos. Funciona. El problema es dónde termina: en una fila de Postgres que solo existe si alguien entra al panel y mira la campanita.

Una cotización que vence a las seis de la tarde, un pago rechazado tres veces seguidas o un cliente pidiendo hablar con una persona no pueden depender de que alguien recuerde revisar. El equipo ya vive en un chat. Ahí es donde tiene que llegar el aviso, y ahí mismo debería poder resolverse.

La regla que sostiene todo lo demás: las dependencias apuntan hacia adentro. El código de negocio no conoce el conector, publica un evento. El núcleo no conoce Slack ni Lark, habla con un puerto. Solo los adaptadores, en la orilla, conocen una plataforma concreta.

La capa 4 es el camino de vuelta: cuando alguien aprieta un botón, cada adaptador verifica la firma de su plataforma, normaliza la interacción al mismo sobre y se la entrega al despachador. De ahí en adelante el núcleo no distingue de dónde vino.

Esto es lo que ve el equipo. El mismo evento del catálogo, el mismo Card IR por detrás, y dos resultados que se sienten nativos en su casa: en Slack un attachment con barra de color, en Lark una tarjeta con cabecera sólida. Nadie escribe el mensaje dos veces.

Una notificación llega a un canal que tiene otras diez cosas encima, se discute, alguien aprieta un botón y al día siguiente alguien más quiere el resumen sin revolver el historial. Eso es lo que hay que diseñar, no el rectángulo aislado. Este es el cliente completo, a escala.

Cuando la acción viene de una tarjeta con discusión abierta, el conector responde en el hilo, no en el canal: el canal queda limpio y el contexto no se pierde. Es una opción de la regla de ruteo, responderEnHilo: true, no un comportamiento fijo.

Un conector serio no es solo mensajes al canal. «Pedir cambios» necesita que alguien escriba por qué; la pestaña Inicio convierte la app en un panel personal dentro de Slack; y /mogos permite consultar sin publicarle nada a nadie.

Lark no tiene canales con almohadilla: tiene grupos con avatar, la lista lateral muestra el último mensaje y las tarjetas van dentro del flujo del chat. Y trae algo que Slack no tiene: un toast de confirmación instantánea, y campos de formulario dentro de la propia tarjeta.

El toast oscuro es la confirmación que Lark devuelve en el mismo cuerpo del callback, antes de que la tarjeta termine de actualizarse. Slack no tiene equivalente: allá la señal de que el clic entró es que los botones se apagan.

Un evento no es una cadena de texto suelta. Es una entrada del catálogo con su payload validado por Zod, su severidad y la lista blanca de acciones que puede ofrecer. Si un servicio intenta publicar algo que no está aquí, no compila.

export const SERVICE_QUOTE_EVENTS = defineEvents({

  'service_quote.pending_approval': {
    severidad: 'accion',
    titulo:    'Cotización esperando aprobación',
    payload:   z.object({
      quoteId:   z.string().uuid(),
      code:      z.string(),          // SQ-2481
      client:    z.string(),
      amountUsd: z.number().positive(),
      marginPct: z.number(),
      expiresAt: z.date(),
      builtBy:   z.string(),
    }),
    // lista blanca: solo estas acciones pueden llegar a ser un botón
    acciones: ['quote.approve', 'quote.request_changes', 'quote.reject'],
  },

})

Publicar es una línea dentro del servicio que ya existe. El tipo del payload se infiere del catálogo:

// service-quotes.service.ts · dentro de la transacción que ya corre
await this.notifier.publish('service_quote.pending_approval', {
  quoteId: quote.id,   code: quote.code,       client: client.name,
  amountUsd: quote.total,  marginPct: quote.margin,
  expiresAt: quote.expiresAt,  builtBy: user.fullName,
})

Qué evento sale, a qué destino, bajo qué condición y con qué mención. Todo en TypeScript, revisable en un PR y con historia en git. Ningún evento sale por defecto: si no tiene regla, se queda en el panel y ya.

export const ROUTES: Route[] = [

  // operación diaria · informativo, sin ruido
  { on: 'freight.arrived_port', to: [canal('operaciones')] },

  // solo las cotizaciones que de verdad requieren a un manager
  {
    on:      'service_quote.pending_approval',
    to:      [canal('cotizaciones')],
    cuando:  (p) => p.amountUsd >= 5_000 || p.marginPct < 20,
    mencion: 'aqui',
    agrupar: (p) => `quote:${p.quoteId}`,   // una sola tarjeta por cotización
    responderEnHilo: true,
  },

  // el mismo evento, dos destinos, y silencio por cliente
  {
    on:       'payment.verification_failed',
    to:       [canal('pagos'), canal('guardia')],
    cuando:   (p) => p.attempts >= 3,
    mencion:  'canal',
    silencio: { ventanaMin: 60, por: (p) => p.clientId },
  },

]

Aquí el sistema es agnóstico o no lo es. El renderer convierte un evento en bloques semánticos — ni Block Kit, ni tarjeta de Lark. Seis tipos de bloque cubrieron las cuatro tarjetas de este documento, y cubrirían las siguientes veinte.

export type Card = {
  severidad: 'info' | 'accion' | 'critico' | 'exito'
  titulo:    string
  mencion?:  'aqui' | 'canal' | { usuarios: string[] }
  bloques:   Bloque[]
}

export type Bloque =
  | { t: 'texto';    md: string }
  | { t: 'campos';   items: { k: string; v: string }[] }
  | { t: 'linea' }
  | { t: 'pie';      items: string[] }
  | { t: 'enlace';   texto: string; url: string }
  | { t: 'acciones'; items: Accion[] }

export type Accion =
  | { tipo: 'enlace';  texto: string; url: string }
  | { tipo: 'ejecuta'
      clave: AccionKey                 // del registro de acciones
      texto: string                  // ≤ 30 · Slack trunca ahí
      estilo?: 'primario' | 'peligro'
      confirmar?: string
      campos?: CampoFormulario[] }     // modal en Slack, en tarjeta en Lark

Esto es todo lo que hay que implementar para enchufar Teams, Discord o lo que aparezca. Un archivo, sin tocar el núcleo.

export interface MessagingConnector {
  readonly plataforma: Plataforma

  // ── ida ──────────────────────────────────────────────────
  resolverDestino(ref: DestinoRef): Promise<string>
  enviar(destino: string, card: Card): Promise<EnvioRef>
  actualizar(ref: EnvioRef, card: Card): Promise<void>

  // ── vuelta ───────────────────────────────────────────────
  verificarFirma(req: PeticionCruda): boolean
  parsearAccion(req: PeticionCruda): SobreDeAccion
  acuse(sobre: SobreDeAccion, card?: Card): RespuestaHttp

  // ── capacidades opcionales · el núcleo pregunta antes ────
  enviarEfimero?(destino: string, usuario: string, card: Card): Promise<void>
  abrirFormulario?(sobre: SobreDeAccion, campos: CampoFormulario[]): Promise<void>
  publicarPanel?(usuario: string, card: Card): Promise<void>
}

SobreDeAccion es el mismo objeto venga de donde venga: { claveAccion, payload, usuarioPlataforma, envioRef, plataforma }. A partir de ese punto el núcleo no distingue Slack de Lark.

Slack y Lark coinciden en algo que define la arquitectura: hay 3 segundos para responder o el usuario ve un error en su pantalla. Aprobar una cotización toca base de datos, dispara correos y quizá un WhatsApp — eso no cabe. Por eso el despachador es ack-first: acusa recibo de inmediato y hace el trabajo después.

Alguien aprieta «Aprobar» y el conector no sabe quién es dentro de Mogos. Esto le pasa a todo el equipo el primer día, así que hay que diseñarlo, no improvisarlo.

Un botón en un chat es una superficie de ejecución expuesta a internet. Se trata como tal.

El repo no tiene BullMQ, ni Redis, ni bus de eventos — son llamadas directas a servicios, Prisma y @nestjs/schedule. Esta propuesta no los introduce: una tabla y el cron que ya está instalado alcanzan de sobra para el volumen de un equipo interno.

model ConnectorDelivery {
  id             String    @id @default(uuid()) @db.Uuid
  eventKey       String
  dedupeKey      String    @unique
  plataforma     ConnectorPlatformEnum
  destino        String
  card           Json
  estado         DeliveryStatusEnum @default(PENDIENTE)
  intentos       Int       @default(0)
  proximoIntento DateTime?
  refExterna     String?   // ts de Slack · message_id de Lark
  ultimoError    String?
  creadoEn       DateTime  @default(now())
  enviadoEn      DateTime?

  @@index([estado, proximoIntento])
  @@map("connector_deliveries")
}

La prueba de que la abstracción sirve. Esto es todo lo que costaría meter Teams mañana:

Esta tabla es el contrato del puerto: lo que está en las dos es obligatorio; lo que está en una sola es capacidad opcional.

Cada fase deja algo funcionando en producción. Ninguna depende de que la siguiente exista, así que el proyecto se puede detener en cualquier corte sin dejar nada a medias.

Tres cosas quedaron sin respuesta explícita durante el diseño. Están resueltas con el criterio más conservador para no bloquear la escritura del plan, pero cualquiera de las tres se puede cambiar sin rehacer nada. Si una de estas no te cuadra, dilo antes de empezar la fase 1.