# Plan de reacciones del bot de tareas (WhatsApp)

Objetivo: añadir un “ack” visual de bajo ruido en grupos, usando reacciones a los mensajes con comandos `/t`. Alcance inicial:
- Reaccionar 1 sola vez por comando:
  - Éxito (comando procesado): 🤖
  - Error (uso inválido, permisos, no encontrada…): ⚠️
- Plus opcional sin mucha complejidad: si el comando creó una tarea y esta se completa dentro de un TTL (7–14 días), reaccionar con ✅ al mensaje origen del comando.

No se añaden mensajes al chat; solo reacciones. Por defecto solo en grupos. Todo detrás de “feature flags”.

---

## 1) UX y reglas

- Ámbito:
  - Grupos permitidos (AllowedGroups) por defecto (REACTIONS_SCOPE=groups).
  - 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 vía REACTIONS_TTL_DAYS).

Emojis:
- Éxito de procesamiento: 🤖
- Error: ⚠️
- Tarea completada (tardío): ✅

---

## 2) Flags/entorno

Añadir variables de entorno:
- REACTIONS_ENABLED=true|false (default: false)
- 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

Se reutilizan:
- GROUP_GATING_MODE (off|discover|enforce)
- AllowedGroups.isAllowed para coherencia con el gating.

---

## 3) Persistencia: nueva tabla `task_origins` (migración v17)

Objetivo: vincular una tarea creada con el mensaje de WhatsApp que originó el comando para poder reaccionar con ✅ al completarse.

Esquema:
- task_id INTEGER PRIMARY KEY REFERENCES tasks(id) ON DELETE CASCADE
- chat_id TEXT NOT NULL        // JID completo del grupo (p. ej. 123@g.us)
- message_id TEXT NOT NULL     // id del mensaje del comando
- created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%d %H:%M:%f','now'))

Índices:
- CREATE INDEX IF NOT EXISTS idx_task_origins_task ON task_origins(task_id);
- (Opcional) CREATE INDEX IF NOT EXISTS idx_task_origins_chat_msg ON task_origins(chat_id, message_id);

Notas:
- 1 fila por tarea (PK = task_id). Suficiente para nuestro caso.
- No toca esquemas existentes.

---

## 4) Cola: soporte de “jobs de reacción” en ResponseQueue

Formato del job (reutilizamos `response_queue`, sin cambiar esquema):
- recipient: usar `chatId` (JID) para cumplir NOT NULL.
- message: puede estar vacío (no se usa para reactions).
- metadata (JSON):
  ```
  {
    "kind": "reaction",
    "emoji": "🤖" | "⚠️" | "✅",
    "chatId": "<jid>",
    "messageId": "<msg-id>"
  }
  ```

Envío (Evolution API):
- POST {EVOLUTION_API_URL}/message/sendReaction/{instance}
- Headers: { apikey, Content-Type: application/json }
- Body:
  ```
  {
    "key": { "remoteJid": "<jid>", "fromMe": false, "id": "<msg-id>" },
    "reaction": "<emoji>"
  }
  ```

Reintentos:
- Backoff existente.
- Opcional: limitar reacciones con `RQ_REACTIONS_MAX_ATTEMPTS` (p. ej. 3). 4xx → fallo definitivo; 5xx/red → reintentos.

Idempotencia:
- Antes de insertar, consultar si ya existe (status IN queued|processing|sent) un job con metadata idéntica (mismo chatId, messageId, emoji) en las últimas 24h; si existe, no insertar otro.
- Mantener JSON canónico (mismas claves/orden) al construir metadata para hacer la comparación fiable o parsear JSON en la consulta.

---

## 5) Cambios por fichero (implementación por fases)

Fase 1 — Infra y reacción final por comando
- src/services/response-queue.ts
  - Detectar `metadata.kind === 'reaction'`.
  - Construir y enviar POST a `/message/sendReaction/{instance}` con el payload anterior.
  - Opcional: `RQ_REACTIONS_MAX_ATTEMPTS` para jobs de reacción.
- src/server.ts (WebhookServer)
  - Capturar `messageId = data.key.id`.
  - Pasar `messageId` en el `CommandContext`.
  - Tras ejecutar el comando, decidir emoji:
    - 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 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
  - Ampliar `CommandContext` con `messageId: string`.
  - En la rama `/t nueva`, tras crear la tarea:
    - Si `isGroupId(context.groupId)` y `context.messageId`, insertar fila en `task_origins (task_id, chat_id, message_id)`.
  - (Recomendado) Añadir `handleWithOutcome` para clasificar ok/error sin depender del texto.
- src/db/migrations/index.ts
  - Añadir migración v17 con `task_origins` e índices.

Fase 2 — Reacción tardía (✅) al completar
- src/tasks/service.ts
  - En `completeTask`, cuando `status === 'updated'`:
    - Buscar `task_origins` por `taskId`.
    - Si no existe, salir.
    - Comprobar TTL: `now - created_at <= REACTIONS_TTL_DAYS`.
    - Flags/política: `REACTIONS_ENABLED` y, si `REACTIONS_SCOPE=groups`, que `chat_id` termine en `@g.us`.
    - (Opcional) En modo enforce, verificar AllowedGroups.isAllowed(chat_id).
    - Encolar job `kind:'reaction', emoji:'✅', chatId, messageId`.
    - Idempotencia: mismo check previo antes de insertar.

---

## 6) Flujo E2E (grupo permitido)

1) Usuario envía mensaje con `/t nueva …` en un grupo.
2) WebhookServer:
   - Obtiene `remoteJid`, `messageId`.
   - Construye `CommandContext` con `sender`, `groupId`, `message`, `mentions`, `messageId`.
3) CommandService:
   - Procesa el comando.
   - Si crea tarea: inserta fila en `task_origins`.
4) WebhookServer:
   - Clasifica outcome (ok/err).
   - Si aplica, encola una reacción (🤖 o ⚠️) usando ResponseQueue.
5) Más tarde, alguien completa la tarea:
   - TaskService.completeTask → si dentro del TTL, encola ✅ apuntando al `messageId` original.
6) ResponseQueue:
   - Consume jobs `kind:'reaction'` y llama a Evolution `/message/sendReaction`.

---

## 7) Idempotencia, límites y gating

- Idempotencia:
  - No duplicar reacciones para el mismo (chatId, messageId, emoji) gracias a la consulta previa en `response_queue`.
  - Completar varias veces → solo 1 job ✅ (misma idempotencia).
- Gating:
  - Respetar `GROUP_GATING_MODE='enforce'`: no reaccionar en grupos no permitidos.
  - No reaccionar en DMs salvo `REACTIONS_SCOPE=all`.
- Límites:
  - RateLimiter de comandos ya limita frecuencia.
  - Reintentos de reacciones limitados para evitar ruido prolongado.

---

## 8) Errores previstos y manejo

- Mensaje borrado / bot expulsado / permisos → error 4xx → marcar `failed` sin reintentos excesivos.
- Errores de red/5xx → reintentos con backoff hasta `RQ_REACTIONS_MAX_ATTEMPTS` (si definido) o los globales.
- Falta de `messageId` en el evento → omitir reacciones y `task_origins` (no romper el flujo).

---

## 9) Pruebas a añadir

Unitarias:
- Reacción final:
  - Grupo allowed, `REACTIONS_ENABLED=true`, `/t nueva …` → se encola 🤖 (1 job con metadata.kind='reaction', emoji='🤖', chatId=grupo, messageId capturado).
  - Comando inválido (p. ej. `/t x` sin IDs) → se encola ⚠️.
  - DM con `REACTIONS_SCOPE=groups` → no se encola.
  - `REACTIONS_ENABLED=false` → no se encola.
- task_origins:
  - Tras `/t nueva` en grupo, existe `task_origins(task_id, chat_id, message_id)`.
- Completar → ✅:
  - Dentro de TTL → se encola ✅ con el `messageId` de origen.
  - Fuera de TTL → no se encola.
  - Completar dos veces → solo 1 job ✅ (idempotencia).
- ResponseQueue:
  - Jobs `kind:'reaction'` llaman a `/message/sendReaction…` (no a sendText).
  - Manejo de 4xx/5xx conforme a política de reintentos.

Integración simulada:
- Flujo feliz: `/t nueva` → 🤖; `completeTask` → ✅.
- Error: comando desconocido o “Uso:” → ⚠️.
- Grupo bloqueado en enforce → no reacción.

---

## 10) Despliegue y configuración

- Añadir flags al entorno:
  - `REACTIONS_ENABLED=false` (arranque en “off”).
  - `REACTIONS_TTL_DAYS=14`.
  - `REACTIONS_SCOPE=groups`.
  - (Opcional) `RQ_REACTIONS_MAX_ATTEMPTS=3`.
- Aplicar migraciones (incluye v17: `task_origins`).
- Activar `REACTIONS_ENABLED` gradualmente y monitorizar efectos.

---

## 11) Consideraciones

- Notificaciones: algunos usuarios reciben notificación por reacciones; una sola por comando minimiza ruido.
- Privacidad: no se envían datos nuevos; solo reacciones en el mismo chat.
- Observabilidad: se puede añadir contadores de métricas (opcional):
  - `reactions_enqueued_total{emoji=…}`, `reactions_sent_total`, `reactions_failed_total`.

---

## 12) Trabajos futuros (opcional)

- Debounce de “procesando” (⏳) >1–2s y reemplazo por 🤖.
- Opt-out por grupo (preferencia guardada en DB).
- Cambio de reacción previa (quitar ⚠️/🤖 y dejar solo ✅) — requiere leer/gestionar estado de reacciones y añade complejidad.
- Reaccionar a otros comandos (tomar/soltar) con emojis específicos.