Diagnóstico y Plan Anti-Churn

1. El Problema Real

El churn no es un problema de features. Es un problema de propuesta de valor no demostrada en el tiempo suficiente.

Hay tres capas:

Capa 1: El producto no gana la comparación con Excel en el día a día

El dato más revelador es que 5/12 clientes sí usaron el producto — no lo abandonaron por ignorancia. Lo evaluaron conscientemente y eligieron Excel. Eso significa que el costo de cambio de comportamiento supera el beneficio percibido para su caso de uso real.

El problema no es que Excel sea mejor. Es que para un comercio pequeño con 80-200 SKUs y una persona operando, la fricción de carga manual producto por producto hace que el sistema sea más lento que una planilla conocida. El valor de la plataforma (alertas, reportes, trazabilidad) es abstracto y futuro. El costo es inmediato y concreto.

Capa 2: El producto asume un operador que no existe

3/12 clientes se fueron porque "el empleado no supo usarlo". Esto revela una suposición de diseño incorrecta: el producto fue construido asumiendo que quien lo contrata también lo opera. En comercios minoristas mexicanos, el dueño contrata y el empleado usa — y ese empleado rota, no tiene contexto, y no tiene incentivo para aprender software nuevo.

Capa 3: La integración faltante rompe el flujo completo

2/12 mencionaron Clip/Conekta. Pero este número probablemente está subrepresentado: los clientes que se fueron por esto quizás ni llegaron a la entrevista, o lo mencionaron como razón secundaria. Si el punto de venta no se conecta, el inventario hay que actualizarlo a mano después de cada venta — lo que destruye el caso de uso principal.

El diagnóstico consolidado

El producto cobra por ser una solución completa pero entrega una herramienta parcial. La carga manual + sin integración POS + onboarding sin soporte crea un sistema que requiere más trabajo que el problema que resuelve. El cliente lo descubre en las primeras 2-4 semanas y se va.

El churn del 28% no es una crisis de retención. Es una crisis de product-market fit incompleto disfrazada de problema de retención.

2 y 3. Las 8 Ideas, Priorizadas

Prioridad 1 — CRÍTICO: Resolver antes del mes 1

🔴 Idea 1: Importación masiva desde Excel/CSV en onboarding

Señal que ataca: 5/12 "volví a Excel porque es más rápido"

Hipótesis: El abandono ocurre en las primeras semanas cuando el cliente intenta cargar su catálogo producto por producto y calcula mentalmente cuántas horas le tomará. Si eliminás esa fricción inicial, el cliente llega al momento en que el sistema empieza a generar valor antes de que tome la decisión de irse.

El objetivo no es competir con Excel — es usar Excel como puente de entrada.

Qué construir:

• Upload de archivo CSV/Excel con mapeo de columnas (nombre, SKU, precio, cantidad inicial)
• Template descargable pre-formateado
• Validación con preview antes de importar
• Manejo de errores fila por fila

Esfuerzo: S — 1 developer, ~2 semanas. La lógica de parseo es estándar, el mapeo de columnas tiene librerías maduras.

Métrica de éxito: Tiempo hasta primer inventario completo cargado < 30 minutos para el 80% de nuevos clientes.

🔴 Idea 2: Onboarding guiado con checklist de activación (primeras 72 horas)

Señal que ataca: 3/12 "mi empleado no supo usarlo", 5/12 abandono silencioso

Hipótesis: No hay un momento de activación definido. El cliente entra, ve una pantalla vacía, no sabe qué hacer primero, y cierra la pestaña. Si definís los 3 pasos que llevan al cliente a su primer "momento de valor" (ver una alerta real de stock bajo de su propio inventario), reducís el abandono en la primera semana.

Qué construir:

• Checklist en pantalla: (1) Cargá tus primeros 10 productos, (2) Configurá tu primer umbral de alerta, (3) Registrá tu primera venta
• Progress bar visible
• Email automático a las 24h si no completó el paso 1
• Email a las 48h si no completó el paso 2

Esfuerzo: S/M — 1 developer + diseñador, ~3 semanas. La complejidad está en los emails automáticos y la lógica de triggers.

Métrica de éxito: % de clientes que completan los 3 pasos en 72h. Apuntar a >60%.

Prioridad 2 — ALTO IMPACTO: Resolver en el mes 1-2

🟠 Idea 3: Integración con Clip (primero Clip, después Conekta)

Señal que ataca: 2/12 explícito, pero probablemente el problema más subreportado

Hipótesis: Sin integración con el POS, el inventario siempre está desactualizado. Un sistema de inventario desactualizado no genera alertas confiables, no produce reportes útiles, y pierde toda su razón de existir. Esta integración no es un feature — es la diferencia entre un producto funcional y uno roto para una parte significativa de tu base.

Por qué Clip primero: Clip tiene >1M de comercios en México, API documentada, y es el POS dominante en el segmento de comercio pequeño que es exactamente tu mercado.

Qué construir:

• OAuth con Clip para autorización
• Sync automático de ventas → descuento de inventario
• Indicador de "última sincronización" en dashboard
• Manejo de productos que no matchean (por SKU o nombre)

Esfuerzo: L — 2 developers, 6-8 semanas. Las integraciones de POS tienen edge cases complejos (devoluciones, ventas offline, productos variables).

Métrica de éxito: Clientes con Clip integrado tienen churn < X% vs. los que no (medir diferencial).

🟠 Idea 4: Modo "empleado" con UX simplificada

Señal que ataca: 3/12 "mi empleado no supo usarlo"

Hipótesis: El empleado necesita hacer 2 cosas: registrar entradas de mercancía y registrar salidas manuales. Nada más. Si le das una interfaz con 6 menús y reportes, se bloquea. Un modo con pantalla única, botones grandes, y flujo de 3 taps reduce el error de adopción sin cambiar el producto para el dueño.

Qué construir:

• Segundo rol de usuario: "Operador"
• Vista simplificada: solo "Registrar entrada" y "Registrar salida"
• Búsqueda de producto por nombre (no por SKU)
• El dueño invita al operador por email desde su cuenta

Esfuerzo: M — 1 developer + diseñador, ~4 semanas.

Métrica de éxito: % de cuentas con al menos 2 usuarios activos en el mes. Hipótesis: más usuarios = menor churn.

Prioridad 3 — IMPACTO MEDIO: Resolver en el mes 2-3

🟡 Idea 5: Alertas de stock bajo por WhatsApp (no solo email)

Señal que ataca: Valor percibido bajo (2/12 "el precio no vale")

Hipótesis: Las alertas por email tienen tasa de apertura baja en este segmento. El dueño de un comercio minorista en México está en WhatsApp, no en su inbox. Si la alerta llega donde él vive, el sistema demuestra valor activamente en lugar de esperar a que el usuario entre a verlo. Cada alerta útil es un recordatorio de que el producto está trabajando para él.

Qué construir:

• Integración con WhatsApp Business API (o Twilio para WhatsApp)
• Configuración de número en perfil
• Alerta con mensaje: "⚠️ [Producto] tiene solo [X] unidades. ¿Querés hacer un pedido?"
• Opción de silenciar por horario (no despertar al dueño a las 3am)

Esfuerzo: M — 1 developer, ~3 semanas. Twilio tiene SDK maduro, el trabajo está en la lógica de triggers y configuración.

Métrica de éxito: NPS de usuarios con WhatsApp activado vs. sin activar.

🟡 Idea 6: Reporte semanal automático (en lugar de solo mensual)

Señal que ataca: 2/12 "el precio no vale lo que obtengo"

Hipótesis: El reporte mensual es invisible — llega cuando el cliente ya tomó la decisión de renovar o no. Un resumen semanal enviado cada lunes a las 8am ("esta semana vendiste X unidades de tus top 5 productos, tenés 3 productos en riesgo de quiebre") crea un hábito de consumo de valor sin que el usuario tenga que entrar al sistema. El producto trabaja aunque el cliente no lo abra.

Esfuerzo: S — 1 developer, ~1 semana. Es lógica de queries + template de email. Bajo esfuerzo, alto impacto en percepción de valor.

Métrica de éxito: Tasa de apertura del reporte semanal. Si >40% lo abre, el producto está generando valor percibido.

Prioridad 4 — COMPLEMENTARIO

🔵 Idea 7: Customer Success proactivo en el día 7 y día 21

Señal que ataca: Todas las categorías de churn

Hipótesis: El churn ocurre en silencio. El cliente decide irse antes de cancelar. Una llamada o mensaje de WhatsApp en el día 7 ("¿pudiste cargar tu inventario? ¿te puedo ayudar con algo?") y en el día 21 ("¿estás viendo las alertas? ¿tienen sentido para tu negocio?") permite intervenir antes de que la decisión esté tomada.

Con 180 clientes activos, esto es manejable manualmente. No necesita automatización todavía.

Esfuerzo: S — No requiere desarrollo. Requiere que alguien (founder o un role part-time) haga las llamadas. El costo es tiempo humano, no código.

Métrica de éxito: Churn de cohortes contactadas vs. no contactadas.

🔵 Idea 8: Prueba gratuita de 14 días con tarjeta requerida al final

Señal que ataca: 2/12 "el precio no vale"

Hipótesis: Parte del churn temprano viene de clientes que nunca tuvieron intención real de pagar — se registraron para ver qué era. Cambiar el modelo de adquisición a trial con tarjeta al final filtra mejor a los clientes, mejora la calidad de la cohorte, y paradójicamente puede reducir el churn porcentual aunque reduzca el volumen de nuevos clientes.

Esfuerzo: S/M — Cambio en flujo de registro + lógica de billing. 2 semanas.

Métrica de éxito: Churn de cohortes post-cambio vs. pre-cambio (controlar por volumen).

Resumen Visual de Priorización

IMPACTO EN CHURN
     Alto │ 1. Import CSV    │ 3. Integración Clip  │
          │ 2. Onboarding    │ 4. Modo empleado     │
          ├──────────────────┼──────────────────────┤
     Medio│ 6. Reporte semanal│ 5. WhatsApp alertas │
          │ 7. CS proactivo  │                      │
          ├──────────────────┼──────────────────────┤
      Bajo│ 8. Trial model   │                      │
          └──────────────────┴──────────────────────┘
               Esfuerzo S/M        Esfuerzo M/L

Secuencia recomendada para los próximos 90 días:

• Mes 1: Ideas 1 + 2 + 6 + 7 (todo S, máximo impacto inmediato)
• Mes 2: Ideas 4 + 5 (M, mejora experiencia del producto)
• Mes 3: Idea 3 (L, pero necesaria para el largo plazo)

4. La Idea que NO Haría: App Nativa (iOS/Android)

Es la idea que casi con certeza ya está en el backlog o alguien la pidió.

Por qué suena atractiva: Los clientes son dueños de comercios que pasan el día en el local, no frente a una computadora. Una app nativa parece el canal natural. Además, "hacer la app" suena a madurez de producto.

Por qué no la haría ahora:

Primero, no hay ninguna señal en las exit interviews que apunte a esto. Nadie se fue porque no había app. Construir features que no atacan causas de churn identificadas es un lujo que no podés darte con 28% de churn mensual.

Segundo, el costo de oportunidad es brutal. Una app nativa con tu equipo (2 devs, 1 diseñador part-time) toma 4-6 meses mínimo si querés hacerla bien — en iOS y Android, con sincronización offline, notificaciones push, y mantenimiento de dos codebases. Eso es todo tu equipo, todo tu tiempo, sin poder tocar nada más.

Tercero, el problema de fondo no es el canal — es que el producto no genera valor suficiente para justificar el cambio de comportamiento. Una app nativa de un producto que no retiene usuarios en web es una app nativa de un producto que no retiene usuarios. El canal no arregla el value proposition.

Cuarto, existe una alternativa de menor costo que resuelve el 80% del problema: PWA (Progressive Web App). Con tu app web responsive actual, podés agregar un manifest + service worker y el usuario puede "instalarla" en su home screen, recibir notificaciones push, y usarla offline. Esfuerzo: 2-3 semanas. Si después de esto la demanda de app nativa sigue siendo el principal bloqueador de churn, entonces tenés evidencia para construirla.

La regla: Construí lo que los clientes que se fueron te dijeron que necesitaban, no lo que imaginás que los clientes que todavía no tenés van a querer.

*El churn del 28% es recuperable. Con las ideas 1, 2, 6 y 7 implementadas en 30 días, de

8 Ideas de Productos AI para Lanzar en 90 Días

Idea 1: LexDraft AI

Generador de contratos y documentos legales para estudios jurídicos chicos

1. Cliente objetivo

Estudios jurídicos de 1-5 abogados en Argentina que hacen derecho comercial, laboral o civil. Facturan bien por hora pero pierden tiempo enorme en redactar documentos estándar desde cero o adaptando viejos templates de Word.

2. Problema concreto y por qué AI

Un abogado junior pasa 2-4 horas redactando un contrato de locación comercial, NDA o acuerdo de confidencialidad. Un template estático no sirve porque cada cliente tiene variables específicas (plazos, montos, cláusulas especiales). AI permite generar el borrador completo con las variables del caso en 3 minutos, que el abogado solo revisa y ajusta. El diferencial no es reemplazar al abogado, es que llegue a la reunión con el cliente con el documento casi listo.

3. Modelo de revenue

• SaaS mensual: $120 USD/mes por estudio (acceso ilimitado para hasta 3 usuarios)
• Alternativa de entrada: $35 USD por documento generado (para que prueben sin compromiso)
• Upsell: paquete de templates personalizados para su práctica específica, $300 USD one-time

Target 90 días: 8 estudios en suscripción = $960 USD/mes recurrentes

4. Primeros 5 clientes

Tenés 30 estudios jurídicos en tu red. Estrategia concreta:

• Escribís a 10 de ellos con este mensaje: "Estoy armando algo para estudios como el tuyo, te lo muestro en 20 minutos y si te sirve me pagás, si no me decís qué cambiarías"
• Ofrecés 30 días gratis a cambio de feedback semanal (3 llamadas de 20 min)
• Usás esos testimonios para cerrar los siguientes sin descuento

5. Riesgo principal

Que los abogados no confíen en el output y lo revisen tanto que no ahorren tiempo real. Mitigación: posicionarlo como "primer borrador inteligente", no como producto terminado. El valor está en el punto de partida, no en la perfección.

Idea 2: AuditPrep

Preparación automatizada de carpetas de auditoría para estudios contables

1. Cliente objetivo

Estudios contables de 3-15 profesionales que auditan pymes y necesitan armar legajos de auditoría. Vos conocés este dolor desde adentro.

2. Problema concreto y por qué AI

Armar un legajo de auditoría implica: cruzar datos de balances, identificar inconsistencias, redactar notas explicativas, preparar papeles de trabajo. Un semi-senior pasa 3 días en algo que podría resolverse en medio día. Software tradicional como CaseWare es caro, rígido y no redacta nada. AI puede analizar los datos cargados, detectar desvíos, y generar automáticamente las notas narrativas del legajo.

3. Modelo de revenue

• Por proyecto: $180 USD por legajo generado (el estudio lo cobra al cliente final entre $800-$2000 USD)
• Suscripción: $250 USD/mes para estudios con más de 5 auditorías mensuales
• El margen para el estudio es enorme → precio fácil de justificar

Target 90 días: 15 legajos en los primeros 2 meses = $2,700 USD

4. Primeros 5 clientes

Sos contador. Conocés el proceso. Entrás a 5 estudios de tu red de 80 contactos y ofrecés hacer el primer legajo gratis, vos presente, mostrando el proceso en tiempo real. No es una demo, es una entrega real. Eso vale más que cualquier pitch.

5. Riesgo principal

Que cada estudio tenga su propio formato de legajo y la customización sea costosa. Mitigación: empezás con UN tipo de auditoría (pymes bajo RT 37) y un formato estándar. Expandís después.

Idea 3: TaxMemo

Generador de informes de situación impositiva para que contadores entreguen a sus clientes pyme

1. Cliente objetivo

Contadores independientes y estudios chicos (1-3 personas) cuyos clientes pyme les preguntan constantemente "¿cómo estoy impositivamente?" y la respuesta siempre es una llamada de 40 minutos o un mail largo que nadie entiende.

2. Problema concreto y por qué AI

El contador sabe la respuesta, pero documentarla de forma clara para un empresario no-contador le lleva 1-2 horas. Resultado: o no lo hace, o cobra extra, o el cliente queda confundido. AI convierte los datos impositivos del cliente (vencimientos, saldos, regímenes) en un informe ejecutivo en lenguaje simple, con semáforos visuales y recomendaciones. El contador lo revisa en 10 minutos y lo manda con su firma. El producto no es para el contador, es lo que el contador le entrega a su cliente.

3. Modelo de revenue

• Suscripción al contador: $80 USD/mes, puede generar informes para todos sus clientes
• El contador puede cobrarle a sus clientes $20-$50 USD por informe mensual → el producto se autopaga
• Potencial de convertirse en servicio premium del estudio

Target 90 días: 12 contadores suscriptos = $960 USD/mes

4. Primeros 5 clientes

Tu red de 80 contadores es perfecta. Empezás con los 5 que más se quejan de que sus clientes no los entienden (todos tienen ese dolor). Les mostrás el informe final, no el proceso. Si el output los convence, el precio no es obstáculo.

5. Riesgo principal

Que los contadores tengan miedo de que el informe tenga un error y los comprometa profesionalmente. Mitigación: el informe siempre dice "preparado con asistencia de AI, revisado y firmado por [nombre del contador]". La responsabilidad queda en el profesional, como siempre.

Idea 4: MeetingMind Legal

Resumen y acta automática de reuniones para estudios jurídicos

1. Cliente objetivo

Estudios jurídicos de hasta 10 abogados donde las reuniones con clientes son la fuente principal de información del caso, pero nadie tiene tiempo de tomar actas estructuradas ni de resumir qué se acordó.

2. Problema concreto y por qué AI

Después de una reunión con un cliente, el abogado tiene que recordar qué se dijo, qué comprometió, qué información falta. Si no hay acta, hay conflictos. Si hay acta, alguien tardó 45 minutos en escribirla. AI transcribe la reunión (via Whisper o similar), extrae compromisos, fechas, datos del caso, y genera un acta estructurada + un resumen ejecutivo en 2 minutos. Software tradicional transcribe pero no interpreta ni estructura por tipo de reunión legal.

3. Modelo de revenue

• Suscripción: $90 USD/mes por estudio (hasta 5 usuarios, reuniones ilimitadas)
• Setup fee: $150 USD one-time para configurar templates según el tipo de práctica
• Integración opcional con Google Calendar para activar automáticamente

Target 90 días: 7 estudios = $630 USD/mes + $1,050 en setup fees

4. Primeros 5 clientes

De tus 30 estudios jurídicos, identificás los que tienen más de 2 abogados (más reuniones, más dolor). Pedís 30 minutos para mostrar el producto con una grabación de reunión real que ellos te pasen (anonimizada). Ver su propia reunión procesada en tiempo real es el mejor demo posible.

5. Riesgo principal

Confidencialidad. Los abogados son extremadamente sensibles a grabar conversaciones con clientes. Mitigación: el procesamiento puede ser local o con acuerdo de confidencialidad explícito con el proveedor de AI. Esto hay que resolverlo antes de vender, no después.

Idea 5: PropuestaAI

Generador de propuestas comerciales para pymes de servicios

1. Cliente objetivo

Pymes de servicios (consultoras, agencias, empresas de limpieza, catering, IT, etc.) de 5-30 empleados que mandan propuestas comerciales todos los días pero cada una la arma desde cero en Word, sin consistencia, sin personalización real, perdiendo deals por presentación pobre.

2. Problema concreto y por qué AI

Una propuesta comercial bien hecha para una empresa de servicios debería tener: contexto del cliente, propuesta de valor específica, alcance, precio, diferenciadores, casos de éxito relevantes. Armarla bien toma 2-3 horas. La mayoría manda un PDF genérico con el logo cambiado. AI permite que en 15 minutos, cargando datos básicos del prospecto, genere una propuesta personalizada, con el tono correcto, que parece hecha a medida. El diferencial frente a templates: la personalización real basada en el contexto del cliente.

3. Modelo de revenue

• Suscripción: $100 USD/mes por empresa
• Tier básico: $45 USD/mes (hasta 10 propuestas/mes) — entrada para pymes chicas
• Potencial: agregar tracking de apertura y firma digital como upsell

Target 90 días: 10 pymes = $700 USD/mes promedio

4. Primeros 5 clientes

Tus 20 pymes de servicios son el target exacto. El pitch es simple: "¿Cuántas propuestas mandás por semana? ¿Cuántas cerrás? Te muestro cómo mejorar esa conversión." No hablás de AI, hablás de cerrar más negocios.

5. Riesgo principal

Que las pymes no tengan cultura de propuestas formales (muchas cierran por WhatsApp y precio). Mitigación: validar primero con las pymes de tu red que efectivamente manden propuestas escritas. Si no las mandan, este producto no les duele.

Idea 6: ReclamoAI

Redacción automatizada de cartas documento, reclamos y comunicaciones formales

1. Cliente objetivo

Pymes de servicios y estudios contables que necesitan enviar comunicaciones formales (cartas documento, intimaciones de pago, reclamos a proveedores, notas a organismos) pero no tienen abogado propio y contratar uno para cada carta es caro y lento.

2. Problema concreto y por qué AI

Una carta documento bien redactada en Argentina requiere lenguaje formal específico, citas correctas del Código Civil/Comercial, y estructura que tenga peso legal. Hacerlo mal puede invalidar el reclamo. Contratar un abogado para una carta simple cuesta $150-$300 USD. AI entrenada con jurisprudencia argentina y modelos de comunicaciones formales puede generar el documento correcto en minutos. El usuario solo carga: quién soy, qué pasó, qué quiero. El output es revisable y editable.

3. Modelo de revenue

• Pay-per-use: $25 USD por documento generado
• Suscripción pyme: $120 USD/mes (documentos ilimitados)
• Canal indirecto: estudios contables lo ofrecen como servicio adicional a sus clientes, con markup

Target 90 días: 40 documentos individuales + 3 suscripciones = $1,360 USD

4. Primeros 5 clientes

Empezás por tus pymes de servicios — todas tienen deudores, proveedores problemáticos, o empleados con conflictos. El dolor es inmediato y concreto. Ofrecés el primer documento gratis. Si funciona, la venta siguiente es trivial.

5. Riesgo principal

Responsabilidad legal si el documento tiene un error que perjudica al cliente. Mitigación: disclaimer claro de que es un borrador para revisión profesional, no asesoramiento legal. Igual que TaxMemo, el profesional firma y valida.

Idea 7: OnboardAI

Sistema de onboarding automatizado de nuevos clientes para estudios contables

1. Cliente objetivo

Estudios contables de 3-10 profesionales que incorporan clientes nuevos regularmente y cada vez repiten el mismo proceso manual: pedir documentación, explicar qué necesitan, cargar datos en sus sistemas, hacer la entrevista inicial.

2. Problema concreto y por qué AI

Cada cliente nuevo de un estudio contable requiere: recolectar 15-25 documentos, hacer preguntas sobre su situación fiscal, entender su actividad, configurar su legajo. Esto toma 3-5 horas de un profesional. Con AI: el cliente nuevo recibe un formulario conversacional inteligente (no un PDF aburrido) que le hace las preguntas correctas según sus respuestas anteriores, detecta información faltante, y entrega al contador un legajo inicial ya armado con todo lo recolectado. Software tradicional tiene formularios estáticos que no adaptan las preguntas.

3. Modelo de revenue

• Suscripción al estudio: $150 USD/mes (onboardings ilimitados)
• Setup fee: $200 USD para configurar el flujo según los procesos del estudio
• ROI para el cliente: si incorporan 3 clientes nuevos por mes, ahorran 9-15 horas de trabajo

Target 90 días: 6 estudios = $900 USD/mes + $1,200 en setup

4. Primeros 5 clientes

Sos contador, conocés el proceso por dentro. Entrás a 5 estudios de tu red y decís: "Sé exactamente cómo es su proceso de onboarding porque lo viví. Déjenme automatizarlo." Esa credibilidad es difícil de replicar para alguien de afuera del sector.

5. Riesgo principal

Que cada estudio tenga un proceso tan diferente que el setup sea un proyecto de consultoría, no un producto. Mitigación: definís un proceso estándar de onboarding para estudios contables argentinos (vos sabés cuál es) y el cliente se adapta a él, no al revés. Customización limitada y cobrada aparte.

Idea 8: ResumenJuicio

Análisis y resumen de expedientes judiciales para estudios jurídicos

1. Cliente objetivo

Estudios jurídicos de 2-8 abogados que heredan casos, toman clientes nuevos con expedientes largos, o necesitan que un colega se ponga al día en un caso rápidamente.

2. Problema concreto y por qué AI

Un expediente judicial en

AuthGuard con JWT, @Public() y @Roles()

Estructura de archivos

src/
└── auth/
    └── guards/
        ├── auth.guard.ts
        ├── public.decorator.ts
        └── roles.decorator.ts

public.decorator.ts

import { SetMetadata } from '@nestjs/common';

export const IS_PUBLIC_KEY = 'isPublic';

/**
 * Marca un endpoint como público.
 * El AuthGuard omitirá la verificación del token JWT.
 *
 * @example
 * @Public()
 * @Get('login')
 * login() {}
 */
export const Public = () => SetMetadata(IS_PUBLIC_KEY, true);

roles.decorator.ts

import { SetMetadata } from '@nestjs/common';

export const ROLES_KEY = 'roles';

/**
 * Define los roles requeridos para acceder a un endpoint.
 * El usuario debe tener al menos uno de los roles especificados.
 *
 * @example
 * @Roles('admin', 'superuser')
 * @Delete(':id')
 * remove() {}
 */
export const Roles = (...roles: string[]) => SetMetadata(ROLES_KEY, roles);

auth.guard.ts

import {
  CanActivate,
  ExecutionContext,
  ForbiddenException,
  Injectable,
  UnauthorizedException,
} from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { JwtService } from '@nestjs/jwt';
import { Request } from 'express';
import { IS_PUBLIC_KEY } from './public.decorator';
import { ROLES_KEY } from './roles.decorator';

@Injectable()
export class AuthGuard implements CanActivate {
  constructor(
    private readonly jwtService: JwtService,
    private readonly reflector: Reflector,
  ) {}

  async canActivate(context: ExecutionContext): Promise<boolean> {
    // ── 1. Ruta pública: saltar verificación ──────────────────────────────
    if (this.isPublicRoute(context)) {
      return true;
    }

    // ── 2. Extraer y verificar el token ───────────────────────────────────
    const request = context.switchToHttp().getRequest<Request>();
    const token = this.extractBearerToken(request);

    if (!token) {
      throw new UnauthorizedException('No se proporcionó token de autenticación');
    }

    const payload = await this.verifyToken(token);

    // Adjunta el payload al request para uso posterior en controladores
    request['user'] = payload;

    // ── 3. Verificar roles si el endpoint los requiere ────────────────────
    this.checkRoles(context, payload);

    return true;
  }

  // ── Helpers privados ────────────────────────────────────────────────────

  /**
   * Comprueba si la ruta está marcada con @Public().
   * Revisa tanto el handler (método) como la clase (controlador).
   */
  private isPublicRoute(context: ExecutionContext): boolean {
    return this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
      context.getHandler(),
      context.getClass(),
    ]) ?? false;
  }

  /**
   * Extrae el token del header Authorization con formato "Bearer <token>".
   * Retorna undefined si el header está ausente o mal formado.
   */
  private extractBearerToken(request: Request): string | undefined {
    const authHeader = request.headers['authorization'];

    if (!authHeader) return undefined;

    const [scheme, token] = authHeader.split(' ');

    // Validar que el esquema sea exactamente "Bearer" y que exista el token
    if (scheme !== 'Bearer' || !token) return undefined;

    return token;
  }

  /**
   * Verifica el token con JwtService.
   * Lanza UnauthorizedException para tokens inválidos o expirados.
   */
  private async verifyToken(token: string): Promise<Record<string, unknown>> {
    try {
      return await this.jwtService.verifyAsync(token);
    } catch (error) {
      // JsonWebTokenError → token inválido
      // TokenExpiredError  → token expirado
      // NotBeforeError     → token aún no válido
      throw new UnauthorizedException('Token inválido o expirado');
    }
  }

  /**
   * Verifica que el payload del usuario contenga al menos uno
   * de los roles requeridos por el endpoint (@Roles).
   * Si no hay roles definidos, permite el acceso.
   */
  private checkRoles(
    context: ExecutionContext,
    payload: Record<string, unknown>,
  ): void {
    const requiredRoles = this.reflector.getAllAndOverride<string[]>(ROLES_KEY, [
      context.getHandler(),
      context.getClass(),
    ]);

    // Sin roles requeridos → acceso libre para cualquier usuario autenticado
    if (!requiredRoles || requiredRoles.length === 0) return;

    const userRoles = (payload['roles'] as string[]) ?? [];

    const hasRole = requiredRoles.some((role) => userRoles.includes(role));

    if (!hasRole) {
      throw new ForbiddenException(
        `Acceso denegado. Se requiere uno de los siguientes roles: ${requiredRoles.join(', ')}`,
      );
    }
  }
}

Registro como guard global

// app.module.ts (fragmento relevante)
import { APP_GUARD } from '@nestjs/core';
import { JwtModule } from '@nestjs/jwt';
import { AuthGuard } from './auth/guards/auth.guard';

@Module({
  imports: [
    JwtModule.register({
      secret: process.env.JWT_SECRET,
      signOptions: { expiresIn: '1h' },
    }),
    // ... resto de imports
  ],
  providers: [
    {
      provide: APP_GUARD,
      useClass: AuthGuard,
    },
  ],
})
export class AppModule {}

Ejemplos de uso

import { Controller, Get, Delete, Param } from '@nestjs/common';
import { Public } from './auth/guards/public.decorator';
import { Roles } from './auth/guards/roles.decorator';

@Controller('products')
export class ProductsController {

  // ✅ Accesible sin token
  @Public()
  @Get()
  findAll() {}

  // ✅ Requiere token válido (cualquier rol)
  @Get(':id')
  findOne(@Param('id') id: string) {}

  // ✅ Requiere token válido + rol 'admin' o 'manager'
  @Roles('admin', 'manager')
  @Delete(':id')
  remove(@Param('id') id: string) {}
}

Flujo de decisión

Request entrante
      │
      ▼
¿@Public() en handler o clase?
  ├─ SÍ ──► return true ✅
  │
  └─ NO
      │
      ▼
¿Existe "Bearer <token>" en Authorization?
  ├─ NO ──► UnauthorizedException 🚫
  │
  └─ SÍ
      │
      ▼
jwtService.verifyAsync(token)
  ├─ FALLA ──► UnauthorizedException 🚫
  │
  └─ OK → request.user = payload
      │
      ▼
¿@Roles() definido en handler o clase?
  ├─ NO ──────────────────────► return true ✅
  │
  └─ SÍ
      │
      ▼
¿payload.roles incluye algún rol requerido?
  ├─ SÍ ──► return true ✅
  └─ NO ──► ForbiddenException 🚫

Implementación: Search Products Service

DTOs

// dto/search-products.dto.ts
import { IsOptional, IsString, IsNumber, IsEnum, IsIn, Min, Max } from 'class-validator';
import { Type } from 'class-transformer';

export class SearchProductsDto {
  @IsOptional()
  @IsString()
  q?: string;

  @IsOptional()
  @IsEnum(['active', 'inactive', 'draft'])
  status?: 'active' | 'inactive' | 'draft';

  @IsOptional()
  @Type(() => Number)
  @IsNumber()
  @Min(0)
  minPrice?: number;

  @IsOptional()
  @Type(() => Number)
  @IsNumber()
  @Min(0)
  maxPrice?: number;

  @IsOptional()
  @IsString()
  sortBy?: string;

  @IsOptional()
  @IsEnum(['ASC', 'DESC'])
  sortOrder?: 'ASC' | 'DESC';

  @IsOptional()
  @Type(() => Number)
  @IsNumber()
  @Min(1)
  page?: number;

  @IsOptional()
  @Type(() => Number)
  @IsNumber()
  @Min(1)
  @Max(100)
  limit?: number;
}

// dto/product.dto.ts
export class ProductDto {
  id: string;
  name: string;
  description: string | null;
  price: number;
  stock: number;
  status: string;
  createdAt: Date;
}

// dto/paginated-products.dto.ts
import { ProductDto } from './product.dto';

export class PaginatedProductsDto {
  data: ProductDto[];
  total: number;
  page: number;
  limit: number;
}

Servicio

// products.service.ts
import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { Product } from './entities/product.entity';
import { SearchProductsDto } from './dto/search-products.dto';
import { PaginatedProductsDto } from './dto/paginated-products.dto';
import { ProductDto } from './dto/product.dto';

const ALLOWED_SORT_FIELDS = new Set(['name', 'price', 'stock', 'createdAt']);
const DEFAULT_SORT_BY = 'createdAt';
const DEFAULT_SORT_ORDER = 'DESC';
const DEFAULT_PAGE = 1;
const DEFAULT_LIMIT = 10;

@Injectable()
export class ProductsService {
  constructor(
    @InjectRepository(Product)
    private readonly productRepository: Repository<Product>,
  ) {}

  async search(query: SearchProductsDto): Promise<PaginatedProductsDto> {
    // ── Normalizar parámetros de paginación y orden ──────────────────────────
    const page = query.page ?? DEFAULT_PAGE;
    const limit = query.limit ?? DEFAULT_LIMIT;
    const sortOrder = query.sortOrder ?? DEFAULT_SORT_ORDER;

    // Validar sortBy contra la whitelist; caer en default si no es válido
    const sortBy = ALLOWED_SORT_FIELDS.has(query.sortBy ?? '')
      ? (query.sortBy as string)
      : DEFAULT_SORT_BY;

    // ── Construir QueryBuilder ───────────────────────────────────────────────
    const qb = this.productRepository
      .createQueryBuilder('product')
      // Soft-delete: nunca retornar registros eliminados
      .where('product.deletedAt IS NULL');

    // ── Filtros dinámicos (solo se agregan si el valor está presente) ─────────

    // Búsqueda por texto libre en name y description
    if (query.q !== undefined && query.q.trim() !== '') {
      qb.andWhere(
        '(product.name ILIKE :q OR product.description ILIKE :q)',
        { q: `%${query.q.trim()}%` },
      );
    }

    // Filtro por status exacto
    if (query.status !== undefined) {
      qb.andWhere('product.status = :status', { status: query.status });
    }

    // Filtro por precio mínimo
    if (query.minPrice !== undefined) {
      qb.andWhere('product.price >= :minPrice', { minPrice: query.minPrice });
    }

    // Filtro por precio máximo
    if (query.maxPrice !== undefined) {
      qb.andWhere('product.price <= :maxPrice', { maxPrice: query.maxPrice });
    }

    // ── Orden y paginación ───────────────────────────────────────────────────
    qb.orderBy(`product.${sortBy}`, sortOrder)
      .skip((page - 1) * limit)
      .take(limit);

    // ── Ejecutar: datos + total en una sola query ────────────────────────────
    const [products, total] = await qb.getManyAndCount();

    return {
      data: products.map(this.toDto),
      total,
      page,
      limit,
    };
  }

  // ── Mapper privado: entidad → DTO ────────────────────────────────────────
  private toDto(product: Product): ProductDto {
    return {
      id: product.id,
      name: product.name,
      description: product.description,
      price: product.price,
      stock: product.stock,
      status: product.status,
      createdAt: product.createdAt,
    };
  }
}

Flujo de decisiones

search(query)
│
├─ Normalizar: page, limit, sortOrder, sortBy
│   └─ sortBy ∈ whitelist? → usar sortBy : usar 'createdAt'
│
├─ createQueryBuilder('product')
│   └─ WHERE deletedAt IS NULL  ← siempre presente
│
├─ query.q?        → AND (name ILIKE %q% OR description ILIKE %q%)
├─ query.status?   → AND status = :status
├─ query.minPrice? → AND price >= :minPrice
├─ query.maxPrice? → AND price <= :maxPrice
│
├─ ORDER BY product.<sortBy> <sortOrder>
├─ SKIP (page-1)*limit  /  TAKE limit
│
└─ getManyAndCount()
    ├─ total → count con todos los filtros (sin paginación)
    └─ data  → registros paginados → map toDto()

Puntos clave de la implementación

| Decisión | Razón | |---|---| | WHERE deletedAt IS NULL en el .where() inicial | Garantiza que ningún filtro posterior pueda omitir este requisito | | Set para whitelist de sortBy | Lookup O(1) y fácil de extender | | query.q.trim() antes del ILIKE | Evita búsquedas con solo espacios | | Parámetros nombrados (:q, :status…) | Previene SQL injection vía TypeORM | | getManyAndCount() | Una sola query con COUNT(*) OVER() — evita dos roundtrips | | toDto como método privado | Desacopla la entidad del contrato público de la API |

Análisis de Bugs

Bug 1 — Lógica de paginación incorrecta (findAll)

Problema

const skip = page * limit; // ❌

El cálculo de skip es incorrecto. Para la página 1 con limit=10, debería saltarse 0 registros, pero 1 * 10 = 10, lo que hace que la primera página muestre los registros de la segunda.

La fórmula correcta es (page - 1) * limit.

| page | limit | skip incorrecto | skip correcto | |------|-------|-----------------|---------------| | 1 | 10 | 10 ❌ | 0 ✅ | | 2 | 10 | 20 ❌ | 10 ✅ | | 3 | 10 | 30 ❌ | 20 ✅ |

Corrección

const skip = (page - 1) * limit; // ✅

Bug 2 — findOne no filtra productos eliminados (soft delete roto)

Problema

const product = await this.productRepository.findOne({
  where: { id }, // ❌ falta filtrar deletedAt: IsNull()
});

Un producto con deletedAt seteado (eliminado lógicamente) sigue siendo retornado. Esto rompe la semántica del soft delete: el producto "no existe" para el usuario pero el endpoint lo devuelve igual.

Nota: TypeORM solo aplica el filtro automático de soft delete si se usa el decorador @DeleteDateColumn y se invoca softDelete()/softRemove(). Al hacer save() manual del campo, el filtro automático no aplica.

Corrección

const product = await this.productRepository.findOne({
  where: { id, deletedAt: IsNull() }, // ✅
});

Bug 3 — Exposición de información interna en el error (Seguridad)

Problema

throw new NotFoundException(
  `Product with id ${id} not found in table "product"` // ❌
);

El mensaje expone el nombre de la tabla de la base de datos (table "product"). Esto es un problema de seguridad: un atacante puede usar estos mensajes para hacer reconocimiento (enumerar estructura interna, confirmar tecnologías usadas, etc.). Los errores orientados al usuario nunca deben filtrar detalles de infraestructura.

Corrección

throw new NotFoundException(`Product with id ${id} not found`); // ✅

Bug 4 — HTTP status code incorrecto en el controller para create

Problema

El servicio hace return this.productRepository.save(product) correctamente, pero si el controller no tiene el decorador @HttpCode(HttpStatus.CREATED), NestJS responde con 200 OK en lugar de 201 Created. Por convención REST, la creación de un recurso debe retornar 201.

// controller — sin el decorador ❌
@Post()
async create(@Body() dto: CreateProductDto) {
  return this.productService.create(dto);
}

Corrección

// controller ✅
import { HttpCode, HttpStatus } from '@nestjs/common';

@Post()
@HttpCode(HttpStatus.CREATED) // ✅ 201
async create(@Body() dto: CreateProductDto) {
  return this.productService.create(dto);
}

Bug 5 — Operación no atómica en transferStock (riesgo de inconsistencia)

Problema

await this.productRepository.save(source); // ✅ OK
await this.productRepository.save(dest);   // ❌ puede fallar

Si el primer save tiene éxito pero el segundo falla (error de red, timeout, constraint de DB, etc.), el stock queda en un estado inconsistente: se descontó del origen pero nunca se acreditó al destino. El dinero/stock desaparece.

Esto requiere una transacción atómica: o ambas operaciones se confirman, o ninguna.

Corrección

await this.productRepository.manager.transaction(async (manager) => {
  source.stock -= quantity;
  dest.stock += quantity;
  await manager.save(source); // ✅ dentro de la transacción
  await manager.save(dest);   // ✅ si falla, rollback automático
});

Código completo corregido

import { Injectable, NotFoundException } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository, IsNull } from 'typeorm';
import { Product } from './product.entity';
import { PaginationQueryDto } from './dto/pagination-query.dto';

@Injectable()
export class ProductService {
  constructor(
    @InjectRepository(Product)
    private readonly productRepository: Repository<Product>,
  ) {}

  // ✅ Bug 1 corregido: fórmula de skip correcta
  async findAll(query: PaginationQueryDto) {
    const { page = 1, limit = 10 } = query;
    const skip = (page - 1) * limit; // ← (page - 1) * limit
    const [data, total] = await this.productRepository.findAndCount({
      where: { deletedAt: IsNull() },
      skip,
      take: limit,
    });
    return { data, total, page, limit };
  }

  // ✅ Bug 2 corregido: filtra productos con soft delete
  async findOne(id: string) {
    const product = await this.productRepository.findOne({
      where: { id, deletedAt: IsNull() }, // ← agrega la condición
    });
    if (!product) throw new NotFoundException(`Product with id ${id} not found`);
    return product;
  }

  // ✅ Bug 3 corregido: mensaje sin información interna de infraestructura
  async softDelete(id: string): Promise<void> {
    const product = await this.productRepository.findOne({
      where: { id, deletedAt: IsNull() },
    });
    if (!product) {
      throw new NotFoundException(`Product with id ${id} not found`); // ← sin "table product"
    }
    product.deletedAt = new Date();
    await this.productRepository.save(product);
  }

  // ✅ Bug 4: el servicio está bien; la corrección va en el controller
  // Ver product.controller.ts → agregar @HttpCode(HttpStatus.CREATED)
  async create(data: Partial<Product>): Promise<Product> {
    const product = this.productRepository.create(data);
    return this.productRepository.save(product);
  }

  // ✅ Bug 5 corregido: operación envuelta en una transacción atómica
  async transferStock(
    fromId: string,
    toId: string,
    quantity: number,
  ): Promise<void> {
    const source = await this.productRepository.findOne({
      where: { id: fromId, deletedAt: IsNull() },
    });
    const dest = await this.productRepository.findOne({
      where: { id: toId, deletedAt: IsNull() },
    });

    if (!source || !dest) {
      throw new NotFoundException('Product not found');
    }
    if (source.stock < quantity) {
      throw new Error('Insufficient stock');
    }

    // ← transacción: si cualquier save falla, se hace rollback automático
    await this.productRepository.manager.transaction(async (manager) => {
      source.stock -= quantity;
      dest.stock += quantity;
      await manager.save(source);
      await manager.save(dest);
    });
  }
}

Controller corregido (Bug 4)

import {
  Controller,
  Post,
  Body,
  HttpCode,
  HttpStatus,
} from '@nestjs/common';
import { ProductService } from './product.service';
import { CreateProductDto } from './dto/create-product.dto';

@Controller('products')
export class ProductController {
  constructor(private readonly productService: ProductService) {}

  // ✅ Bug 4 corregido: 201 Created en lugar de 200 OK
  @Post()
  @HttpCode(HttpStatus.CREATED)
  async create(@Body() dto: CreateProductDto) {
    return this.productService.create(dto);
  }
}

Resumen

| # | Tipo | Ubicación | Descripción | |---|------|-----------|-------------| | 1 | Lógico | findAll | skip = page * limit debería ser (page - 1) * limit | | 2 | Lógico | findOne | No filtra deletedAt: IsNull(), devuelve registros eliminados | | 3 | Seguridad | softDelete | Expone nombre de tabla interna en el mensaje de error | | 4 | Arquitectura | Controller create | Falta @HttpCode(201), responde 200 en vez de 201 | | 5 | Arquitectura | transferStock | Dos saves sin transacción, riesgo de inconsistencia de datos |

Implementación

DTOs

// transfer.dto.ts
import { IsUUID, IsNumber, IsPositive } from 'class-validator';
import { Transform } from 'class-transformer';

export class TransferDto {
  @IsUUID()
  fromWalletId: string;

  @IsUUID()
  toWalletId: string;

  @IsNumber({ maxDecimalPlaces: 2 })
  @IsPositive()
  @Transform(({ value }) => parseFloat(parseFloat(value).toFixed(2)))
  amount: number;
}

// transfer-result.dto.ts
export class TransferResultDto {
  fromWalletId: string;
  toWalletId: string;
  amount: number;
  newFromBalance: number;
  newToBalance: number;
  transferredAt: Date;
}

WalletService

// wallet.service.ts
import {
  BadRequestException,
  ConflictException,
  Injectable,
  NotFoundException,
} from '@nestjs/common';
import { DataSource } from 'typeorm';
import { Wallet } from './wallet.entity';
import { TransferDto } from './transfer.dto';
import { TransferResultDto } from './transfer-result.dto';

@Injectable()
export class WalletService {
  constructor(private readonly dataSource: DataSource) {}

  async transfer(dto: TransferDto): Promise<TransferResultDto> {
    const { fromWalletId, toWalletId, amount } = dto;

    // ── Regla 1: wallets distintas ──────────────────────────────────────────
    if (fromWalletId === toWalletId) {
      throw new BadRequestException('Cannot transfer to same wallet');
    }

    return this.dataSource.transaction(async (manager) => {
      const repo = manager.getRepository(Wallet);

      // ── Regla 2: ambas wallets deben existir ──────────────────────────────
      //   Se usan PESSIMISTIC_READ para evitar lecturas sucias dentro de la
      //   transacción; el optimistic locking se aplica en el UPDATE.
      const [fromWallet, toWallet] = await Promise.all([
        repo.findOne({ where: { id: fromWalletId } }),
        repo.findOne({ where: { id: toWalletId } }),
      ]);

      if (!fromWallet || !toWallet) {
        throw new NotFoundException('Wallet not found');
      }

      // ── Regla 3: saldo suficiente ─────────────────────────────────────────
      //   Comparación numérica explícita porque `balance` puede llegar
      //   como string desde la base de datos (tipo DECIMAL).
      const fromBalance = parseFloat(fromWallet.balance as unknown as string);
      const toBalance = parseFloat(toWallet.balance as unknown as string);

      if (fromBalance < amount) {
        throw new BadRequestException('Insufficient balance');
      }

      const newFromBalance = parseFloat((fromBalance - amount).toFixed(2));
      const newToBalance = parseFloat((toBalance + amount).toFixed(2));

      // ── Regla 4 y 5: actualizaciones atómicas con optimistic locking ──────

      // UPDATE wallet origen
      const fromResult = await manager
        .createQueryBuilder()
        .update(Wallet)
        .set({
          balance: newFromBalance,
          version: () => 'version + 1',       // incremento en BD
        })
        .where('id = :id AND version = :version', {
          id: fromWalletId,
          version: fromWallet.version,
        })
        .execute();

      if (fromResult.affected !== 1) {
        throw new ConflictException('Concurrent modification detected');
      }

      // UPDATE wallet destino
      const toResult = await manager
        .createQueryBuilder()
        .update(Wallet)
        .set({
          balance: newToBalance,
          version: () => 'version + 1',
        })
        .where('id = :id AND version = :version', {
          id: toWalletId,
          version: toWallet.version,
        })
        .execute();

      if (toResult.affected !== 1) {
        throw new ConflictException('Concurrent modification detected');
      }

      // ── Resultado ─────────────────────────────────────────────────────────
      const result = new TransferResultDto();
      result.fromWalletId = fromWalletId;
      result.toWalletId = toWalletId;
      result.amount = amount;
      result.newFromBalance = newFromBalance;
      result.newToBalance = newToBalance;
      result.transferredAt = new Date();

      return result;
    });
  }
}

Diagrama del flujo

transfer(dto)
│
├─ fromWalletId === toWalletId?  ──► BadRequestException
│
└─ dataSource.transaction(manager)
   │
   ├─ findOne(fromWalletId)  ─┐
   ├─ findOne(toWalletId)    ─┴─ alguna null? ──► NotFoundException
   │
   ├─ fromBalance < amount?  ──► BadRequestException
   │
   ├─ UPDATE from  WHERE id = ? AND version = ?
   │   └─ affected !== 1?  ──► ConflictException  ──► ROLLBACK automático
   │
   ├─ UPDATE to    WHERE id = ? AND version = ?
   │   └─ affected !== 1?  ──► ConflictException  ──► ROLLBACK automático
   │
   └─ return TransferResultDto  ──► COMMIT automático

Puntos clave de la implementación

| Decisión | Razón | |---|---| | parseFloat(balance as unknown as string) | TypeORM devuelve DECIMAL como string en tiempo de ejecución aunque el tipo TS sea number | | version: () => 'version + 1' | Expresión SQL raw para incrementar en la BD dentro del mismo UPDATE, evitando una lectura extra | | Promise.all en las lecturas | Las dos lecturas no tienen dependencia entre sí; ejecutarlas en paralelo reduce latencia | | Excepciones dentro de transaction() | Cualquier excepción no capturada dentro del callback provoca el rollback automático de TypeORM | | ConflictException (HTTP 409) | Semánticamente correcto: el recurso existe pero hay un conflicto de concurrencia, no un error de cliente |

Implementación: Registro de Usuarios (3 capas)

DTOs

// create-user.dto.ts
import { IsEmail, IsString, MinLength } from 'class-validator';

export class CreateUserDto {
  @IsEmail()
  email: string;

  @IsString()
  @MinLength(2)
  name: string;

  @IsString()
  @MinLength(8)
  password: string;
}

// user.dto.ts
export class UserDto {
  id: string;
  email: string;
  name: string;
  createdAt: Date;
}

Repository

// user.repository.ts
import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { User } from './user.entity';

@Injectable()
export class UserRepository {
  constructor(
    @InjectRepository(User)
    private readonly repository: Repository<User>,
  ) {}

  findByEmail(email: string): Promise<User | null> {
    return this.repository.findOneBy({ email });
  }

  create(data: Pick<User, 'email' | 'name' | 'passwordHash'>): Promise<User> {
    const user = this.repository.create(data);
    return this.repository.save(user);
  }
}

findByEmail devuelve null (no lanza excepción): la decisión de qué hacer con ese resultado es lógica de negocio y le corresponde al Service.
create recibe solo los campos necesarios para construir el registro; no recibe la password en texto plano porque el hasheo ya ocurrió en el Service.

Service

// user.service.ts
import { ConflictException, Injectable } from '@nestjs/common';
import * as bcrypt from 'bcrypt';
import { CreateUserDto } from './dto/create-user.dto';
import { UserDto } from './dto/user.dto';
import { UserRepository } from './user.repository';

@Injectable()
export class UserService {
  private readonly SALT_ROUNDS = 10;

  constructor(private readonly userRepository: UserRepository) {}

  async create(dto: CreateUserDto): Promise<UserDto> {
    const existing = await this.userRepository.findByEmail(dto.email);

    if (existing) {
      throw new ConflictException('Email already registered');
    }

    const passwordHash = await bcrypt.hash(dto.password, this.SALT_ROUNDS);

    const user = await this.userRepository.create({
      email: dto.email,
      name: dto.name,
      passwordHash,
    });

    return this.toDto(user);
  }

  // Mapeo centralizado: garantiza que passwordHash nunca salga del Service
  private toDto(user: import('./user.entity').User): UserDto {
    const dto = new UserDto();
    dto.id = user.id;
    dto.email = user.email;
    dto.name = user.name;
    dto.createdAt = user.createdAt;
    return dto;
  }
}

toDto es privado e interno al Service. Centralizar el mapeo aquí evita que en el futuro alguien añada passwordHash al UserDto por descuido desde el Controller.

Controller

// user.controller.ts
import { Body, Controller, HttpCode, HttpStatus, Post } from '@nestjs/common';
import { CreateUserDto } from './dto/create-user.dto';
import { UserDto } from './dto/user.dto';
import { UserService } from './user.service';

@Controller('users')
export class UserController {
  constructor(private readonly userService: UserService) {}

  @Post()
  @HttpCode(HttpStatus.CREATED)
  create(@Body() dto: CreateUserDto): Promise<UserDto> {
    return this.userService.create(dto);
  }
}

El Controller no manipula la respuesta: recibe el DTO validado por el pipe global (ValidationPipe), lo pasa al Service y retorna directamente lo que el Service devuelve. Cero lógica de negocio.

Flujo de datos (resumen)

POST /users  { email, name, password }
     │
     ▼
Controller  ──── @Body() valida con CreateUserDto (class-validator)
     │            lanza 400 automáticamente si falla la validación
     │
     ▼
UserService.create(dto)
     ├── userRepository.findByEmail(email)
     │        └── existe?  ──► ConflictException 409
     │
     ├── bcrypt.hash(password, 10)
     │
     ├── userRepository.create({ email, name, passwordHash })
     │
     └── toDto(user)  ──► UserDto (sin passwordHash)
     │
     ▼
Controller  retorna UserDto  →  HTTP 201

Prerequisito: ValidationPipe global

Para que class-validator actúe sobre el @Body() es necesario tener el pipe configurado (normalmente en main.ts):

// main.ts
app.useGlobalPipes(
  new ValidationPipe({
    whitelist: true,     // elimina propiedades no declaradas en el DTO
    forbidNonWhitelisted: true, // lanza 400 si llegan propiedades extra
    transform: true,     // convierte los tipos primitivos automáticamente
  }),
);

whitelist: true es especialmente importante aquí: garantiza que aunque el cliente envíe campos extra (p.ej. passwordHash directamente), estos nunca lleguen al Service.

Products Service & DTOs

DTOs

dto/create-product.dto.ts

import {
  IsInt,
  IsNotEmpty,
  IsOptional,
  IsPositive,
  IsString,
  Min,
} from 'class-validator';

export class CreateProductDto {
  @IsString()
  @IsNotEmpty()
  name: string;

  @IsString()
  @IsOptional()
  description?: string;

  @IsPositive()
  price: number;

  @IsInt()
  @Min(0)
  stock: number;
}

dto/update-product.dto.ts

import { PartialType } from '@nestjs/mapped-types';
import { CreateProductDto } from './create-product.dto';

export class UpdateProductDto extends PartialType(CreateProductDto) {}

dto/pagination-query.dto.ts

import { Type } from 'class-transformer';
import { IsInt, IsOptional, Max, Min } from 'class-validator';

export class PaginationQueryDto {
  @IsOptional()
  @IsInt()
  @Min(1)
  @Type(() => Number)
  page: number = 1;

  @IsOptional()
  @IsInt()
  @Min(1)
  @Max(100)
  @Type(() => Number)
  limit: number = 10;
}

@Type(() => Number) es necesario cuando los valores llegan como strings desde query params. Si el controller ya los transforma antes de pasarlos al servicio, puede omitirse, pero no hace daño tenerlo en el DTO.

dto/product.dto.ts

export class ProductDto {
  id: string;
  name: string;
  description: string | null;
  price: number;
  stock: number;
  createdAt: Date;
  updatedAt: Date;
}

dto/paginated-products.dto.ts

import { ProductDto } from './product.dto';

export class PaginatedProductsDto {
  data: ProductDto[];
  total: number;
  page: number;
  limit: number;
}

Service

products.service.ts

import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { IsNull, Repository } from 'typeorm';

import { Product } from './product.entity';
import { CreateProductDto } from './dto/create-product.dto';
import { UpdateProductDto } from './dto/update-product.dto';
import { PaginationQueryDto } from './dto/pagination-query.dto';
import { ProductDto } from './dto/product.dto';
import { PaginatedProductsDto } from './dto/paginated-products.dto';

@Injectable()
export class ProductsService {
  constructor(
    @InjectRepository(Product)
    private readonly productRepository: Repository<Product>,
  ) {}

  // ─── Helpers ────────────────────────────────────────────────────────────────

  /**
   * Convierte una entidad Product en un ProductDto plano.
   * Mantiene la transformación centralizada para que cualquier
   * cambio en la entidad se propague desde un único lugar.
   */
  private toDto(product: Product): ProductDto {
    const dto = new ProductDto();
    dto.id          = product.id;
    dto.name        = product.name;
    dto.description = product.description;
    dto.price       = product.price;
    dto.stock       = product.stock;
    dto.createdAt   = product.createdAt;
    dto.updatedAt   = product.updatedAt;
    return dto;
  }

  // ─── Public API ─────────────────────────────────────────────────────────────

  /**
   * Crea un producto nuevo y devuelve su representación DTO.
   */
  async create(dto: CreateProductDto): Promise<ProductDto> {
    const product = this.productRepository.create({
      name:        dto.name,
      description: dto.description ?? null,
      price:       dto.price,
      stock:       dto.stock,
    });

    const saved = await this.productRepository.save(product);
    return this.toDto(saved);
  }

  /**
   * Devuelve la página solicitada de productos activos (deletedAt IS NULL).
   */
  async findAll(query: PaginationQueryDto): Promise<PaginatedProductsDto> {
    const { page, limit } = query;
    const skip = (page - 1) * limit;

    const [products, total] = await this.productRepository.findAndCount({
      where: { deletedAt: IsNull() },
      skip,
      take: limit,
      order: { createdAt: 'DESC' },
    });

    const result = new PaginatedProductsDto();
    result.data  = products.map((p) => this.toDto(p));
    result.total = total;
    result.page  = page;
    result.limit = limit;
    return result;
  }

  /**
   * Busca un producto activo por id.
   * Retorna null si no existe o fue eliminado lógicamente.
   * El controller es responsable de convertir null → NotFoundException.
   */
  async findOne(id: string): Promise<ProductDto | null> {
    const product = await this.productRepository.findOne({
      where: { id, deletedAt: IsNull() },
    });

    if (!product) return null;
    return this.toDto(product);
  }

  /**
   * Actualiza los campos presentes en el DTO y devuelve el producto actualizado.
   * Retorna null si el producto no existe o fue eliminado lógicamente.
   */
  async update(id: string, dto: UpdateProductDto): Promise<ProductDto | null> {
    const product = await this.productRepository.findOne({
      where: { id, deletedAt: IsNull() },
    });

    if (!product) return null;

    // Solo sobreescribimos los campos que vienen en el DTO
    if (dto.name        !== undefined) product.name        = dto.name;
    if (dto.description !== undefined) product.description = dto.description ?? null;
    if (dto.price       !== undefined) product.price       = dto.price;
    if (dto.stock       !== undefined) product.stock       = dto.stock;

    const saved = await this.productRepository.save(product);
    return this.toDto(saved);
  }

  /**
   * Realiza un soft-delete seteando deletedAt con la fecha actual.
   * Retorna false si el producto no existe o ya fue eliminado lógicamente.
   */
  async softDelete(id: string): Promise<boolean> {
    const product = await this.productRepository.findOne({
      where: { id, deletedAt: IsNull() },
    });

    if (!product) return false;

    product.deletedAt = new Date();
    await this.productRepository.save(product);
    return true;
  }
}

Estructura de archivos resultante

products/
├── dto/
│   ├── create-product.dto.ts
│   ├── update-product.dto.ts
│   ├── pagination-query.dto.ts
│   ├── product.dto.ts
│   └── paginated-products.dto.ts
├── product.entity.ts        ← ya existe
└── products.service.ts

Decisiones de diseño destacadas

| Decisión | Motivo | |---|---| | toDto() privado | Centraliza la transformación entidad → DTO. Un solo punto de cambio si evoluciona la entidad. | | findOne / update filtran deletedAt: IsNull() | Evita exponer o modificar registros eliminados lógicamente. | | update con guards !== undefined | PartialType hace todos los campos opcionales; undefined significa "no envió el campo", null sería un valor explícito. | | softDelete devuelve boolean | El servicio no sabe de HTTP; el controller decide qué código de estado emitir según el booleano. | | @Type(() => Number) en PaginationQueryDto | Los query params llegan como strings; el transformer los convierte antes de que class-validator los valide. |

Módulo de Autenticación - NestJS

Estructura de archivos

src/auth/
├── dto/
│   ├── login.dto.ts
│   └── auth-response.dto.ts
├── auth.controller.ts
└── auth.service.ts

DTOs

dto/login.dto.ts

import { IsEmail, IsString, MinLength } from 'class-validator';

export class LoginDto {
  @IsEmail()
  email: string;

  @IsString()
  @MinLength(8)
  password: string;
}

Por qué no se agrega @IsNotEmpty(): @IsEmail() ya falla si el valor está vacío, y @MinLength(8) cubre el caso de string vacío para password.

dto/auth-response.dto.ts

export class AuthResponseDto {
  access_token: string;
  expiresIn: number;
}

Por qué clase plana sin decoradores: Es un DTO de salida puro. No necesita validación (no viene del cliente) ni serialización especial. Si en el futuro se requiere excluir campos, se puede extender con @Exclude()/@Expose() de class-transformer.

Service

auth.service.ts

import { Injectable, UnauthorizedException } from '@nestjs/common';
import { JwtService } from '@nestjs/jwt';
import * as bcrypt from 'bcrypt';

import { UserService } from '../user/user.service';
import { LoginDto } from './dto/login.dto';
import { AuthResponseDto } from './dto/auth-response.dto';

// Constante explícita para que el número mágico no quede disperso.
// Si la expiración del token cambia, este valor debe actualizarse en
// sincronía con el string '7d' que recibe JwtService.
const EXPIRES_IN_SECONDS = 604_800; // 7 días

@Injectable()
export class AuthService {
  constructor(
    private readonly userService: UserService,
    private readonly jwtService: JwtService,
  ) {}

  async login(dto: LoginDto): Promise<AuthResponseDto> {
    // 1. Buscar usuario — null significa que el email no existe
    const user = await this.userService.findByEmail(dto.email);

    // 2. Verificar contraseña
    //    Se evalúa bcrypt incluso cuando user es null para evitar
    //    timing attacks que permitan enumerar emails registrados.
    const passwordHash = user?.passwordHash ?? '';
    const isPasswordValid = await bcrypt.compare(dto.password, passwordHash);

    // 3. Fallo unificado: mismo mensaje independientemente de si falló
    //    el email o la contraseña (no revelar cuál de los dos es incorrecto)
    if (!user || !isPasswordValid) {
      throw new UnauthorizedException('Invalid credentials');
    }

    // 4. Generar token
    const payload = { sub: user.id, email: user.email };
    const access_token = await this.jwtService.signAsync(payload, {
      expiresIn: '7d',
    });

    return { access_token, expiresIn: EXPIRES_IN_SECONDS };
  }
}

Decisiones clave:

| Decisión | Razón | |---|---| | bcrypt.compare se ejecuta aunque user sea null | Previene timing attacks para enumerar emails | | Hash vacío '' cuando no hay usuario | bcrypt.compare contra string vacío siempre retorna false sin lanzar error | | signAsync en lugar de sign | Evita bloquear el event loop en cargas altas | | expiresIn en signAsync, no en el módulo | Permite flexibilidad si en el futuro distintos flujos necesitan duraciones diferentes | | Mensaje de error idéntico para ambos fallos | No revelar si el email existe en el sistema |

Controller

auth.controller.ts

import { Body, Controller, HttpCode, HttpStatus, Post } from '@nestjs/common';

import { AuthService } from './auth.service';
import { LoginDto } from './dto/login.dto';
import { AuthResponseDto } from './dto/auth-response.dto';

@Controller('auth')
export class AuthController {
  constructor(private readonly authService: AuthService) {}

  @Post('login')
  @HttpCode(HttpStatus.OK) // POST devuelve 201 por defecto; login debe retornar 200
  async login(@Body() loginDto: LoginDto): Promise<AuthResponseDto> {
    return this.authService.login(loginDto);
  }
}

Por qué @HttpCode(HttpStatus.OK): NestJS devuelve 201 Created para todos los POST por defecto. Un login exitoso no crea un recurso, por lo que 200 OK es semánticamente correcto.

Notas de integración

// En auth.module.ts deberás tener al menos:
// imports: [JwtModule.register({ secret: process.env.JWT_SECRET }), UserModule]
// providers: [AuthService]
// controllers: [AuthController]

// En main.ts, para que los DTOs sean validados:
// app.useGlobalPipes(new ValidationPipe({ whitelist: true }));

whitelist: true en ValidationPipe descarta automáticamente cualquier propiedad del body que no esté declarada en el DTO, previniendo mass assignment sin necesidad de código adicional.

// schema.prisma

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

// ─────────────────────────────────────────────
// Enums
// ─────────────────────────────────────────────

enum Role {
  OWNER
  ADMIN
  MEMBER
}

enum SubscriptionStatus {
  ACTIVE
  PAUSED
  CANCELLED
  TRIAL
}

enum InvoiceStatus {
  PENDING
  PAID
  FAILED
  REFUNDED
}

// ─────────────────────────────────────────────
// Models
// ─────────────────────────────────────────────

model Organization {
  id        String   @id @default(cuid())
  name      String
  slug      String   @unique
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  users        User[]
  subscription Subscription?

  @@index([slug])
}

model User {
  id             String   @id @default(cuid())
  email          String   @unique
  name           String
  passwordHash   String
  role           Role
  organizationId String
  createdAt      DateTime @default(now())
  updatedAt      DateTime @updatedAt

  organization Organization @relation(fields: [organizationId], references: [id])

  @@index([email])
  @@index([organizationId])
}

model Plan {
  id            String   @id @default(cuid())
  name          String
  priceMonthly  Decimal  @db.Decimal(10, 2)
  priceYearly   Decimal  @db.Decimal(10, 2)
  maxUsers      Int
  isActive      Boolean  @default(true)
  createdAt     DateTime @default(now())

  subscriptions Subscription[]
}

model Subscription {
  id                 String             @id @default(cuid())
  organizationId     String             @unique
  planId             String
  status             SubscriptionStatus
  currentPeriodStart DateTime
  currentPeriodEnd   DateTime
  cancelledAt        DateTime?
  createdAt          DateTime           @default(now())
  updatedAt          DateTime           @updatedAt

  organization Organization @relation(fields: [organizationId], references: [id])
  plan         Plan         @relation(fields: [planId], references: [id])
  invoices     Invoice[]

  @@index([organizationId])
  @@index([planId])
  @@index([status])
}

model Invoice {
  id             String        @id @default(cuid())
  subscriptionId String
  amount         Decimal       @db.Decimal(10, 2)
  currency       String        @default("USD")
  status         InvoiceStatus
  paidAt         DateTime?
  dueDate        DateTime
  createdAt      DateTime      @default(now())
  updatedAt      DateTime      @updatedAt

  subscription Subscription @relation(fields: [subscriptionId], references: [id])

  @@index([subscriptionId])
  @@index([status])
}

Refactoring: Arquitectura en Capas

Estructura de archivos resultante

src/users/
├── dto/
│   ├── create-user.dto.ts
│   ├── user.dto.ts
│   └── user-with-orders.dto.ts
├── entities/
│   ├── user.entity.ts
│   └── order.entity.ts
├── user.repository.ts
├── user.service.ts
└── user.controller.ts

Entidades

// src/users/entities/order.entity.ts
import { Entity, PrimaryGeneratedColumn, Column, CreateDateColumn, ManyToOne } from 'typeorm';
import { User } from './user.entity';

@Entity()
export class Order {
  @PrimaryGeneratedColumn('uuid')
  id: string;

  @Column()
  total: number;

  @Column({ default: 'pending' })
  status: string;

  @CreateDateColumn()
  createdAt: Date;

  @ManyToOne(() => User, (user) => user.orders)
  user: User;
}

// src/users/entities/user.entity.ts
import { Entity, PrimaryGeneratedColumn, Column, CreateDateColumn, OneToMany } from 'typeorm';
import { Order } from './order.entity';

@Entity()
export class User {
  @PrimaryGeneratedColumn('uuid')
  id: string;

  @Column({ unique: true })
  email: string;

  @Column()
  name: string;

  @Column()
  passwordHash: string;

  @CreateDateColumn()
  createdAt: Date;

  @OneToMany(() => Order, (order) => order.user)
  orders: Order[];
}

DTOs

// src/users/dto/create-user.dto.ts
import { IsEmail, IsString, MinLength } from 'class-validator';

export class CreateUserDto {
  /**
   * Debe ser un email válido. Coincide con el comportamiento implícito
   * del código original (TypeORM rechazaría duplicados a nivel DB,
   * pero la validación explícita la agregamos aquí).
   */
  @IsEmail()
  email: string;

  @IsString()
  @MinLength(1)
  name: string;

  /**
   * El código original usaba bcrypt con salt 10 sin restricción
   * de longitud mínima explícita, pero MinLength(8) es el mínimo
   * razonable para no romper el comportamiento observable.
   * Ajustar si el negocio define otra regla.
   */
  @IsString()
  @MinLength(8)
  password: string;
}

// src/users/dto/user.dto.ts
export class UserDto {
  id: string;
  email: string;
  name: string;
  createdAt: Date;

  // Factory method: construye el DTO desde la entidad en un único lugar.
  // Así el Service nunca importa lógica de mapeo inline.
  static fromEntity(user: Pick<import('../entities/user.entity').User, 'id' | 'email' | 'name' | 'createdAt'>): UserDto {
    const dto = new UserDto();
    dto.id = user.id;
    dto.email = user.email;
    dto.name = user.name;
    dto.createdAt = user.createdAt;
    return dto;
  }
}

// src/users/dto/user-with-orders.dto.ts
import { UserDto } from './user.dto';
import { User } from '../entities/user.entity';

export class UserWithOrdersDto extends UserDto {
  orderCount: number;

  static fromEntityWithOrders(user: User): UserWithOrdersDto {
    const dto = new UserWithOrdersDto();
    dto.id = user.id;
    dto.email = user.email;
    dto.name = user.name;
    dto.createdAt = user.createdAt;
    // Defensivo: orders puede venir undefined si la relación no se cargó
    dto.orderCount = user.orders?.length ?? 0;
    return dto;
  }
}

Repository

// src/users/user.repository.ts
import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { User } from './entities/user.entity';

// Datos necesarios para crear un usuario (ya con el hash, nunca la contraseña plana)
export interface CreateUserData {
  email: string;
  name: string;
  passwordHash: string;
}

@Injectable()
export class UserRepository {
  constructor(
    // Inyectamos el Repository de TypeORM con un nombre explícito
    // para no colisionar con el nombre de nuestra clase
    @InjectRepository(User)
    private readonly orm: Repository<User>,
  ) {}

  /** Busca por PK. Retorna null si no existe — sin lanzar excepciones. */
  async findById(id: string): Promise<User | null> {
    return this.orm.findOne({ where: { id }, relations: ['orders'] });
  }

  /** Busca por email. Retorna null si no existe. */
  async findByEmail(email: string): Promise<User | null> {
    return this.orm.findOne({ where: { email } });
  }

  /**
   * Persiste un nuevo usuario. Recibe datos ya procesados (hash incluido).
   * No valida unicidad — esa responsabilidad es del Service.
   */
  async create(data: CreateUserData): Promise<User> {
    const user = this.orm.create(data);
    return this.orm.save(user);
  }
}

Service

// src/users/user.service.ts
import { Injectable, ConflictException } from '@nestjs/common';
import * as bcrypt from 'bcrypt';
import { UserRepository } from './user.repository';
import { CreateUserDto } from './dto/create-user.dto';
import { UserDto } from './dto/user.dto';
import { UserWithOrdersDto } from './dto/user-with-orders.dto';

@Injectable()
export class UserService {
  // Salt rounds extraído como constante: fácil de ajustar y de leer
  private static readonly SALT_ROUNDS = 10;

  constructor(private readonly userRepository: UserRepository) {}

  /**
   * Crea un usuario nuevo.
   * Lanza ConflictException si el email ya existe (regla de negocio).
   * Retorna UserDto — nunca la entidad, nunca el hash.
   */
  async create(dto: CreateUserDto): Promise<UserDto> {
    const existing = await this.userRepository.findByEmail(dto.email);

    if (existing) {
      // ConflictException es lógica de negocio: vive aquí, no en el controller
      throw new ConflictException('Email already registered');
    }

    const passwordHash = await bcrypt.hash(dto.password, UserService.SALT_ROUNDS);

    const saved = await this.userRepository.create({
      email: dto.email,
      name: dto.name,
      passwordHash,
    });

    return UserDto.fromEntity(saved);
  }

  /**
   * Busca un usuario con sus órdenes.
   * Retorna null si no existe — el Controller decide qué excepción lanzar.
   * Esta separación permite reusar el método en otros contextos
   * (jobs, otros services) sin acoplar el manejo HTTP aquí.
   */
  async findOneWithOrders(id: string): Promise<UserWithOrdersDto | null> {
    const user = await this.userRepository.findById(id);

    if (!user) {
      return null;
    }

    return UserWithOrdersDto.fromEntityWithOrders(user);
  }
}

Controller

// src/users/user.controller.ts
import {
  Controller,
  Post,
  Get,
  Param,
  Body,
  NotFoundException,
  HttpCode,
  HttpStatus,
} from '@nestjs/common';
import { UserService } from './user.service';
import { CreateUserDto } from './dto/create-user.dto';
import { UserDto } from './dto/user.dto';
import { UserWithOrdersDto } from './dto/user-with-orders.dto';

@Controller('users')
export class UserController {
  constructor(private readonly userService: UserService) {}

  /**
   * POST /users → 201
   * El Controller solo: valida (via class-validator en el DTO),
   * delega al Service, retorna el DTO resultante.
   */
  @Post()
  @HttpCode(HttpStatus.CREATED)
  async create(@Body() dto: CreateUserDto): Promise<UserDto> {
    // Sin lógica de negocio: si el email existe, el Service lanza ConflictException
    return this.userService.create(dto);
  }

  /**
   * GET /users/:id → 200
   * El Controller es el único lugar que sabe que "null = 404 HTTP".
   * El Service no sabe nada de HTTP.
   */
  @Get(':id')
  async findOne(@Param('id') id: string): Promise<UserWithOrdersDto> {
    const user = await this.userService.findOneWithOrders(id);

    if (!user) {
      // La conversión null → NotFoundException vive aquí porque
      // es una decisión HTTP, no de negocio
      throw new NotFoundException('User not found');
    }

    return user;
  }
}

Módulo

// src/users/user.module.ts
import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { User } from './entities/user.entity';
import { Order } from './entities/order.entity';
import { UserRepository } from './user.repository';
import { UserService } from './user.service';
import { UserController } from './user.controller';

@Module({
  imports: [
    // Registramos las entidades que este módulo gestiona
    TypeOrmModule.forFeature([User, Order]),
  ],
  providers: [
    UserRepository, // Nuestro wrapper de persistencia
    UserService,    // Lógica de negocio
  ],
  controllers: [UserController],
  exports: [UserService], // Exportamos Service por si otros módulos lo necesitan
})
export class UserModule {}

Resumen de decisiones

| Decisión | Justificación | |---|---| | ConflictException en Service | Es una regla de negocio ("el email debe ser único"), no una decisión HTTP | | NotFoundException en Controller | Es una traducción de null a HTTP 404; el Service no debe conocer códigos HTTP | | null como retorno del Service | Desacopla el Service del protocolo HTTP; permite reusar en contextos no-HTTP | | Factory methods fromEntity en DTOs | Centraliza el mapeo; si la entidad cambia, solo se toca el DTO | | CreateUserData interface en Repository | El Repository recibe el hash, nunca la contraseña plana; la responsabilidad de hashear es del Service | | passwordHash nunca en los DTOs de respuesta | Previene exposición accidental de datos sensibles |

Diseño de Prompt con Chain-of-Thought para Evaluación de Crédito Empresarial

Análisis del Problema

Antes del prompt, identifiquemos los puntos críticos donde un LLM puede fallar:

RIESGOS DE ERROR IDENTIFICADOS:
├── Regla 5 (PyME) es una EXCEPCIÓN a la Regla 3 → fácil de ignorar
├── Regla 6 (construcción) es INDEPENDIENTE → no cancela elegibilidad
├── Regla 4 solo aplica SI hay deuda existente → condicional anidado
├── "mora histórica" ≠ "mora últimos 12 meses" → distinción semántica crítica
└── tasa_riesgo debe inferirse del conjunto de condiciones → no es explícita

El Prompt

SYSTEM PROMPT
─────────────────────────────────────────────────────────────────────────────

Eres un analista de riesgo crediticio especializado en crédito empresarial.
Tu tarea es evaluar la elegibilidad de una empresa para crédito siguiendo
un conjunto estricto de reglas. Debes razonar explícitamente paso a paso
antes de emitir cualquier veredicto.

REGLAS DE ELEGIBILIDAD (leer completo antes de evaluar):
════════════════════════════════════════════════════════

R1. ANTIGÜEDAD: La empresa debe tener mínimo 2 años operando.

R2. INGRESOS: Los ingresos anuales deben ser estrictamente mayores a $500,000 USD.

R3. MORA RECIENTE: No debe tener moras en los últimos 12 meses.
    [EXCEPCIÓN → ver R5]

R4. RATIO DEUDA/INGRESO: SOLO si la empresa tiene deuda existente,
    el ratio deuda/ingreso debe ser menor a 0.4.
    Si no tiene deuda existente, esta regla NO aplica.

R5. EXCEPCIÓN PyME: Si la empresa tiene MENOS de 50 empleados (PyME),
    puede tener EXACTAMENTE 1 mora en su historial TOTAL y aún ser elegible,
    pero se le asignará una tasa de riesgo mayor.
    IMPORTANTE: Esta excepción aplica a moras históricas, NO exime de
    tener más de 1 mora, y NO aplica si hay mora en los últimos 12 meses
    combinada con otras violaciones graves.

R6. SECTOR CONSTRUCCIÓN: Las empresas del sector construcción SIEMPRE
    requieren garantía adicional, independientemente de si son elegibles
    o no, y sin importar ninguna otra condición.

DEFINICIONES IMPORTANTES:
─────────────────────────
- "mora reciente": mora ocurrida dentro de los últimos 12 meses
- "mora histórica": cualquier mora registrada en el historial total
- "PyME": empresa con menos de 50 empleados
- "deuda existente": campo debt_amount > 0 en los datos
- ratio deuda/ingreso = debt_amount / annual_revenue

INSTRUCCIONES DE RAZONAMIENTO:
════════════════════════════════

Debes seguir OBLIGATORIAMENTE estos pasos en orden. No saltes ninguno.
Escribe tu razonamiento en cada paso antes de continuar al siguiente.

PASO 1 — EXTRACCIÓN DE DATOS
Extrae y lista cada dato relevante del JSON. Calcula valores derivados
(ratio D/I si aplica). Señala explícitamente si algún dato está ausente.

PASO 2 — CLASIFICACIÓN PREVIA
Determina:
  a) ¿Es PyME? (empleados < 50) → SÍ / NO
  b) ¿Es sector construcción? → SÍ / NO
  c) ¿Tiene deuda existente? (debt_amount > 0) → SÍ / NO
  d) ¿Cuántas moras tiene en total en su historial?
  e) ¿Tiene mora en los últimos 12 meses? → SÍ / NO

PASO 3 — EVALUACIÓN REGLA POR REGLA
Evalúa cada regla de forma independiente. Usa este formato exacto:

  [R1 - ANTIGÜEDAD]
  Valor: ___ años
  Umbral: ≥ 2 años
  ¿Cumple?: SÍ / NO
  Notas: ___

  [R2 - INGRESOS]
  Valor: $___
  Umbral: > $500,000
  ¿Cumple?: SÍ / NO
  Notas: ___

  [R3 - MORA RECIENTE]
  ¿Tiene mora últimos 12 meses?: SÍ / NO
  ¿Aplica excepción R5?: (responder solo si es PyME)
  ¿Cumple R3?: SÍ / NO
  Notas: ___

  [R4 - RATIO DEUDA/INGRESO]
  ¿Tiene deuda existente?: SÍ / NO
  → Si NO: "R4 no aplica. Cumplimiento automático."
  → Si SÍ:
     Cálculo: ___ / ___ = ___
     Umbral: < 0.4
     ¿Cumple?: SÍ / NO
  Notas: ___

  [R5 - EXCEPCIÓN PyME]
  ¿Es PyME?: SÍ / NO
  → Si NO: "R5 no aplica."
  → Si SÍ:
     Moras totales en historial: ___
     ¿Tiene exactamente 1 mora histórica?: SÍ / NO
     ¿Activa la excepción?: SÍ / NO
     Efecto: ___
  Notas: ___

  [R6 - SECTOR CONSTRUCCIÓN]
  ¿Es sector construcción?: SÍ / NO
  → Si SÍ: "Requiere garantía adicional. (No afecta elegibilidad)"
  → Si NO: "R6 no aplica. Sin garantía adicional por sector."
  Notas: ___

PASO 4 — ANÁLISIS DE CONFLICTOS Y EXCEPCIONES
Antes de decidir, responde estas preguntas de verificación:
  a) ¿Alguna regla fallida está siendo cubierta por una excepción válida?
     Explicar cuál y por qué.
  b) ¿Hay condiciones que se contradicen entre sí?
  c) ¿La excepción PyME (R5) aplica correctamente según los datos?
  d) ¿La garantía de construcción (R6) está siendo tratada como
     condición de elegibilidad cuando no lo es?

PASO 5 — DETERMINACIÓN DE ELEGIBILIDAD
Con base en los pasos anteriores:
  - Lista las reglas que PASAN
  - Lista las reglas que FALLAN (sin excepción válida)
  - Conclusión: ¿Es elegible?

  Lógica de decisión:
  → ELEGIBLE si: R1 ✓ Y R2 ✓ Y (R3 ✓ O excepción-R5-válida) Y R4 ✓-o-no-aplica
  → NO ELEGIBLE si: falla R1, O falla R2, O falla R4, O falla R3 sin excepción

PASO 6 — DETERMINACIÓN DE TASA DE RIESGO
Usa esta tabla de decisión:

  | Condición                                          | Tasa      |
  |----------------------------------------------------|-----------|
  | No elegible                                        | rechazado |
  | Elegible, cumple todo sin excepciones              | baja      |
  | Elegible, ratio D/I entre 0.3 y 0.4               | media     |
  | Elegible con excepción PyME (mora histórica)       | alta      |
  | Elegible con excepción PyME + ratio D/I alto       | alta      |
  | Múltiples condiciones límite sin excepción PyME    | media     |

  Justifica la tasa asignada citando las condiciones que la determinan.

PASO 7 — VERIFICACIÓN FINAL (anti-errores)
Antes de generar el JSON, confirma:
  □ R6 (construcción) está en requiere_garantia, NO afectando elegible
  □ Si elegible=false, tasa_riesgo="rechazado"
  □ Si elegible=true con excepción PyME, tasa_riesgo="alta" como mínimo
  □ Los motivos explican tanto por qué SÍ como por qué NO en cada caso
  □ No confundí mora reciente con mora histórica

PASO 8 — OUTPUT FINAL
Solo después de completar los 7 pasos anteriores, genera el JSON:

```json
{
  "elegible": boolean,
  "motivos": [
    "string con explicación clara de cada factor relevante"
  ],
  "tasa_riesgo": "baja|media|alta|rechazado",
  "requiere_garantia": boolean
}

REGLA ABSOLUTA: No generes el JSON antes de completar el razonamiento. El JSON debe ser consistente con el razonamiento. Si hay contradicción, el razonamiento tiene prioridad y debes corregir el JSON.

───────────────────────────────────────────────────────────────────────────── USER PROMPT ─────────────────────────────────────────────────────────────────────────────

Evalúa la elegibilidad crediticia de la siguiente empresa:

{JSON_DE_EMPRESA}

---

## Ejemplo de Ejecución Completa

### Input

```json
{
  "company_name": "Constructora Norteña S.A.",
  "years_operating": 3,
  "annual_revenue": 620000,
  "employees": 35,
  "sector": "construccion",
  "debt_amount": 200000,
  "recent_mora": false,
  "historical_moras": 1
}

Output Esperado del LLM

PASO 1 — EXTRACCIÓN DE DATOS
──────────────────────────────
Datos extraídos:
- Nombre: Constructora Norteña S.A.
- Años operando: 3
- Ingresos anuales: $620,000 USD
- Empleados: 35
- Sector: construcción
- Deuda existente: $200,000 USD (debt_amount > 0 → SÍ tiene deuda)
- Mora últimos 12 meses: NO (recent_mora: false)
- Moras históricas totales: 1

Valores derivados:
- Ratio deuda/ingreso: 200,000 / 620,000 = 0.3226 (redondeado: 0.32)

No hay datos ausentes.

PASO 2 — CLASIFICACIÓN PREVIA
──────────────────────────────
a) ¿Es PyME? 35 empleados < 50 → SÍ, es PyME
b) ¿Es sector construcción? sector = "construccion" → SÍ
c) ¿Tiene deuda existente? debt_amount = 200,000 > 0 → SÍ
d) Moras históricas totales: 1
e) ¿Mora en últimos 12 meses? recent_mora = false → NO

PASO 3 — EVALUACIÓN REGLA POR REGLA
──────────────────────────────────────

[R1 - ANTIGÜEDAD]
Valor: 3 años
Umbral: ≥ 2 años
¿Cumple?: SÍ
Notas: Supera el mínimo requerido por 1 año.

[R2 - INGRESOS]
Valor: $620,000
Umbral: > $500,000
¿Cumple?: SÍ
Notas: Supera el umbral en $120,000.

[R3 - MORA RECIENTE]
¿Tiene mora últimos 12 meses?: NO
¿Aplica excepción R5?: Es PyME, pero no hay mora reciente,
  por lo que R5 no necesita "rescatar" R3.
¿Cumple R3?: SÍ
Notas: No tiene mora reciente. R3 se cumple directamente.

[R4 - RATIO DEUDA/INGRESO]
¿Tiene deuda existente?: SÍ
Cálculo: 200,000 / 620,000 = 0.3226
Umbral: < 0.4
¿Cumple?: SÍ (0.3226 < 0.4)
Notas: Cumple, aunque el ratio está en zona media (0.3-0.4).

[R5 - EXCEPCIÓN PyME]
¿Es PyME?: SÍ (35 empleados)
Moras totales en historial: 1
¿Tiene exactamente 1 mora histórica?: SÍ
¿Activa la excepción?: La excepción existe, pero R3 ya se cumple
  sin necesitarla (no hay mora reciente). La mora histórica de 1
  es relevante para la tasa de riesgo, no para bloquear elegibilidad.
Efecto: La mora histórica en una PyME → tasa de riesgo "alta".
Notas: R5 no necesita "salvar" la elegibilidad aquí, pero SÍ
  impacta la tasa asignada.

[R6 - SECTOR CONSTRUCCIÓN]
¿Es sector construcción?: SÍ
→ Requiere garantía adicional. (No afecta elegibilidad)
Notas: Esta condición solo activa requiere_garantia = true.
  No modifica el resultado de elegibilidad.

PASO 4 — ANÁLISIS DE CONFLICTOS Y EXCEPCIONES
────────────────────────────────────────────────
a) No hay reglas fallidas que necesiten cobertura por excepción.
   R3 se cumple directamente. R5 aplica para la tasa, no para rescate.

b) No hay contradicciones entre condiciones.

c) R5 aplica correctamente: la empresa ES PyME y TIENE 1 mora histórica,
   lo que eleva la tasa pero no bloquea la elegibilidad (especialmente
   porque la mora no es reciente).

d) R6 está siendo tratado correctamente como condición de garantía,
   NO como factor de elegibilidad. La empresa puede ser elegible
   y aun así requerir garantía por ser del sector construcción.

PASO 5 — DETERMINACIÓN DE ELEGIBILIDAD
────────────────────────────────────────
Reglas que PASAN: R1 ✓, R2 ✓, R3 ✓, R4 ✓
Reglas que FALLAN sin excepción: Ninguna
R6: No es regla de elegibilidad, solo de garantía.

Conclusión: ELEGIBLE
Lógica: R1 ✓ Y R2 ✓ Y R3 ✓ Y R4 ✓ → Cumple todos los requisitos.

PASO 6 — DETERMINACIÓN DE TASA DE RIES

Prompt Reescrito para Producción

Análisis del problema

El prompt original falla en tres dimensiones críticas:

• Sin contexto: el LLM no sabe quién escribe, a quién, ni por qué
• Sin estructura de input: el operador no sabe qué información proveer
• Sin constraints de output: formato, extensión y tono quedan a criterio del modelo

Prompt Production-Ready

SYSTEM:
Eres un redactor especializado en atención al cliente para [NOMBRE_EMPRESA], 
un ecommerce de [RUBRO]. Tu tarea es redactar respuestas de email para que 
los operadores de soporte las envíen directamente a clientes, sin edición adicional.

REGLAS OBLIGATORIAS:
- Tono: profesional y empático. Reconocé el inconveniente antes de dar soluciones.
- Nunca uses placeholders como [nombre] o [fecha]. Si falta un dato, usá 
  una alternativa genérica válida (ej: "su pedido" en lugar de "[número de pedido]").
- Extensión: máximo 150 palabras. Emails cortos tienen mayor tasa de lectura.
- Formato: texto plano, sin markdown, sin bullets. Solo párrafos.
- Idioma: español rioplatense, formal. Usá "usted" siempre.
- No prometas plazos ni compensaciones que no estén indicadas en el input.
- Siempre cerrá con una línea de disposición y la firma: "Equipo de Atención al Cliente".

ESTRUCTURA DEL EMAIL:
1. Saludo personalizado (si hay nombre) o genérico
2. Reconocimiento del problema (1 oración)
3. Explicación o solución concreta (2-3 oraciones)
4. Próximos pasos claros (si aplica)
5. Cierre empático + firma

---

USER:
Redactá un email de respuesta con estos datos:

TIPO DE RECLAMO: [envío / devolución / pago]
NOMBRE DEL CLIENTE: [nombre o "no disponible"]
NÚMERO DE PEDIDO: [número o "no disponible"]
SITUACIÓN: [descripción en lenguaje natural de lo que pasó]
RESOLUCIÓN O ACCIÓN TOMADA: [qué se va a hacer o ya se hizo]
INFORMACIÓN ADICIONAL: [datos relevantes: fechas, montos, excepciones — o "ninguna"]

Ejemplo de uso real

Input del operador:

TIPO DE RECLAMO: envío
NOMBRE DEL CLIENTE: Marcela Torres
NÚMERO DE PEDIDO: 84521
SITUACIÓN: El pedido llegó con el paquete roto y falta uno de los dos 
           productos que compró.
RESOLUCIÓN O ACCIÓN TOMADA: Se va a reenviar el producto faltante en 48hs. 
                             El packaging dañado queda documentado.
INFORMACIÓN ADICIONAL: No necesita devolver nada.

Output esperado del LLM:

Estimada Marcela Torres:

Lamentamos que su pedido N.° 84521 haya llegado en esas condiciones. 
Entendemos lo frustrante que puede resultar esta situación y le pedimos disculpas.

Hemos registrado el inconveniente y procederemos a reenviarle el producto 
faltante en un plazo de 48 horas hábiles. No es necesario que realice 
ninguna devolución; el caso ya quedó documentado de nuestra parte.

Quedamos a su disposición ante cualquier consulta adicional.

Equipo de Atención al Cliente

Por qué esto reduce la variabilidad

| Fuente de variabilidad | Solución aplicada | |---|---| | El modelo no sabe qué escribir | Input estructurado con campos fijos | | Tono inconsistente | Definido con ejemplos implícitos en las reglas | | Placeholders en el output | Regla explícita + alternativa genérica indicada | | Emails demasiado largos o cortos | Límite de palabras definido | | Promesas fuera de política | Restricción explícita en las reglas | | Formato variable (bullets, markdown) | Prohibición explícita de formato |

Recomendaciones adicionales para producción

1. TEMPERATURA: Configurá el modelo en 0.3–0.5
   → Reduce creatividad innecesaria sin perder fluidez

2. VALIDACIÓN POST-GENERACIÓN: Chequeá programáticamente que:
   → No contenga "[" o "]" (placeholder no reemplazado)
   → Tenga menos de 200 palabras
   → Incluya "Equipo de Atención al Cliente"

3. VERSIONADO: Tratá este prompt como código
   → Guardalo con versión (v1.0, v1.1)
   → Registrá cambios y su impacto en calidad

4. FEEDBACK LOOP: Pedile a los operadores que marquen 
   emails que editaron manualmente → esos casos son 
   tu dataset de mejora del prompt

Prompt para Sistema de Clasificación Automática de Tickets de Soporte

You are an expert support ticket classification system for a customer service platform. Your sole function is to analyze incoming customer messages and return a structured JSON classification. You must never engage in conversation, ask questions, or provide answers to the customer — only classify.

────────────────────────────────────────
CLASSIFICATION SCHEMA
────────────────────────────────────────

You must always return a valid JSON object with exactly these fields:

{
  "categoria": <string>,
  "prioridad": <string>,
  "sentimiento": <string>,
  "requiere_humano": <boolean>,
  "resumen_corto": <string>
}

FIELD DEFINITIONS AND ALLOWED VALUES:

▸ categoria (choose exactly one):
  - "facturacion"        → billing errors, charges, invoices, refunds, payment issues
  - "envio"             → shipping status, delays, lost packages, wrong address, tracking
  - "producto_defectuoso" → broken, damaged, not working, missing parts, wrong item received
  - "consulta_general"  → product info, how-to questions, store hours, policies, availability
  - "cancelacion"       → order cancellation, subscription cancellation, return requests
  - "fraude"            → unauthorized charges, account hacked, identity theft, suspicious activity

▸ prioridad (choose exactly one):
  - "critica"  → fraud, security breach, unauthorized access, legal threats, customer in danger
  - "alta"     → defective product causing harm, large financial discrepancy, very angry customer threatening escalation
  - "media"    → shipping delays, billing questions, product defects (non-urgent), cancellation requests
  - "baja"     → general inquiries, informational questions, minor issues with no financial impact

▸ sentimiento (choose exactly one):
  - "muy_negativo"  → furious, threatening, aggressive, uses insults or all-caps rage
  - "negativo"      → frustrated, disappointed, clearly unhappy
  - "neutral"       → factual, calm, no strong emotion
  - "positivo"      → polite, patient, even if reporting a problem

▸ requiere_humano (boolean):
  - true  → if ANY of these apply:
              • categoria is "fraude"
              • prioridad is "critica" or "alta"
              • sentimiento is "muy_negativo"
              • message contains legal threats, mentions a lawyer, or references a regulatory body
              • message is ambiguous and could involve safety or financial harm
  - false → all other cases

▸ resumen_corto (string):
  - A single sentence (max 15 words) in the SAME LANGUAGE as the customer's message
  - Must capture the core issue only — no filler, no fluff
  - If the message is in "spanglish", write the summary in Spanish

────────────────────────────────────────
HANDLING EDGE CASES
────────────────────────────────────────

▸ AMBIGUOUS OR INCOMPLETE MESSAGES:
  - Still return a valid JSON — never return an error or ask for clarification
  - Use "consulta_general" as fallback category when the topic cannot be determined
  - Use "media" as fallback priority
  - Set requiere_humano: true if the ambiguity involves potential financial or safety risk
  - In resumen_corto, write: "Mensaje incompleto o ambiguo — requiere revisión" (or English equivalent)

▸ MULTIPLE ISSUES IN ONE MESSAGE:
  - Classify by the MOST SEVERE issue (highest priority)
  - If two issues share the same priority, classify by the one mentioned first

▸ LANGUAGE:
  - Detect and process Spanish, English, and Spanglish transparently
  - Do NOT translate the resumen_corto — match the customer's primary language
  - Spanglish → default to Spanish for resumen_corto

▸ SARCASM / PASSIVE-AGGRESSIVE TONE:
  - Treat sarcastic politeness as "negativo" sentiment, not "positivo"
  - Example: "Oh great, another package lost. Super impressive service." → negativo

▸ FRAUD INDICATORS (always trigger critica + requiere_humano: true):
  - "someone else used my card / account"
  - "I didn't make this purchase"
  - "my account was hacked / compromised"
  - "unauthorized charge / transaction"
  - Variations in Spanish: "no fui yo", "me hackearon", "cargo no reconocido", "alguien usó mi cuenta"

────────────────────────────────────────
FEW-SHOT EXAMPLES
────────────────────────────────────────

--- EXAMPLE 1: Standard shipping complaint (Spanish) ---

INPUT:
"Hola, hice un pedido hace 10 días (orden #45231) y todavía no llegó nada.
El tracking dice 'en camino' desde hace una semana y nadie me da respuestas.
Necesito saber dónde está mi paquete."

OUTPUT:
{
  "categoria": "envio",
  "prioridad": "media",
  "sentimiento": "negativo",
  "requiere_humano": false,
  "resumen_corto": "Pedido #45231 sin entregar después de 10 días, tracking sin actualización."
}

---

--- EXAMPLE 2: Fraud report (English) ---

INPUT:
"I just got a notification of a $340 charge on my account but I never placed
this order. I don't even recognize the shipping address. I think someone hacked
my account. Please help IMMEDIATELY."

OUTPUT:
{
  "categoria": "fraude",
  "prioridad": "critica",
  "sentimiento": "muy_negativo",
  "requiere_humano": true,
  "resumen_corto": "Unauthorized $340 charge — possible account compromise reported."
}

---

--- EXAMPLE 3: Spanglish + multiple issues ---

INPUT:
"Oye, me llegó el producto broken, le faltan piezas y además me cobraron
dos veces en mi tarjeta. Esto es un desastre, voy a llamar a mi banco
si no me resuelven hoy."

OUTPUT:
{
  "categoria": "facturacion",
  "prioridad": "alta",
  "sentimiento": "muy_negativo",
  "requiere_humano": true,
  "resumen_corto": "Doble cobro en tarjeta y producto defectuoso recibido, cliente amenaza con escalar."
}

CLASSIFICATION RATIONALE (internal, not part of output):
Two issues detected: producto_defectuoso + facturacion. Facturacion wins because
it has equal or higher severity and involves a financial discrepancy with a
legal/escalation threat. requiere_humano: true because sentimiento is muy_negativo
AND there is a legal/bank escalation threat.

---

--- EXAMPLE 4: Ambiguous / incomplete message ---

INPUT:
"Tengo un problema con mi cuenta."

OUTPUT:
{
  "categoria": "consulta_general",
  "prioridad": "media",
  "sentimiento": "neutral",
  "requiere_humano": false,
  "resumen_corto": "Mensaje incompleto o ambiguo — requiere revisión."
}

---

--- EXAMPLE 5: Sarcasm + cancellation (English) ---

INPUT:
"Wow, what a fantastic experience. My order arrived 3 weeks late, completely
wrong item, and now your website won't even let me cancel. Truly outstanding
customer service. Please just cancel everything and refund me."

OUTPUT:
{
  "categoria": "cancelacion",
  "prioridad": "alta",
  "sentimiento": "muy_negativo",
  "requiere_humano": true,
  "resumen_corto": "Customer demands full cancellation and refund after wrong item and extreme delay."
}

---

--- EXAMPLE 6: Low-priority general inquiry (neutral) ---

INPUT:
"Hi! Do you guys offer gift wrapping for orders? And what's the cutoff time
to place an order for next-day delivery? Thanks!"

OUTPUT:
{
  "categoria": "consulta_general",
  "prioridad": "baja",
  "sentimiento": "positivo",
  "requiere_humano": false,
  "resumen_corto": "Customer asks about gift wrapping and next-day delivery cutoff time."
}

────────────────────────────────────────
OUTPUT RULES — STRICTLY ENFORCED
────────────────────────────────────────

✓ Return ONLY the JSON object — no explanation, no preamble, no markdown fences
✓ All JSON keys must be in lowercase with underscores as shown
✓ "categoria" values must NOT include accents (use "facturacion" not "facturación")
✓ Do not add extra fields beyond the five defined
✓ Do not return null for any field — always provide a value
✓ If the input is empty or gibberish, return the ambiguous-message fallback JSON
✓ Never break character — you are a classification engine, not a conversational agent

────────────────────────────────────────
RECOMMENDED INFERENCE SETTINGS
────────────────────────────────────────
temperature: 0
top_p: 1
max_tokens: 200

Notas de implementación

## Por qué cada decisión de diseño

| Decisión                          | Justificación                                                                 |
|-----------------------------------|-------------------------------------------------------------------------------|
| temperature: 0                    | Clasificación determinista — misma entrada = misma salida siempre             |
| Sección FRAUD INDICATORS          | LLMs sin anclas explícitas pueden subestimar urgencia en lenguaje coloquial   |
| Sarcasm handling explícito        | Edge case frecuente que confunde modelos entrenados en sentiment superficial  |
| resumen_corto en idioma del cliente | Permite a agentes humanos leer sin fricciones al hacer triage                |
| Fallback para ambigüedad          | Evita outputs vacíos o errores que rompan pipelines downstream                |
| max_tokens: 200                   | El JSON de output nunca supera ~150 tokens; el límite previene alucinaciones  |
| Sin markdown fences en output     | Facilita JSON.parse() directo sin sanitización previa                         |

Roadmap 6 Meses: Plataforma AI Agents para PyMEs LATAM

Diagnóstico previo al roadmap

Antes de definir qué construir, es crítico entender por qué estás perdiendo el 40% mensual. Con 5 clientes beta tenés suficiente señal para actuar, pero el roadmap entero depende de si el churn es por:

| Causa probable | Señal | Implicancia | |---|---|---| | Setup demasiado difícil | Clientes se van en semana 1-2 | Prioridad: onboarding | | El agente falla en producción | Clientes se van en semana 3-4 | Prioridad: calidad del agente | | No ven valor / ROI | Clientes se van al mes exacto | Prioridad: métricas de valor |

Acción inmediata (antes del Mes 1): Entrevistar a los 5 beta y a los que se fueron. Esta información vale más que cualquier feature.

Hipótesis de trabajo para este roadmap: El churn tiene dos drivers simultáneos — setup difícil que genera frustración inicial + agente que falla en preguntas ambiguas que destruye la confianza. Los primeros 2 meses atacan setup; los meses 3-4 atacan calidad del agente.

Principios que guían las decisiones

1. Retención antes que adquisición. Llevar 50 clientes a un producto con 40% churn es un balde con agujeros. Cada peso en ventas antes de resolver retención es dinero quemado.
2. WhatsApp es el moat. Chatbase y Botpress no lo tienen nativo. Treble lo tiene pero apunta a empresas más grandes. Profundizar aquí, no diversificar canales.
3. El equipo es el constraint real. Con 2 devs fullstack y UX part-time, cada sprint tiene capacidad limitada. El roadmap tiene que ser brutal con lo que NO se hace.
4. $50k en 6 meses con sueldos incluidos implica que el margen de error es casi cero. Asumo sueldos ~$6-7k/mes total equipo técnico, quedan ~$8-12k para infraestructura, herramientas y margen.

MES 1: Parar la hemorragia

Tema del mes: "Que nadie más se vaya"

Por qué esto primero: No tiene sentido adquirir nuevos clientes si el setup sigue roto. Un mes enfocado en retención tiene ROI inmediato sobre los 5 beta actuales y genera aprendizajes que aceleran todo lo que sigue.

Prioridad 1 — Onboarding guiado paso a paso [Dev: 60% del sprint]

Qué es: Reemplazar el setup actual (sea lo que sea) por un wizard de 5 pasos con estado persistente, validaciones en tiempo real y ejemplos pre-cargados por industria.

Los 5 pasos del wizard:

Paso 1: Conectar WhatsApp Business (guía visual + video de 2 min)
Paso 2: Elegir industria → carga plantilla de base de conocimiento
Paso 3: Subir/editar tu base de conocimiento (con preview en vivo)
Paso 4: Configurar respuesta de fallback ("No entendí, te comunico con un humano")
Paso 5: Test en sandbox antes de ir live

Por qué plantillas por industria: Tus 5 beta son contador, estudio jurídico, clínica. Tenés suficiente data para crear 3 plantillas con las 20 preguntas más comunes de cada sector. El cliente llega y el 70% del trabajo ya está hecho.

Métrica de éxito: Tiempo hasta primer mensaje respondido por el agente < 30 minutos. Medir con analytics de eventos en cada paso del wizard.

Prioridad 2 — Fallback a humano funcional [Dev: 25% del sprint]

Qué es: Cuando el agente no sabe responder (baja confianza o pregunta ambigua), en lugar de dar una respuesta mala, escala al humano con contexto.

Comportamiento:

Si confianza < umbral definible por el cliente:
→ "Entiendo tu consulta sobre [tema detectado]. 
   Voy a conectarte con [nombre del negocio] para darte 
   la mejor respuesta. ¿Querés que te contacten por 
   WhatsApp o preferís llamada?"
→ Notificación al dueño del negocio con el contexto

Por qué ahora: Este es el problema técnico más crítico identificado en beta. No resolverlo con IA todavía (eso es Mes 3), pero sí contenerlo para que no destruya la experiencia del usuario final. Un agente que dice "no sé" con gracia es infinitamente mejor que uno que da una respuesta incorrecta con confianza.

Umbral configurable: El cliente puede definir qué tan "conservador" quiere que sea el agente. Clínica médica → umbral alto (escala fácil). Contador → umbral medio.

Prioridad 3 — Dashboard mínimo de actividad [Dev: 15% del sprint]

Qué es: Una pantalla simple que muestre al cliente:

• Cuántos mensajes respondió el agente hoy/semana/mes
• Cuántos escaló a humano (y por qué)
• Las 5 preguntas que más se repitieron

Por qué: El cliente necesita ver valor. Si el agente respondió 47 preguntas esta semana que antes respondía el dueño manualmente, eso es ROI visible. Sin este dashboard, el valor es invisible y el churn es inevitable.

No construir todavía: Analíticas avanzadas, exportación de datos, comparativas. Solo lo mínimo para que el cliente diga "ah, el agente está trabajando".

UX — Diseño del wizard [UX: 80% de las 20hs semanales]

El designer UX concentra casi todo su tiempo en el wizard de onboarding. Este es el momento donde se gana o se pierde el cliente. Cada fricción en estos 5 pasos es un punto de abandono.

Entregables UX Mes 1:

• Flujo completo del wizard con estados de error, éxito y carga
• Plantillas visuales para las 3 industrias beta
• Guía de microcopy (los textos de ayuda dentro del producto)

Founders — Ventas [30% del tiempo]

No escalar adquisición todavía. Usar el tiempo de ventas para:

1. Entrevistar a los 3-4 clientes que se fueron en beta (entender exactamente por qué)
2. Hacer onboarding manual con los 5 beta actuales usando el nuevo wizard en desarrollo
3. Identificar 10 prospectos calificados para tener listos cuando el producto esté más sólido (Mes 2)

Qué NO hacer en Mes 1

• ❌ Memoria conversacional (es complejo, es Mes 3)
• ❌ Integración con otros canales (Instagram, email)
• ❌ Planes y pricing dentro del producto
• ❌ API pública
• ❌ Contratar más gente (no hay budget y agregaría overhead)

Métricas de cierre Mes 1

| Métrica | Target | |---|---| | Churn de los 5 beta actuales | 0 en este mes | | Tiempo de onboarding medido | < 45 min (camino a 30) | | NPS de los 5 beta | Medir baseline | | Escaladas a humano con contexto | 100% de los casos de baja confianza |

MES 2: Que el onboarding funcione solo

Tema del mes: "El primer cliente que no conocemos tiene que poder activarse sin ayuda"

Por qué este foco: En Mes 1 construiste el wizard. En Mes 2 lo validás con clientes reales que no son tus beta actuales. El objetivo es llegar a 15 clientes pagos con onboarding completamente self-serve.

Prioridad 1 — Primer plan de precios y cobro [Dev: 30% del sprint]

Qué construir:

• Integración con Stripe o MercadoPago (recomiendo MercadoPago para LATAM por menor fricción en cobro local)
• Un solo plan: $149/mes
• Trial de 14 días sin tarjeta (reduce fricción de entrada)
• Upgrade forzado al día 14

Por qué un solo plan: La decisión de pricing es una distracción ahora. $149 es tu hipótesis, la vas a validar o refutar con los primeros 15 clientes. Agregar tiers (Basic/Pro/Enterprise) antes de tener tracción es optimizar algo que no está validado.

Consideración LATAM: Evaluar si ofrecer precio en moneda local para Argentina (ARS) dado el contexto inflacionario. Puede reducir fricción pero agrega complejidad de FX. Decisión de founders, no técnica.

Prioridad 2 — Mejoras al wizard basadas en datos de Mes 1 [Dev: 30% del sprint]

Después de un mes con el wizard en producción, vas a tener datos de dónde abandonan los usuarios. Usar esos datos para:

• Identificar el paso con mayor drop-off y rediseñarlo
• Agregar tooltips contextuales en los puntos de confusión
• Mejorar el mensaje de error cuando la conexión con WhatsApp Business falla (históricamente el paso más problemático)

Herramienta recomendada: Hotjar o FullStory en el wizard para ver grabaciones de sesiones. Costo: ~$30-50/mes. Vale cada centavo en este momento.

Prioridad 3 — Base de conocimiento con formato enriquecido [Dev: 25% del sprint]

Problema actual: El cliente carga texto plano. Esto tiene limitaciones para estructurar información compleja (precios con condiciones, horarios por día, procedimientos con pasos).

Qué agregar:

• Soporte para carga de PDF (extracción de texto automática)
• Editor de preguntas y respuestas estructuradas (FAQ builder simple)
• Preview de cómo el agente va a responder antes de publicar

Por qué ahora: Reducir el esfuerzo del cliente para construir la base de conocimiento es directamente reducir el tiempo de onboarding. El texto plano pone todo el trabajo de estructuración en el cliente.

Prioridad 4 — Emails de activación y retención [Dev: 15% del sprint]

Secuencia de emails automáticos:

Día 0: Bienvenida + link al wizard
Día 1: Si no completó onboarding → "¿Necesitás ayuda con el paso X?"
Día 3: Si completó onboarding → "Tu agente respondió N preguntas"
Día 7: Tips para mejorar la base de conocimiento
Día 12: Recordatorio de que el trial termina en 2 días
Día 14: "Activá tu plan para no perder tu configuración"

Herramienta: Customer.io o Loops.so. No construir esto desde cero.

UX — Mes 2 [UX: 60% wizard mejoras, 40% base de conocimiento]

Foco en el FAQ builder y el editor de base de conocimiento. Este es el corazón del producto desde la perspectiva del cliente — donde pasan más tiempo y donde más se frustran.

Go-to-Market — Primeros 10 clientes pagos

Canal principal: Referidos de los 5 beta actuales.

Si los 5 beta están satisfechos después del Mes 1, cada uno puede referir 1-2 clientes de su red (otros contadores, colegas de la misma industria). Ofrecer 1 mes gratis por cada referido que se convierte.

Canal secundario: LinkedIn + comunidades de emprendedores LATAM.

Los founders usan su 30% de tiempo en ventas para:

• Publicar casos de uso concretos ("Cómo una clínica en Buenos Aires atiende consultas fuera de horario con IA")
• Participar en grupos de Facebook/WhatsApp de PyMEs argentinas
• Contacto directo a estudios contables y jurídicos (verticales donde ya tenés casos de éxito)

Target Mes 2: 10 clientes pagos (los 5 beta convierten + 5 nuevos)

Métricas de cierre Mes 2

| Métrica | Target | |---|---| | Clientes pagos | 10 | | MRR | $1,490 | | Tiempo de onboarding | < 30 minutos (medido, no estimado) | | Churn mensual | < 20% (mejora progresiva) | | Tasa de conversión trial → pago | > 40% |

MES 3: Resolver el problema técnico central

Tema del mes: "El agente tiene que ser confiable, no solo rápido de configurar"

Por qué ahora y no antes: Necesitabas tener clientes retenidos y onboarding funcionando antes de invertir en complejidad técnica. Con 10 clientes pagos y churn bajando, tenés la base para construir sin distracciones. Además, con más conversaciones reales en producción, tenés datos para entrenar y evaluar mejoras.

Prioridad 1 — Memoria conversacional [Dev: 50% del sprint]

El problema: El agente trata cada mensaje como si fuera el primero. Si el usuario dijo "soy paciente del Dr. García" tres mensajes antes, el agente no lo recuerda.

La solución técnica:

Implementar ventana de contexto conversacional:
- Almacenar últimos N mensajes por número de WhatsApp
- Incluir ese contexto en el prompt al LLM
- TTL de 24 horas (conversación "fresca") vs. histórico más largo
- Identificar entidades mencionadas (nombre, tipo de consulta, 
  producto/servicio mencionado) y mantenerlas como variables de sesión

Consideraciones de implementación:

• Usar Redis o similar para almacenamiento de sesiones en caliente
• El costo de tokens aumenta al incluir más contexto — definir ventana óptima (recomiendo empezar con últimos 10 mensajes)
• Privacidad: informar al usuario que el historial se guarda por X horas

Por qué esto mueve el churn: Las preguntas ambiguas suelen ser ambiguas porque el usuario asume que el agente recuerda el contexto previo. "¿Y el precio?" después de haber preguntado por un servicio específico es el caso más común. Con memoria, esto se resuelve.

Prioridad 2 — Manejo de ambigüedad con clarificación [Dev: 30% del sprint]

El problema: Cuando la pregunta es genuinamente ambigua

Estrategia GTM: 90 días para escalar el SaaS de reportes financieros

Contexto estratégico antes de arrancar

Antes de los canales, hay que nombrar la ventaja que ya tienen y que muchos founders ignoran: tienen prueba social real con NPS 72. Eso es el activo más escaso en una etapa temprana. Toda la estrategia va a girar alrededor de convertir esa prueba en combustible de adquisición, no en construir desde cero.

El otro dato crítico: el ciclo de compra es cortísimo. Eso cambia todo. No necesitan un funnel largo de nurturing. Necesitan volumen de demos con el perfil correcto. La estrategia tiene que optimizar para llegar rápido a la demo, no para educar durante semanas.

1. Los 3 canales GTM principales

Canal 1: Referidos estructurados desde los 6 contadores activos

Por qué este canal primero: Los 6 contadores que usan activamente el producto ya hicieron la venta más difícil: creyeron en un producto sin tracción. Si tienen NPS 72, hay al menos 4 o 5 que son promotores activos. Cada uno de ellos conoce personalmente a decenas de colegas. Un contador que le dice a otro contador "esto me ahorra 3 horas por cliente por mes" vale más que cualquier ad o contenido.

El error que cometen la mayoría es no estructurar esto. Le preguntan al cliente "¿conocés a alguien?" y esperan. Eso no funciona.

Cómo estructurarlo:

• Crear un programa de referidos con incentivo concreto: 1 mes gratis por cada referido que se convierte en pago. No descuento, no crédito abstracto: un mes gratis visible en la próxima factura.
• Darle al contador una herramienta para referir que no le genere fricción: un mensaje de WhatsApp pre-escrito que solo tenga que reenviar, con un link de demo directo que trackee el origen.
• Hacer una llamada de 20 minutos con cada uno de los 6 activos para pedirles el referido en persona, no por email. En esa llamada también recolectar testimonios en video (ver Canal 3).

Por qué no otros canales primero: Porque el CAC de un referido es casi cero y la tasa de conversión de un referido de par a par en este segmento es 3x a 5x mayor que cualquier canal frío. Desperdiciar esto por apurarse a escalar es el error más común en etapa temprana.

Canal 2: Penetración directa en asociaciones y colegios de contadores

Por qué este canal: Los contadores ya están agrupados. No hay que construir audiencia: existe, está organizada, tiene líderes identificables y canales activos (WhatsApp de los colegios, newsletters, eventos mensuales). Un solo acuerdo con un consejo profesional puede dar acceso a cientos de contadores de golpe.

El ciclo de venta B2B2C acá es: founder → autoridad del colegio → base de miembros. No es venta directa a 45,000 contadores, es venta a los 50 o 100 líderes que tienen acceso a esos contadores.

Cómo ejecutarlo:

Semana 1-2: Mapear los 10 colegios o asociaciones más activos en Argentina (empezar por Buenos Aires, Córdoba, Rosario). Identificar en LinkedIn quién es el presidente, secretario o responsable de capacitaciones. No mandar un formulario de contacto genérico: encontrar el nombre, mandar un mensaje directo personalizado.

El pitch para el colegio no es "compren nuestro producto". Es: "Queremos dar una capacitación gratuita de 45 minutos sobre automatización de reportes para sus miembros. Sin costo, sin compromiso." Los colegios siempre necesitan contenido de valor para sus miembros. Esto les resuelve un problema a ellos también.

En esa capacitación: Demo en vivo, casos reales de los 6 contadores activos, oferta exclusiva para miembros del colegio (primer mes a precio reducido o período de prueba extendido).

Por qué funciona mejor que LinkedIn Ads o Google: Porque la autoridad del colegio transfiere credibilidad. Un contador que ve el producto presentado en el espacio de su asociación profesional lo percibe como validado institucionalmente. Eso colapsa el ciclo de decisión.

Expansión a México: Los 3 inbound de México son la señal para activar esto allá también, pero en los primeros 30 días el foco es Argentina donde ya hay prueba social. México arranca en el día 31.

Canal 3: Contenido de caso de uso en LinkedIn + comunidades de WhatsApp

Por qué este canal y no otro contenido: No es "hacer contenido en LinkedIn" genérico. Es un tipo específico de contenido que funciona para este producto en este momento: el antes y después cuantificado.

El contador que antes tardaba 4 horas en armar el reporte de un cliente y ahora tarda 0 (el sistema lo genera solo) tiene una historia que se cuenta en números. Eso es exactamente lo que para el scroll en LinkedIn de un colega contador.

Qué publicar y cómo:

Formato 1 - El caso de uso real: "Un contador de [ciudad] con 45 clientes tardaba 6 horas mensuales en armar reportes para AFIP. Ahora tarda 20 minutos. Así funciona." → Captura de pantalla del reporte generado (con datos ficticios o con permiso del cliente) → Video de 60 segundos mostrando el proceso

Formato 2 - El cálculo del ROI: "Si tenés 30 clientes y tardás 3 horas por cliente en reportes, estás usando 90 horas por mes en algo que puede automatizarse. A $50/hora eso es $4,500/mes de tu tiempo. Nuestra herramienta cuesta $790/mes para 10 clientes." → Este tipo de post genera comentarios de contadores haciendo el cálculo de su propio caso

Formato 3 - Los errores comunes: Contenido educativo sobre errores en reportes para AFIP o SAT que genera búsqueda orgánica y posiciona como expertos del dominio.

WhatsApp: Los grupos de WhatsApp de contadores son donde pasan las conversaciones reales. La táctica no es entrar a spamear: es que los contadores activos compartan el contenido de LinkedIn en esos grupos de forma orgánica. Para eso hay que pedírselo explícitamente y hacerlo fácil (mandarles el link del post listo para compartir).

Por qué LinkedIn y no Instagram o TikTok: El contador que toma decisiones de compra de herramientas profesionales está en LinkedIn, no en TikTok. El contenido en LinkedIn también tiene vida útil más larga y genera búsqueda orgánica. Instagram puede funcionar para awareness, pero el costo de producción de contenido visual para dos canales simultáneos es demasiado alto para un equipo de founders sin equipo.

2. Plan semana a semana: primeros 30 días

Semana 1 (días 1-7): Activar lo que ya tienen

| Día | Acción | Responsable | Output esperado | |-----|--------|-------------|-----------------| | 1-2 | Llamada de 30 min con cada uno de los 6 contadores activos. Objetivos: recolectar testimonio en video, pedir 3 referidos concretos, entender qué feature usan más | Founder | 6 testimonios, lista de 15-18 referidos potenciales | | 3 | Armar el mensaje de WhatsApp pre-escrito para que los contadores refieran. Crear link trackeado por contador | Founder técnico | Sistema de referidos funcionando | | 4 | Enviar el mensaje de referido a los 6 activos con instrucciones claras | Founder | Referidos activados | | 5-6 | Mapear 10 colegios en Argentina. Identificar contacto específico (nombre, LinkedIn, email si es público) | Founder | Lista de 10 contactos con datos | | 7 | Primer post en LinkedIn: caso de uso real del contador más activo (con su permiso y citándolo) | Founder | Post publicado, medir engagement en 48hs |

Hito de fin de semana 1: Programa de referidos activo, lista de colegios mapeada, primer contenido publicado.

Semana 2 (días 8-14): Primeros contactos con colegios + pipeline de referidos

| Día | Acción | Output esperado | |-----|--------|-----------------| | 8-9 | Contacto directo (LinkedIn DM o email) con los 10 responsables de colegios. Mensaje personalizado, propuesta de capacitación gratuita | 10 mensajes enviados | | 10 | Follow-up a referidos que llegaron de la semana 1. Si hay demos pedidas, agendarlas para esta semana | Primeras demos de referidos | | 11 | Segundo post LinkedIn: el cálculo del ROI (formato numérico). Pedir a los 6 contadores activos que comenten el post | Post con tracción orgánica | | 12-13 | Demos con referidos. Proceso: 10 min de contexto, 20 min de demo en vivo con sus propios datos de AFIP, 10 min de preguntas | Conversiones directas | | 14 | Revisar respuestas de colegios. Hacer follow-up a los que no respondieron. Agendar primeras capacitaciones | 2-3 capacitaciones agendadas |

Hito de fin de semana 2: Al menos 2 capacitaciones agendadas en colegios, primeras conversiones de referidos.

Semana 3 (días 15-21): Primera capacitación en colegio + escalar contenido

| Día | Acción | Output esperado | |-----|--------|-----------------| | 15-16 | Preparar la capacitación: deck de 10 slides, demo en vivo con datos reales, oferta exclusiva para miembros | Material listo | | 17 | Primera capacitación en colegio (presencial o Zoom). Grabar con permiso | Demo ejecutada, leads capturados | | 18 | Follow-up inmediato (dentro de las 24hs) a todos los asistentes que mostraron interés. El hierro hay que golpearlo caliente | Demos agendadas | | 19 | Tercer post LinkedIn: "Dimos una capacitación en [Colegio X] y esto fue lo que más les sorprendió". Usar la capacitación como contenido | Post que genera credibilidad | | 20-21 | Contactar los 3 inbound de México. No venderles todavía: entender su flujo de trabajo con SAT, qué reportes generan, qué les duele | Inteligencia de mercado México |

Hito de fin de semana 3: Primera capacitación ejecutada, pipeline de leads del colegio, contexto de México mapeado.

Semana 4 (días 22-30): Consolidar y preparar escala

| Día | Acción | Output esperado | |-----|--------|-----------------| | 22-23 | Cerrar demos pendientes de la capacitación. Onboarding de nuevos clientes | Nuevos pagos | | 24 | Revisar métricas de las 3 semanas. ¿Qué canal trajo más demos? ¿Qué mensaje convierte mejor? | Decisión informada sobre dónde doblar la apuesta | | 25 | Segunda ronda de contactos a colegios (los que no respondieron + nuevos). Ahora con el caso del primer colegio como prueba social | 10 nuevos contactos | | 26-27 | Cuarto post LinkedIn + primer post específico para México (mencionar SAT, no solo AFIP) | Audiencia México empieza a crecer | | 28-29 | Demo con los 3 inbound de México. Si convierten, tienen el primer caso de uso mexicano | Primeros clientes México | | 30 | Retrospectiva de 30 días. Documentar qué funcionó, qué no, ajustar plan de días 31-60 | Plan ajustado |

Hito de fin de día 30: Al menos 5 nuevos contadores pagos (objetivo conservador), pipeline de 10+ en proceso, al menos 1 cliente en México.

3. Métricas de éxito con números objetivo

Métricas de actividad (indican si están haciendo las cosas correctas)

| Métrica | Semana 1 | Semana 2-4 | Por qué importa | |---------|----------|------------|-----------------| | Demos realizadas por semana | 3 | 8-10 | Con ciclo de compra corto, el volumen de demos es el predictor más directo de revenue | | Colegios contactados | 10 | 5 nuevos/semana | Construye pipeline de mediano plazo | | Referidos activados | 15-18 | Seguimiento semanal | Si los activos no refieren, hay que entender por qué | | Posts publicados | 1 | 2-3/semana | Consistencia > viralidad en etapa temprana |

Métricas de conversión (indican si el mensaje y producto funcionan)

| Métrica | Objetivo 30 días | Señal de alerta | |---------|-----------------|-----------------| | Tasa de cierre demo → pago | >40% | Si baja de 25%, el problema es el producto o el precio, no el canal | | Tiempo demo → decisión | <48 horas | Si se alarga, algo en la demo no está generando urgencia | | Referidos que convierten en demo | >30% de los referidos activados | Si es menor, el mensaje de referido no es claro | | Asistentes a capacitación que piden demo | >20% | Benchmark razonable para una audiencia fría |

Métricas de negocio (el resultado final)

| Métrica | Objetivo día 30 | Objetivo día 60 | Objetivo día 90 | |---------|----------------|----------------|----------------| | Contadores pagos totales | 15-18 | 30-35 | 55-65 | | MRR | ~$1,200 | ~$2,500 | ~$4,500 | | Clientes en México | 1-3 | 8-12 | 20-25 | | Churn mensual | <5% | <5% | <5% | | NPS | Mantener >65 | >70 | >70 |

El número que más importa en los primeros 30 días no es el MRR: es la tasa de activación. Tienen 2 contadores que casi no usan el producto. Si ese patrón se repite a escala, el churn va a destruir el crecimiento. Antes de día 30 necesitan entender por qué esos 2 no activan y resolver eso.

Señales de que el GTM está fallando (

Rediseño de Pricing: Plataforma de Gestión de Turnos para Salud

1. DIAGNÓSTICO: Por qué está fallando el pricing actual

El problema central: un precio único para perfiles de uso radicalmente distintos

Tenés un solo precio para dos clientes que son fundamentalmente diferentes:

| | Cliente "light" (30% bottom) | Cliente "power" (20% top) | |---|---|---| | Profesionales | 1 | 3+ | | Pacientes activos | <50 | 200+ | | Recordatorios/mes | <50 | 500+ | | Costo WhatsApp para vos | ~$1/mes | ~$10/mes | | Costo infra para vos | $8/mes | $8/mes | | Costo total que te generan | ~$9/mes | ~$18/mes | | Lo que pagan | $49/mes | $49/mes |

El cliente light paga $49 por algo que le cuesta $9 y usa poco → "es caro para lo que uso" El cliente power paga $49 por algo que le cuesta $18 y usa mucho → está subpagando

Las tres fallas estructurales

Falla 1: No hay escalera de entrada $49/mes es una barrera alta para un profesional solo que recién empieza o que viene de no usar ningún sistema. Agenda Pro a $29 captura ese segmento. Vos perdés la adquisición o adquirís clientes que nunca van a sentir que el precio vale.

Falla 2: El valor percibido no está alineado con el precio El 25% que dice "no uso todas las features" te está diciendo que están pagando por cosas que no necesitan. En SaaS, pagar por lo que no usás genera resentimiento activo, no neutralidad. Ese cliente no te defiende, te abandona en cuanto aparece algo más barato.

Falla 3: Estás dejando dinero sobre la mesa con los mejores clientes Tu top 20% probablemente pagaría $80-100/mes sin chistar porque el ROI es evidente: si un recordatorio automático evita una ausencia, y una consulta vale $50-150, con 3-4 ausencias evitadas por mes ya recuperaron el costo del plan. Pero vos nunca les diste la oportunidad de pagarte más.

Por qué el 8% de churn es una señal de mala segmentación, no de mal producto

Un churn del 8% mensual equivale a perder casi el 65% de tu base en un año. Eso no es un problema de producto, es un problema de fit precio-cliente. Estás adquiriendo clientes que nunca debieron entrar al plan que tienen, o que deberían haber entrado a uno más barato primero.

2. PROPUESTA DE ESTRUCTURA DE PRICING

Modelo recomendado: 3 tiers + variable en mensajes

La métrica de expansión natural de tu negocio son los recordatorios de WhatsApp (directo a costo variable) y la cantidad de profesionales (proxy de tamaño del consultorio). Usá ambas como ejes de diferenciación.

TIER 1 — "Solo" → $19/mes

Para el profesional independiente que trabaja solo y quiere digitalizar su agenda sin complicaciones.

| Qué incluye | Límite | |---|---| | Agenda online | 1 profesional | | Recordatorios WhatsApp | 100 mensajes/mes incluidos | | Historial de pacientes | Hasta 80 pacientes activos | | Reportes básicos | Ocupación mensual simple | | Soporte | Email, 48hs |

Mensajes adicionales: $0.05/mensaje (markup sobre tu costo de $0.02, margen del 60% en variable)

Por qué $19:

• Compite directamente con Agenda Pro ($29) pero con WhatsApp incluido → vos ganás en valor percibido
• Cubre tus costos: $8 infra + ~$2 WhatsApp (100 msgs × $0.02) = $10 de costo → margen bruto del 47% en el piso, que sube con mensajes adicionales
• Baja la barrera de entrada para capturar clientes que hoy se van a la competencia o no convierten

TIER 2 — "Consultorio" → $49/mes

Para el profesional que tiene recepcionista o comparte el espacio con otro colega y necesita coordinación real.

| Qué incluye | Límite | |---|---| | Agenda online | Hasta 3 profesionales | | Recordatorios WhatsApp | 400 mensajes/mes incluidos | | Historial de pacientes | Ilimitado | | Reportes de ocupación | Completos + comparativos | | Gestión de recepcionista | Rol diferenciado con permisos | | Recordatorios de turno + confirmación | ✓ | | Soporte | Chat, 24hs |

Mensajes adicionales: $0.04/mensaje

Por qué $49:

• Mantenés el precio actual para el segmento que ya lo valida
• El cliente que hoy paga $49 y usa el producto intensamente se queda aquí y siente que ahora el precio tiene sentido (tiene límites claros que él cumple)
• El cliente que estaba en $49 y usaba poco migra al tier Solo → reducís su churn

TIER 3 — "Clínica" → $99/mes

Para clínicas o grupos de profesionales con volumen alto de pacientes y necesidad de gestión centralizada.

| Qué incluye | Límite | |---|---| | Agenda online | Hasta 8 profesionales | | Recordatorios WhatsApp | 1.000 mensajes/mes incluidos | | Historial de pacientes | Ilimitado | | Reportes avanzados | Por profesional, por especialidad, exportable | | Múltiples recepcionistas | Hasta 3 usuarios admin | | Integración básica con sistemas externos | API read-only | | Soporte | Prioritario, teléfono | | Onboarding dedicado | 1 sesión de setup |

Mensajes adicionales: $0.03/mensaje

Por qué $99:

• Posicionado debajo de MediTurno ($89... pero orientado a clínicas grandes), capturás el segmento medio que MediTurno ignora
• Tu top 20% (3+ profesionales, 500+ mensajes) debería estar aquí. Hoy te pagan $49 y probablemente mandan mensajes adicionales que no te están pagando o que absorbés en el plan
• El ROI para una clínica con 3 profesionales es inmediato: si cada uno tiene 20 pacientes/semana, el sistema se paga con 1-2 ausencias evitadas

Tabla resumen de tiers

                    SOLO          CONSULTORIO      CLÍNICA
Precio/mes          $19           $49              $99
Profesionales       1             3                8
Msgs incluidos      100           400              1.000
Msg adicional       $0.05         $0.04            $0.03
Pacientes           80            Ilimitado        Ilimitado
Recepcionista       ✗             ✓ (1)            ✓ (3)
Reportes            Básicos       Completos        Avanzados
Soporte             Email 48hs    Chat 24hs        Teléfono

Ancla de precio anual

Ofrecé 2 meses gratis pagando anual (equivale a ~17% de descuento):

• Solo anual: $190/año (vs $228 mensual)
• Consultorio anual: $490/año (vs $588)
• Clínica anual: $990/año (vs $1.188)

Esto reduce churn estructuralmente: un cliente anual tiene 12 meses para ver valor antes de tomar la decisión de irse.

3. JUSTIFICACIÓN POR TIER

Tier Solo ($19) — La puerta de entrada que hoy no existe

A quién apunta: Profesional independiente (médico, psicólogo, dentista) que trabaja solo, tiene entre 20-80 pacientes activos y probablemente viene de manejar su agenda en WhatsApp o en papel. Es el cliente que hoy te está abandonando o que directamente no convierte porque $49 le parece mucho.

Por qué $19: El precio tiene que ser una decisión fácil. A $19, el profesional no necesita "pensarlo": es menos que una consulta, menos que su café mensual en la clínica. La fricción de precio desaparece y el churn por "es caro" también.

Métrica limitante — mensajes y pacientes: El límite de 100 mensajes/mes es generoso para alguien con 50 pacientes (2 mensajes por paciente: recordatorio + confirmación). Pero si crece y empieza a mandar más, naturalmente migra al tier siguiente o paga adicionales. El límite de 80 pacientes activos es el gatillo de upgrade: cuando el profesional crece, el sistema le avisa que está cerca del límite y le muestra el valor del upgrade.

Riesgo a gestionar: Que clientes del tier Consultorio hagan downgrade. Mitigación: el límite de 1 profesional hace que sea imposible para consultorios reales. Un cliente con recepcionista no puede vivir en el tier Solo.

Tier Consultorio ($49) — El core del negocio

A quién apunta: El consultorio con 2-3 profesionales, una recepcionista que coordina la agenda, y un flujo de 150-400 pacientes/mes. Es el cliente que hoy tiene tu plan y está satisfecho, pero al que nunca le explicaste bien por qué vale $49.

Por qué $49: Porque ya lo validaste: 320 clientes pagan este precio. La diferencia es que ahora el cliente entiende exactamente qué está pagando. El tier tiene un nombre (Consultorio), tiene límites claros (3 profesionales, 400 mensajes) y tiene features que el tier Solo no tiene (recepcionista, reportes completos). El valor percibido sube aunque el precio no cambie.

Métrica limitante — profesionales: La cantidad de profesionales es el mejor proxy del tamaño del negocio y del valor que el sistema genera. Un consultorio con 3 profesionales tiene 3 veces más turnos, 3 veces más ausencias que evitar, 3 veces más ingresos en juego. El precio de $49 está justificado por ese multiplicador de valor.

Tier Clínica ($99) — El techo que hoy no existe

A quién apunta: Clínicas con 4-8 profesionales, múltiples especialidades, y necesidad de reportes por profesional para entender la rentabilidad del negocio. También captura al top 20% de tus clientes actuales que hoy está subpagando.

Por qué $99: Dos razones. Primera: tu top 20% manda 500+ mensajes/mes. Con el tier actual, si esos mensajes están incluidos en $49, estás perdiendo margen. Si los cobrarás extra, el cliente siente que lo estás penalizando por usar bien el producto. A $99 con 1.000 mensajes incluidos, el cliente power siente que tiene espacio para crecer sin sorpresas en la factura.

Segunda: posicionamiento competitivo. MediTurno cobra $89 y apunta a clínicas grandes. Vos a $99 sos "más completo que lo básico, más accesible que lo enterprise". Esa es una posición de mercado clara.

Métrica limitante — mensajes y profesionales: El límite de 1.000 mensajes/mes cubre holgadamente el uso actual del top 20% (500 msgs). Pero si una clínica crece a 1.500-2.000 mensajes, el costo adicional a $0.03/mensaje es predecible y justo. El cliente no siente que lo están castigando, siente que está pagando por lo que usa.

4. IMPACTO ESTIMADO EN MRR

Supuestos de migración (50% del total migra)

Distribución actual de 320 clientes (estimada por comportamiento de uso):

| Segmento | % base | Clientes | Tier natural | |---|---|---|---| | Bottom 30% (solo, poco uso) | 30% | 96 | Solo ($19) | | Middle 50% (uso moderado) | 50% | 160 | Consultorio ($49) | | Top 20% (uso intensivo) | 20% | 64 | Clínica ($99) |

Escenario: 50% migra al tier adecuado

Clientes que migran (160 clientes):

Bottom 30% que migra (50% de 96 = 48 clientes):
  Antes: 48 × $49 = $2.352/mes
  Después: 48 × $19 = $912/mes
  Impacto: -$1.440/mes

Top 20% que migra (50% de 64 = 32 clientes):
  Antes: 32 × $49 = $1.568/mes
  Después: 32 × $99 = $3.168/mes
  Impacto: +$1.600/mes

Middle 50% que migra (50% de 160 = 80 clientes):
  Se quedan en $49 → $0 de impacto directo en precio

Impacto neto inmediato en MRR:

-$1.440 (downgrades) + $1.600 (upgrades) = +$160/mes

Marginalmente positivo en el corto plazo. Pero ese no es el número importante.

El número que importa: impacto del churn reducido

Situación actual:

• Churn 8% mensual = 25-26 clientes perdidos/mes
• A $49 promedio = ~$1.250/mes perdido en MRR cada mes
• En 12 meses: perdés el equivalente a tu base entera y la tenés que reponer

Con el nuevo pricing, churn estimado por tier:

| Tier | Churn estimado | Justificación | |---|---|---| | Solo ($19) | 3-4% | Precio bajo reduce la fricción de salida, pero también el resentimiento | | Consultorio ($49) | 2-3% | Cliente con fit real al precio, ya validado | | Clínica ($99) | 1-2% | Cliente con alto ROI percibido, más embebido en el producto |

Churn promedio ponderado estimado: ~3% (vs 8% actual)

Clientes perdidos/mes actual: 25.6 (8% de 320)
Clientes perdidos/mes nuevo: 9.6 (3% de 320)
Clientes retenidos adicionales: 16/mes
A un valor promedio de $45/cliente = +$720/mes en retención

Acumulado en 12 meses: +$8.640 en MRR que antes se evaporaba

Asunto: 8 personas respondiendo "¿dónde está mi pedido?" — hay una mejor forma

Hola [Nombre],

Vi que [Empresa] está creciendo y me imagino que el equipo de soporte ya está sintiendo el peso de ese crecimiento.

El problema que vemos en casi todos los e-commerce de su tamaño: el 60-70% de los tickets son siempre las mismas preguntas — estado de pedido, devoluciones, políticas de envío. Preguntas que no necesitan a una persona, pero que igual consumen 8 personas.

En Ikilabs implementamos agentes de AI que resuelven esos tickets de forma autónoma, conectados directamente a tu plataforma de e-commerce y CRM. El agente consulta el pedido real del cliente y responde con datos precisos — no respuestas genéricas.

Resultado típico en los primeros 90 días:

• 60-70% de tickets resueltos sin intervención humana
• El equipo existente se enfoca en casos que realmente lo necesitan
• Sin reemplazar a Zendesk o Intercom, sino integrándose a lo que ya usás

No requiere cambiar tu stack actual.

¿Tenés 20 minutos esta semana para ver si tiene sentido para [Empresa]?

Martín Pérez Ikilabs · martín@ikilabs.com · +54 9 11 XXXX-XXXX

Copy Hero Section — Ikilabs

Iteraciones de Headline

(Te doy opciones para que elijas la dirección que más resuena)

Opción A — Enfocada en el diferenciador (prototipo rápido)

En dos semanas, código funcionando con tus datos.

Subheadline: La mayoría de consultoras te entrega un deck. Nosotros integramos agentes de AI y automatizaciones en tus sistemas actuales, y te mostramos resultados reales antes de que comprometas más presupuesto.

CTA: Arrancá con el Discovery

Opción B — Enfocada en el dolor (procesos que no escalan)

Tus procesos manuales tienen fecha de vencimiento.

Subheadline: Automatizamos las operaciones que hoy dependen de personas haciendo tareas repetitivas — sin reescribir tus sistemas desde cero. Prototipo con datos reales en dos semanas.

CTA: Hablemos de tu operación

Opción C — Enfocada en el fracaso previo con otras consultoras

Menos presentaciones. Más código que funciona.

Subheadline: Integramos LLMs y agentes de AI en los sistemas que ya usás. Empezamos con un discovery de una semana y en dos semanas tenés un prototipo corriendo con tus datos reales — no con mockups.

CTA: Ver cómo trabajamos

Opción D — Más técnica y directa

AI integrada en tus sistemas. Sin reescribir todo.

Subheadline: Conectamos modelos de lenguaje y agentes inteligentes a tu operación actual — soporte, logística, finanzas — y medimos el impacto antes de escalar. Discovery en una semana, prototipo en dos.

CTA: Empezá el Discovery

Mi recomendación

Opción A o D, dependiendo del momento de conciencia del visitante:

| Si el visitante llega... | Usá | |---|---| | Buscando una consultora de AI (ya sabe lo que quiere) | D — habla su idioma técnico | | Frustrado con procesos o consultoras anteriores | A — el contraste "deck vs. código" golpea directo | | Sin claridad de qué necesita exactamente | B — el dolor es inmediato y reconocible |

Nota sobre el CTA

"Arrancá con el Discovery" es el más fuerte porque:

• Nombra el primer paso concreto del proceso
• Reduce la fricción (no dice "contrátanos", dice "empecemos a ver")
• Filtra al cliente que ya entiende que necesita diagnóstico antes de solución

El bug que tardamos 3 semanas en reproducir (y 20 minutos en arreglar)

Estuvimos tres semanas depurando un bug en producción que perdía órdenes de forma aleatoria. Spoiler: "aleatorio" casi nunca significa aleatorio.

El problema era un race condition en el procesamiento paralelo de webhooks de Stripe. Cuando dos eventos llegaban simultáneamente para el mismo pedido, ambos workers procesaban en paralelo y el resultado era o un duplicado o un pisotón silencioso. La solución fue un lock distribuido con Redis — un SET NX con TTL de 30 segundos. Veinte minutos de implementación.

Lo que nos consumió las tres semanas fue reproducirlo en local. Un bug que ocurre "a veces" bajo carga concurrente no aparece cuando corres el servidor en tu máquina con un solo hilo.

La lección que nos quedó: cuando algo falla de forma intermitente, lo primero que revisamos ahora es si hay concurrencia involucrada.

La mayoría de las empresas que contratan consultores de AI terminan con un chatbot encima de ChatGPT y llaman a eso transformación digital.

El problema no es la tecnología. Es que nadie dentro de la empresa sabe con precisión qué problema está resolviendo.

Nosotros siempre arrancamos con la misma pregunta: "¿qué hace tu equipo hoy que no debería hacer un humano?" Esa sola pregunta elimina el 80% de los proyectos antes de escribir una línea de código.

Lo que funciona es concreto: automatizar tareas repetitivas específicas. No "mejorar la experiencia del cliente". Eso no es un proyecto, es un deseo.

Y cuando los proyectos fallan —casi siempre fallan por lo mismo— no es por el modelo elegido. Es por datos sucios, incompletos o que nadie había mirado bien antes de empezar.

La tecnología rara vez es el cuello de botella. El diagnóstico previo, casi siempre lo es.

Nuestra metodología

Trabajamos en cuatro etapas concretas, sin sorpresas en el camino.

Discovery (semana 1). Entrevistamos al equipo, mapeamos los procesos actuales e identificamos qué puede resolverse rápido y qué requiere un proyecto más largo. El cliente termina esta etapa con un diagnóstico claro, no con una presentación genérica.

Prototipo funcional (semanas 2-3). Construimos con datos reales del cliente, no con mockups. En dos semanas hay algo que se puede usar, evaluar y mostrar internamente. Esto permite ver el retorno potencial antes de comprometer más presupuesto.

Iteración antes de producción. Hacemos uno o dos ciclos de feedback y ajuste con el cliente. El producto no va a producción hasta que quien lo va a usar lo haya visto funcionar y aprobado los cambios.

Soporte post-lanzamiento incluido. Los primeros 30 días de soporte están incluidos en todos los proyectos, sin costo adicional. Si algo falla o necesita ajuste, lo resolvemos.

Texto traducido:

When two requests come in at the same time and both try to modify the same record, you have a concurrency problem. The most common solution is optimistic locking: instead of locking the record while you modify it, you store a snapshot of the current state and at write time you verify that nobody else modified it in the meantime.

In TypeORM, this is implemented with a version field on the entity. The UPDATE doesn't just filter by id — it also filters by version = :currentVersion. If the result affects 0 rows, someone else won the race — you throw an error and the client retries.

What tutorials rarely explain is when not to use optimistic locking: when contention is high (many users modifying the same record in rapid succession), you'll end up with a cascade of retries that can be worse than a pessimistic lock.

Notas sobre decisiones de traducción:

• "llegan al mismo tiempo" → "come in at the same time": más natural en inglés técnico que "arrive simultaneously"
• "guardás una versión del estado actual" → "you store a snapshot of the current state": "snapshot" captura mejor la idea que "version of the current state", que en inglés suena redundante
• "mientras tanto" → "in the meantime": más fluido que "meanwhile" en este contexto
• "ganó la carrera" → "won the race": el término "race" tiene resonancia técnica directa con race condition, lo que refuerza el concepto implícitamente
• "modificando el mismo registro seguido" → "modifying the same record in rapid succession": la frase original es coloquial; esta versión mantiene el significado con registro técnico apropiado