ICS → Importador do Discourse via API REST

Plugin Extras
,
12

Notas de comportamento de testes do ics_to_discourse.py

Tenho executado uma série de testes neste script (com e sem --time-only-dedupe) e pensei que seria útil documentar o fluxo de atualização/adoção em detalhes.

1. Como a exclusividade é determinada

  • Modo padrão: a adoção requer que início + fim + local correspondam exatamente.
  • Com --time-only-dedupe: a adoção requer apenas início + fim; o local é tratado como “próximo o suficiente”.

Se nenhum tópico existente corresponder a essas regras, um novo tópico é criado.

2. O papel do marcador UID

  • Cada tópico de evento recebe um marcador HTML oculto na primeira postagem:
  <!-- ICSUID:xxxxxxxxxxxxxxxx -->
  • Em execuções subsequentes, o script procura primeiro por esse marcador.
  • Se encontrado, o tópico é considerado uma correspondência de UID e atualizado diretamente, independentemente de quão barulhento ou desatualizado o texto da DESCRIÇÃO possa ser.
  • Isso torna o UID a verdadeira chave de identidade. Campos de descrição visíveis não afetam a correspondência.

3. Fluxo de atualização com correspondência de UID

  1. O script busca a primeira postagem e remove o marcador:
 old_clean = strip_marker(old_raw)
 fresh_clean = strip_marker(fresh_raw)
  1. Se old_clean == fresh_clean: nenhuma atualização (evita rotatividade).
  2. Se eles diferem: verifica se a alteração é “significativa”:
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"))
)
  • Se meaningful = True → atualiza com bump (tópico sobe em “Mais Recentes”).
  • Se meaningful = False → atualiza silenciosamente (bypass_bump=True → apenas revisão, sem bump).
  1. As tags são mescladas (garante que as tags estáticas/padrão estejam presentes, nunca remove as manuais/de moderador).
  2. Título e categoria nunca são alterados na atualização.
  1. Fluxo de atualização sem correspondência de UID
  2. O script tenta a adoção:
    • Constrói triplas candidatas de início/fim/local (ou apenas início/fim com --time-only-dedupe).
    • Pesquisa em /search.json e /latest.json por um evento existente com atributos correspondentes.
    • Se encontrado → adota esse tópico, adapta o marcador UID + tags (corpo deixado inalterado nesta fase).
    • Se não encontrado → cria um tópico totalmente novo com o marcador e as tags.
  3. Uma vez adotado ou criado, todas as sincronizações futuras serão resolvidas diretamente por UID.

⸻

  1. Consequências práticas
    • Alterações de horário
    • Padrão: a adoção falha (horários diferem) → novo tópico criado.
    • Com --time-only-dedupe: a adoção falha da mesma forma; novo tópico criado.
    • Alterações de local
    • Padrão: a adoção falha (local difere) → novo tópico criado.
    • Com --time-only-dedupe: a adoção é bem-sucedida (horários correspondem), mas a diferença de local é sinalizada como “significativa” → atualiza com bump.
    • Alterações de descrição
    • Se o texto da DESCRIÇÃO muda, mas início/fim/local não mudam:
    • O corpo é atualizado silenciosamente (bypass_bump=True).
    • Revisão do tópico criada, mas sem bump em “Mais Recentes”.
    • Se a DESCRIÇÃO não for alterada (ou apenas ruído como “Última Atualização:” que se normaliza), nenhuma atualização ocorre.
    • Marcador UID
    • Garante correspondência confiável em sincronizações futuras.
    • Significa que campos de DESCRIÇÃO ruidosos não afetam se o tópico correto é encontrado.

⸻

  1. Por que a DESCRIÇÃO às vezes “permanece a mesma”
    O script compara todo o corpo (menos o marcador UID).
    Se apenas uma linha volátil como “Última Atualização:” for diferente, mas se normalizar (por exemplo, espaços em branco, finais de linha, Unicode), old_clean e fresh_clean parecerão idênticos → nenhuma atualização é feita.
    Isso é intencional, para evitar rotatividade de ruído do feed.

⸻

Resumo
• O horário define a exclusividade (sempre cria um novo tópico quando os horários mudam).
• Alterações de local → bump visível (para que os usuários notem atualizações de local).
• Alterações de descrição → atualização silenciosa (revisão, mas sem bump).
• Marcador UID = chave de identidade confiável, garante que o tópico correto seja sempre encontrado, mesmo que a DESCRIÇÃO esteja desatualizada ou ruidosa.

Isso atinge um bom equilíbrio: mudanças importantes aparecem em “Mais Recentes”, a rotatividade sem importância permanece invisível.