@ -29,6 +29,7 @@ Un chatbot de WhatsApp para gestionar tareas en grupos, integrado con Evolution
- Nombres amigables vía caché de contactos (sin llamadas de red en tests).
- Sincronización de miembros de grupos (snapshot periódica + webhooks incrementales; tolerante a fallos).
- Mensajes compactos con emojis y cursiva; fechas dd/MM; vencidas con ⚠️.
- Observabilidad mínima: /metrics (Prometheus por defecto, JSON opcional) y /health detallado.
## Requisitos
- Evolution API accesible (recomendado: misma red interna Docker).
@ -61,6 +62,11 @@ Un chatbot de WhatsApp para gestionar tareas en grupos, integrado con Evolution
- Opcionales — migraciones
- MIGRATOR_CHECKSUM_STRICT: si "false" desactiva validación estricta de checksum de migraciones; por defecto "true".
- MIGRATIONS_LOG_PATH: ruta del fichero de log de migraciones; por defecto data/migrations.log.
- Opcionales — métricas y mantenimiento
- METRICS_ENABLED: "true"|"false" para habilitar /metrics; por defecto true (desactivado en test).
- METRICS_FORMAT: "prom"|"json"; por defecto "prom".
- GROUP_MEMBERS_INACTIVE_RETENTION_DAYS: días para purgar miembros inactivos; 180 por defecto; 0 desactiva.
- FORCE_SCHEDULERS: "true" para forzar arranque de jobs en NODE_ENV=test.
- Entorno
- NODE_ENV: production | development | test.
@ -87,7 +93,7 @@ Consulta .env.example para un listado comentado con valores de ejemplo.
## Limitaciones conocidas
- Sin orden garantizado por destinatario en la cola.
- Sin endpoint /metrics por ahora.
- /metrics básico sin histogramas ni etiquetas; mejoras futuras.
- Permisos/roles y validación estricta de pertenencia a grupos no implementados.
## Roadmap
@ -115,9 +121,9 @@ Consulta .env.example para un listado comentado con valores de ejemplo.
- Objetivo: conocer miembros activos por grupo para features avanzadas.
- Implica: endpoints Evolution API para miembros; cache/migraciones.
10) Métricas y observabilidad (deferido del MVP)
10) Métricas y observabilidad
- Objetivo: visibilidad con bajo coste.
- Implica: counters/gauges/histograms y endpoint /metrics; logging estructurado. Se pospone al final de esta lista.
- Implementado: /metrics (Prometheus/JSON) con counters/gauges y /health detallado; pendiente: histogramas/latencias y logging estructurado avanzado.
## 🔑 Key Considerations & Caveats
* **WhatsApp ID Normalization:** Crucial for consistently identifying users and groups. Needs careful implementation to handle edge cases. (Utility function exists).
@ -26,6 +26,10 @@ Estado general: listo para piloto con la junta directiva; 170 tests pasando. Rie
- 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)
@ -34,7 +38,7 @@ Estado general: listo para piloto con la junta directiva; 170 tests pasando. Rie
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: /metrics con contadores de cola, errores y latencias.
- 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.
@ -44,7 +48,7 @@ Estado general: listo para piloto con la junta directiva; 170 tests pasando. Rie
- 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, plan de /metrics (pospuesto si no es crítico), guía de troubleshooting.
- 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.
