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.
256 lines
12 KiB
Markdown
256 lines
12 KiB
Markdown
# 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"`
|