brobert
/
taskbot
1
0
Fork 0
Code Issues Pull Requests 1 Packages Projects Releases Wiki Activity
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.
main
webui
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'c3737b967b'
${ noResults }
taskbot/docs/operations.md

7.1 KiB
Raw Blame History

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'
  • 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'

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&search=...
      • Orden por fecha de vencimiento ascendente (NULL al final). Aplica gating por AllowedGroups + membresía activa (group_members). Búsqueda por descripción con LIKE y ESCAPE ''. Filtros dueBefore y soonDays (en días). Paginación page/limit y campos hasMore/total en la respuesta.
    • 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).

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).

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í.
  • 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.