diff --git a/docs/plan-ayuda-bot.md b/docs/plan-ayuda-bot.md new file mode 100644 index 0000000..9834e94 --- /dev/null +++ b/docs/plan-ayuda-bot.md @@ -0,0 +1,255 @@ +# 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"`