# 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 diario|l-v|semanal|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 (completado)

- 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 (completado)

- 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: `❓ Comando no reconocido`
    - 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 (completado)

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