ICS → Importador de Discourse vía API REST

Plugin Extras
,
12

Notas de comportamiento de las pruebas de ics_to_discourse.py

He estado ejecutando una serie de pruebas en este script (con y sin --time-only-dedupe) y pensé que sería útil documentar el flujo de actualización/adopción en detalle.

1. Cómo se determina la unicidad

  • Modo predeterminado: la adopción requiere que inicio + fin + ubicación coincidan exactamente.
  • Con --time-only-dedupe: la adopción requiere solo inicio + fin; la ubicación se trata como “suficientemente cercana”.

Si ningún tema existente coincide con estas reglas, se crea un nuevo tema.

2. El papel del marcador UID

  • Cada tema de evento recibe un marcador HTML oculto en la primera publicación:
  <!-- ICSUID:xxxxxxxxxxxxxxxx -->
  • En ejecuciones posteriores, el script busca primero ese marcador.
  • Si se encuentra, el tema se considera una coincidencia de UID y se actualiza directamente, independientemente de lo ruidoso o obsoleto que sea el texto de DESCRIPCIÓN.
  • Esto convierte al UID en la clave de identidad real. Los campos de descripción visibles no afectan la coincidencia.

3. Flujo de actualización con coincidencia de UID

  1. El script recupera la primera publicación y elimina el marcador:
 old_clean = strip_marker(old_raw)
 fresh_clean = strip_marker(fresh_raw)
  1. Si old_clean == fresh_clean: no hay actualización (evita cambios innecesarios).
  2. Si difieren: comprueba si el cambio es “significativo”:
meaningful = (
    _norm_time(old_attrs.get("start")) != _norm_time(new_attrs.get("start"))
    or _norm_time(old_attrs.get("end")) != _norm_time(new_attrs.get("end"))
    or _norm_loc(old_attrs.get("location")) != _norm_loc(new_attrs.get("location"))
)
  • Si meaningful = True → actualizar con un impulso (el tema aparece en Últimos).
  • Si meaningful = False → actualizar silenciosamente (bypass_bump=True → solo revisión, sin impulso).
  1. Las etiquetas se fusionan (asegura que las etiquetas estáticas/predeterminadas estén presentes, nunca elimina las de moderador/manuales).
  2. El título y la categoría nunca se cambian al actualizar.
  1. Flujo de actualización sin coincidencia de UID
  2. El script intenta la adopción:
    • Construye tuplas candidatas de inicio/fin/ubicación (o solo inicio/fin con --time-only-dedupe).
    • Busca en /search.json y /latest.json un evento existente con atributos coincidentes.
    • Si se encuentra → adopta ese tema, adapta el marcador UID + etiquetas (el cuerpo se deja sin cambios en esta etapa).
    • Si no se encuentra → crea un tema completamente nuevo con el marcador y las etiquetas.
  3. Una vez adoptado o creado, todas las sincronizaciones futuras se resolverán directamente por UID.

⸻

  1. Consecuencias prácticas
    • Cambios de hora
    • Predeterminado: la adopción falla (las horas difieren) → se crea un nuevo tema.
    • Con --time-only-dedupe: la adopción falla de la misma manera; se crea un nuevo tema.
    • Cambios de ubicación
    • Predeterminado: la adopción falla (la ubicación difiere) → se crea un nuevo tema.
    • Con --time-only-dedupe: la adopción tiene éxito (las horas coinciden), pero la diferencia de ubicación se marca como “significativa” → actualizar con impulso.
    • Cambios de descripción
    • Si el texto de DESCRIPCIÓN cambia pero el inicio/fin/ubicación no:
    • El cuerpo se actualiza silenciosamente (bypass_bump=True).
    • Se crea una revisión del tema, pero sin impulso en Últimos.
    • Si la DESCRIPCIÓN no cambia (o solo ruido como Última actualización: que se normaliza), no se realiza ninguna actualización.
    • Marcador UID
    • Asegura una coincidencia confiable en sincronizaciones futuras.
    • Significa que los campos de DESCRIPCIÓN ruidosos no afectan si se encuentra el tema correcto.

⸻

  1. Por qué la DESCRIPCIÓN a veces “permanece igual”
    El script compara todo el cuerpo (menos el marcador UID).
    Si solo una línea volátil como Última actualización: es diferente, pero se normaliza (por ejemplo, espacios en blanco, finales de línea, Unicode), old_clean y fresh_clean parecen idénticos → no se realiza ninguna actualización.
    Esto es intencional, para evitar cambios innecesarios por ruido en la fuente.

⸻

Resumen
• La hora define la unicidad (siempre crea un nuevo tema cuando cambian las horas).
• Los cambios de ubicación → impulso visible (para que los usuarios noten las actualizaciones del lugar).
• Los cambios de descripción → actualización silenciosa (revisión pero sin impulso).
• Marcador UID = clave de identidad confiable, asegura que siempre se encuentre el tema correcto, incluso si la DESCRIPCIÓN está obsoleta o es ruidosa.

Esto logra un buen equilibrio: los cambios importantes aparecen en Últimos, la rotación sin importancia permanece invisible.