brobert
/
taskbot
1
0
Fork 0
Code Issues Pull Requests 1 Packages Projects Releases Wiki Activity
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
main
webui
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '04a3dd13f7'
${ noResults }
taskbot/docs/plan-ayuda-bot.md

12 KiB
Raw Blame History

Plan de Modernización de Ayuda y Estilo de Mensajes (Help v2)

Estado: propuesta
Ámbito: bot (responde siempre por DM)
Objetivo: hacer la ayuda consistente, útil ante comandos desconocidos, visible el acceso web, y estandarizar el estilo de todos los mensajes.

Principios

  • Responder siempre por DM (incluso si el comando se escribe en un grupo).
  • Ayuda accesible y progresiva: ayuda rápida en flujos comunes y ayuda extendida bajo demanda.
  • Estilo WhatsApp consistente: secciones en negrita y mayúsculas, listas con “- ”, comandos en monoespaciado, notas en cursiva.
  • Fuente única para contenidos de ayuda (centralizar copy).
  • Cambios compatibles con tests: minimizar fragilidad de asserts por copy.

Inventario de comandos actual (derivado de src/services/command.ts)

  • Crear
    • Comandos: /t n, /t nueva, /t crear, /t +
    • Soporta: fecha explícita YYYY-MM-DD, YY-MM-DD (expande a 20YY), tokens hoy/mañana
    • Asignación:
      • En DM: por defecto asignada al creador si no hay menciones
      • En grupo: por defecto “sin responsable” si no hay menciones
    • Menciones: detecta @tokens y JIDs crudos; filtra no plausibles; emite DM “JIT onboarding” si no se pudo resolver
  • Ver
    • Comando base: /t ver (alias: ver, mostrar, listar, ls)
    • Alcances: grupo (si se escribe desde grupo activo), mis (DM), todos (mis + sin responsable de grupos donde soy miembro activo), sin (solo sin responsable del grupo actual)
    • Límite: 10 ítems; “… y N más” cuando excede
    • Indicadores:
      • Fecha en formato DD/MM
      • Aviso de vencida (⚠️) cuando due_date < hoy (calculado por TZ configurada)
  • Completar
    • Comandos: /t x, /t hecho, /t completar, /t done
    • Acepta múltiples IDs (separados por espacios y/o comas); máx. 10
    • Resolución de ID: primero por display_code de tareas activas; si no, por PK
    • Gating opcional: si GROUP_MEMBERS_ENFORCE=true y snapshot fresca, requiere ser miembro activo
  • Tomar
    • Comandos: /t tomar, /t claim, /t asumir, /t asumo
    • Múltiples IDs; máx. 10; gating de membresía igual que “completar”
  • Soltar
    • Comandos: /t soltar, /t unassign, /t dejar, /t liberar, /t renunciar
    • Un solo ID
  • Configurar recordatorios
    • Comandos: /t configurar daily|l-v|weekly|off [HH:MM]
    • Mapea alias a daily, weekdays, weekly, off; hora opcional con normalización
  • Ayuda
    • Comandos: /t ayuda, /t help, /t ?, y variante “ayuda avanzada”
    • Actualmente genera mensajes en línea (no centralizados)
  • Web
    • Comando: /t web
    • Genera token one-shot, invalida tokens previos, devuelve URL de login basada en WEB_BASE_URL
  • Notas de formato ya en uso
    • IDs se muestran con 4 dígitos (backticks)
    • Estilos disponibles: bold, italic; se usa codeId() para IDs y formatDDMM() para fechas

Roadmap por fases

Fase 0 — Documentación de inventario y estilo (docs)

  • Objetivo: dejar por escrito el inventario de comandos y una guía de estilo para WhatsApp.
  • Tareas:
    • Crear docs/commands-inventory.md con matriz de comandos, alias, alcance, ejemplos, límites y prerequisitos.
    • Crear docs/whatsapp-style-guide.md con convenciones de formato y ejemplos.
  • Archivos a crear:
    • docs/commands-inventory.md
    • docs/whatsapp-style-guide.md
  • Criterios de aceptación:
    • El inventario cubre todos los comandos listados arriba.
    • La guía incluye: secciones, comandos en monoespaciado, bullets, notas en cursiva y ejemplos cortos.

Fase 1 — Helpers mínimos de formato (código)

  • Objetivo: ofrecer utilidades simples y reutilizables sin romper lo existente.
  • Cambios:
    • Extender src/utils/formatting.ts añadiendo:
      • export function code(s: string): string → wrap con backticks
      • export function section(s: string): string → *${s.toUpperCase()}*
      • export function bullets(items: string[]): string → - ${item} por línea
  • Archivos a tocar:
    • src/utils/formatting.ts (añadir funciones)
  • Tests:
    • Nuevo: tests/unit/utils/formatting.test.ts (para code, section, bullets)
  • Criterios de aceptación:
    • Formateadores devuelven exactamente el formato esperado y no rompen los existentes.

Fase 2 — Centralizar contenido de ayuda

  • Objetivo: tener una única fuente de verdad para la ayuda.
  • Cambios:
    • Crear src/services/messages/help.ts con:
      • getQuickHelp(baseUrl?: string): string
      • getFullHelp(baseUrl?: string): string
    • Contenido sugerido (resumen):
      • Ayuda rápida:
        • Secciones: “COMANDOS BÁSICOS”, “LISTADOS”, “ACCESO WEB”
        • Bullets con: crear (/t n ...), ver (/t ver mis|grupo|todos|sin), completar/tomar/soltar, configurar recordatorios, y /t web
        • Nota: El bot responde por DM, incluso si escribes desde un grupo.
      • Ayuda extendida:
        • Además: formatos de fecha (YYYY-MM-DD, YY-MM-DD→20YY-MM-DD, hoy|mañana), límites (máx. 10 IDs), reglas de asignación por contexto, gating de grupos, detalles de “ver todos”.
  • Archivos a crear:
    • src/services/messages/help.ts
  • Archivos a consultar:
    • src/services/command.ts (para mantener alineación de copy con funcionalidad)
  • Tests:
    • Nuevo: tests/unit/services/help-content.test.ts (asserts por substrings clave, no igualdad exacta)
  • Criterios de aceptación:
    • getQuickHelp() incluye /t web y comandos básicos.
    • getFullHelp() cubre scopes de “ver”, formatos de fecha y límites.

Fase 3 — Comportamiento ante comandos desconocidos

  • Objetivo: responder útilmente cuando no se reconoce la acción.
  • Cambios en src/services/command.ts:
    • Reemplazar la respuesta “Acción X no implementada aún” por:
      • Encabezado tipo: *NO RECONOCÍ ESE COMANDO*
      • Sugerencia: “Prueba /t ayuda”
      • Adjuntar getQuickHelp(baseUrl) en el mismo mensaje
    • Mantener logging/telemetría si aplica (ej. Metrics.inc('commands_unknown_total') opcional)
  • Archivos a tocar:
    • src/services/command.ts
    • src/services/messages/help.ts (uso desde aquí)
  • Tests:
    • Nuevo: tests/unit/services/command.unknown-help.test.ts
      • Input: /t qué tareas tengo hoy?
      • Expect: mensaje contenga indicador de comando desconocido, /t ayuda, y fragmentos de quick help (p.ej., /t ver mis, /t web)
  • Criterios de aceptación:
    • DM siempre; mensaje claro y accionable.

Fase 4 — Unificar el comando /t ayuda

  • Objetivo: que /t ayuda y “ayuda avanzada” usen el módulo centralizado.
  • Cambios en src/services/command.ts:
    • Si ayuda con “avanzada” → getFullHelp(baseUrl)
    • Si ayuda sin “avanzada” → getQuickHelp(baseUrl) + CTA a “ayuda avanzada”
    • Quitar los textos embebidos actuales en command.ts para estos casos
  • Archivos a tocar:
    • src/services/command.ts
    • src/services/messages/help.ts
  • Archivos a consultar:
    • src/services/command.ts (acción ayuda)
  • Tests:
    • Nuevo: tests/unit/services/command.help.test.ts
      • “/t ayuda” incluye /t web
      • “/t ayuda avanzada” incluye scopes de “ver” y formatos de fecha
  • Criterios de aceptación:
    • Ayuda centralizada y consistente en ambos modos.

Fase 5 — Flag de activación y configuración

  • Objetivo: habilitar rollback rápido si hiciera falta.
  • Cambios:
    • Soportar FEATURE_HELP_V2 (por defecto true). Si false, usar el comportamiento actual (fallback).
    • Fuente para baseUrl: process.env.WEB_BASE_URL (ya empleada por /t web); pasarla opcionalmente a help.ts.
  • Archivos a tocar:
    • src/services/command.ts (condicionar branches de ayuda/fallback con el flag)
    • src/services/messages/help.ts (aceptar baseUrl?)
  • Tests:
    • Añadir caso con FEATURE_HELP_V2=false que mantenga el behavior anterior (solo si compensa; opcional).
  • Criterios de aceptación:
    • Con flag on/off, el bot responde acorde.

Fase 6 — Estilo global en mensajes (incremental)

  • Objetivo: aplicar el estilo unificado en más respuestas (crear, tomar, soltar, completar, ver).
  • Cambios (incrementales, por PRs pequeños):
    • Introducir helpers de estilo donde falten (bold, italic, code, section, bullets)
    • Estandarizar encabezados, bloques de detalle y notas
  • Archivos a tocar:
    • src/services/command.ts (copys de confirmaciones y listados)
    • Potenciales módulos de mensajes: src/services/messages/*.ts (si extraemos piezas)
  • Tests:
    • Actualizar asserts frágiles para comparar substrings semánticos, o crear helper de test stripFormatting que quite *, _, ` para aserciones menos frágiles.
  • Criterios de aceptación:
    • Mensajes alineados con la guía de estilo, sin romper funcionalidad.

Fase 7 — Tests y mantenimiento

  • Nuevos tests a añadir:
    • tests/unit/utils/formatting.test.ts
    • tests/unit/services/help-content.test.ts
    • tests/unit/services/command.unknown-help.test.ts
    • tests/unit/services/command.help.test.ts
  • Tests existentes a revisar (no editar salvo necesario):
    • tests/unit/services/command.*.test.ts
    • tests/unit/server.*.test.ts (si comparan copys)
    • tests/unit/web/* no deberían verse afectados
  • Estrategia:
    • Preferir asserts por “contiene” para evitar fragilidad.
    • Añadir helper stripFormatting en tests si se requiere.

Archivos implicados

  • A crear (docs):
    • docs/commands-inventory.md
    • docs/whatsapp-style-guide.md
  • A crear (código):
    • src/services/messages/help.ts
  • A modificar (código — ya disponibles en este chat):
    • src/services/command.ts
    • src/utils/formatting.ts
  • A consultar (sin cambios, solo referencia):
    • src/services/webhook-manager.ts (no requiere cambios para Help v2)
  • A modificar (tests — NO añadidos aún a este chat; cuando llegue el momento, añadir):
    • tests/unit/utils/formatting.test.ts
    • tests/unit/services/help-content.test.ts
    • tests/unit/services/command.unknown-help.test.ts
    • tests/unit/services/command.help.test.ts

Cuando ejecutemos las fases de código/tests, si estos archivos no están en el chat, pediré que los añadas para poder proponer los parches exactos.

Criterios de aceptación globales

  • Un comando desconocido devuelve un mensaje útil con ayuda rápida (incluye /t ayuda y referencia a /t web).
  • /t ayuda usa contenido centralizado; “ayuda avanzada” despliega la versión extendida.
  • Estilo consistente: secciones en negrita y mayúsculas; comandos/IDs en monoespaciado; listas con “- ”; notas en cursiva.
  • Documentación (inventario y guía de estilo) creada.
  • Tests nuevos cubriendo formateadores y flujos de ayuda.

Riesgos y mitigaciones

  • Riesgo: rotura de tests por cambios de copy.
    • Mitigación: asserts por substrings; helper stripFormatting; cambios incrementales.
  • Riesgo: ambigüedad de URLs/web.
    • Mitigación: mostrar CTA a /t web en la ayuda; opcionalmente mostrar WEB_BASE_URL como referencia informativa sin token.
  • Riesgo: sobrecarga de mensajes.
    • Mitigación: quick vs full help; mantener mensajes cortos y con bullets.

Siguientes pasos

  1. Fase 0 (docs) — crear docs/commands-inventory.md y docs/whatsapp-style-guide.md.
  2. Fase 1 (helpers) — añadir code, section, bullets a src/utils/formatting.ts + tests.
  3. Fase 2 (help.ts) — centralizar ayuda + tests de contenido.
  4. Fase 3-4 (wire-up) — usar help.ts en /t ayuda y en comando desconocido.
  5. Fase 5-6 — flag FEATURE_HELP_V2 y estandarización incremental de copys.

Incluye validación manual: probar /t ayuda, /t ayuda avanzada, un comando desconocido y /t web.

Comandos útiles

  • Añadir y confirmar este documento:
    • git add docs/commands-inventory.md docs/whatsapp-style-guide.md docs/plan-ayuda-bot.md
    • git commit -m "docs: plan Help v2, inventario y guía de estilo"