You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
99 lines
4.5 KiB
Markdown
99 lines
4.5 KiB
Markdown
# 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.
|
|
- Formato de fechas en comandos: se aceptan YYYY-MM-DD y YY-MM-DD (YY → 20YY). También se admiten los tokens "hoy" y "mañana". Las fechas se almacenan normalizadas como YYYY-MM-DD y se muestran como dd/MM en los listados.
|
|
|
|
## 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).
|
|
- REMINDERS_GRACE_MINUTES (ventana de gracia tras la hora; por defecto 60).
|
|
- 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.
|
|
- DATA_DIR: directorio raíz para la base de datos SQLite compartida (por defecto ./data).
|
|
|
|
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
|