taskbot/docs/operations.md

Operación y configuración

Variables de entorno (principales)

• EVOLUTION_API_URL: base URL de Evolution API.
• EVOLUTION_API_INSTANCE: nombre/ID de instancia en Evolution.
• EVOLUTION_API_KEY: API key para peticiones salientes (contacts, etc.).
• WEBHOOK_URL: URL pública del webhook (puede usarse para auto-registro/config).
• WHATSAPP_COMMUNITY_ID: comunidad cuyos grupos se sincronizan.
• PORT: puerto HTTP (por defecto 3007).
• NODE_ENV: 'development' | 'test' | 'production'.
• METRICS_ENABLED: 'true'|'false'|'1'|'0' (por defecto habilitado salvo en test). Ej.: METRICS_ENABLED='true'
• RATE_LIMIT_PER_MIN: tokens por minuto por usuario (default 15).
• RATE_LIMIT_BURST: capacidad del bucket (default = RATE_LIMIT_PER_MIN).
• GROUP_SYNC_INTERVAL_MS: intervalo de sync de grupos (default 24h; min 10s en dev).
• GROUP_MEMBERS_SYNC_INTERVAL_MS: intervalo de sync de miembros (default 6h; min 10s en dev).
• GROUP_MEMBERS_INACTIVE_RETENTION_DAYS: días para borrar miembros inactivos (default 180).
• TZ: zona horaria para recordatorios (default Europe/Madrid).
• REMINDERS_GRACE_MINUTES: minutos de gracia tras la hora programada para enviar recordatorios atrasados (por defecto 60).
• GROUP_GATING_MODE: 'off' | 'discover' | 'enforce' (control de acceso por grupos; por defecto 'off'). Ej.: GROUP_GATING_MODE='discover'
• ADMIN_USERS: lista separada por comas de IDs/JIDs autorizados para /admin (se normalizan a dígitos). Ej.: ADMIN_USERS='34600123456, 5554443333, +34 600 111 222'
• ALLOWED_GROUPS: lista separada por comas de group_id@g.us para sembrado inicial en arranque. Ej.: ALLOWED_GROUPS='12345-67890@g.us, 11111-22222@g.us'
• NOTIFY_ADMINS_ON_DISCOVERY: 'true'/'false' para avisar por DM a ADMIN_USERS al descubrir un grupo (modo 'discover'). Ej.: NOTIFY_ADMINS_ON_DISCOVERY='true'
• DATA_DIR: directorio base para la base de datos SQLite (por defecto ./data).

Endpoints operativos

• GET /metrics
  • 200 si Metrics.enabled() y formato Prometheus por defecto.
  • 404 si métricas deshabilitadas; 405 si método no permitido.

Arranque y servicios

• src/server.ts::start()
  • Valida entorno (logs de variables presentes/faltantes).
  • Aplica migraciones up-only.
  • Inicia HTTP y (según entorno) schedulers.

Schedulers

• GroupSyncService.startGroupsScheduler() y .startMembersScheduler()
  • Saltan en test; intervalos controlados por env.
• RemindersService.start()
  • Tick cada minuto, filtra por zona horaria y preferencias, con ventana de gracia configurable (60 min por defecto) tras la hora programada.
• MaintenanceService.start()
  • Tarea diaria; borra miembros inactivos según retención.

Datos y backups

• Data path: data/tasks.db (por defecto).
• Migraciones con backup opcional (withBackup=false por defecto en initializeDatabase).
• Recomendación: planificar copia de seguridad periódica del directorio data/ y retención externa.

Métricas de referencia

• sync_runs_total, identity_alias_resolved_total, contadores/gauges específicos de colas y limpieza.
• Control de acceso por grupos (multicomunidades):
  • allowed_groups_total_pending, allowed_groups_total_allowed, allowed_groups_total_blocked (gauges).
  • unknown_groups_discovered_total (counter).
  • messages_blocked_group_total (counter).
  • commands_blocked_total (counter).
  • sync_skipped_group_total (counter).
  • admin_actions_total_allow, admin_actions_total_block (counters).
• Añadir nuevas métricas usando Metrics.inc/set y documentarlas aquí.

Buenas prácticas

• No arrancar schedulers en test salvo que FORCE_SCHEDULERS='true'.
• Validar nuevas env en src/server.ts::validateEnv() y documentarlas aquí.

Formato de fechas en comandos

• Se aceptan únicamente YYYY-MM-DD y YY-MM-DD (YY se expande a 20YY).
• También se soportan tokens naturales: "hoy" y "mañana".
• Se rechazan otros formatos (p. ej., dd-mm, mm/dd, fechas inválidas).
• Las fechas se guardan normalizadas como YYYY-MM-DD y se muestran como dd/MM en listados y mensajes.