Especificación funcional y técnica de cómo un prospecto solicita una demo, cómo el equipo la aprueba desde el panel de administración y cómo se controla y mide el acceso a cada demo.

Fases del roadmap: Fase 1 — Funnel y solicitud de demos (núcleo), con extensiones en la Fase 2 y la Fase 3.

Páginas relacionadas:

• El recorrido del cliente está en Flujo del cliente.
• Las pantallas en detalle están en Panel de administración y Portal del cliente.
• El backend en general está en Backend y API.

Cómo leer esta página: objetivo, estado actual y problemas en la sección 1; plan detallado en las secciones 2 a 16; tareas en la 17; pruebas y riesgos en la 18 y la 19; métricas de éxito en la 20.

1. Objetivo y alcance: incluye estado actual y problemas que resuelve
2. Decisiones de diseño
3. Actores, roles y permisos
4. Modos de acceso
5. Modelo de datos
6. Estados y transiciones
7. Secuencias
8. API
9. Rutas web
10. Control de acceso a las demos
11. Notificaciones y plantillas
12. Jobs programados
13. Analítica
14. Datos personales (Ley 1581 de 2012)
15. Controles anti-abuso
16. Casos borde
17. Plan de implementación y tareas
18. Plan de pruebas
19. Riesgos y mitigaciones
20. Métricas de éxito

Objetivo: convertir el interés en conversaciones comerciales medibles.

• Cualquier visitante puede pedir una demo en un minuto.
• El equipo decide en menos de 1 día hábil.
• El prospecto entra con un clic.
• KopTup sabe qué demo usó, cuánto tiempo y qué le interesó.
• El acceso se decide siempre en el servidor.

Relación con el reposicionamiento RAG. El producto principal son los sistemas RAG (ver Visión de producto y Sistemas RAG), y en ese camino la demo del asistente es pública: no pide registro y tiene la opción "Prueba con tu documento".

/demo/chatbot es publico y no pasa por este flujo. La demo con el documento de ejemplo se abre sin cuenta. Para subir un documento propio, el visitante da solo su email y la autorización de tratamiento de datos (Ley 1581 de 2012); ese email entra como lead con origen demo-rag, y el documento se borra a la hora. Límites, tope de gasto, variables y cumplimiento en Reposicionamiento RAG. El catálogo de demos con accessMode (publico, solicitud, privado) que define esta página aplica al resto de las demos: las "Otras soluciones a medida" y las demos privadas de salud.

El sistema de demos:

• Controla el acceso a las "Otras soluciones a medida" que estén en modo solicitud y a las demos privadas de salud (cuentas médicas, sistema experto).
• Acompaña la venta RAG: demo guiada, preparación del Piloto y, en la Fase 2, un acceso ampliado con más cupo y datos del sector del cliente.
• Unifica todos los leads en un solo modelo, venga de donde venga: el formulario de contacto, "Prueba con tu documento" o una solicitud de demo.

Lo que existe hoy en main (producción) para pedir, dar y medir el acceso a las demos. Estado al 8 de octubre de 2026.

1. El interés no se captura. Un visitante que quiere ver una demo a fondo solo encuentra un formulario de contacto genérico que, además, pierde el producto y el plan que traía preseleccionados (Contacto).
2. Nadie sabe quién usa qué demo. No hay eventos de uso: el comercial no sabe si el prospecto abrió la demo, cuánto tiempo la usó ni qué módulos vio, y llama a ciegas.
3. El acceso no se puede gobernar. Un código común no tiene dueño, vigencia ni revocación, así que no sirve para administrar demos con backend real (salud) o con costo de IA. El acceso debe decidirse en el servidor y por persona.
4. Leads duplicados y sin dueño. El mismo email puede llegar por contacto, por la demo RAG y por una cotización sin unirse, sin etapa, responsable ni plazo de respuesta.
5. Sin prueba del consentimiento (Ley 1581 de 2012) para contactar y hacer seguimiento.
6. Sin roles para el equipo comercial ni para el prospecto, y el paso de prospecto a cliente con proyecto es manual.
7. Promesas sin respaldo: "Agendar llamada" abre el correo (mailto:) en lugar de una agenda real.

El diseño detallado que resuelve estos problemas ocupa las secciones 2 a 16; las tareas están en la sección 17 y las métricas de éxito en la sección 20.

Se compararon tres diseños: uno mínimo, uno centrado en seguridad y uno centrado en la operación comercial. Esta tabla recoge lo que se eligió y por qué.

Matriz de permisos. Vive en apps/backend/src/config/permissions.ts y se aplica con requirePermission('<permiso>') en middleware/auth.ts. Siempre se verifica en el servidor; la interfaz solo oculta botones.

El modo de cada demo (accessMode) vive en la base de datos y se cambia desde Admin › Catálogo de demos sin desplegar.

Excepción fija: chatbot (Sistemas RAG). Su modo es publico y no se cambia a solicitud ni a privado: es el destino de la pauta y de todos los CTA "Probar la demo". "Prueba con tu documento" no usa grants, cuentas ni el formulario de solicitud: pide email y autorización Ley 1581 y tiene sus propios límites (5 MB, 30 páginas, 10 preguntas por documento, 3 documentos por IP al día, borrado a la hora y tope DEMO_MONTHLY_BUDGET_USD). Ver Reposicionamiento RAG. La tabla de abajo y el resto de esta sección aplican a las demás demos.

Son valores de partida. La página de cada producto puede recomendar otro (ver Catálogo de productos).

En total: 20 demos publico, 6 solicitud y 2 privado, es decir, las 28 rutas de apps/web/src/app/demo/.

Notas sobre la semilla:

• Las ofertas qa-automatizado-ia y vpn-empresarial hoy no tienen demo propia y no se les asigna ninguna. Si se construye la demo propuesta en su página (ver QA automatizado con IA), se agrega a la semilla.
• Una versión anterior de la página del chatbot proponía solicitud. Con el reposicionamiento RAG, la demo del asistente es pública (sin registro) y la página Sistemas RAG ya lo refleja. Un grant del chatbot solo sirve para el acceso ampliado de la Fase 2 (más cupo y un bot con la marca del prospecto en el Builder).
• cuentas-medicas se presenta como "Sistema experto para salud" (su código no usa búsqueda vectorial). La rama rag-reposicionamiento la enlaza desde /rag/salud y desde el inicio con un enlace directo a la demo; cuando se active este control de acceso, esos enlaces llevan a la vista previa con "Solicitar demo personalizada", porque la demo es privado.

Todos los modelos son colecciones Mongoose en apps/backend/src/models/. Los nombres de campo van en inglés (como el código actual) y los valores de estado en español (como fija la DECISIÓN 4).

erDiagram
  Lead ||--o{ Contact : "agrupa mensajes"
  Lead ||--o{ ConsentRecord : "otorga"
  Lead ||--o{ LeadActivity : "registra"
  Lead ||--o{ DemoRequest : "envía"
  Lead |o--o| User : "se vuelve cuenta"
  Lead ||--o{ OutboundMessage : "recibe"
  Lead ||--o{ Quote : "recibe"
  DemoRequest }o--|{ DemoCatalogItem : "pide"
  DemoRequest ||--o{ DemoGrant : "origina"
  DemoCatalogItem ||--o{ DemoGrant : "habilita"
  User ||--o{ DemoGrant : "tiene"
  DemoGrant ||--o{ DemoEvent : "genera"
  User ||--o{ MagicLinkToken : "recibe"
  User ||--o{ AuditLog : "realiza"
  DemoGrant }o--o| Quote : "cierra con"
  Quote |o--o| Project : "origina"
  User ||--o{ Project : "es cliente de"

  User {
    objectid id PK
    string email UK
    string role "admin sales manager developer prospect client"
    string accountStatus "invitado activo suspendido"
    number tokenVersion
    objectid leadId FK
  }
  Lead {
    objectid id PK
    string email UK
    string company
    string stage
    number score
    string grade "A B C D"
    objectid ownerId FK
    objectid userId FK
  }
  Contact {
    objectid id PK
    objectid leadId FK
    string source "contacto demo_rag"
    string message
    string status
  }
  ConsentRecord {
    objectid id PK
    objectid leadId FK
    string policyVersion
    string textHash
    boolean marketing
    date grantedAt
  }
  LeadActivity {
    objectid id PK
    objectid leadId FK
    string type
    date dueAt
    date doneAt
  }
  DemoCatalogItem {
    objectid id PK
    string slug UK
    string demoSlug
    string offeringSlug
    string accessMode "publico solicitud privado"
    boolean active
    number defaultDurationDays
  }
  DemoRequest {
    objectid id PK
    string code UK
    objectid leadId FK
    string status
    objectid assignedTo FK
    number scoreAtSubmit
    date slaDueAt
  }
  DemoGrant {
    objectid id PK
    objectid userId FK
    objectid demoRequestId FK
    string catalogSlug FK
    string mode "guiada autoservicio"
    string status
    date expiresAt
  }
  DemoEvent {
    objectid id PK
    objectid grantId FK
    string catalogSlug
    string sessionId
    string type
    date at
  }
  MagicLinkToken {
    objectid id PK
    string tokenHash UK
    objectid userId FK
    string purpose "invitacion acceso"
    date expiresAt
    date usedAt
  }
  AuditLog {
    objectid id PK
    objectid actorId FK
    string action
    string entityType
    objectid entityId
    date at
  }
  OutboundMessage {
    objectid id PK
    objectid leadId FK
    string channel
    string templateKey
    string status
    string idempotencyKey UK
  }
  Quote {
    objectid id PK
    string number UK
    objectid leadId FK
    string currency "COP USD"
    number total
    string status
  }
  Project {
    objectid id PK
    objectid client_id FK
    objectid quoteId FK
    string status
  }

Ver diagrama como imagen

DemoCatalogItem: una entrada por cada ruta /demo/<demoSlug>, 28 en la semilla.

Lead: una persona interesada (deduplicada por email).

DemoRequest: cada envío del formulario, o pedido desde el portal.

Índices: {code} único, {status, slaDueAt}, {assignedTo, status}, {leadId}.

DemoGrant: un acceso de un usuario a una demo.

Índices:

• Único parcial {userId, catalogSlug} cuando status ∈ {activo, por_expirar}: un solo acceso vigente por demo.
• {status, expiresAt}.

DemoEvent: eventos de uso, sin datos personales.

Retención: TTL de 13 meses; los eventos anónimos, 180 días.

MagicLinkToken

AuditLog: solo se agregan registros; nunca se editan ni se borran. Retención de 5 años.

Modelos de soporte

• apps/backend/src/scripts/seed-demo-catalog.ts
  • Lee apps/backend/src/data/demo-catalog.seed.json con los 28 ítems de la tabla de la sección 4.
  • Hace upsert por slug. No pisa los cambios hechos desde el panel, salvo con --force.
• apps/backend/src/scripts/migrate-roles.ts
  • Pasa user a client si la cuenta tiene Project u Order, y a prospect en los demás casos.
  • Crea un Lead para cada cuenta.
  • Es idempotente y tiene modo --dry-run.
• apps/backend/src/scripts/backfill-leads.ts
  • Crea los Lead a partir de los Contact históricos, deduplicados por email, con source.channel = contacto.
• El fallback estático apps/web/src/lib/demo-access.ts se genera desde la misma semilla, con un script en apps/web/scripts/, para que el middleware y el sitemap usen los mismos modos.

El puntaje lo calcula services/lead-scoring.service.ts. Es una función pura, sus pesos están en config/scoring.ts y guarda el desglose de cada regla.

Grados: A ≥ 65, B 45–64, C 25–44 y D menos de 25. Los pesos se revisan cada mes contra los cierres reales.

El SLA de primera respuesta lo calcula services/sla.service.ts. Cuenta horas hábiles en Bogotá: lunes a viernes de 8:00 a 17:00, sin festivos de Colombia.

Qué cuenta como primera respuesta: aprobar, rechazar o registrar un contacto manual (llamada o email). El acuse automático no cuenta.

Alertas del plazo:

• Al 75 % se avisa al responsable.
• Al vencer se marca slaBreached, se avisa al admin y la solicitud sube al inicio de la bandeja.

Todas las transiciones pasan por un único servicio, services/demo-state.service.ts:

• Usa findOneAndUpdate condicionado al estado de origen; una transición no permitida responde 409.
• Cada transición queda en history y en AuditLog.

stateDiagram-v2
  [*] --> pendiente: formulario enviado
  pendiente --> en_revision: asignar o abrir
  en_revision --> aprobada: aprobar y crear accesos
  en_revision --> rechazada: rechazar con motivo
  rechazada --> en_revision: reabrir, solo admin
  aprobada --> [*]
  rechazada --> [*]

Ver diagrama como imagen

• Aprobar o rechazar desde pendiente también está permitido: el servicio registra un paso implícito por en_revision en history, así el flujo de la DECISIÓN 4 se mantiene.
• Spam y duplicadas son motivos de rechazo, no estados aparte.
• Una solicitud aprobada no se reabre. Para dar más demos se usa una invitación directa o una solicitud nueva.

stateDiagram-v2
  [*] --> activo: aprobar o invitar
  activo --> por_expirar: faltan 3 días
  por_expirar --> activo: extender
  por_expirar --> expirado: vence
  activo --> expirado: vence sin aviso previo
  expirado --> activo: extender, hasta 30 días después
  activo --> revocado: revocar con motivo
  por_expirar --> revocado: revocar con motivo
  activo --> convertido: convertir
  por_expirar --> convertido: convertir
  expirado --> convertido: convertir
  revocado --> [*]
  convertido --> [*]

Ver diagrama como imagen

Reglas:

• Vigencia. demo-access permite entrar con activo o por_expirar mientras ahora < expiresAt. Con convertido, al convertir se fija expiresAt = max(expiresAt, ahora + 90 días).
• Extender suma días a max(expiresAt, ahora) y reinicia notices.
• Pasado el límite. Un acceso que lleva más de 30 días en expirado no se extiende: hace falta una solicitud nueva.
• Estados finales. revocado y convertido son finales. Para volver a dar acceso se crea un grant nuevo; el índice único parcial lo permite.

stateDiagram-v2
  [*] --> nuevo
  nuevo --> calificado: solicitud aprobada o contacto del comercial
  nuevo --> perdido: spam o fuera de perfil
  calificado --> en_demo: primer acceso a una demo
  en_demo --> propuesta: pide propuesta o el comercial la envía
  propuesta --> negociacion: pide ajustes
  propuesta --> ganado: acepta y paga anticipo
  negociacion --> ganado: acepta y paga anticipo
  negociacion --> perdido: descarta
  propuesta --> perdido: rechaza
  calificado --> nutricion: sin respuesta
  en_demo --> nutricion: el acceso expira sin interés
  nutricion --> calificado: vuelve a interactuar
  nutricion --> perdido: descarta o 6 meses sin actividad
  ganado --> [*]
  perdido --> [*]

Ver diagrama como imagen

• Cada cambio de etapa crea un LeadActivity de tipo cambio_estado.
• Un Lead perdido puede volver a nuevo si envía una solicitud nueva.

sequenceDiagram
  autonumber
  participant V as Visitante
  participant W as Web Next
  participant T as Turnstile
  participant A as API backend
  participant D as MongoDB
  participant O as Outbox y jobs
  participant E as Equipo comercial
  V->>W: Llena Solicitar demo y acepta la autorización Ley 1581
  W->>A: POST /api/demo-requests con el token del captcha
  A->>T: Verifica token, hostname y acción
  T-->>A: Resultado
  A->>A: Honeypot, tiempo mínimo, esquema zod, rate-limit y riesgo del email
  alt Captcha inválido o email desechable
    A-->>W: 400 o 422 con mensaje para corregir
  else Datos válidos
    A->>D: Upsert del Lead por email y ConsentRecord
    A->>D: Busca una solicitud abierta del mismo email en los últimos 30 días
    alt Ya existe
      A->>D: Suma los productos y registra en history
    else No existe
      A->>D: Crea DemoRequest pendiente con puntaje, grado y slaDueAt
    end
    A->>D: Programa acuse y aviso interno en OutboundMessage
    A-->>W: 201 con el código de la solicitud
  end
  W-->>V: Página de gracias con el código y Agendar llamada
  O->>D: Toma los mensajes programados
  O-->>V: Email de acuse
  O-->>E: Email, aviso en el panel y WhatsApp si es grado A o B

Ver diagrama como imagen

sequenceDiagram
  autonumber
  participant C as Comercial
  participant AW as Admin web
  participant A as API backend
  participant D as MongoDB
  participant O as Outbox y jobs
  participant P as Prospecto
  participant W as Web Next
  C->>AW: Elige demos, 14 días, modo y mensaje
  AW->>A: POST /api/demo-requests/:id/approve
  A->>A: Verifica el permiso del rol y el modo de cada demo
  alt Demo privada y el rol no es admin
    A-->>AW: 403 Requiere administrador
  else Permitido
    A->>D: Inicia transacción
    A->>D: Solicitud a aprobada solo si está pendiente o en_revision
    alt La solicitud ya cambió de estado
      A-->>AW: 409 Ya fue procesada
    else Estado correcto
      A->>D: Busca o crea User prospect en estado invitado
      A->>D: Crea o extiende un DemoGrant por demo
      A->>D: Crea MagicLinkToken con hash y vigencia de 72 h
      A->>D: Lead a calificado, AuditLog y OutboundMessage de invitación
      A->>D: Confirma la transacción
      A-->>AW: 200 con los accesos creados
    end
  end
  O-->>P: Email con el botón Activar mi acceso
  P->>W: Abre /acceso/activar con el token
  W->>A: POST /api/auth/magic-link/check
  A-->>W: Nombre y email enmascarado, sin consumir el token
  P->>W: Crea su contraseña y pulsa Activar
  W->>A: POST /api/auth/magic-link/consume
  A->>D: Marca usedAt solo si está vacío y no venció
  A->>D: User a activo
  A-->>W: Sesión iniciada
  W-->>P: Redirige a /dashboard/demos
  A->>O: Aviso al comercial de que el prospecto activó su acceso

Ver diagrama como imagen

sequenceDiagram
  autonumber
  participant N as Navegador
  participant M as Middleware Next
  participant P as Ruta /api/demo-pass
  participant B as API backend
  participant D as MongoDB
  N->>M: GET /demo/erp
  M->>M: Modo de la demo, desde caché de 60 s o mapa estático
  alt Modo publico
    M-->>N: Muestra la demo con banner
  else Modo solicitud o privado
    M->>M: Verifica la cookie de pase con jose
    alt Pase válido para erp
      M-->>N: Muestra la demo con barra de acceso
    else Sin pase y con sesión
      M-->>N: 302 a /api/demo-pass con slug y ruta de regreso
      N->>P: GET /api/demo-pass
      P->>B: GET /api/demo-access/erp con el token de sesión
      B->>D: Catálogo activo y DemoGrant vigente según la hora actual
      B->>D: Guarda DemoEvent open o denied
      alt Acceso permitido
        B-->>P: allowed, grantId y expiresAt
        P-->>N: Cookie de pase httpOnly de 15 min y 302 a /demo/erp
        N->>M: GET /demo/erp con el pase
        M-->>N: Muestra la demo con barra de acceso
      else Acceso denegado
        B-->>P: allowed false y motivo
        P-->>N: 302 a /demo/acceso con el motivo
      end
    else Sin sesión
      M-->>N: 302 a /demo/acceso con motivo sin_sesion
    end
  end
  loop Cada 5 min y al volver a la pestaña
    N->>P: Renueva el pase en modo json
    P->>B: GET /api/demo-access/erp
    B-->>P: Decisión actual
    P-->>N: Pase renovado o bloqueo de la pantalla
  end

Ver diagrama como imagen

sequenceDiagram
  autonumber
  participant J as Job grant-lifecycle
  participant D as MongoDB
  participant O as Outbox
  participant P as Prospecto
  participant C as Comercial
  participant A as API backend
  loop Cada hora
    J->>D: Toma el lease en JobRun
    J->>D: Busca accesos activos que vencen en 3 días o menos y sin recordatorio
    J->>D: Pasa a por_expirar y fija reminderSentAt de forma condicionada
    J->>O: Programa expiring_3d al prospecto y aviso al comercial
    J->>D: Busca accesos con expiresAt vencido en activo o por_expirar
    J->>D: Pasa a expirado y fija expiredNotifiedAt
    J->>O: Programa el email expired y la tarea cerrar o nutrir
  end
  O-->>P: Email Tu acceso vence en 3 días
  O-->>C: Aviso en el panel
  opt El prospecto pide más tiempo
    P->>A: POST /api/me/demos/:grantId/actions con tipo extension
    A->>O: Aviso al comercial
    C->>A: POST /api/demo-grants/:id/extend con 7 días y motivo
    A->>D: Nuevo expiresAt, estado activo, avisos reiniciados y AuditLog
    A->>O: Programa el email extension_approved
    O-->>P: Email Extendimos tu acceso
  end
  Note over J,D: La vigencia se evalúa en tiempo real en demo-access. El job solo cambia etiquetas y avisa

Ver diagrama como imagen

• Rutas nuevas en apps/backend/src/routes/, con un controlador por recurso en controllers/ y la lógica en services/. Se registran en src/index.ts igual que las rutas actuales.

• Validación con zod (ya es dependencia).

• Errores con el formato actual { success, message, code? }:

  Código	Cuándo
  400	Validación
  401	Sin sesión
  403	Sin permiso
  404	No existe
  409	Transición no permitida o estado ya cambiado
  422	Regla de negocio (demo desactivada, email desechable, extensión fuera de plazo)
  429	Rate-limit

• Las llamadas servidor a servidor desde Next (/api/demo-pass → /api/demo-access):

  • llevan una cabecera interna con un secreto compartido (INTERNAL_API_KEY);
  • se limitan por usuario, porque todas llegan desde las IP de Vercel.

• Toda escritura del equipo queda en AuditLog.

En Panel de administración y Portal del cliente está el detalle de columnas, filtros y estados vacíos de cada pantalla.

Landing de producto (/productos/<slug>). CTA principal "Solicitar demo" y secundario "Agendar llamada".

Formulario Solicitar demo. Campos de la DECISIÓN 3, selección múltiple de productos, consentimiento Ley 1581 y captcha.

Confirmación (/solicitar-demo/gracias).

Demo sin acceso (/demo/acceso).

Email de invitación con enlace mágico (640 px de ancho).

Portal › Mis demos (/dashboard/demos).

Admin › Solicitudes de demo (/admin/solicitudes).

Admin › Detalle de solicitud (/admin/solicitudes/[id]), con los paneles Aprobar y Rechazar.

Admin › Accesos a demos (/admin/accesos).

Admin › Catálogo de demos (/admin/catalogo-demos).

Admin › Métricas (/admin/metricas).

flowchart TD
  R["Petición a /demo/slug"] --> M1{"Modo de la demo"}
  M1 -->|"publico"| OK1["Muestra la demo con banner"]
  M1 -->|"solicitud o privado"| C1{"¿Pase válido en cookie httpOnly?"}
  C1 -->|"Sí"| OK2["Muestra la demo con barra de acceso"]
  C1 -->|"No"| S1{"¿Hay sesión?"}
  S1 -->|"No"| X1["/demo/acceso: vista previa, solicitar o iniciar sesión"]
  S1 -->|"Sí"| P1["/api/demo-pass consulta GET /api/demo-access"]
  P1 --> D1{"Respuesta del backend"}
  D1 -->|"allowed"| K1["Emite el pase de 15 min y vuelve a la demo"]
  K1 --> OK2
  D1 -->|"denegado"| X2["/demo/acceso con motivo: sin_acceso, expirado, revocado, privado, desactivada"]
  D1 -->|"error o timeout"| X3["Falla cerrada: /demo/acceso con motivo no_disponible"]

Ver diagrama como imagen

Reglas de evaluateAccess (services/demo-access.service.ts), en este orden:

1. La demo no existe en el catálogo → 404 no_existe.
2. El usuario es staff (admin, sales, manager, developer) → permitido (staff).
3. active = false → denegado (desactivada).
4. accessMode = publico → permitido (publico). Si hay un grant vigente, se devuelve su grantId para medir el uso.
5. Sin sesión → denegado (sin_sesion).
6. La cuenta está invitado o suspendido → denegado (cuenta_inactiva).
7. Hay un grant activo, por_expirar o convertido y ahora < expiresAt → permitido (grant).
8. Hay un grant expirado o con expiresAt vencido → denegado (expirado, con puedeExtender si no han pasado 30 días).
9. Hay un grant revocado → denegado (revocado).
10. En cualquier otro caso → denegado (privado o sin_acceso, según el modo).

Archivos: apps/web/middleware.ts, apps/web/src/lib/demo-access.ts, apps/web/src/app/api/demo-pass/route.ts. Dependencia nueva: jose.

Las maquetas cargan sus datos simulados en el bundle público. Por eso el control de una maqueta es comercial, no de confidencialidad, y no deben tener datos reales ni sensibles. Lo valioso (IA, datos y motores reales) vive detrás de APIs que exigen acceso.

requireDemoGrant('<slug>') es un middleware Express nuevo (middleware/requireDemoGrant.ts) que reutiliza evaluateAccess:

• Dónde se aplica: en las rutas del backend que usan las demos solicitud y privado con backend real. Son:
  • cuentas médicas: auditoria.routes.ts, documentoConocimientoConfig.routes.ts y la búsqueda de cups.routes.ts, que son las rutas que consume apps/web/src/app/demo/cuentas-medicas/api.ts;
  • el sistema experto: expert-system.routes.ts;
  • la generación de LinkedIn Ads: apps/web/src/app/api/linkedin-ads/generate/route.ts, que verifica el pase o consulta demo-access;
  • cuentas.routes.ts y liquidacion.routes.ts, si se confirma que solo las usan estas demos.
• Staff: siempre pasa.
• Antes de aplicarlo: confirmar que ninguna función pública del sitio usa esas rutas.
• El chatbot RAG es publico: no exige grant. Mantiene sus cupos por IP y por documento y el tope de gasto mensual (DEMO_MONTHLY_BUDGET_USD), hechos en la rama rag-reposicionamiento (pendiente de merge). Un grant solo aumenta el cupo (Fase 2).
• Demos con IA: cupo diario por acceso (quotas.aiActionsPerDay) y apagado de emergencia (active = false).

Hoy el catálogo /demo abre la demo de cuentas médicas con un código de acceso fijo. Ese mecanismo se retira en la misma entrega que activa el control nuevo:

1. Sembrar el catálogo con cuentas-medicas y sistema-experto en modo privado.
2. Desplegar el backend: demo-access, requireDemoGrant e invitación directa.
3. Desplegar la web: middleware, /api/demo-pass, /demo/acceso y DemoAccessShell. El cambio va detrás de la variable DEMO_GATE_ENABLED para poder revertirlo sin desplegar.
4. En apps/web/src/app/demo/page.tsx:
   • eliminar el estado del modal, la validación del código y el modal;
   • la tarjeta pasa a "Con invitación" y su botón a "Solicitar demo personalizada".
5. Eliminar las claves demos.accessModal.* de apps/web/messages/es.json y en.json.
6. Invitar por invitación directa (POST /api/demo-grants) a quienes hoy usan el código, para que cada uno reciba su acceso personal y medido.
7. Activar DEMO_GATE_ENABLED=true y verificar con la prueba e2e de la sección 18.

Dónde viven:

• Todo mensaje pasa por OutboundMessage y lo envía el job outbox-dispatcher.
• Las plantillas de la Fase 1 están en código, en apps/backend/src/templates/demo/, en español con "tú".
• En la Fase 2 se podrán editar desde el panel.

Envío:

• Email: con el transporte actual de email.service.ts, al que se agrega sendTemplate. Antes de lanzar se recomienda un proveedor transaccional con SPF, DKIM y DMARC del dominio.
• WhatsApp: usa whatsapp.service.ts.
  • Al equipo, mensajes libres y sin datos de contacto del prospecto.
  • Al prospecto, solo si autorizó WhatsApp y con plantillas aprobadas por Meta (P2).

Reglas de envío:

• Máximo 1 mensaje comercial por lead al día.
• Horario de 8:00 a 19:00 (hora de Bogotá).
• Las secuencias se detienen si el prospecto agenda, pide propuesta, se da de baja o el acceso se revoca o se convierte.

Variables disponibles en todas las plantillas: {{nombre}}, {{empresa}}, {{producto}}, {{demos}}, {{codigo}}, {{expiraEl}}, {{dias}}, {{comercial}}, {{agendaUrl}}, {{misDemosUrl}}, {{politicaUrl}}, {{bajaUrl}}. Todo texto que venga del usuario se escapa.

demo_request_received: email al solicitante, inmediato.

Asunto: Recibimos tu solicitud de demo ({{codigo}})

Hola {{nombre}}:

Recibimos tu solicitud para conocer {{productos}}. Un especialista de KopTup la revisará y te responderá en máximo 1 día hábil (lunes a viernes, de 8:00 a. m. a 5:00 p. m., hora de Colombia).

Mientras tanto puedes:

• Probar ya la demo pública del asistente RAG: {{demoPublicaUrl}}
• Agendar una llamada de 30 minutos: {{agendaUrl}}

Tu código de solicitud es {{codigo}}. Si no hiciste esta solicitud, ignora este mensaje.

Equipo KopTup · Tratamos tus datos según nuestra política: {{politicaUrl}}

demo_request_internal: email y aviso en el panel para el equipo.

Asunto: [{{grado}}] Nueva solicitud {{codigo}} · {{empresa}}

{{nombre}} ({{cargo}}), {{empresa}}. {{pais}}, {{tamano}} personas. Productos: {{productos}} · Urgencia: {{urgencia}} · Prefiere: {{modoPreferido}} Caso de uso: {{casoDeUso}} (primeros 300 caracteres) Puntaje: {{puntaje}} ({{grado}}) · Responder antes de: {{slaDueAt}} Revisar: {{adminUrl}}

WhatsApp al equipo (sin email ni teléfono del prospecto):

Nueva solicitud {{codigo}} ({{grado}}): {{empresa}}, {{productos}}. Responder antes de las {{slaHora}}. {{adminUrl}}

demo_invite_autoservicio: aprobación con enlace mágico.

Asunto: Tu acceso a la demo de {{producto}} está listo

Hola {{nombre}}:

Aprobamos tu acceso a: {{demos}}. Podrás usarlas hasta el {{expiraEl}} ({{dias}} días).

[Activar mi acceso] (enlace válido por 72 horas y de un solo uso)

Qué sigue:

1. Activa tu cuenta y crea tu contraseña. Toma un minuto.
2. Entra a Mis demos y sigue el recorrido guiado.
3. Cuando quieras, agenda una llamada con {{comercial}}: {{agendaUrl}}

{{mensajeProspecto}}

¿El botón ya no funciona? Pide uno nuevo aquí: {{enlaceNuevoUrl}} Las demos usan datos simulados. No cargues información confidencial.

demo_invite_guiada: igual que la anterior, más:

Tu sesión guiada con {{comercial}} es el {{fechaSesion}} ({{duracion}} minutos): {{enlaceReunion}}. Agrégala a tu calendario: {{icsUrl}}

demo_new_access: para quien ya tiene cuenta.

Asunto: Tienes nuevas demos en KopTup

Hola {{nombre}}: habilitamos {{demos}} hasta el {{expiraEl}}. Entra con tu cuenta de siempre: {{misDemosUrl}}

demo_rejected: opcional; nunca se envía si el motivo es spam o competidor.

Asunto: Sobre tu solicitud de demo en KopTup

Hola {{nombre}}:

Gracias por tu interés en {{producto}}. Por ahora no podemos habilitar esta demo para tu solicitud{{motivoAmable}}.

Igual puedes:

• Probar las demos abiertas: {{catalogoUrl}}
• Contarnos más de tu proyecto en una llamada: {{agendaUrl}}

Si tu situación cambia, responde este correo y retomamos.

{{motivoAmable}} según el motivo:

• fuera_de_perfil: ", porque está fuera del tipo de proyectos que hoy atendemos";
• datos_invalidos: ", porque no pudimos verificar tus datos de contacto";
• otro: el texto que escriba el comercial.

invite_reminder: 48 h sin activar.

Asunto: Tu acceso a {{producto}} te espera

Hola {{nombre}}: aún no activas tu acceso. Te enviamos un enlace nuevo, válido por 72 horas: [Activar mi acceso]. Si prefieres que te mostremos la demo en vivo, agenda aquí: {{agendaUrl}}

followup_d2_activo

Asunto: ¿Ya probaste {{accionClave}}?

Hola {{nombre}}: vimos que ya entraste a {{demo}}. Te recomendamos probar {{accionClave}}: es lo que más valoran empresas como la tuya. Si quieres, {{comercial}} te lo muestra en 20 minutos: {{agendaUrl}}

followup_d2_inactivo: reenvío del enlace, con el mismo texto de invite_reminder si no ha activado.

followup_d7

Asunto: Tu semana con {{demo}}

Hola {{nombre}}: llevas {{minutos}} minutos de uso y completaste {{pasos}} de {{totalPasos}} pasos del recorrido. ¿Hablamos de cómo se vería con tus datos? [Solicitar propuesta] · [Agendar llamada]

expiring_3d

Asunto: Tu acceso a la demo de {{demo}} vence el {{expiraEl}}

Hola {{nombre}}: te quedan 3 días de acceso. Hasta hoy usaste la demo {{minutos}} minutos y completaste {{pasos}} de {{totalPasos}} pasos del recorrido.

¿Cuál es tu siguiente paso? [Solicitar propuesta] · [Agendar llamada] · [Necesito más tiempo]

expired

Asunto: Terminó tu acceso a la demo de {{demo}}

Hola {{nombre}}: tu acceso terminó el {{expiraEl}}. Gracias por probar {{producto}}.

Si quieres avanzar: [Solicitar propuesta] · [Agendar llamada]. ¿Te faltó tiempo? [Pedir extensión] (disponible durante 30 días).

extension_approved

Asunto: Extendimos tu acceso a {{demo}}

Hola {{nombre}}: {{comercial}} extendió tu acceso hasta el {{expiraEl}}. Entra desde Mis demos: {{misDemosUrl}}

grant_revoked

Asunto: Actualización de tu acceso a {{demo}}

Hola {{nombre}}: tu acceso a la demo de {{demo}} quedó cerrado. Si crees que es un error o quieres retomarlo, responde este correo o agenda una llamada: {{agendaUrl}}

Avisos al comercial (panel y WhatsApp interno):

• first_access: "{{nombre}} ({{empresa}}) abrió {{demo}} por primera vez. Buen momento para llamar."
• prospect_action: "{{nombre}} pidió {{accion}} en {{demo}}. Plazo: {{dueAt}}."
• sla_warning: "La solicitud {{codigo}} vence su SLA a las {{hora}}."

WhatsApp al prospecto (P2; solo con su autorización y con plantilla aprobada por Meta):

• demo_listo: "Hola {{1}}, tu acceso a la demo de {{2}} está listo. Te enviamos el enlace de activación a {{3}}. Equipo KopTup."
• demo_por_vencer: "Hola {{1}}, tu acceso a {{2}} vence el {{3}}. ¿Agendamos una llamada? {{4}}"

Dónde viven: apps/backend/src/jobs/, con node-cron.

Cómo arrancan:

• Solo después de conectar a MongoDB y solo si JOBS_ENABLED=true.
• Antes de ejecutar, cada job toma un lease en JobRun, para que nunca corran dos copias.
• Todos son idempotentes: usan actualizaciones condicionadas y idempotencyKey.

Salud: se consulta en GET /api/admin/jobs/health. Si un job pasa más del doble de su intervalo sin correr, se alerta al admin.

Hay tres capas.

Eventos del embudo público:

• Ya implementados en la rama rag-reposicionamiento (pendiente de merge): generate_lead, demo_start, demo_upload, whatsapp_click, plan_click.
• Nuevos:
  • demo_request_open: abre el formulario.
  • demo_request_step1: completa el paso 1.
  • demo_request_submit: envía el formulario; también se envía como generate_lead con lead_source = demo_request.
  • schedule_call_click: pulsa "Agendar llamada".
  • demo_access_view: llega a la pantalla sin acceso, con motivo.
• Propiedades: product, plan, demo_slug, access_mode, source_page. Nunca datos personales.

Eventos de uso (DemoEvent.type):

Métricas del tablero (GET /api/metrics/demo-funnel):

Este diseño cumple las exigencias de la ley así. Debe validarlo un asesor legal; el texto de la política vive en Legal y en Comercial, marketing y legal.

Autorización previa, expresa e informada

• Casilla sin marcar, separada por finalidad:
  • obligatoria: gestionar la solicitud y el contacto comercial sobre ella;
  • opcional: recibir comunicaciones comerciales y de marketing;
  • opcional: recibir mensajes por WhatsApp.
• La prueba se guarda en ConsentRecord: versión de la política, hash del texto mostrado, fecha, IP en hash, user agent y canal.

Política de tratamiento

• Publicada y versionada en /privacy (apps/web/src/config/legal.ts, PRIVACY_POLICY_VERSION).
• Incluye responsable, finalidades, derechos, canal de atención y la transmisión internacional a proveedores de nube, correo e IA.

Derechos del titular

• Conocer, actualizar, rectificar, suprimir y revocar.
• Se ejercen desde Mis datos (/dashboard/privacidad) o por el canal de la política.
• Plazos legales, que se calculan en PrivacyRequest.dueAt con alerta al admin:
  • consultas: 10 días hábiles, prorrogables 5;
  • reclamos: 15 días hábiles, prorrogables 8.

Minimización

• No se piden datos sensibles.
• El formulario y las demos de salud avisan "no incluyas datos de pacientes ni información confidencial".
• Ni los logs ni los eventos guardan datos personales.
• Las IP se guardan en hash.

Retención propuesta

Supresión

• La acción Anonimizar Lead (solo admin) reemplaza los datos identificables y revoca los accesos (motivo supresion).
• Conserva solo lo necesario para demostrar la autorización y la atención de la solicitud.

Registro Nacional de Bases de Datos

• Evaluar con el asesor si KopTup está obligada a inscribirse ante la SIC.

"Prueba con tu documento" (demo pública del chatbot RAG)

• No usa el formulario de solicitud: pide solo el email y la casilla de autorización (sin marcar) con enlace a /privacy.
• Su ConsentRecord se guarda con canal demo_rag y el Lead queda con la finalidad "responder sobre el documento y contacto comercial". Mientras no exista el Lead unificado, la rama rag-reposicionamiento (pendiente de merge) deja la fecha de la autorización en el mensaje del lead demo-rag, y el backend rechaza la subida sin autorización.
• La política debe informar la transmisión internacional al proveedor de IA y que el documento se borra a la hora.
• El documento nunca se guarda en almacenamiento permanente y el Lead solo registra datos de uso (páginas, preguntas usadas), no el contenido.
• Detalle en Reposicionamiento RAG.

Son controles genéricos que se configuran por variables de entorno.

• Captcha Turnstile verificado en el servidor, incluidos el hostname y la acción.
• Honeypot oculto y tiempo mínimo de llenado.
• Rate-limit con almacén compartido, para que funcione con varias instancias:
  • por IP y por email en las solicitudes;
  • por email en "Enviarme un enlace nuevo";
  • por usuario en demo-access y en los eventos.
• Riesgo del email: lista actualizable de dominios desechables y consulta de MX con timeout.
• Respuestas uniformes en los endpoints públicos relacionados con cuentas, para que no se pueda averiguar qué emails existen.
• Aprobación humana obligatoria en solicitud y privado. Es la barrera más fuerte.
• Demos con IA: cupo por acceso, tope global de gasto y apagado de emergencia por demo.
• Cuentas compartidas:
  • máximo 3 sesiones activas por prospecto;
  • alerta si un acceso se usa desde muchas redes distintas;
  • la barra muestra la empresa del prospecto, lo que desincentiva compartir la cuenta.
• Texto libre guardado como texto plano y escapado en el panel y en los emails.
• Prerrequisito (Fase 0): auditar y exigir autenticación y autorización en servidor en todas las rutas de la API, rotar credenciales y actualizar dependencias. Ver Seguridad y calidad.

Tallas para 1 dev senior: S ≤ 2 días · M 3–5 días · L 1–2 semanas · XL más de 2 semanas. Prioridad: P0 bloquea la salida · P1 alta · P2 media.

Prerrequisitos de la Fase 0 (ver Seguridad y calidad y Roadmap):

• autorización en servidor en toda la API;
• rotación de credenciales;
• CI funcionando con Jest para TypeScript;
• dependencias actualizadas.

Pasar la sesión a cookies httpOnly es P1 y no bloquea este sistema.

Hito 1a (tareas P0, de la 1 a la 28 salvo la 8): unos 60 días-dev.

Hito 1b (tareas P1: 8 y 29–33): unas 4 semanas más para 1 dev.

Las variables de la demo pública del chatbot y de la medición para anuncios (DEMO_UPLOAD_ENABLED, DEMO_MONTHLY_BUDGET_USD, REDIS_URL, TRUST_PROXY_HOPS, NEXT_PUBLIC_GA_ID, NEXT_PUBLIC_GOOGLE_ADS_ID, NEXT_PUBLIC_LINKEDIN_PARTNER_ID, entre otras) vienen de la rama rag-reposicionamiento (hecho, pendiente de merge). La lista final, con dónde se configura cada una, está en Reposicionamiento RAG.

Requisito: Jest con TypeScript funcionando en CI (Fase 0).

Con supertest y mongodb-memory-server en modo réplica, para que las transacciones funcionen.

• POST /api/demo-requests
  • Captcha simulado, honeypot, tiempo mínimo y rate-limit por IP y por email.
  • Sin consentimiento: 400.
  • Fusión de duplicados.
  • Programa exactamente 2 mensajes.
• Aprobación
  • Crea el usuario, los accesos, el token, el mensaje y la bitácora en una transacción.
  • Si se fuerza un fallo a mitad, no queda nada creado.
  • El doble clic da 409.
  • sales con una demo privado da 403.
  • Si el email ya existe, se vincula sin bajar el rol.
• Enlace mágico
  • check no consume el token.
  • consume funciona una vez; el segundo intento falla.
  • Un token vencido falla.
  • Reenviar el enlace invalida los anteriores.
• GET /api/demo-access: cada motivo de la sección 10.1, incluido el staff.
• requireDemoGrant en las rutas de demos reales: 403 sin acceso y 200 con acceso.
• Matriz de permisos completa: prueba tabla con los 6 roles contra todas las rutas del equipo.
• Jobs
  • Dos corridas seguidas envían un solo recordatorio.
  • El lease evita que dos instancias corran a la vez.
  • El outbox reintenta y marca fallido.

Con Playwright, que ya es dependencia de apps/web. Archivo: apps/web/e2e/demo-flow.spec.ts.

Para estas pruebas, Turnstile usa sus claves de prueba y el email se captura con un transporte de prueba que lee el outbox.

Son metas iniciales a validar con 8 semanas de operación real (igual que en Flujo del cliente). No son resultados actuales. Las definiciones exactas de cada métrica están en la sección 13 y se ven en Admin › Métricas (Panel de administración, sección 10).

• Flujo del cliente · Panel de administración · Portal del cliente
• Catálogo de demos · Landing de producto · Autenticación · Legal
• Backend y API · Seguridad y calidad · Comercial, marketing y legal · Roadmap