From eeccfa623403512794706d53575646f50e9d693d Mon Sep 17 00:00:00 2001 From: brobert Date: Fri, 17 Oct 2025 14:12:18 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20completar=20fase=200=20con=20inventario?= =?UTF-8?q?=20de=20comandos=20y=20gu=C3=ADa=20de=20estilo?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: aider (openrouter/openai/gpt-5) --- docs/commands-inventory.md | 181 +++++++++++++++++++++++++++++++++++ docs/whatsapp-style-guide.md | 95 ++++++++++++++++++ 2 files changed, 276 insertions(+) create mode 100644 docs/commands-inventory.md create mode 100644 docs/whatsapp-style-guide.md diff --git a/docs/commands-inventory.md b/docs/commands-inventory.md new file mode 100644 index 0000000..c2ad617 --- /dev/null +++ b/docs/commands-inventory.md @@ -0,0 +1,181 @@ +# Inventario de Comandos del Bot de Tareas + +Ámbito: WhatsApp (DM y grupos) +Objetivo: fuente única y estable de copy y comportamiento actual. + +Notas generales +- El bot responde por DM, incluso cuando escribes en un grupo, salvo mensajes muy concretos de estado. En modo de “gating” estricto de grupos (GROUP_GATING_MODE='enforce'), si el grupo no está permitido, el bot puede no responder en absoluto. +- Zona horaria: se usa TZ (por defecto Europe/Madrid) para calcular “hoy”, “mañana” y vencimientos. +- IDs: se muestran con 4 dígitos (ej.: `0026`), pero puedes escribirlos sin ceros (ej.: 26). +- Límite de listados: 10 elementos por sección; si hay más, se muestra “... y N más”. +- Fechas: formato visual DD/MM; indicador de vencida con ⚠️. + +--- + +## /t nueva (crear) + +Alias: `n`, `nueva`, `crear`, `+` +Sintaxis: `/t n [fecha] [@menciones...]` + +Parámetros +- descripción: texto libre. +- fecha (opcional): formatos aceptados: + - `YYYY-MM-DD` + - `YY-MM-DD` (se expande a `20YY-MM-DD`) + - Tokens naturales: `hoy`, `mañana` (con o sin acento) + - Se ignora puntuación adyacente simple; se usa la última fecha válida encontrada; no se aceptan fechas pasadas. +- @menciones (opcional): puedes mencionar JIDs crudos o tokens `@...`. Se filtran no plausibles y se intenta resolver alias. Si no se puede, se envía un DM al creador con instrucciones de onboarding (activar). + +Asignación por contexto +- En grupos: si no hay menciones, la tarea queda “sin responsable”. +- En DM: si no hay menciones, se asigna al creador. + +Grupo asociado +- Solo se asigna `group_id` si el grupo está activo. Si GROUP_GATING_MODE='enforce' y el grupo no está permitido, se crea “sin grupo”. + +Ejemplos +- `/t n Preparar informe 2025-11-05 @600123456` +- `/t + Comprar pan mañana` +- `/t crear Llamar a proveedores @ana @juan` +- `/t n Presentación 25-02-02` (→ 2025-02-02) + +--- + +## /t ver (listar) + +Alias: `ver`, `mostrar`, `listar`, `ls` +Sintaxis: `/t ver [grupo|mis|todos|sin]` (el alcance es opcional) + +Alcances +- `grupo`: lista pendientes del grupo actual (solo desde grupo activo). +- `mis`: tus tareas pendientes (por DM). +- `todos`: “Tus tareas” + “sin responsable”. + - En grupo: incluye “sin responsable” solo del grupo actual (compatibilidad). + - En DM: incluye “sin responsable” de todos los grupos donde eres miembro activo (si el snapshot de membresía es fresco). +- `sin`: solo tareas sin responsable del grupo actual (desde grupo). + +Indicadores +- Fechas en `DD/MM`. +- ⚠️ delante de la fecha si está vencida (según TZ configurada). + +Límites +- Máx. 10 elementos por sección; si hay más, se añade “... y N más”. + +Ejemplos +- En grupo: `/t ver` (equivale a `grupo`), `/t ver sin` +- Por DM: `/t ver mis`, `/t ver todos` + +--- + +## /t x (completar) + +Alias: `x`, `hecho`, `completar`, `done` +Sintaxis: `/t x ` +Soporta múltiples IDs separados por espacios y/o comas. Máx. 10 IDs. + +Resolución de ID +- Primero intenta `display_code` (código corto de 4 dígitos) en tareas activas; si no, usa el ID real. + +Gating de membresía (opcional) +- Si `GROUP_MEMBERS_ENFORCE=true` y el snapshot del grupo es fresco, debes ser miembro activo para completar. + +Ejemplos +- `/t x 26` +- `/t x 14 19 24` +- `/t x 14,19,24` + +--- + +## /t tomar (asumir) + +Alias: `tomar`, `claim`, `asumir`, `asumo` +Sintaxis: `/t tomar ` +Múltiples IDs; máx. 10. + +Gating de membresía (opcional) +- Si `GROUP_MEMBERS_ENFORCE=true` y snapshot fresco, debes ser miembro activo para tomar tareas del grupo. + +Ejemplos +- `/t tomar 12` +- `/t tomar 12 19 50` +- `/t tomar 12,19,50` + +--- + +## /t soltar (unassign) + +Alias: `soltar`, `unassign`, `dejar`, `liberar`, `renunciar` +Sintaxis: `/t soltar ` +Un solo ID. + +Gating de membresía (opcional) +- Si `GROUP_MEMBERS_ENFORCE=true` y snapshot fresco, debes ser miembro activo para soltar tareas del grupo. + +Ejemplos +- `/t soltar 26` + +--- + +## /t configurar (recordatorios) + +Alias: `config`, `configurar` +Sintaxis: `/t configurar daily|l-v|weekly|off [HH:MM]` + +Valores admitidos y alias +- `daily`: también `diario`, `diaria` → recordatorio diario. +- `weekdays`: también `l-v`, `lv`, `laborables` → lunes a viernes. +- `weekly`: también `semanal` → semanal (asume lunes). +- `off`: también `apagar`, `ninguno` → sin recordatorios. + +Hora +- Formato `HH:MM` (minutos 00–59; hora se normaliza a 0–23). +- Si omites la hora, se conserva la anterior o se usa `08:30` por defecto (y `lunes` para semanal). + +Nota de localización +- Internamente se almacenan claves en inglés (`daily`, `weekdays`, `weekly`, `off`), pero el copy al usuario es en español. Pendiente de revisión futura para evitar fugas como “weekly” en mensajes. + +Ejemplos +- `/t configurar diaria 09:00` +- `/t configurar l-v 08:30` +- `/t configurar semanal` (→ lunes 08:30) +- `/t configurar off` + +--- + +## /t ayuda + +Alias: `ayuda`, `help`, `?` +Sintaxis: `/t ayuda` | `/t ayuda avanzada` + +Comportamiento actual +- Ayuda rápida con comandos básicos, límites y ejemplos cortos. +- “Ayuda avanzada” lista alias y detalla opciones y límites. + +Plan futuro +- Se centralizará el contenido en un módulo único y se uniformará el estilo. + +--- + +## /t web + +Sintaxis: `/t web` (solo por DM) + +Descripción +- Genera un token de acceso one‑shot válido 10 minutos, invalida tokens previos y devuelve una URL de login basada en `WEB_BASE_URL`. + +Ejemplo +- `Acceso web: https://…/login?token=...` + “Válido durante 10 minutos. Si caduca, vuelve a enviar `/t web`.” + +--- + +## Notas adicionales + +- Estilo y formato: + - IDs: `codeId()` → 4 dígitos entre backticks. + - Fechas: `formatDDMM()` → `DD/MM`. + - Estilos disponibles: negrita `*...*`, cursiva `_<...>_`. Próximamente: `code()`, `section()`, `bullets()`. +- Gating de grupos: + - Si `GROUP_GATING_MODE='enforce'` y el grupo no está permitido, los comandos en ese grupo pueden quedar bloqueados (sin respuesta). +- Membresía de grupo: + - Si `GROUP_MEMBERS_ENFORCE=true` y el snapshot es fresco, algunas acciones requieren ser miembro activo (ver grupo, completar, tomar, soltar). diff --git a/docs/whatsapp-style-guide.md b/docs/whatsapp-style-guide.md new file mode 100644 index 0000000..87fcbc2 --- /dev/null +++ b/docs/whatsapp-style-guide.md @@ -0,0 +1,95 @@ +# Guía de Estilo de Mensajes para WhatsApp (Help v2) + +Objetivo: mensajes claros, consistentes y resistentes a cambios menores de copy. + +Principios +- Responder por DM: incluso si el comando viene de un grupo, las respuestas al usuario llegan por privado. Nota: en modo gating estricto (GROUP_GATING_MODE='enforce') el bot puede no responder en grupos no permitidos. +- Estructura visual reconocible: + - Secciones en negrita y MAYÚSCULAS: `*COMANDOS BÁSICOS*`. + - Comandos e IDs en monoespaciado (backticks). + - Listas con “- ” por línea. + - Notas en cursiva. +- Brevedad y accionabilidad: priorizar ejemplos cortos y CTAs (“Prueba `/t ayuda`”, “Envía `/t web`”). +- Estabilidad para tests: evitar asserts por igualdad exacta; preferir substrings semánticos. + +Componentes de formato +- Encabezados de sección: + - Patrón: `*${TÍTULO EN MAYÚSCULAS}*` + - Ej.: `*COMANDOS BÁSICOS*` +- Comandos: + - Siempre en backticks: `` `/t ver mis` `` +- IDs: + - Mostrar con 4 dígitos entre backticks: `` `0026` `` (usar `codeId()`). +- Fechas: + - Mostrar como `DD/MM`, precedidas de icono si aplica (ej.: `⚠️` si vencida). Usar `formatDDMM()`. +- Notas: + - En cursiva: `_Este grupo no está activo._` +- Bullets: + - “- ” al inicio de cada línea. Evitar listas demasiado largas (>10). + +Emojis recurrentes +- ⚠️ Advertencia (vencida, no encontrado, truncado). +- ✅ Confirmación genérica. +- 📅 Fecha (según `ICONS.date`). +- 👤 / 👥 Responsables (uno o varios). +- ➕ Crear, ✔️ Completar, 🧲/✋ Tomar/Soltar (según `ICONS` disponibles). +- Evitar exceso: 1–2 por línea como máximo. + +Patrones comunes +- Confirmación de creación: + - Línea 1: icono + ID + descripción + - Línea 2: fecha (si existe) + - Línea 3: responsable(s) o “sin responsable” +- Listados: + - Título (nombre de grupo o `Tus tareas`) + - Bullets de items con: ID, descripción, fecha (con `⚠️` si vencida), responsable + - Sufijo “... y N más” si aplica +- Ayuda rápida: + - Secciones: “COMANDOS BÁSICOS”, “LISTADOS”, “ACCESO WEB” + - Bullets con ejemplos: `` `/t n ...` ``, `` `/t ver mis|grupo|todos|sin` ``, `` `/t x 26` ``, `` `/t tomar 12` ``, `` `/t configurar ...` ``, `` `/t web` `` + +Localización +- Todo copy en español. Evitar fugas de claves internas en inglés (ej. “weekly”). +- En recordatorios, exponer etiquetas en español: + - daily → “diario” + - weekdays → “laborables (lunes a viernes)” + - weekly → “semanal (lunes)” + - off → “apagado” +- Si por compatibilidad se aceptan términos en inglés como input, la respuesta debe mantener español. + +Buenas prácticas +- Evitar párrafos largos; preferir 1–3 líneas por bloque. +- Incluir uso cuando falten argumentos: + - Ej.: `ℹ️ Uso: \`/t tomar 26\` o múltiples: \`/t tomar 12 19 50\` o \`/t tomar 12,19,50\` (máx. 10)` +- Mensajes de error claros y accionables: “No puedes tomar esta tarea… Pide acceso a un admin si crees que es un error.” +- En listados, omitir líneas en blanco finales. + +Para tests +- Preferir asserts de “contiene” con fragmentos estables (IDs en backticks, comandos en backticks, nombres de secciones). +- Si hace falta, crear helper `stripFormatting` que quite `*`, `_` y `` ` `` para comparar texto plano. + +Ejemplos + +Ayuda rápida +``` +*COMANDOS BÁSICOS* +- `/t n Descripción 2025-11-05 @Ana` +- `/t ver` (en grupo) · `/t ver mis` (DM) · `/t ver todos` +- `/t x 26` · `/t tomar 12` +- `/t configurar daily|l-v|weekly|off [HH:MM]` +- `/t web` +_El bot responde por DM, incluso si escribes desde un grupo._ +``` + +Confirmación de completar (ya estaba) +``` +ℹ️ `0026` ya estaba completada — Preparar informe — 📅 05/11 +``` + +Listado de “sin responsable” +``` +Nombre del Grupo — Sin responsable +- `0142` Revisión de PR — 📅 12/03 +- `0185` Montar demo — ⚠️ 📅 09/03 +... y 3 más +```