​

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

​

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: enrichPropertiesFromV2 (src/chat/sync/sync.service.ts, dentro del sync_full de ~06:00 Madrid) revierte bedrooms/bathrooms/size con el valor de vivla-api (v2) en las casas con hid; este job, a las 07:00, los re-aplica desde Webflow. Durante el día laborable el feed sirve los valores de Webflow; entre ~06:00 y 07:00 puede haber una ventana con valores v2. Es interino y desaparece con la migración final. address y latitude/longitude no los toca el nocturno.
• 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