tcef-notifications/docs/legacy-matching.md

Comportamiento del matching viejo (fase 1b — caracterización)

Fuente: subflow "send notifications" de node-red en todos-contra-el-fuego/telegram-bot/flows.json (copia rescatada, fase 0), más todos-contra-el-fuego-web: imports/api/Subscriptions/Subscriptions.js, imports/api/ActiveFires/ActiveFires.js, imports/modules/url-encode.js, imports/api/Fires/server/publications.js, y locales node-red.

Objetivo: reproducir campo a campo los docs notifications que node-red crea, para que los workers de la fase 1a no noten el cambio de origen.

0. Entorno (recordatorio)

• MongoDB 3.2 → no hay change streams. La ingesta de fuegos es por polling de activefires (marca de tiempo / checkpoint), no change stream.
• Driver mongodb@3.7 (ya en el servicio). subscriptions.geo tiene índice 2dsphere → las geo-queries $near/$geoWithin funcionan en 3.2.

1. Colecciones implicadas

activefires (fuego)

{ _id, ourid:{type:'Point',coordinates:[lon,lat]}, lat, lon, when:Date,
  type:'modis'|'viirs'|'vecinal', acq_date, acq_time, confidence, frp, ...,
  createdAt:Date, updatedAt:Date, fireUnion?:ObjectId }

La importación NASA (cron de incinera cada 15 min) inserta/actualiza aquí. createdAt marca cuándo entró el fuego → base para el polling de fuegos nuevos.

subscriptions

{ _id:ObjectId, location:{lat,lon}, geo:{type:'Point',coordinates:[lon,lat]},
  distance:Number,           // RADIO de la sub en km
  owner:String,              // userId
  type:String,               // 'web' | 'mobile' | 'telegram'
  chatId?:Number, telegramBot?:String,  // solo type 'telegram'
  createdAt, updatedAt }

notifications (lo que hay que generar — ver legacy-behavior.md §1)

Campos escritos por node-red: userId, subsId, content, geo(Point), type, when, sealed, createdAt, updatedAt. Sin notified/emailNotified (pendiente → lo consumen los workers de 1a).

2. Reglas del matching (por cada fuego)

1. Candidatas (geo grueso): query sobre subscriptions con geo $near { $geometry: Point(fireLon,fireLat), $minDistance:0, $maxDistance:1000000 } (1000 km de prefiltro), filtrando la audiencia:
   • Telegram: { telegramBot: <bot> }.
   • Si el flag global notifyWebUsers está activo, además: $or: [{telegramBot},{type:'web'},{type:'mobile'}].
   • Fase 1b (workers 1a) solo genera para type ∈ {web, mobile}; el envío Telegram es fase 1c.
2. Filtro fino por distancia: por cada candidata, dist = geolib.getDistance(sub.location, fire) (metros, great-circle). Si dist/1000 <= sub.distance (km) → hit.
   • km = Math.round(dist/1000 * 10) / 10 (1 decimal) para el texto.
3. Dedupe 500 m: antes de insertar, buscar en notifications del mismo userId una notif con geo $near { $maxDistance: 500 } (0,5 km). Si existe alguna → NO se crea (ya notificado en esa zona). node-red guarda además cacheKey = "lat,lon" (informativo; el dedupe real es el geo-query 500 m).
4. Contenido (content), i18n por lang del owner de la sub:
   • type fuego modis/viirs → clave kmnasa.
   • type fuego vecinal → clave kmvecinal.
   • Interpolando {{km}}. ⚠️ Las cadenas llevan literalmente км (cirílico, no km) — es un error histórico de las traducciones; se replica verbatim.
5. sealed: Iron.seal(firePayload, ironPassword, Iron.defaults) con el paquete iron (Hapi Iron). firePayload = el doc del fuego con ourversion:"1" y sin _id; contiene al menos {lon,lat,when,type}. La web lo descifra en imports/modules/url-encode.js (Iron.unseal) para la ruta fire/<sealed> y la app.
   • Nota: Iron usa IV/salt aleatorios → sealed no es byte-idéntico entre ejecuciones ni sistemas, y no debe compararse por bytes. Lo que importa es que descifre al fuego correcto con el mismo ironPassword. El shadow compara sealed descifrándolo, no como string.
6. Doc insertado en notifications:

   { userId: sub.owner, subsId: sub._id, content, type: sub.type,
     geo: { type:'Point', coordinates:[fire.lon, fire.lat] },
     when: fire.when, sealed, createdAt: now, updatedAt: now }
   

3. Cadenas i18n (verbatim de los locales node-red)

kmnasa:

• es: 🔥 Alerta de posible fuego a {{km}} км de distancia (fuente NASA)
• en: 🔥 Alert of possible fire in {{km}} км of distance (source NASA)
• gl: 🔥 Alerta posible lume a {{km}} км de distancia (orixe NASA)
• ast: 🔥 Alerta de fueu posible a {{km}} км de distancia (fonte NASA)
• pt: 🔥 Alerta, possível fogo posto em {{km}} км de distância (origem NASA)

kmvecinal:

• es: 🔥 Alerta vecinal de fuego a {{km}} км de distancia
• gl: 🔥 Alerta veciñal de lume a {{km}} км de distancia
• ast: 🔥 Alerta vecinal de fueu a {{km}} км de distancia

(El sufijo : y el prefijo 🔥 los quita trim() en los workers — ver legacy-behavior.md §5. Aquí el contenido NO lleva : final; node-red lo añade solo para el mensaje de Telegram, no para el doc notifications.)

4. Ingesta de fuegos (fase 1b, sin change streams)

• Polling de activefires por createdAt > checkpoint (fuegos nuevos desde la última pasada), con checkpoint persistido (colección propia del servicio, p.ej. matcher_state). Alternativa/disparo: al final del import NASA.
• Re-detecciones (mismo fuego re-visto): el dedupe 500 m evita duplicar; no hace falta tratar updatedAt para no re-notificar.
• "Union of fires": activefires tiene fireUnion (agrupación de fuegos cercanos, lógica de 2018). Pendiente de confirmar si afecta a qué fuego dispara notificación; por defecto se procesa por fuego individual y el dedupe 500 m agrupa la vecindad. Anotar como punto a verificar en el shadow.

5. Puntos abiertos a validar en shadow

• ¿El matching viejo notifica solo fuegos createdAt nuevos, o re-procesa? (el cron NASA corre cada 15 min; el subflow procesa el batch del import).
• Efecto exacto de fireUnion / "union of fires" en el disparo.
• notifyWebUsers: ¿está activo en prod? (determina si se generan notifs web/mobile o solo telegram). Verificar el global en la config de node-red.
• Lang usado para content: el del owner de la sub (users.lang). Confirmar con casos reales en shadow.