From 3d73988c66d5ab2676151042cacc4d472842b463 Mon Sep 17 00:00:00 2001 From: borja Date: Sat, 6 Sep 2025 12:27:25 +0200 Subject: [PATCH] docs: actualiza README y STATUS para reflejar estado y fallo de pruebas Co-authored-by: aider (openrouter/openai/gpt-5) --- README.md | 40 +++++++++++++++++++++++----------------- STATUS.md | 35 +++++++++++++++++------------------ 2 files changed, 40 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 11751cf..efeaf93 100644 --- a/README.md +++ b/README.md @@ -84,30 +84,36 @@ Estado: la tabla response_queue ya está creada e incluida en los tests de DB. - Limpieza/retención y métricas/observabilidad. - Opcional: idempotencia e índices adicionales. -## ✅ Current Status (as of latest commit, all tests passing) +## ✅ Current Status (as of latest commit) ### Implemented - Webhook server setup (`src/server.ts`) receiving Evolution API events. -- Database schema definition and initialization (`src/db.ts`). -- Group synchronization service (`src/services/group-sync.ts`) to fetch/store/cache groups. Includes active group caching. +- Database schema definition and initialization (`src/db.ts`), including lightweight migration to add `response_queue.metadata`. +- Group synchronization service (`src/services/group-sync.ts`) to fetch/store/cache groups. Includes active group caching and `isGroupActive` checks in server. - Webhook registration and verification with Evolution API (`src/services/webhook-manager.ts`). - WhatsApp ID normalization utility (`src/utils/whatsapp.ts`). -- User creation function (`src/db.ts::ensureUserExists`). -- Basic `/tarea` command detection (`src/server.ts`) and processing structure (`src/services/command.ts` - logic is placeholder). -- Task data models (`src/tasks/model.ts`). -- Basic task creation service stub (`src/tasks/service.ts` - needs `created_by` and assignment logic). -- Response queue persistente con workers en background y envío vía Evolution API (`src/services/response-queue.ts`). +- User creation/update function (`src/db.ts::ensureUserExists`) integrated into the main flow. +- Command handling for `/tarea nueva` end-to-end (`src/services/command.ts`): + - Parses description and selects the last future date (YYYY-MM-DD) as due date. + - Extracts assignees from explicit mentions and plain-text @tokens; defaults to creator only when none found. + - 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`. +- 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. - Environment variable validation (`src/server.ts`, `src/services/webhook-manager.ts`). - Health check endpoint (`/health`). -- **User validation integration**: Normalization and `ensureUserExists` are now fully integrated in the main message handling flow (`src/server.ts`). -- **Comprehensive test suite**: All tests pass (97 pass, 0 fail), including integration tests for user validation. -- **Database isolation in unit tests**: Implemented using in-memory instances to avoid conflicts between tests. +- **Database isolation in unit tests**: Using in-memory instances to avoid conflicts. ### Incomplete / Missing Core Functionality -- **Filtro de grupos activos:** La sincronización existe y hay caché; queda por reforzar el uso del filtro de grupos activos en `src/server.ts` si se requiere un bloqueo más estricto. -- **Core Command Logic:** Actual processing of `/tarea nueva` (parsing args, calling `TaskService`) is missing in `CommandService`. Other commands (`mostrar`, `completar`) not implemented. -- **Task Service Implementation:** `TaskService` needs updating to handle `created_by`, assignments, and potentially methods for listing/completing tasks. -- **Database Migrations:** No system in place to manage schema changes. -- **Robust Error Handling:** Comprehensive error handling, logging, and transaction management need improvement, especially around API calls and DB operations. +- 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). +- 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. +- Test suite: currently 1 failing test — “Database > Table Schemas > response_queue table should have required columns”. ## 🛠️ Setup ### Environment Variables @@ -202,7 +208,7 @@ bun test - WhatsApp ID normalization (`whatsapp.test.ts`). - Group sync operations (`group-sync.test.ts`). - **Needed:** Tests for `ensureUserExists` integration, `isGroupActive` integration, `CommandService` logic, `ResponseQueue` processing (mocking API), `TaskService` operations. -- All tests now pass (97 pass, 0 fail), including isolated DB instances for group-sync tests. +- Tests mostly pass; currently 1 failing test: “Database > Table Schemas > response_queue table should have required columns”. ## 🧑‍💻 Contributing 1. Fork the repository diff --git a/STATUS.md b/STATUS.md index d79d65d..a11fdc3 100644 --- a/STATUS.md +++ b/STATUS.md @@ -9,51 +9,50 @@ - Modelo de tareas y asignaciones - Normalización de IDs de WhatsApp - Transacciones atómicas + - Esquema de `response_queue` extendido con columna `metadata` (migración ligera al inicio) - **Sincronización de Grupos** - - Cache de grupos activos + - Caché de grupos activos y validación en el servidor - Sync periódico con Evolution API - **Webhooks** - Registro/verificación con Evolution API - - Manejo básico de eventos (MESSAGES_UPSERT) - - Normalización del nombre del evento del webhook (soporta MESSAGES_UPSERT/messages.upsert) + - Manejo de eventos (MESSAGES_UPSERT) con normalización del nombre del evento - **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 - **Comandos** - - Detección de /tarea - - Parser básico de acciones/fechas + - `/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. - **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 completa de tests unitarios - - Todos los tests pasan (97 pass, 0 fail) -- **Aislamiento de Base de Datos en Pruebas** - - Uso de instancias en memoria para evitar conflictos entre tests + - Suite de tests unitarios con DB en memoria para aislamiento ## ⚠️ Funcionalidades Pendientes - **Gestión de Tareas** - - Completar persistencia de creación (añadir `created_by` y asignaciones) - - Listar/completar/eliminar tareas + - Listar (`/tarea mostrar`) y completar (`/tarea completar`) tareas; eliminación opcional - **Cola de Respuestas** - Reintentos con backoff y jitter - Recuperación de ítems en estado `processing` tras caídas - Métricas/observabilidad y limpieza/retención - **Validaciones** - - Permisos de usuario no implementados - - Verificación de pertenencia a grupos (si se requiere política estricta) -- **Comandos** - - Implementar `/tarea mostrar` y `/tarea completar` + - 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) - **Migraciones** - Sistema de migraciones de esquema ## ➡️ Próximos Pasos Prioritarios -1. Completar persistencia de tareas: `created_by` y asignaciones con `ensureUserExists`. -2. Implementar comandos: `/tarea mostrar` y `/tarea completar`. +1. Implementar `/tarea mostrar` y `/tarea completar`. +2. Mejorar UX de menciones: resolver nombres y formateo de “asignados”. 3. Extender soporte de entrada: `extendedTextMessage` y captions de media. 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. +## 🐞 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”. +- 1 test falla actualmente: “Database > Table Schemas > response_queue table should have required columns”. + ## 🔧 Archivos Clave a Modificar - `src/services/response-queue.ts` - `src/services/command.ts` @@ -61,4 +60,4 @@ - `src/server.ts` ## Commit history and status -- Latest commit: All tests passing, infrastructure solid, ready for core logic implementation. +- Latest commit: One schema test failing and mentions UX pending; resto verde y funcionalidad principal de creación de tareas operativa.