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 del proxy interno (por defecto 3000).
• BOT_PORT: puerto interno del bot (por defecto 3007).
• WEB_PORT: puerto interno de la web SvelteKit (por defecto 3008).
• 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'
• REACTIONS_ENABLED: 'true'|'false' para activar reacciones (por defecto 'false'). Ej.: REACTIONS_ENABLED='true'
• REACTIONS_SCOPE: 'groups'|'all' para limitar reacciones a grupos o permitir en DMs (por defecto 'groups'). Ej.: REACTIONS_SCOPE='groups'
• REACTIONS_TTL_DAYS: días para permitir la reacción ✅ al completar respecto al mensaje origen (por defecto 14). Ej.: REACTIONS_TTL_DAYS='14'
• RQ_REACTIONS_MAX_ATTEMPTS: reintentos máximos para jobs de reacción (si no se define, aplica el global). Ej.: RQ_REACTIONS_MAX_ATTEMPTS='3'
• 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).
• DB_PATH: ruta absoluta o relativa al archivo SQLite; si se define, tiene prioridad sobre DATA_DIR. Ej.: DB_PATH='./data/tasks.db'
• MIGRATIONS_LOG_LEVEL: 'silent' para silenciar logs del migrador (en test se silencian automáticamente).
• WEB_BASE_URL: base pública de la interfaz web para construir enlaces absolutos (p. ej., /login?token=...). Obligatoria para /t web. Ej.: WEB_BASE_URL='https://wtask.org'
• DEV_AUTOSEED_DB: 'true'/'false' para sembrar automáticamente la BD en desarrollo cuando está vacía (apps/web). Ej.: DEV_AUTOSEED_DB='true'
• DEV_DEFAULT_USER: ID de usuario por defecto en desarrollo (bypass y semilla). Idealmente numérico (solo dígitos). Ej.: DEV_DEFAULT_USER='34600123456'

Endpoints operativos

• GET /metrics
  • 200 si Metrics.enabled() y formato Prometheus por defecto.
  • 404 si métricas deshabilitadas; 405 si método no permitido.
• GET /health
  • 200 siempre (proxy interno), útil para healthcheck del contenedor.
• APIs web (requieren sesión)
  • GET /api/me/tasks?status=open|recent&search=...
    • status=open (por defecto): orden por due_date asc (NULL al final). Aplica gating por AllowedGroups + membresía activa (group_members). Búsqueda con LIKE ESCAPE ''. Filtros dueBefore y soonDays (días). Paginación page/limit y hasMore/total.
    • status=recent: tareas asignadas al usuario completadas en las últimas 24 h; orden por completed_at DESC; incluye campos completed y completed_at; mismo gating y búsqueda.
  • GET /api/me/groups
    • Devuelve solo grupos permitidos donde el usuario está activo. Incluye counts.open y counts.unassigned por grupo.
  • GET /api/groups/:id/tasks?unassignedFirst=true
    • Requiere que el usuario sea miembro activo del grupo y que el grupo esté permitido. Orden por due_date (NULL al final); admite parámetros unassignedFirst, onlyUnassigned y limit (clamp a 100).
  • GET /api/me/preferences
    • Devuelve las preferencias del usuario para recordatorios como { freq, time }. Si no hay registro previo, responde { freq: 'off', time: '08:30' }.
  • POST /api/me/preferences
    • Actualiza preferencias. Valida freq ∈ {off,daily,weekly,weekdays} y time en formato HH:MM (24h); normaliza hora (p. ej., 7:5 → 07:05). Upsert con updated_at; si freq='off' y no se envía time, conserva la última hora guardada (o '08:30' por defecto).
  • POST /api/tasks/:id/claim
    • Reclama la tarea para el usuario actual (idempotente). Requiere sesión; valida que la tarea esté abierta y aplica gating: t.group_id IS NULL o (grupo permitido y membresía activa).
  • POST /api/tasks/:id/unassign
    • Elimina la asignación del usuario actual (idempotente) si existe. Requiere sesión; tarea abierta y gating equivalente.
  • POST /api/tasks/:id/complete
    • Marca como completada (idempotente). Si es de grupo y no tiene responsables, auto-asigna al usuario que completa antes de marcarla como completada. Gating: si tiene group_id, cualquier miembro activo del grupo de un grupo allowed; si no tiene group_id, solo un asignado. Devuelve la tarea con completed y completed_at.
  • PATCH /api/tasks/:id
    • Actualiza { due_date: 'YYYY-MM-DD' | null, description?: string }. Valida due_date y normaliza/sanea description (texto plano, 1–1000 chars, colapsa espacios). Requiere sesión, tarea abierta y gating.

Arranque y servicios

• src/server.ts::start() (bot)
• proxy.ts y startup.sh (contenedor único con Bun):
  • El proxy escucha en PORT (3000 por defecto) y enruta /webhook y /metrics → BOT_PORT; el resto → WEB_PORT.
  • startup.sh normaliza DB_PATH/DATA_DIR a absolutas, arranca bot, espera tablas web_tokens/web_sessions y arranca la web antes del proxy.
  • Valida entorno (logs de variables presentes/faltantes).
  • Aplica migraciones up-only.
  • Inicia HTTP y (según entorno) schedulers.
  • Compresión HTTP: desactivada temporalmente (el proxy fuerza Accept-Encoding: identity hacia la web y elimina Content-Encoding/Vary/Content-Length en las respuestas; además, SvelteKit se construye con precompress=false para no generar .br/.gz).
  • En tests, el migrador silencia logs; puede forzarse en cualquier entorno con MIGRATIONS_LOG_LEVEL='silent'.

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: /app/data/tasks.db (por defecto).
• startup.sh normaliza DB_PATH y DATA_DIR a rutas absolutas para que bot y web apunten al mismo archivo, y espera a que existan web_tokens/web_sessions antes de iniciar la web.
• 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.
• DB_PATH permite aislar BD por rama/entorno sin tocar DATA_DIR; útil para pruebas en CapRover.
• En Docker/CapRover, el volumen por defecto es /app/data. Para persistencia, usa rutas de DB_PATH dentro de ese directorio (p. ej., /app/data/tasks-next.db).

Semilla de desarrollo (apps/web)

• Activación: establecer DEV_AUTOSEED_DB='true'. La semilla solo se ejecuta en desarrollo cuando la tabla tasks está vacía.
• Usuario por defecto: definir DEV_DEFAULT_USER con un ID numérico (p. ej., 34600123456). Se crea como usuario, se hace miembro activo de varios grupos y se usa para asignaciones.
• Ruta del archivo en dev (apps/web): por defecto tmp/tasks.db (véase apps/web/src/lib/server/env.ts). En producción, la web usa /app/data por defecto.
• Regenerar la BD de dev: detener el servidor web, borrar el archivo de BD y reiniciar con DEV_AUTOSEED_DB='true'.
  • Ejemplo: rm -f tmp/tasks.db
• Datos que se crean:
  • Usuarios: 3–5 (incluido el usuario por defecto).
  • Grupos: “Familia”, “Trabajo”, “Voluntariado”, “Compras” (allowed) y “Varios” (pending).
  • Allowed groups: allowed para los grupos principales; “Compras” allowed sin membresía del usuario por defecto (sirve para validar gating); “Varios” en pending.
  • Membresías: el usuario por defecto activo en Familia, Trabajo y Voluntariado; otros usuarios repartidos para soportar múltiples responsables.
  • Preferencias: recordatorios diarios a las 08:30 para el usuario por defecto.
  • Tareas: ~30–35 con mezcla rica:
    • Personales (sin grupo) y de grupo.
    • due_date en pasado, hoy, futuro y NULL.
    • Sin responsables, con 1 responsable y con múltiples responsables (incluye “tú”).
    • Completadas recientemente (≤24h) y antiguas (>48h), con completed_by coherente.
• Idempotencia: si ya existen tareas no vuelve a sembrar. Para resembrar, borra el archivo de BD o define un DB_PATH nuevo.

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).
• Reacciones del bot:
  • reactions_enqueued_total{emoji=robot|warn|check|other}
  • reactions_sent_total{emoji=...}
  • reactions_failed_total{emoji=...}
• 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í.
• En apps/web, kit.csrf.checkOrigin=false debido al proxy interno; considerar alternativas si se elimina el proxy.
• Tests web con bun:test: construcción programática de apps/web (build/), arranque real del servidor y peticiones HTTP reales; ver tests/web/helpers/server.ts.

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.