From 4fb172b4fe6fe69503358c165a2706fd52ec9ee3 Mon Sep 17 00:00:00 2001 From: borja Date: Sat, 6 Sep 2025 22:34:49 +0200 Subject: [PATCH] docs: actualizar README.md y STATUS.md para reflejar estado actual Co-authored-by: aider (openrouter/openai/gpt-5) --- README.md | 26 ++++++++++++++++---------- STATUS.md | 31 ++++++++++++++++++------------- 2 files changed, 34 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 31c28bd..e283dec 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,9 @@ This service provides a WhatsApp interface for task management within WhatsApp g - Manages user permissions and group membership (partially implemented). - Integrates with Evolution API for WhatsApp connectivity. - Sends direct messages to acknowledge the creator and notify each assignee; includes mentions with phone numbers for quick action. +- DM-only responses: the bot does not post messages in groups; all outputs are sent via DM to the author (except the optional creation summary below). +- Advanced listings: "/t ver" supports scopes "grupo", "mis", "sin" and "todos" with pagination ("… y X más"). +- Complete tasks: "/t x " (aliases: hecho, completar, done) with compact DM feedback. - Optional: group notification on task creation controlled by NOTIFY_GROUP_ON_CREATE (default false), including proper mentions for visibility. ## 🔐 Security Model @@ -43,20 +46,20 @@ graph TD ``` *(Diagram updated for planned flow)* -## Decisiones de diseño de la cola de respuestas (MVP) +## Decisiones de diseño de la cola de respuestas (estado actual) 1) Persistencia: 100% persistente (tabla única). 2) Worker: continuo en background. 3) Locking: status=processing (sin lease). 4) Orden: sin orden estricto por chat. -5) Reintentos: sin reintentos en MVP. -6) Errores: 4xx = fallo definitivo; 5xx/red = fallo (sin reintentos). +5) Reintentos: activados con backoff exponencial + jitter (configurables). +6) Errores: 4xx = fallo definitivo; 5xx/red = reintento hasta RQ_MAX_ATTEMPTS con `next_attempt_at`. 7) Idempotencia: no. 8) Esquema DB: tabla única response_queue. 9) Transporte: envío desde ResponseQueue (fetch directo a Evolution API). 10) Concurrencia: N workers globales. 11) Integración: encolar y worker continuo (arranca con el servidor). 12) Configuración: defaults fijos (sin nuevas env vars por ahora). -13) Limpieza: sin limpieza/retención de historiales (por ahora). +13) Limpieza: retención periódica de historiales aplicada (sent y failed antiguos). 14) Seguridad: no enviar al número del bot (CHATBOT_PHONE_NUMBER). 15) Pruebas: unitarias de cola con mocks de fetch. @@ -79,11 +82,11 @@ Estado: la tabla response_queue ya está creada e incluida en los tests de DB. - Ciclo: seleccionar hasta un pequeño batch de mensajes queued, marcar processing, enviar a Evolution API, marcar sent o failed según respuesta. - Sin reintentos; logs mínimos y no sensibles. -## Limitaciones explícitas del MVP -- Sin backoff ni reintentos. -- Sin orden garantizado por chat. -- Sin idempotencia ni limpieza automática. -- Sin lease; en caso de crash podrían quedar mensajes en processing que requerirán recuperación manual en una iteración futura. +## Limitaciones actuales +- Sin orden garantizado por chat (pendiente serialización por destinatario). +- Sin idempotencia (pendiente `idempotency_key` e índice único). +- Métricas/observabilidad básicas pendientes (endpoint /metrics). +- Sin garantía de orden cross-chat; fair scheduling pendiente. ## Plan incremental posterior - Añadir reintentos con backoff exponencial y jitter. (Completado) @@ -107,8 +110,11 @@ Estado: la tabla response_queue ya está creada e incluida en los tests de DB. - Cleans description to remove @mentions tokens. - Persists task and assignments atomically via `TaskService`. - Builds response with assignment list and includes Evolution API “mentioned” JIDs via `ResponseQueue`. +- Command handling for listings and completion: + - `/t ver` with scopes `grupo`, `mis`, `sin` and `todos` with top-N and “… y X más”; DM-only policy enforced. + - `/t x ` to complete tasks (aliases: `hecho`, `completar`, `done`) with compact feedback. - Task persistence service (`src/tasks/service.ts`) with `created_by` and assignment inserts in a transaction; supports DB injection for tests. -- Response queue persistente con workers en background y envío vía Evolution API (`src/services/response-queue.ts`), persistiendo metadata `{ mentioned: [...] }` y enviándola como `mentioned` en el payload, con reintentos (backoff exponencial + jitter) y programación por `next_attempt_at`. +- Response queue persistente con workers en background y envío vía Evolution API (`src/services/response-queue.ts`), persistiendo metadata `{ mentioned: [...] }` y enviándola como `mentioned` en el payload, con reintentos (backoff exponencial + jitter), recuperación de `processing` y limpieza/retención. - Contacts service and friendly names: `ContactsService` resolves display names via webhooks (CONTACTS_UPDATE/CHATS_UPDATE) and Evolution API fallback; used to render names in outgoing texts (falls back to numbers). Skips network calls under NODE_ENV=test for fast and isolated unit tests. - Notification UX: Always send DM acknowledgment to the creator in a single line (format: ✅ Tarea creada: "description"), DM to each assignee (excluding the creator); optional group notification controlled by `NOTIFY_GROUP_ON_CREATE` (default false) with proper mentions. - Environment variable validation (`src/server.ts`, `src/services/webhook-manager.ts`). diff --git a/STATUS.md b/STATUS.md index fef6001..146405e 100644 --- a/STATUS.md +++ b/STATUS.md @@ -25,11 +25,15 @@ - 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 ` (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 @@ -38,20 +42,22 @@ ## ⚠️ Funcionalidades Pendientes - **Gestión de Tareas** - - Eliminación opcional de tareas y mejoras de edición + - 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** - - Métricas/observabilidad + - Métricas/observabilidad (contadores, latencias, tamaño de cola, endpoint /metrics). - **Validaciones** - - Permisos de usuario (roles) y pertenencia a grupos (si se requiere política estricta) + - 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. Añadir tests de Fase 3 (ver/x, entradas extendidas) y paginación “… y X más”. -2. Mejorar UX de menciones: resolver nombres y formateo de “asignados”. -3. Unificar y pulir formatos de mensajes (dd/MM en todos, compacidad). -4. Mejoras de fiabilidad de la cola: reintentos con backoff y recuperación de `processing`. -5. Métricas/observabilidad básicas y plan de migraciones de DB. +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”. +4. Métricas/observabilidad básicas para ResponseQueue (contadores, latencias, /metrics). ## 🐞 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. @@ -69,14 +75,13 @@ - Etapa 4 — Limpieza/retención: COMPLETADA. ## Commit history and status -- Latest status: All unit tests passing; Phase 2 completada; ACK to creator always in single-line format; optional group notify disabled by default; ContactsService avoids network calls under tests; basic name resolution via ContactsService integrated. +- 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 ver` (grupo y mis) y `/t x `. -- Asegurar comportamiento “solo DM” en `src/server.ts` (no responder en grupos). -- Extender `TaskService` con métodos `claimTask`, `unassignTask`, `completeTask`. -- Afinar `ResponseQueue` para DMs de listados y confirmaciones (manteniendo metadata de menciones). +- Implementar comandos: `/t tomar ` y `/t soltar ` (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`