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 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**
  - 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. Rate limiting básico (bucket en memoria por remitente; desactivado en tests).
2. Recordatorios diarios por DM (opt-in daily|off; hora fija local; resumen compacto).
3. Refinar ContactsService (caché/nombres; TTL configurable; robustez ante fallos; sin red en tests).
4. Sincronización mínima de miembros (cacheada; no bloqueante).
5. Ampliar test suite (recordatorios, rate limiting, 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; soporte de fechas naturales “hoy/mañana” con TZ configurable (por defecto Europe/Madrid) y formato unificado dd/MM en mensajes; ayuda por DM (“/t”, “/t ayuda”); 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.

## ▶️ Para continuar ahora
Propuesta inmediata:
- Rate limiting básico (bucket en memoria por remitente; desactivado en tests).
- Recordatorios diarios por DM (opt-in daily|off; hora fija local; resumen compacto).
- 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, rate limiting, 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`