taskbot/STATUS.md

Estado del Proyecto — Task Manager para WhatsApp

Estado general: listo para piloto con la junta directiva; 170 tests pasando. Riesgos operativos principales: CI/CD básico, red interna entre Evolution API y el bot, y backups/persistencia. Siguiente paso de desarrollo: ejecutar el plan mínimo de CI/CD, healthcheck y backups descrito en docs/CI-CD-PLAN.md (pendiente de cerrar las decisiones marcadas).

Hecho (por áreas)

• Servidor webhook
  • Endpoint /health, validación de entorno, extracción robusta de texto (conversation/extended/captions).
  • Detección DM vs grupo y política “solo DM”.
  • Registro/verificación de webhooks y sincronización de grupos activos con caché; sincronización periódica de miembros y handlers incrementales (alta/baja/rol) idempotentes.
  • Rate limiting por usuario (15/min por defecto; desactivado en tests; aviso con cooldown).
• Base de datos y migraciones
  • Inicialización con PRAGMA FK y timestamps de alta precisión.
  • Esquema: users, tasks, task_assignments, user_preferences, response_queue (con metadata).
  • Modo journal WAL activado (busy_timeout y autocheckpoint configurados) para mejorar concurrencia y rendimiento.
  • Migrador up-only con tabla schema_migrations; FK siempre ON al abrir; backup automático con VACUUM INTO; sin baseline por defecto; validación de checksum; log persistente en data/migrations.log; resumen de estado al arrancar.
• Cola de respuestas
  • Persistente con workers en background, reintentos con backoff exponencial + jitter, recuperación de items processing tras reinicios, y limpieza/retención.
  • 2xx=sent, 4xx=failed definitivo, 5xx/red=reintento; evita enviar al propio bot.
• Comandos
  • Crear, listar (grupo/mis/sin/todos), completar, tomar, soltar; ayuda por DM.
  • Fechas “hoy/mañana” con TZ configurable; formato dd/MM; vencidas con ⚠️.
  • Menciones reales y tokens @…; reglas por defecto: grupo→sin responsable, DM→creador.
• Recordatorios por DM
  • Preferencias por usuario (daily|weekly|off; hora con soporte en modelo/servicio), evita duplicados por día, weekly en lunes, respeta TZ, no envía si no hay tareas.
• Contactos y nombres
  • Caché en memoria, actualización por webhooks, fallback a Evolution API (saltado en tests); nombres amigables en textos.
• Testing
  • ~170 tests unitarios con SQLite en memoria; ResponseQueue (reintentos/cleanup), comandos (alias/fechas/listados/x/tomar/soltar), recordatorios, utilidades.
• Observabilidad y mantenimiento
  • Endpoint /metrics (Prometheus por defecto; JSON opcional) con contadores/gauges básicos: sync_runs_total, sync_errors_total, webhook_events_total_, webhook_errors_total, active_groups, active_members, last_sync_.
  • /health detallado (full=1) con active_groups, active_members, last_sync_at y snapshot_age_ms.
  • Job diario de limpieza de miembros inactivos configurable (GROUP_MEMBERS_INACTIVE_RETENTION_DAYS; por defecto 180 días).

Pendiente (priorizado)

• MVP operativo (bloqueantes/casi bloqueantes)
  1. CI/CD: pipeline mínimo (build + bun test + build/push imagen + despliegue CapRover). Ver docs/CI-CD-PLAN.md.
  2. Persistencia/backup: volumen /app/data y backup diario del fichero SQLite.
  3. Seguridad/red: ejecutar en red interna con Evolution API; si no, proteger el webhook (IP allowlist/reverse proxy).
  4. Ensayo E2E en staging: registro de webhook, recepción de MESSAGES_UPSERT reales y envío de DMs.
• Post-MVP (mejoras)
  • Observabilidad: ampliar métricas (latencias/histogramas, etiquetas), dashboards y alertas.
  • Orden por destinatario en ResponseQueue; idempotency_key opcional.
  • Permisos/roles y pertenencia a grupos (si se requiere).
  • Edición/eliminación de tareas.
  • Política de caché de contactos (TTL configurable, invalidación más fina).

Roadmap y próximas iteraciones

• Iteración A — Operativa lista para piloto
  • Entregables: pipeline CI (GitHub Actions), build de imagen, despliegue CapRover con volumen /app/data, backup diario configurado, checklist de red interna verificada.
• Iteración B — Observabilidad mínima
  • Entregables: logs con contexto en puntos clave, ruta /metrics (Prometheus/JSON) y /health detallada, guía de troubleshooting.
• Iteración C — Calidad de datos/UX
  • Entregables: mejoras de caché de contactos, afinado de recordatorios (hora por usuario), pruebas adicionales de ResponseQueue y comandos.

Checklist de readiness para piloto

• Infra
  • App en CapRover con volumen /app/data.
  • Variables de entorno configuradas; TZ correcta.
  • Evol. API y bot en la misma red; /health OK.
• Operación
  • Backups diarios de data/tasks.db y procedimiento de restauración.
  • Logs accesibles; worker de cola activo.
• Funcional
  • Bot añadido a los grupos; grupos activos sincronizados.
  • Comandos base verificados en un grupo real (crear/ver/x/tomar/soltar/configurar).
• Comunicación/privacidad
  • Aviso a la junta: cómo usar, qué se guarda, cómo desactivar recordatorios.

Riesgos y mitigaciones

• Webhook expuesto públicamente
  • Mitigación: red interna; si no es posible, IP allowlist/reverse proxy y rotación de claves.
• Pérdida de datos en SQLite
  • Mitigación: volumen persistente + backups diarios + prueba de restore.
• TZ incorrecta y mensajes con fecha errónea
  • Mitigación: fijar TZ en entorno, tests de humo con “hoy/mañana”.
• Fallos o latencia de Evolution API
  • Mitigación: reintentos con backoff; logs de error; visibilidad en ResponseQueue.

Testing y cobertura

• Cubre: comandos, ResponseQueue (reintentos/cleanup), recordatorios (daily/weekly/TZ), utilidades, normalización de IDs, validaciones básicas en servidor.
• Falta: pruebas E2E reales contra Evolution API (recomendado antes del piloto).

Notas de despliegue/operación

• SQLite en modo WAL; backups consistentes con VACUUM INTO previo; tener en cuenta archivos -wal y -shm.
• Log persistente de migraciones en data/migrations.log (una línea por evento, formato JSONL); revisar en despliegues.
• Persistencia en data/; mapear a volumen y monitorizar tamaño; ejecutar VACUUM periódicamente si procede.
• Rotación de logs vía orquestador; considerar niveles/etiquetas para búsquedas.

Changelog breve

• Reintentos/backoff y recuperación de ResponseQueue: completado.
• Recordatorios por DM (daily/weekly) con preferencias: completado.
• Rate limiting por usuario: completado.
• Ayuda por DM y formato de mensajes unificado: completado.
• Sincronización de miembros (full sync + webhooks incrementales): completado.
• Limpieza/retención de historiales de cola: completado.