taskbot/docs/plan-onboarding-usuarios.md

# Plan de Onboarding de Usuarios y Resolución de Alias (JID opaco → número)

Resumen y diagnóstico (basado en el código actual)
- Fuentes automáticas actuales de aprendizaje de alias (sin intervención de usuarios):
  1) Mensajes en grupos: en src/server.ts, si participantAlt y participant difieren, se hace IdentityService.upsertAlias(participant, participantAlt, 'message.key'), mapeando un @lid “opaco” al JID real @s.whatsapp.net.
  2) Sincronización de miembros: en src/services/group-sync.ts, si el payload trae p.id y p.jid, se hace upsertAlias(id, jid, 'group.participants') y además se asegura el usuario con ensureUserExists.
  3) Actualizaciones de contactos/chats: en src/services/contacts.ts, si se recibe objeto con id=@lid y jid=@s.whatsapp.net, se hace upsertAlias(alias, jid, 'contacts.update').
- Alta de usuarios sin DM: src/services/group-sync.ts::reconcileGroupMembers llama ensureUserExists(userId) para cada miembro activo; si tenemos número, el usuario “existe” aunque no haya enviado DM.
- Normalización robusta: utils/whatsapp.normalizeWhatsAppId elimina dominio y sufijo “:xx”, quedando el número limpio si venía en el JID.
- Problema detectado: en src/services/command.ts, al parsear menciones, si una mención llega como @lid sin alias aún, se descarta (aunque a veces podría venir como JID real). Resultado: “se puede crear tarea pero no asignar responsables” en algunos casos, especialmente con usuarios “silenciosos” (no escriben en grupo) cuando la API no aporta número en ninguno de los eventos.

Objetivo
- Minimizar fricción y tiempo hasta poder asignar y autenticar: que los usuarios queden asignables con la mínima acción (idealmente sin DM).
- Evitar spam y códigos por-usuario. Publicar, solo si hace falta, un único mensaje por grupo con enlace wa.me.
- Cubrir casos de usuarios “silenciosos” (no escriben en grupo) garantizando una vía de mapeo fiable (DM “hola”).

Estrategia general
- Exprimir al máximo el aprendizaje automático que ya tenemos (participants y contacts).
- Ajustar CommandService para no descartar menciones válidas con números reales.
- Medir cobertura y publicar un único mensaje por grupo con wa.me únicamente si faltan usuarios por resolver; con cooldown.
- DM “activar” como último recurso confiable para cerrar huecos de usuarios silenciosos; considerar “código por grupo” solo como fallback extremo si una instancia no correlaciona jamás sin token.

Fases

Fase A0 — Verificación y observabilidad (rápida, sin UX visible)
- Estado: completada (deploy tras commit d25efb0).
- Métricas nuevas:
  - alias_coverage_ratio{group_id}: gauge con el porcentaje aproximado de miembros activos con número resoluble (o alias).
  - onboarding_prompts_sent_total / onboarding_prompts_skipped_total: counters para controlar ruido.
  - onboarding_assign_failures_total: counter de menciones no resolubles al crear tareas.
- Logs de desarrollo (NODE_ENV=development): en src/server.ts, comparar participant vs participantAlt (normalizados) y mentionedJid normalizados para comprobar la frecuencia de correlación automática en tu instancia Evolution.

Fase A1 — Aprendizaje “agresivo” al entrar en grupos (Completada)
- Al recibir groups.upsert (src/server.ts):
  - syncGroups → refreshActiveGroupsCache → syncMembersForActiveGroups (ya implementado).
  - Efectos:
    - Crea usuarios con ensureUserExists(userId).
    - Si el payload incluye id + jid, rellena alias automáticamente.
- Mantener activo ContactsService.updateFromWebhook para capturar correlaciones adicionales en los primeros minutos.

Fase A2 — Ajuste clave sin fricción: conservar menciones con números (Completada)
- Estado: completada (deploy tras commit 8b1af56).
- En src/services/command.ts, al construir los candidatos a assignees:
  - Si normalizeWhatsAppId(token) produce dígitos y resolveAliasOrNull devuelve null, CONSERVAR ese número (no descartarlo).
  - Asegurar ensureUserExists para esos IDs conservados antes de usarlos.
  - Filtrar CHATBOT_PHONE_NUMBER para evitar autoasignaciones al bot.
- Métrica: se incrementa onboarding_assign_failures_total con labels {group_id, source, reason} cuando una mención/token no es resoluble ni plausible.
- Configuración: ONBOARDING_FALLBACK_MIN_DIGITS (por defecto 8) controla la longitud mínima para considerar un número “plausible”.
- Efecto: reduce drásticamente los fallos de asignación por mención sin necesidad de DM.

Fase A3 — Mensaje único por grupo con wa.me (Completada)
- Condición de publicación:
  - Tras A1 y un breve grace period (≈1–2 min) para permitir contacts/chats updates, calcular alias_coverage_ratio{group_id}.
  - Si cobertura = 100% → NO publicar.
  - Si cobertura < 100% → publicar UNA vez un mensaje por grupo con el texto:
    - “Para poder asignarte tareas y acceder a la web, envía ‘activar’ al bot por privado. Solo hace falta una vez. Enlace: https://wa.me/<NUM_BOT>”
- Control de ruido:
  - Persistir timestamp de último envío por grupo (cooldown, p. ej., 7 días) y re-publicar solo si entran nuevos miembros sin resolver tras el cooldown.
- Fallback extremo (probablemente no necesario con tu stack):
  - Si en una instancia concreta el DM “hola” no basta para correlacionar, usar “código por grupo” como texto pre-rellenado en wa.me: “alta XYZ123” (único por grupo, nunca por-usuario), almacenado con caducidad. Aplicarlo solo si la métrica demuestra que el caso existe.

Fase A4 — Asistentes “just-in-time” y UX mínima (Completada)
- Si una asignación falla por mención no resoluble:
  - Enviar DM al asignador (ResponseQueue) con: “No puedo asignar a X aún. Pídele que toque este enlace y diga ‘activar’: https://wa.me/<NUM_BOT>”.
- Primer DM “activar” de un usuario:
  - Asegurar ensureUserExists y responder con: “Listo, ya puedes reclamar/ser responsable en: …”.
- Opcional web: si el usuario llega sin estar identificado, mostrar banner con botón a wa.me “activar”.

Fase A5 — Optimizaciones post-A1 (pendiente)
- Optimizar encadenado tras groups.upsert para sincronizar solo los grupos afectados cuando el payload lo permita.
- Añadir debounce/backoff por grupo (2–5 s) para coalescer ráfagas de upserts en corto intervalo.
- Añadir tests: uno que valide el filtrado a “grupos afectados” y otro que verifique que el debounce evita ejecuciones duplicadas dentro de la ventana.

Fase Final — Pruebas E2E
- Objetivo: validar end-to-end en un entorno de staging con Evolution API que los prompts A3 funcionan sin efectos secundarios.
- Casos a verificar:
  - Envío al grupo (@g.us) mediante sendText: que el backend acepte recipient con @g.us y el mensaje se entregue.
  - Publicación condicional: cobertura < 100% tras el grace → se envía; cobertura = 100% → se omite; cooldown activo → se omite.
  - Gating: en modo enforce, grupos no allowed → se omite.
  - Configuración: sin CHATBOT_PHONE_NUMBER o ONBOARDING_PROMPTS_ENABLED=false → se omite.
  - Métricas: alias_coverage_ratio, onboarding_prompts_sent_total y onboarding_prompts_skipped_total con su reason se actualizan.
- Preparación recomendada:
  - Instancia Evolution apuntando a un grupo de pruebas; CHATBOT_PHONE_NUMBER configurado; METRICS_ENABLED=true.
  - Reducir ONBOARDING_GRACE_SECONDS y ONBOARDING_COOLDOWN_DAYS para acelerar validación.
  - Confirmar que ResponseQueue.process está activo y que los workers pueden enviar.

Criterios de aceptación
- p95 del tiempo desde que un usuario toca el enlace a quedar asignable < 1 minuto.
- En la mayoría de grupos no se publica ningún mensaje (cobertura ≈100% tras primer sync + contacts).
- Caída significativa de onboarding_assign_failures_total respecto al baseline.
- Sin spam: un único mensaje por grupo y cooldown aplicado.

Archivos a ver/editar/crear

A) Núcleo bot
- src/services/command.ts (EDITAR)
  - Puntos: construcción de mentionsNormalizedFromContext y normalizedFromAtTokens.
  - Cambio: fallback a número normalizado cuando resolveAliasOrNull no resuelva; ensureUserExists; filtrar CHATBOT_PHONE_NUMBER; incrementar onboarding_assign_failures_total cuando una mención no sea resoluble en absoluto.
- src/services/group-sync.ts (EDITAR)
  - Tras reconcileGroupMembers, computar cobertura aproximada (miembros activos con número conocido / miembros activos totales).
  - Exponer alias_coverage_ratio{group_id} vía Metrics.set. Si coverage < 100% y cooldown vencido → disparar encolado de un mensaje único por grupo (ResponseQueue).
  - Método util: getActiveGroupIdsForUser, isSnapshotFresh, etc., ya existen; añadir tracking de onboarding_prompted_at (ver persistencia).
- src/server.ts (EDITAR mínimo)
  - Logs de desarrollo comparando participant vs participantAlt y mentionedJid normalizados para verificar correlación automática.
  - Opcional: hook tras groups.upsert para forzar el chequeo de cobertura post-sync (o dejarlo en scheduler de miembros).
- src/services/contacts.ts y src/services/identity.ts (VER)
  - Ya aportan alias automáticamente; no requieren cambios inmediatos.
- src/services/response-queue.ts (VER/EDITAR si hiciera falta)
  - Asegurar que puedes encolar mensajes hacia group_id@g.us sin cambios (parece OK con sendText si el backend lo admite). Añadir, si quieres, etiquetas/metadata para identificar “onboarding”.

B) Persistencia
- Opción simple recomendada: columna en groups
  - Nueva columna: groups.onboarding_prompted_at TEXT NULL.
  - Lógica: publicar si coverage < 100% y (onboarding_prompted_at IS NULL o han pasado ≥ X días).
- Alternativa: tabla dedicada group_onboarding (group_id PK, last_prompt_at, last_coverage, last_pending_count, last_sent_by).
- Archivos:
  - src/db/migrations/index.ts (EDITAR): añadir migración para onboarding_prompted_at (o tabla nueva).
  - src/db.ts (VER): no requiere cambios, migrador ya está integrado.

C) Mensajería y copy
- Texto base:
  - “Para poder asignarte tareas y acceder a la web, envía ‘hola’ al bot por privado. Solo hace falta una vez. Enlace: https://wa.me/<NUM_BOT>”
- Fallback extremo (solo si es necesario, ver A3):
  - “… o envía ‘alta XYZ123’ si el enlace no funciona.”
- Dónde generarlo: en GroupSyncService (o un OnboardingService nuevo) cuando coverage < 100% y cooldown vencido; encolar con ResponseQueue para recipient = group_id@g.us.

D) UI web (opcional a posteriori)
- Banner SSR-safe cuando App.Locals.userId no esté disponible: botón wa.me con “hola”; desaparecer al resolver.

Métricas propuestas
- alias_coverage_ratio{group_id} (gauge).
- onboarding_prompts_sent_total / onboarding_prompts_skipped_total (counters).
- onboarding_assign_failures_total (counter).
- identity_alias_upserts_total, identity_alias_resolved_total / identity_alias_unresolved_total (ya existen).
- time_to_link_p95 (opcional; aproximable por “primer avistamiento” → “primer DM/alias resuelto”).

Caveats y buenas prácticas
- No spamear: un único mensaje por grupo + cooldown; nada si coverage=100%.
- Privacidad: DM “hola” iniciado por el usuario; no mostrar datos sensibles en grupos.
- Entornos de test: suprimir publicación y logs invasivos; respetar NODE_ENV='test'.
- Resiliencia: si Evolution deja de enviar participantAlt/p.jid, el flujo de DM cubre a los silenciosos; si los envía, el DM apenas será necesario.

Checklist de ejecución
- A0: Añadir métricas y logs de verificación (dev).
- A1: Confirmar que el sync de miembros corre al entrar; mantener contacts.update. (hecho)
- A2: Ajuste en CommandService (fallback a número + ensureUserExists + métricas de fallo).
- A3: Publicación condicional de mensaje por grupo con cooldown + persistencia mínima.
- A4: DM “just-in-time” al asignador ante fallo de mención + confirmación al primer DM de usuario.

Archivos adicionales que podríamos necesitar añadir al chat en la implementación
- src/utils/whatsapp.ts (para confirmar normalizeDigits si lo reutilizamos en copy/URLs).
- apps/web/src/app.d.ts (si añadimos banner basado en session/locals).
- tests/unit/* y tests/web/* (para cubrir la nueva lógica de fallback y métricas).