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.
  • Tomar/Soltar: /t tomar <id> y /t soltar <id> implementados end-to-end con feedback compacto por DM (idempotentes).
  • Fechas naturales: soporte de “hoy/mañana” en creación con TZ configurable (env TZ; por defecto Europe/Madrid).
  • Ayuda por DM: “/t” y “/t ayuda” devuelven una guía breve; el bot no publica en grupos.
• 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 (encabezado: 📝 “desc”, con líneas de fecha 📅 y dueño 🚫👤/👤) y DM a cada asignado (📬, excluye al creador); fechas vencidas marcadas con ⚠️.
  • 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
• Recordatorios por DM
  • Preferencias por usuario en user_preferences (reminder_freq: off|daily|weekly; reminder_time; last_reminded_on).
  • Servicio RemindersService con tick minucioso (desactivado en tests), evita duplicados por día y respeta TZ.
  • Soporta daily y weekly (lunes 08:30); no envía si no hay tareas; mensaje compacto con “… y X más”.
  • Comando “/t configurar daily|weekly|off” con confirmación por DM.
  • Pruebas unitarias para RemindersService y configuración de recordatorios.

⚠️ Funcionalidades Pendientes

• Gestión de Tareas
  • Eliminación opcional de tareas y mejoras de edició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. Afinar recordatorios por DM (daily/weekly): hora configurable por usuario y pequeños ajustes de formato.
2. Refinar ContactsService (caché/nombres; TTL configurable; robustez ante fallos; sin red en tests).
3. Sincronización mínima de miembros (cacheada; no bloqueante).
4. Ampliar test suite (contactos, sync de miembros, ResponseQueue).

🐞 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; recordatorios por DM implementados (daily/weekly) con preferencia por usuario y comando “/t configurar”; soporte de fechas “hoy/mañana” con TZ configurable y formato dd/MM; ayuda por DM; listados ver grupo/mis/sin/todos; política solo DM; ACK al creador en una línea; notificación al grupo opcional desactivada; ContactsService evita llamadas de red en tests; nombres amigables integrados; rate limiting básico por usuario (15/min, configurable por env; desactivado en tests) implementado.

▶️ Para continuar ahora

Propuesta inmediata:

• Afinar recordatorios por DM (daily/weekly): hora configurable por usuario; encabezados ⏰ y formato de mensajes ya actualizados.
• Refinar ContactsService (caché y nombres; TTL configurable; robustez ante fallos; sin red en tests).
• Sincronización mínima de miembros (cacheada; no bloqueante).
• Ampliar test suite (recordatorios, contactos, sync de miembros, ResponseQueue).

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