taskbot/docs/commands-inventory.md

Inventario de Comandos del Bot de Tareas

Ámbito: WhatsApp (DM y grupos)
Objetivo: fuente única y estable de copy y comportamiento actual.

Notas generales

• El bot responde por DM, incluso cuando escribes en un grupo, salvo mensajes muy concretos de estado. En modo de “gating” estricto de grupos (GROUP_GATING_MODE='enforce'), si el grupo no está permitido, el bot puede no responder en absoluto.
• Zona horaria: se usa TZ (por defecto Europe/Madrid) para calcular “hoy”, “mañana” y vencimientos.
• IDs: se muestran con 4 dígitos (ej.: 0026), pero puedes escribirlos sin ceros (ej.: 26).
• Límite de listados: 10 elementos por sección; si hay más, se muestra “... y N más”.
• Fechas: formato visual DD/MM; indicador de vencida con ⚠️.

---

/t nueva (crear)

Alias: n, nueva, crear, +
Sintaxis: /t n <descripción> [fecha] [@menciones...]

Parámetros

• descripción: texto libre.
• fecha (opcional): formatos aceptados:
  • YYYY-MM-DD
  • YY-MM-DD (se expande a 20YY-MM-DD)
  • Tokens naturales: hoy, mañana (con o sin acento)
  • Se ignora puntuación adyacente simple; se usa la última fecha válida encontrada; no se aceptan fechas pasadas.
• @menciones (opcional): puedes mencionar JIDs crudos o tokens @.... Se filtran no plausibles y se intenta resolver alias. Si no se puede, se envía un DM al creador con instrucciones de onboarding (activar).

Asignación por contexto

• En grupos: si no hay menciones, la tarea queda “sin responsable”.
• En DM: si no hay menciones, se asigna al creador.

Grupo asociado

• Solo se asigna group_id si el grupo está activo. Si GROUP_GATING_MODE='enforce' y el grupo no está permitido, se crea “sin grupo”.

Ejemplos

• /t n Preparar informe 2025-11-05 @600123456
• /t + Comprar pan mañana
• /t crear Llamar a proveedores @ana @juan
• /t n Presentación 25-02-02 (→ 2025-02-02)

---

/t ver (listar)

Alias: ver, mostrar, listar, ls
Sintaxis: /t ver [grupo|mis|todos|sin] (el alcance es opcional)

Alcances

• grupo: lista pendientes del grupo actual (solo desde grupo activo).
• mis: tus tareas pendientes (por DM).
• todos: “Tus tareas” + “sin responsable”.
  • En grupo: incluye “sin responsable” solo del grupo actual (compatibilidad).
  • En DM: incluye “sin responsable” de todos los grupos donde eres miembro activo (si el snapshot de membresía es fresco).
• sin: solo tareas sin responsable del grupo actual (desde grupo).

Indicadores

• Fechas en DD/MM.
• ⚠️ delante de la fecha si está vencida (según TZ configurada).

Límites

• Máx. 10 elementos por sección; si hay más, se añade “... y N más”.

Ejemplos

• En grupo: /t ver (equivale a grupo), /t ver sin
• Por DM: /t ver mis, /t ver todos

---

/t x (completar)

Alias: x, hecho, completar, done
Sintaxis: /t x <id|id,id,...|id id ...>
Soporta múltiples IDs separados por espacios y/o comas. Máx. 10 IDs.

Resolución de ID

• Primero intenta display_code (código corto de 4 dígitos) en tareas activas; si no, usa el ID real.

Gating de membresía (opcional)

• Si GROUP_MEMBERS_ENFORCE=true y el snapshot del grupo es fresco, debes ser miembro activo para completar.

Ejemplos

• /t x 26
• /t x 14 19 24
• /t x 14,19,24

---

/t tomar (asumir)

Alias: tomar, claim, asumir, asumo
Sintaxis: /t tomar <id|id,id,...|id id ...>
Múltiples IDs; máx. 10.

Gating de membresía (opcional)

• Si GROUP_MEMBERS_ENFORCE=true y snapshot fresco, debes ser miembro activo para tomar tareas del grupo.

Ejemplos

• /t tomar 12
• /t tomar 12 19 50
• /t tomar 12,19,50

---

/t soltar (unassign)

Alias: soltar, unassign, dejar, liberar, renunciar
Sintaxis: /t soltar <id>
Un solo ID.

Gating de membresía (opcional)

• Si GROUP_MEMBERS_ENFORCE=true y snapshot fresco, debes ser miembro activo para soltar tareas del grupo.

Ejemplos

• /t soltar 26

---

/t configurar (recordatorios)

Alias: config, configurar
Sintaxis: /t configurar diario|l-v|semanal|off [HH:MM]

Valores admitidos y alias

• diario/diaria → recordatorio diario (se guarda como daily).
• laborables (l-v, lv) → lunes a viernes (se guarda como weekdays).
• semanal → semanal (asume lunes; se guarda como weekly).
• off/apagar/ninguno → sin recordatorios (se guarda como off).

Hora

• Formato HH:MM (minutos 00–59; hora se normaliza a 0–23).
• Si omites la hora, se conserva la anterior o se usa 08:30 por defecto (y lunes para semanal).

Nota de localización

• Internamente se almacenan claves en inglés (daily, weekdays, weekly, off), pero el copy al usuario es en español. Pendiente de revisión futura para evitar fugas como “weekly” en mensajes.

Ejemplos

• /t configurar diaria 09:00
• /t configurar l-v 08:30
• /t configurar semanal (→ lunes 08:30)
• /t configurar off

---

/t ayuda

Alias: ayuda, help, ?
Sintaxis: /t ayuda | /t ayuda avanzada

Comportamiento actual

• Ayuda rápida con comandos básicos, límites y ejemplos cortos.
• “Ayuda avanzada” lista alias y detalla opciones y límites.

Nota

• El contenido de ayuda está centralizado y consistente.

---

/t web

Sintaxis: /t web (solo por DM)

Descripción

• Genera un token de acceso one‑shot válido 10 minutos, invalida tokens previos y devuelve una URL de login basada en WEB_BASE_URL.

Ejemplo

• Acceso web: https://…/login?token=...
  “Válido durante 10 minutos. Si caduca, vuelve a enviar /t web.”

---

Comandos desconocidos

Ante comandos no reconocidos, el bot responde por DM con un mensaje que incluye el encabezado “❓ Comando no reconocido”, la sugerencia “Prueba /t ayuda” y la ayuda rápida inline.

Notas adicionales

• Estilo y formato:
  • IDs: codeId() → 4 dígitos entre backticks.
  • Fechas: formatDDMM() → DD/MM.
  • Estilos disponibles: negrita *...*, cursiva _<...>_. Próximamente: code(), section(), bullets().
• Gating de grupos:
  • Si GROUP_GATING_MODE='enforce' y el grupo no está permitido, los comandos en ese grupo pueden quedar bloqueados (sin respuesta).
• Membresía de grupo:
  • Si GROUP_MEMBERS_ENFORCE=true y el snapshot es fresco, algunas acciones requieren ser miembro activo (ver grupo, completar, tomar, soltar).