docs: añade plan de ayuda y estilo en docs/plan-ayuda-bot.md

Co-authored-by: aider (openrouter/openai/gpt-5) <aider@aider.chat>

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"`