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