​

Windmill

​

Arquitectura

┌──────────────┐     ┌──────────────────┐     ┌──────────────┐
│  Windmill    │────▶│  Vivla Tools API │────▶│  Supabase    │
│  (Railway)   │     │  (NestJS)        │     │  (PostgreSQL)│
└──────────────┘     └──────────────────┘     └──────────────┘
       │                     │
       │              ┌──────────────┐
       │              │  Firebase    │
       │              │  (Firestore) │
       │              └──────────────┘
       │
       ▼
┌──────────────┐
│  Slack       │
│  (alertas)   │
└──────────────┘

​

Workspace

​

Variables de entorno

const suffix = env === 'prod' ? '_prod' : '_dev'
const apiUrl = await wmill.getVariable(`f/vivla_tools/api_url${suffix}`)
const apiKey = await wmill.getVariable(`f/vivla_tools/api_key${suffix}`)

​

Autenticación

​

Sync Jobs

​

Endpoints

​

Flujo de ejecución

1. Windmill llama POST /chat/sync/{entity} con x-api-key
2. Backend crea un sync job en chat_sync_jobs y ejecuta el sync
3. Windmill poll GET /chat/sync/jobs/:id cada 5 segundos hasta completion
4. En caso de fallo, el error se guarda en error_message + chat_sync_logs

​

Flows programados

​

Daily Full Sync

• Path: f/vivla_tools/sync/sync_full
• Schedule: 0 4 * * * (4:00 AM UTC)
• Retry: 2 reintentos, 5 minutos de backoff

​

NPS Legacy Responses (Hourly)

• Path: f/vivla_tools/sync/sync_firebase_legacy_responses
• Schedule: 0 * * * * (cada hora)
• Colecciones: nps-home-responses, nps-booking, nps-home-excellence-values

​

Booking channels reconcile diario

• Path: f/vivla_tools/chat/reconcile_booking_channels
• Schedule (referencia): 0 0 15 * * * Europe/Madrid (15:00 Madrid) — después del sync diario de bookings (04:00 Madrid). Se movió de las 07:00 a las 15:00 porque crear un canal ahora manda también el primer mensaje al propietario (BookingWelcomeService, env-gated por BOOKING_WELCOME_ENABLED), así que la hora del cron es la hora a la que le suena el móvil: las 15:00 caen en la franja de trabajo de CX para atender respuestas
• Guard del endpoint: Auth0OrApiKeyGuard (igual que /chat/sync/*) — el script usa f/vivla_tools/api_key[_dev|_prod], no notifications_api_key (esa key sólo vale para endpoints con ApiKeyGuard, como el daily health digest o el CRM recompute)
• Args: env, dryRun (default false), windowDays (opcional, el backend usa 30 si no se pasa)

​

Idioma de propietarios: refresco diario

• Path: f/vivla_tools/chat/owner_language_refresh
• Schedule (referencia): 0 0 4 * * * Europe/Madrid (04:00) — después del sync nocturno (de donde salen los usuarios nuevos) y antes de la actividad del día
• Guard del endpoint: Auth0OrApiKeyGuard — el script usa f/vivla_tools/api_key[_dev|_prod] (x-api-key), no notifications_api_key (esa key solo vale para endpoints con ApiKeyGuard)
• Args: env, windowDays (opcional, el backend usa 180 si no se pasa)
• Solo escribe cuando la evidencia es clara: un texto corto, sin marcadores o ambiguo deja la fila intacta, así que una elección hecha a mano por CX no se pisa sola. Idempotente. Avisa por Slack si alguna fila falla.

​

Guardias: GCal sync y reconciler

• sync_guardias — POSTea /chat/shifts/sync/gcal y hace polling de /chat/sync/jobs/:id (pull Google → Tools). Args: env.
• reconcile_guardias — POSTea /chat/shifts/reconcile (activa/desactiva la guardia vigente). Args: env. Devuelve { activated, deactivated, noop }.
• Guard de ambos endpoints: Auth0OrApiKeyGuard — los scripts usan f/vivla_tools/api_url[_dev|_prod] + api_key[_dev|_prod] (x-api-key).
• Schedule (referencia): reconcile_guardias documenta 0 */15 * * * * Europe/Madrid (cada 15 min).

​

Lola: watchdog de handoffs

• watchdog_handoffs — POSTea /chat/lola/handoff/sweep (guard Auth0OrApiKeyGuard). Args: env, dryRun. Devuelve { scanned, remindersSent, escalated, autoAcked, skipped }. Idempotente vía reminded_at/escalated_at (compare-and-set), así que reejecutarlo sin cambios es un no-op.
• Schedule (referencia): 0 */5 * * * * Europe/Madrid (cada 5 min, por debajo del umbral de recordatorio de 15 min). El SELECT usa un lookback de 48 h para no desatar una tormenta de escalación sobre un backlog previo.

​

Lola: reconciliación de memoria y destilación de bios

• ingest_reconcile — 05:00 Europe/Madrid. POSTea /chat/lola/ingest-reconcile (guard Auth0OrApiKeyGuard), que relee chat_message_logs de las últimas 26 h (día + margen: un run caído lo cubre el siguiente) y lo reenvía al ingest de concierge. Cierra el hueco de los canales donde el forward en vivo no corrió (flag apagado, fallos transitorios) y que si no solo se capturaban por read-repair cuando Lola respondía. Idempotente — el dedupe (source:channelCid:messageId) vive en concierge, así que ventanas solapadas o reejecuciones son un no-op. Devuelve { sinceHours, channelsProcessed, channelsWithMessages, messagesRead, channelsFailed }.
• distill_bios — 06:00 Europe/Madrid, una hora después del reconcile para trabajar sobre el historial ya reconciliado de la noche. POSTea /lola/distill en concierge (f/vivla_tools/concierge_url_prod + concierge_api_key_prod), que relee la memoria reciente de cada propietario y reescribe su bio de working-memory con una llamada a modelo pequeño por propietario. Args sinceHours=26, limit=200, dryRun.

​

Atlas: extracción de conocimiento CX → PR

• knowledge/casas/<slug>.md — un digest por propiedad.
• knowledge/zonas/_candidatos-chat.md — zonaItems de todas las propiedades.
• knowledge/general/_candidatos-chat.md — generalItems, sin property_ids/property_hids (el filtro de propiedad de Atlas los sirve sin filtrar).

​

Slack Notifications

• Canal: #vivla-tools-sync
• Resource: slack_auth (tipo RT.Slack configurado en Windmill)

​

Scripts de referencia

docs/internal/tools/chat/implementation/epics/3.2-sync-module-improvements/scripts/
  sync_users.ts
  sync_properties.ts
  sync_deals.ts
  sync_bookings.ts
  sync_firebase_legacy_responses.ts
  sync_full.ts
  slack_notify.ts

​

Sync interino Webflow → módulo web

• Path: f/vivla_tools/sync/sync_web_webflow (snapshot en apps/windmill/f/vivla_tools/sync/)
• Schedule: 0 0 7 * * * diario 07:00 Europe/Madrid, args env=prod
• Matching de casas existentes: primero por slug; si falla, por nombre normalizado (lowercase + sin diacríticos + whitespace colapsado). Webflow no regenera el slug al renombrar una casa, así que tras un rename el item llega con el slug viejo y el name nuevo (p.ej. casa-ribadesella → name “Casa Xuncu”, ya existente en tools como casa-xuncu). Esos casos se resuelven por nombre, salen en el resultado como slug_aliases ({webflow_slug, tools_slug, name}) y no cuentan como extra_in_tools. Sólo un item sin match por slug ni por nombre se considera alta.
• Qué escribe en casas existentes (por slug o por nombre — Webflow gana en todo, es la fuente que ve el cliente):
  • property_web_data: web_title (nombre público del feed title, ← name, i18n en/es/fr, compara normalizado), status_web (issold→sold_out, ishiden→hidden, iscomingsoon→coming_soon (slug real sin guiones), resto→listed), price_from (fraction-price), location_text (i18n = texto Webflow) y description (HTML Webflow → Lexical i18n; sólo si el texto plano normalizado difiere).
  • properties: latitude/longitude (coordinates), address y bedrooms/bathrooms/size (← bedrooms/bathrooms/sqm). No toca properties.name (ése lo ownea el feed operativo).
  • property_videos: vídeo hero visible ← fieldData.video.url. Si la property no tiene vídeo visible → INSERT; si lo tiene → PATCH del hero (o el de menor sort_order) cuando la URL difiere. Nunca borra: si Webflow no trae vídeo, no toca nada.
• El baile con el sync operativo nocturno (resuelto, jul-2026): hasta el cutover de vivla.com, enrichPropertiesFromV2 (src/chat/sync/sync.service.ts, dentro del sync_full de ~05:00 Madrid) revertía bedrooms/bathrooms/size con el valor de vivla-api (v2) en las casas con hid, y este job los re-aplicaba a las 07:00 desde Webflow. Sólo tapaba las casas de la colección Listings: las upcoming viven en otra colección que este script no lee, así que Casa Emilio se rompía a 0/0/0 a diario. Desde el cutover, el enrich ya no escribe ningún campo físico (bedrooms/beds/bathrooms/bathtubs/capacity/size los ownea el CMS); v2 sólo aporta el dato operativo (accesos, wifi, parkings, indications, CP/provincia/maps). Con eso, este job de las 07:00 deja de ser necesario y su schedule se apaga.
• Altas automáticas (v2): crea las casas de Webflow sin match por slug ni por nombre — properties (status inactive, conservador: el sync operativo lo corrige si la casa existe en su fuente) + property_web_data + property_photos (imágenes subidas a Cloudinary con upload firmado, carpeta web/properties/<slug>; si un upload falla, cae a la URL de Webflow como fallback) + property_videos + property_web_amenities. Las casas hidden se crean con status_web='hidden'; las draft/archived de Webflow no se crean. No crea amenities nuevas (sólo enlaza las que ya existen por slug; un slug sin match sale como warning). Fail-safe: más de 10 altas en un run se interpreta como respuesta anómala de Webflow y aborta sin escribir. Las altas salen en el resultado (created[]) y avisan por Slack; missing_in_tools pasa a contener sólo las altas que fallaron.
• Qué NO hace: no borra ni oculta filas de tools ausentes en Webflow (extra_in_tools, report-only), no toca properties.name (feed operativo) ni borra vídeos.
• Excepción al patrón thin-trigger: escribe directo a Supabase vía PostgREST (variables f/vivla_tools/supabase_* + f/vivla_tools/webflow_token + f/vivla_tools/cloudinary_* para las fotos de las altas) porque es tooling interino que se retira al completar la migración; soporta dry_run (las altas se reportan con would_create sin subir a Cloudinary ni escribir).

​

Debugging

​

Ver error de un sync job fallido

-- En Supabase SQL Editor
SELECT id, status, error_message, steps, result
FROM chat_sync_jobs
WHERE id = '<job-id>';

-- Logs detallados
SELECT level, message, context, created_at
FROM chat_sync_logs
WHERE job_id = '<job-id>'
ORDER BY created_at DESC;

​

Errores comunes

​

Notification automation engine

​

Cron consumer

• process_domain_events.ts (cada 30 s) — lee domain_events WHERE status='pending', ejecuta los flows que matchean cada event_type, marca como published o failed con retry. Es el único consumer del pipeline.

​

Cron emitters (eventos derivados)

​

Crons de mantenimiento

​

Variables adicionales para el engine

​

Deploy desde GitHub (CI)

• Trigger: merge a main o develop que toque apps/windmill/**. También workflow_dispatch manual con flag apply / dry-run.
• develop → dry-run (muestra el diff, no aplica).
• main → wmill sync push --yes (aplica).
• Secrets requeridos en GitHub Settings → Secrets and variables → Actions → “Repository secrets”:
  • WMILL_TOKEN (token con scope write)
  • WMILL_WORKSPACE_ID (ej. vivla)
  • WMILL_BASE_URL (URL del Windmill self-hosted)

• Variables (las del cuadro de arriba) — secretos no se suben por CI.
• Resources (conexiones a Postgres, Slack, etc.) si se usan, normalmente no es nuestro caso.
• Permisos del workspace.

​

Documentación técnica detallada

• docs/internal/tools/chat/implementation/epics/3.2-sync-module-improvements/02-windmill-setup-guide.md
• docs/internal/tools/chat/implementation/epics/3.2-sync-module-improvements/03-windmill-configuration-walkthrough.md
• Notification automation specs: docs/internal/tools/notifications/implementation/epics/notification-automation-system/specs/windmill-crons.md