@ -9,6 +9,8 @@ This service provides a WhatsApp interface for task management within WhatsApp g
- Synchronizes group information periodically from the Evolution API.
- 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.
- Optional: group notification on task creation controlled by NOTIFY_GROUP_ON_CREATE (default false), including proper mentions for visibility.
## 🔐 Security Model
- **Internal Networking**: The webhook should ideally only accept connections from Evolution API via internal Docker networking (configuration dependent).
@ -100,6 +102,8 @@ Estado: la tabla response_queue ya está creada e incluida en los tests de DB.
- Builds response with assignment list and includes Evolution API “mentioned” JIDs via `ResponseQueue`.
- 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.
- 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).
- Notification UX: DM acknowledgment to creator (skipped if creator is the only assignee), DM to each assignee; optional group notification controlled by `NOTIFY_GROUP_ON_CREATE` (default false) with proper mentions.
- **Database isolation in unit tests**: Using in-memory instances to avoid conflicts.
@ -107,12 +111,12 @@ Estado: la tabla response_queue ya está creada e incluida en los tests de DB.
### Incomplete / Missing Core Functionality
- Additional commands: `/tarea mostrar` (list) y `/tarea completar`.
- ResponseQueue reliability: reintentos con backoff, recuperación de `processing`, métricas y limpieza/retención.
- Contact names: optional service/cache to resolve friendly names from Evolution API for nicer “@Nombre” rendering in text (the app already sends `mentioned` JIDs).
- ContactsService improvements (optional): refine caching policy and endpoints; basic friendly-name resolution is already implemented and used in outgoing texts.
- Database migrations system (beyond current lightweight on-boot checks).
- More robust error handling and observability around API/DB operations.
### Known Issues
- Mentions UX: although we send `mentioned` JIDs, WhatsApp still shows “@número” in the text. This is expected unless we replace the text with a friendly name known to the bot; the client renders the highlight but doesn’t rewrite the text to each user’s local contact name.
- Mentions UX: In group chats, mentions are highlighted and each client resolves the chip to their local contact name; we include friendly names in text when available. In direct messages, WhatsApp does not render mention chips for third parties, so we include the number as @digits for quick action; no per-recipient name rewriting occurs.
- Test suite: currently 1 failing test — “Database > Table Schemas > response_queue table should have required columns”.
## 🛠️ Setup
@ -137,6 +141,7 @@ NODE_ENV=production # Or development
# Optional
# GROUP_SYNC_INTERVAL_MS=3600000 # Sync interval in ms (default: 24h)
# NOTIFY_GROUP_ON_CREATE=false # If 'true', also post a brief summary with mentions to the group
- Soporte de menciones: persistencia en `metadata` y envío como `mentioned` en el payload
- **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.
- **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).
- **UX de Notificaciones**
- Confirmación por DM al creador (omitida si es el único asignado) y DM a cada asignado.
- Notificación opcional al grupo controlada por `NOTIFY_GROUP_ON_CREATE` (false por defecto), incluyendo menciones para visibilidad.
- **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,7 +43,7 @@
- **Validaciones**
- Permisos de usuario (roles) y pertenencia a grupos (si se requiere política estricta)
- **Menciones y nombres**
- Resolver nombres “amigables” desde Evolution API y/o cache local para reemplazar `@número` por `@Nombre` en el texto (ya se envía `mentioned` para resaltar)
- 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).
- **Migraciones**
- Sistema de migraciones de esquema
@ -50,7 +55,7 @@
5. Métricas/observabilidad básicas y plan de migraciones de DB.
## 🐞 Problemas conocidos
- Las menciones en WhatsApp no muestran todavía el nombre del contacto del usuario final; se envía `mentioned` correctamente, pero el texto contiene `@número`. Pendiente integrar nombres “amigables”.
- 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.
- 1 test falla actualmente: “Database > Table Schemas > response_queue table should have required columns”.
## 🔧 Archivos Clave a Modificar
@ -60,4 +65,4 @@
- `src/server.ts`
## Commit history and status
- Latest commit: One schema test failing and mentions UX pending; resto verde y funcionalidad principal de creación de tareas operativa.
- Latest status: One schema test still failing; DM notifications to creator/assignees implemented; optional group notify disabled by default; basic name resolution via ContactsService integrated.
