From 595e67927675884770c2380946bb8d5ad172df5d Mon Sep 17 00:00:00 2001 From: brobert Date: Tue, 21 Oct 2025 00:31:56 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20actualizar=20documentaci=C3=B3n=20con?= =?UTF-8?q?=20nuevas=20vars=20REACTIONS=5F*=20y=20cambios?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: aider (openrouter/openai/gpt-5) --- README.md | 8 +++++++- docs/operations.md | 4 ++++ docs/plan-reacciones-bot.md | 8 +++----- 3 files changed, 14 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 1225a5b..9551c86 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,7 @@ Taskbot ayuda a coordinar grupos en WhatsApp: crea y asigna tareas, recuerda pen - Alias de identidad con normalización de IDs. - Acceso web por token mágico (/t web) con página intermedia anti-preview y sesión por cookie (idle 2h); tokens de 10 min de un solo uso. - Métricas listas para Prometheus en el endpoint /metrics. +- Acks por reacciones en WhatsApp: 🤖/⚠️ al procesar comandos y ✅ al completar tareas dentro de un TTL configurable; idempotencia y gating por grupo/alcance; requiere Evolution API sendReaction (key.fromMe=false). - Rate limiting por usuario para evitar abuso. - Persistencia simple con SQLite, migraciones automáticas y PRAGMAs seguros (WAL, FK, etc.). @@ -36,7 +37,7 @@ Taskbot ayuda a coordinar grupos en WhatsApp: crea y asigna tareas, recuerda pen 1. Evolution API envía eventos al webhook de Taskbot. 2. El servidor normaliza el mensaje, aplica control de acceso por grupo y rate limit. 3. Los servicios de dominio (tareas, recordatorios, alias, colas) operan sobre SQLite. -4. Las respuestas se encolan y envían a través de Evolution API. +4. Las respuestas y reacciones se encolan y se envían a través de Evolution API. 5. Schedulers ejecutan sincronización de grupos/miembros, recordatorios y tareas de mantenimiento. 6. Las métricas se exponen en /metrics (Prometheus o JSON). 7. Un proxy interno en Bun sirve web y bot bajo el mismo dominio: /webhook y /metrics → bot; el resto → web. Actualmente, la compresión HTTP está desactivada temporalmente (sin Content-Encoding). @@ -69,6 +70,10 @@ Variables clave: - EVOLUTION_API_URL, EVOLUTION_API_INSTANCE, EVOLUTION_API_KEY. - ADMIN_USERS (lista de IDs/JIDs autorizados). - GROUP_GATING_MODE: off | discover | enforce. +- REACTIONS_ENABLED: 'true'|'false' para activar reacciones (por defecto 'false'). +- REACTIONS_SCOPE: 'groups'|'all' para limitar reacciones a grupos o permitir en DMs (por defecto 'groups'). +- REACTIONS_TTL_DAYS: días para permitir la reacción ✅ tras completar (por defecto 14). +- RQ_REACTIONS_MAX_ATTEMPTS: reintentos máximos para jobs de reacción (si no se define, aplica el global). - WHATSAPP_COMMUNITY_ID (para sincronización de grupos). - TZ (por defecto Europe/Madrid). - REMINDERS_GRACE_MINUTES (ventana de gracia tras la hora; por defecto 60). @@ -105,6 +110,7 @@ Consulta: - Etapa 2 (lectura de datos - MVP): completada. GET /api/me/tasks (orden por due_date asc con NULL al final, búsqueda con ESCAPE, filtros soonDays/dueBefore, paginación page/limit), GET /api/me/groups (contadores open/unassigned) y GET /api/groups/:id/tasks (unassignedFirst, onlyUnassigned, limit). UI: /app (Mis tareas, filtros/búsqueda/paginación) y /app/groups (bloque “sin responsable” con prefetch). - Etapa 3 (preferencias): completada. GET/POST /api/me/preferences y página /app/preferences con cálculo de “próximo recordatorio” coherente con la TZ y semántica del bot. - Edición de tareas en web: completada. Reclamar/soltar, editar fecha y descripción desde /app; completar tareas y mostrar “Completadas (24 h)”; reclamar desde /app/groups; lista "sin responsable" sin límite y fichas ordenadas por cantidad de "sin responsable" (con gating y validación). +- Reacciones en WhatsApp: completadas. 🤖/⚠️ al procesar comandos y ✅ al completar dentro de TTL; idempotencia, gating por grupo (enforce) y alcance configurable (groups|all). - Roadmap y contribuciones: pendientes de publicación. ## Enlaces diff --git a/docs/operations.md b/docs/operations.md index 4d1ad6e..3de1534 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -19,6 +19,10 @@ Variables de entorno (principales) - TZ: zona horaria para recordatorios (default Europe/Madrid). - REMINDERS_GRACE_MINUTES: minutos de gracia tras la hora programada para enviar recordatorios atrasados (por defecto 60). - GROUP_GATING_MODE: 'off' | 'discover' | 'enforce' (control de acceso por grupos; por defecto 'off'). Ej.: GROUP_GATING_MODE='discover' +- REACTIONS_ENABLED: 'true'|'false' para activar reacciones (por defecto 'false'). Ej.: REACTIONS_ENABLED='true' +- REACTIONS_SCOPE: 'groups'|'all' para limitar reacciones a grupos o permitir en DMs (por defecto 'groups'). Ej.: REACTIONS_SCOPE='groups' +- REACTIONS_TTL_DAYS: días para permitir la reacción ✅ al completar respecto al mensaje origen (por defecto 14). Ej.: REACTIONS_TTL_DAYS='14' +- RQ_REACTIONS_MAX_ATTEMPTS: reintentos máximos para jobs de reacción (si no se define, aplica el global). Ej.: RQ_REACTIONS_MAX_ATTEMPTS='3' - ADMIN_USERS: lista separada por comas de IDs/JIDs autorizados para /admin (se normalizan a dígitos). Ej.: ADMIN_USERS='34600123456, 5554443333, +34 600 111 222' - ALLOWED_GROUPS: lista separada por comas de group_id@g.us para sembrado inicial en arranque. Ej.: ALLOWED_GROUPS='12345-67890@g.us, 11111-22222@g.us' - NOTIFY_ADMINS_ON_DISCOVERY: 'true'/'false' para avisar por DM a ADMIN_USERS al descubrir un grupo (modo 'discover'). Ej.: NOTIFY_ADMINS_ON_DISCOVERY='true' diff --git a/docs/plan-reacciones-bot.md b/docs/plan-reacciones-bot.md index cf783d2..f9cc4a4 100644 --- a/docs/plan-reacciones-bot.md +++ b/docs/plan-reacciones-bot.md @@ -17,7 +17,7 @@ No se añaden mensajes al chat; solo reacciones. Por defecto solo en grupos. Tod - No reaccionar en DMs salvo que se configure explícitamente (REACTIONS_SCOPE=all). - Una reacción por comando (no usar “procesando”/“pensando”). - No borrar/reemplazar reacciones anteriores; simplemente añadir la correspondiente (🤖/⚠️) y, si aplica, luego ✅. -- TTL para marcar ✅ tras completar: 14 días por defecto (configurable 7–14). +- TTL para marcar ✅ tras completar: 14 días por defecto (configurable vía REACTIONS_TTL_DAYS). Emojis: - Éxito de procesamiento: 🤖 @@ -30,7 +30,7 @@ Emojis: Añadir variables de entorno: - REACTIONS_ENABLED=true|false (default: false) -- REACTIONS_TTL_DAYS=14 (admisible 7–14) +- REACTIONS_TTL_DAYS=14 (configurable; sin clamp, por defecto 14) - REACTIONS_SCOPE=groups|all (default: groups) - (Opcional) RQ_REACTIONS_MAX_ATTEMPTS=3 para limitar reintentos de jobs de reacción @@ -110,9 +110,7 @@ Fase 1 — Infra y reacción final por comando - Si REACTIONS_ENABLED=false → no hacer nada. - Si REACTIONS_SCOPE=groups y no es grupo → no hacer nada. - Si GROUP_GATING_MODE='enforce' y el grupo no está allowed → no hacer nada. - - Determinar outcome: - - Recomendado: usar un wrapper `handleWithOutcome` en CommandService que devuelva `{ responses, ok: boolean, createdTaskIds?: number[] }`. - - Alternativa mínima (temporal): heurística sobre texto (mensajes que empiezan con “ℹ️ Uso: …”, “No puedes …”, “no encontrada”, “Acción … no reconocida”, “⚠️ …” → error). + - Determinar outcome con `handleWithOutcome` en CommandService que devuelve `{ responses, ok: boolean, createdTaskIds?: number[] }` (implementado). - Encolar job con emoji = ok ? 🤖 : ⚠️, `chatId=remoteJid`, `messageId`. - Idempotencia: consulta previa antes de insertar. - src/services/command.ts