diff --git a/README.md b/README.md index 4adfdd1..836b2dd 100644 --- a/README.md +++ b/README.md @@ -224,3 +224,132 @@ bun test ## 📚 Documentation For detailed API documentation and architecture decisions, see the [docs/](docs/) directory (if created). + +--- + +## 📐 Diseño UX acordado (MVP y siguientes iteraciones) + +Este apartado documenta las decisiones de UX aprobadas para el MVP y su evolución inmediata. Objetivo: mínima fricción, cero ruido en grupos y mensajes compactos. + +### Principios +- Silencio en grupos: el bot NO publica mensajes en grupos. Cuando alguien usa un comando en un grupo, el bot responde solo por DM al autor, sin dejar mensaje en el grupo. +- Homogeneidad: mismos comandos y comportamiento tanto en la comunidad “Casa” como en la del AMPA. +- Mensajes compactos: máximo 2–3 líneas, usando emojis y formato WhatsApp (negritas, monoespacio) para legibilidad. +- Aprendizaje progresivo: alias cortos y ayuda accesible por DM. + +### Comando base y alias +- Prefijo admitido: “/t” y “/tarea”. +- Subcomandos y sinónimos (aceptar cualquiera, mapear a una acción canónica): + - Crear: n, nueva, crear, + + - Ver: ver, mostrar, listar, ls + - Completar: x, hecho, completar, done + - Tomar: tomar, claim + - Soltar: soltar, unassign + - Ayuda: ayuda, help, ? + - Configurar: configurar, config + +### Gramática de “crear tarea” +- Texto libre: descripción. +- Fecha: soportar tokens “hoy” y “mañana” (MVP). Futuro: +2d, +1w, lun/mar/… +- Menciones: “@…” y menciones reales del cliente. +- Asignación por defecto: + - En grupos: si no hay menciones → tarea queda “sin dueño”. + - En DM: si no hay menciones → asignada al creador. +- Comandos de gestión de asignación: + - /t tomar → el usuario se asigna la tarea. + - /t soltar → elimina su asignación, devolviendo la tarea a “sin dueño” si no quedan asignados. + +### Listados +- /t ver grupo → devuelve por DM las pendientes del grupo desde el que se invoca (incluye sección “sin dueño”). +- /t ver mis → devuelve por DM las pendientes del usuario agregadas de todos sus grupos. +- Listas extensas: mostrar top N (p. ej., 10) y resumen “y X más…”. + +### Completar +- /t x (alias: /t hecho , /t completar ) +- Registro de quién completó. Por ahora no se restringe a asignados (permite fluidez); política configurable en el futuro. +- Confirmación solo por DM. + +### Ayuda y onboarding +- “/t” sin parámetros o “ayuda” → siempre por DM, con guía corta y 2–3 ejemplos. +- En grupos: no se escribe nada en el grupo; únicamente el DM al autor. + +### Mensajes: plantillas compactas +- Confirmación al crear (DM al creador): + - ✅ 26 “*Acta de la reunión*” + - 📅 2025-09-12 + - 👥 sin dueño (Junta AMPA) — o — 👤 @Juan +- DM a asignados: + - 🔔 Tarea 26 — 📅 2025-09-12 + - “*Acta de la reunión*” + - Grupo: Junta AMPA + - Completar: /t x 26 +- Listado (enviado por DM): + - Junta AMPA + - 26) “*Acta…*” — 📅 12/09 — 👤 @Juan + - 27) “*Carteles fiesta*” — 📅 10/09 — 👥 sin dueño + - … y 3 más +- Completar (feedback por DM): + - ✔️ 26 completada — “*Acta…*” + - Gracias, Juan. + +### Preferencias (MVP) +- Única preferencia: frecuencia de recordatorios por DM: daily | off. +- MVP sin web: el usuario escribe “configurar” por DM y el bot le ofrece elegir “diario” u “off”. +- Por defecto: off (evitar spam). Futuro: hora y zona horaria configurables; magic link a web de configuración. + +### Recordatorios +- Resumen diario por DM (si el usuario eligió “diario”): + - Buenos días, Ana — hoy tienes 3 tareas: + - 26) “*Acta…*” — 12/09 — Junta AMPA + - 31) “*Pagar comedor*” — hoy — Casa + - 33) “*…*” — 15/09 — Casa + - Completar: /t x +- Un solo DM con secciones por comunidad para evitar múltiples mensajes. + +### No objetivos del MVP +- No asignar por defecto a “todo el grupo” (evita DMs masivos y responsabilidad difusa). +- No canal “Tareas” compartido por defecto (riesgo de ruido). Se considerará en el futuro solo si hay demanda y opt‑in. + +### Plan de implementación (iteraciones) +- Iteración A — UX base y silencios + - Alias de comandos y sinónimos en CommandService. + - Respuestas de todos los comandos únicamente por DM (incluido cuando se invocan en grupos). + - Mensajes compactos con plantillas. + - Soporte de “hoy/mañana”. + - Default sin dueño en grupos; asignar al creador en DMs. + - Nuevos comandos: tomar y soltar. + - Ayuda por DM. +- Iteración B — Listados y completar + - /t ver grupo, /t ver mis. + - /t x con registro de quién completa. + - Tests para alias, hoy/mañana, ver y x. +- Iteración C — Recordatorios + - Preferencia reminder_freq (daily|off) por usuario via “configurar” por DM. + - Job diario que envía el resumen (solo “tus tareas” en MVP). +- Iteración D — (Opcional) Miembros de grupo + - Sincronizar miembros si se necesita incluir “sin dueño” por grupo en recordatorios. + +### Cambios técnicos asociados (resumen) +- src/services/command.ts + - Mapeo de sinónimos a acciones canónicas. + - Parser de “hoy/mañana”. + - Subcomandos: ver grupo|mis, x, tomar, soltar. + - Render de mensajes compactos. +- src/server.ts + - Detección de contexto grupo vs DM; nunca responder en grupo (solo DM al autor). +- src/tasks/service.ts + - Permitir tareas sin asignaciones. + - Métodos: claimTask(user_id), unassignTask(user_id), completeTask(id, completed_by). +- src/services/response-queue.ts + - Envío de DMs para ayuda, confirmaciones, listados y recordatorios. +- (Futuro) Preferencias + - Tabla user_preferences(user_id PK, reminder_freq TEXT, updated_at). + - “configurar” por DM en MVP; más adelante, web con magic link (user_tokens). + +### Testing sugerido +- Alias de comandos y “/t” sin parámetros → DM de ayuda. +- Crear en grupo sin menciones → sin dueño; no hay mensaje en el grupo; DM al autor. +- Crear en DM sin menciones → asignada al creador. +- “hoy/mañana” en fechas. +- ver grupo y ver mis → DM con paginación/resumen. +- completar, tomar y soltar → reglas y feedback por DM.