taskbot/STATUS.md

Estado del Proyecto - Task Manager para WhatsApp

✅ Funcionalidades Completadas

• Infraestructura Principal
  • Servidor webhook con health checks
  • Dockerización y despliegue CapRover
  • Gestión de dependencias con Bun
• Base de Datos
  • Modelo de tareas y asignaciones
  • Normalización de IDs de WhatsApp
  • Transacciones atómicas
  • Migrador up-only para SQLite con tabla schema_migrations, backup automático con VACUUM INTO y baseline automático si ya existe esquema
  • Esquema de response_queue extendido con columna metadata
• Sincronización de Grupos
  • Caché de grupos activos y validación en el servidor
  • Sync periódico con Evolution API
• Webhooks
  • Registro/verificación con Evolution API
  • Manejo de eventos (MESSAGES_UPSERT) con normalización del nombre del evento
  • Corrección: extracción robusta de remitente en DMs vs grupos para evitar 'Invalid sender ID'
• Cola de Respuestas
  • Persistencia en DB y envío real a Evolution API
  • Workers en background activos
  • Soporte de menciones: persistencia en metadata y envío como mentioned en el payload
  • Reintentos con backoff exponencial + jitter (4xx = fallo definitivo; 5xx/red = reintento hasta RQ_MAX_ATTEMPTS con next_attempt_at)
• Comandos
  • /tarea nueva end-to-end: parseo de descripción y última fecha futura, extracción de asignados desde menciones y tokens @..., limpieza de la descripción, persistencia de tarea y asignaciones, y respuesta con menciones.
  • Listados: /t ver con grupo, mis, sin y todos, con tope y resumen “… y X más”, siempre por DM.
  • Completar: /t x <id> (alias: hecho, completar, done) con feedback compacto por DM.
  • Alias añadidos para gestión de asignación: tomar (claim, asumir, asumo) y soltar (unassign, dejar, liberar, renunciar) — mapeados en el parser (acciones aún no implementadas).
• Contactos y Nombres
  • Servicio ContactsService con caché en memoria (TTL) y actualización por webhooks (CONTACTS_UPDATE/CHATS_UPDATE); fallback a Evolution API para obtener nombres. Se usa para mostrar nombres en los textos (con fallback a números). En entorno de test evita llamadas de red para acelerar y aislar la suite.
• UX de Notificaciones
  • Confirmación por DM al creador siempre (en una sola línea con id y descripción) y DM a cada asignado (excluyendo al creador).
  • Notificación opcional al grupo controlada por NOTIFY_GROUP_ON_CREATE (false por defecto), incluyendo menciones para visibilidad.
  • Política solo DM: el bot no publica respuestas en grupos; todos los mensajes de salida se envían por DM al autor (salvo la notificación opcional anterior).
• Validaciones de Usuario
  • Integración completa de normalización y ensureUserExists en el flujo principal de mensajes
  • Tests de integración para validaciones de usuarios
• Testing
  • Suite de tests unitarios con DB en memoria para aislamiento

⚠️ Funcionalidades Pendientes

• Gestión de Tareas
  • Implementar comandos “tomar” y “soltar” (claim/unassign) con validaciones.
  • Eliminación opcional de tareas y mejoras de edición.
• Fechas y parsing
  • Parser de fechas naturales “hoy/mañana” en creación.
• Cola de Respuestas
  • (Post-MVP) Observabilidad y métricas: contadores, latencias, tamaño de cola, endpoint /metrics.
• Validaciones
  • Permisos de usuario (roles) y pertenencia a grupos (si se requiere política estricta).
• Menciones y nombres
  • Refinar políticas de caché (TTL, invalidación) y ampliar compatibilidad de endpoints; en DM, WhatsApp no pinta chips de mención de terceros (limitación del cliente).

➡️ Próximos Pasos Prioritarios

1. Implementar “tomar” y “soltar” end-to-end (TaskService + CommandService), con feedback por DM.
2. Añadir parser “hoy/mañana” en creación y unificar formato de fechas (dd/MM) en todos los mensajes.
3. Ayuda por DM: guía corta con ejemplos cuando el usuario escribe “/t” o “ayuda”.

🐞 Problemas conocidos

• En chats privados, WhatsApp no renderiza chips de mención para terceros; en grupos sí se resuelven al nombre local de cada receptor. El bot incluye nombres en el texto cuando los conoce y números como @dígitos para acción rápida; no hay reescritura por receptor.

🔧 Archivos Clave a Modificar

• src/services/response-queue.ts
• src/services/command.ts
• src/tasks/service.ts
• src/server.ts

Phase 4 — Desglose y estado

• Etapa 1 — Reintentos con backoff exponencial + jitter: COMPLETADA.
• Etapa 2 — Recuperación de items en processing (lease/expiración): COMPLETADA.
• Etapa 3 — Métricas y observabilidad: POSPUESTA (post-MVP).
• Etapa 4 — Limpieza/retención: COMPLETADA.

Commit history and status

• Latest status: All unit tests passing; UX Iteración A (parcial) con listados ver grupo/mis/sin/todos y política solo DM; ACK al creador en una línea; notificación al grupo opcional desactivada por defecto; ContactsService evita llamadas de red en tests; nombres amigables integrados.

▶️ Para continuar ahora

Propuesta inmediata:

• Implementar comandos: /t tomar <id> y /t soltar <id> (claim/unassign), con validaciones y mensajes compactos.
• Añadir parser de fechas “hoy/mañana” en creación y ayuda “/t ayuda” por DM.
• Afinar ResponseQueue con métricas básicas y mantener metadata de menciones.

Para que pueda proponer cambios de código, añade estos archivos a este chat:

• src/services/command.ts
• src/tasks/service.ts
• src/services/response-queue.ts
• src/server.ts