From 1d7c1e2f1d332ca90059b4590efcad94c2600933 Mon Sep 17 00:00:00 2001 From: borja Date: Tue, 30 Sep 2025 11:29:42 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20a=C3=B1adir=20README=20inicial=20para?= =?UTF-8?q?=20Taskbot?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: aider (openrouter/openai/gpt-5) --- README.md | 95 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..7379796 --- /dev/null +++ b/README.md @@ -0,0 +1,95 @@ +# Taskbot + +Bot de tareas para WhatsApp con sincronización de grupos, recordatorios y control de acceso. + +Taskbot ayuda a coordinar grupos en WhatsApp: crea y asigna tareas, recuerda pendientes y aplica gobierno de acceso por grupo. Está pensado para equipos y comunidades que ya operan en WhatsApp y quieren visibilidad ligera sin salir de la app. + +## Qué problema resuelve + +- Tareas que se pierden en el chat y falta de responsables o fechas. +- Falta de visibilidad de pendientes por grupo o persona. +- Necesidad de limitar en qué grupos opera el bot (descubrir y aprobar). + +## Características + +- Gestión de tareas: crear, asignar, reclamar/soltar, fechas límite y código corto de referencia. +- Recordatorios configurables por usuario (frecuencia y hora, respetando zona horaria). +- Control de acceso por grupos: modos off, discover y enforce; aprobación y bloqueo por admins. +- Sincronización de grupos y miembros con cachés y schedulers configurables. +- Alias de identidad con normalización de IDs. +- Métricas listas para Prometheus en el endpoint /metrics. +- Rate limiting por usuario para evitar abuso. +- Persistencia simple con SQLite, migraciones automáticas y PRAGMAs seguros (WAL, FK, etc.). + +## Qué no es (limitaciones) + +- No es un framework general de bots ni un CRM. +- No conecta directamente con WhatsApp: requiere Evolution API. +- No gestiona flujos conversacionales complejos ni multimedia avanzada. +- No incluye panel web; la interacción es vía WhatsApp. +- Está optimizado para un despliegue por comunidad/instancia (no multi-tenant masivo). + +## Cómo funciona (alto nivel) + +1. Evolution API envía eventos al webhook de Taskbot. +2. El servidor normaliza el mensaje, aplica control de acceso por grupo y rate limit. +3. Los servicios de dominio (tareas, recordatorios, alias, colas) operan sobre SQLite. +4. Las respuestas se encolan y envían a través de Evolution API. +5. Schedulers ejecutan sincronización de grupos/miembros, recordatorios y tareas de mantenimiento. +6. Las métricas se exponen en /metrics (Prometheus o JSON). + +## Uso básico + +- Los usuarios interactúan con comandos sencillos en WhatsApp para crear tareas, ver pendientes, asignarse o soltar. +- Los administradores pueden aprobar o bloquear grupos cuando el modo de acceso está en discover/enforce. +- Los recordatorios se configuran por usuario (frecuencia y hora) y respetan la zona horaria. + +## Instalación rápida + +Requisitos: +- Node.js LTS. +- Acceso a una instancia de Evolution API. +- URL pública para recibir el webhook. +- Almacenamiento local para SQLite (directorio data/). + +Pasos: +- Clonar el repositorio e instalar dependencias. +- Configurar variables de entorno. +- Arrancar el servidor; la base de datos (data/tasks.db) y migraciones se gestionan automáticamente. + +Recomendación: planificar copias de seguridad periódicas del directorio data/. + +## Configuración esencial + +Variables clave: +- EVOLUTION_API_URL, EVOLUTION_API_INSTANCE, EVOLUTION_API_KEY. +- ADMIN_USERS (lista de IDs/JIDs autorizados). +- GROUP_GATING_MODE: off | discover | enforce. +- WHATSAPP_COMMUNITY_ID (para sincronización de grupos). +- TZ (por defecto Europe/Madrid). +- ALLOWED_GROUPS (semilla inicial), NOTIFY_ADMINS_ON_DISCOVERY. +- METRICS_ENABLED, PORT. +- Rate limit: RATE_LIMIT_PER_MIN, RATE_LIMIT_BURST. +- Intervalos y retención: GROUP_SYNC_INTERVAL_MS, GROUP_MEMBERS_SYNC_INTERVAL_MS, GROUP_MEMBERS_INACTIVE_RETENTION_DAYS. + +Consulta: +- docs/operations.md para operación, endpoints y variables de entorno. +- docs/architecture.md para una visión técnica y responsabilidades por módulo. + +## Operación y mantenimiento + +- /metrics expone contadores y gauges; puede deshabilitarse por configuración. +- Schedulers configurables; se evitan en entornos de test. +- Migraciones up-only al arranque; logging de eventos de migración. +- Copias de seguridad: respaldar el directorio data/ y planificar retención. + +## Estado y licencia + +- Nombre provisional: “Taskbot”. +- Licencia por definir (software libre; se evaluará GPLv3/AGPL/MIT/Apache-2.0). +- Roadmap y contribuciones: pendientes de publicación. + +## Enlaces + +- Documentación de arquitectura: docs/architecture.md +- Operación y configuración: docs/operations.md