ICS → مستورد Discourse عبر واجهة برمجة تطبيقات REST

إضافة إضافات
,
12

ملاحظات سلوكية من اختبار ics_to_discourse.py

لقد أجريت سلسلة من الاختبارات على هذا البرنامج النصي (مع وبدون --time-only-dedupe) واعتقدت أنه سيكون من المفيد توثيق تدفق التحديث/التبني بالتفصيل.

1. كيفية تحديد التفرد

  • الوضع الافتراضي: يتطلب التبني تطابق البداية + النهاية + الموقع بالضبط.
  • مع --time-only-dedupe: يتطلب التبني فقط البداية + النهاية؛ يُعامل الموقع على أنه “قريب بما فيه الكفاية”.

إذا لم يتطابق أي موضوع موجود مع هذه القواعد، يتم إنشاء موضوع جديد.

2. دور علامة UID

  • يحصل كل موضوع حدث على علامة HTML مخفية في المنشور الأول:
  <!-- ICSUID:xxxxxxxxxxxxxxxx -->
  • في عمليات التشغيل اللاحقة، يبحث البرنامج النصي عن تلك العلامة أولاً.
  • إذا تم العثور عليها، يُعتبر الموضوع مطابقًا لـ UID ويتم تحديثه مباشرة، بغض النظر عن مدى صخب أو قدم نص الوصف.
  • هذا يجعل UID مفتاح الهوية الحقيقي. حقول الوصف المرئية لا تؤثر على المطابقة.

3. تدفق التحديث مع مطابقة UID

  1. يجلب البرنامج النصي المنشور الأول ويزيل العلامة:
 old_clean = strip_marker(old_raw)
 fresh_clean = strip_marker(fresh_raw)
  1. إذا كان old_clean == fresh_clean: لا يوجد تحديث (يتجنب التغيير).
  2. إذا اختلفا: تحقق مما إذا كان التغيير “ذا مغزى”:
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"))
)
  • إذا كان meaningful = True → تحديث مع دفعة (يرتفع الموضوع في الأحدث).
  • إذا كان meaningful = False → تحديث بهدوء (bypass_bump=True → مراجعة فقط، لا دفعة).
  1. يتم دمج العلامات (يضمن وجود العلامات الثابتة/الافتراضية، ولا يزيل أبدًا العلامات اليدوية/الخاصة بالمشرف).
  2. لا يتم تغيير العنوان والفئة أبدًا عند التحديث.
  1. تدفق التحديث بدون مطابقة UID
  2. يحاول البرنامج النصي التبني:
    • يبني ثلاثيات مرشحة للبداية/النهاية/الموقع (أو البداية/النهاية فقط مع --time-only-dedupe).
    • يبحث في /search.json و /latest.json عن حدث موجود بسمات متطابقة.
    • إذا تم العثور عليه → تبني هذا الموضوع، وتزويده بعلامة UID والعلامات (يُترك الجسم دون تغيير في هذه المرحلة).
    • إذا لم يتم العثور عليه → إنشاء موضوع جديد تمامًا بالعلامة والعلامات.
  3. بمجرد تبنيه أو إنشائه، ستحل جميع المزامنات المستقبلية مباشرة عن طريق UID.

⸻

  1. العواقب العملية
    • تغييرات الوقت
    • افتراضي: يفشل التبني (الأوقات مختلفة) → يتم إنشاء موضوع جديد.
    • مع --time-only-dedupe: يفشل التبني بنفس الطريقة؛ يتم إنشاء موضوع جديد.
    • تغييرات الموقع
    • افتراضي: يفشل التبني (الموقع مختلف) → يتم إنشاء موضوع جديد.
    • مع --time-only-dedupe: ينجح التبني (الأوقات متطابقة)، ولكن يتم تمييز اختلاف الموقع على أنه “ذو مغزى” → تحديث مع دفعة.
    • تغييرات الوصف
    • إذا تغير نص الوصف ولكن لم تتغير البداية/النهاية/الموقع:
    • يتم تحديث الجسم بهدوء (bypass_bump=True).
    • يتم إنشاء مراجعة للموضوع، ولكن لا توجد دفعة في الأحدث.
    • إذا لم يتغير الوصف (أو كان مجرد ضوضاء مثل Last Updated: التي يتم تطبيعها بعيدًا)، فلن يحدث أي تحديث على الإطلاق.
    • علامة UID
    • يضمن المطابقة الموثوقة في المزامنات المستقبلية.
    • يعني أن حقول الوصف الصاخبة لا تؤثر على ما إذا كان الموضوع الصحيح سيتم العثور عليه.

⸻

  1. لماذا يبقى الوصف “كما هو” أحيانًا
    يقارن البرنامج النصي الجسم بأكمله (باستثناء علامة UID).
    إذا كان سطر متقلب فقط مثل Last Updated: مختلفًا، ولكنه يتم تطبيعه بعيدًا (مثل المسافات البيضاء، نهايات الأسطر، Unicode)، فإن old_clean و fresh_clean يبدوان متطابقين → لا يتم إجراء أي تحديث.
    هذا عن قصد، لمنع التغيير من ضوضاء التغذية.

⸻

ملخص
• الوقت يحدد التفرد (ينشئ دائمًا موضوعًا جديدًا عند تغيير الأوقات).
• تغييرات الموقع → دفعة مرئية (حتى يلاحظ المستخدمون تحديثات المكان).
• تغييرات الوصف → تحديث هادئ (مراجعة ولكن لا دفعة).
• علامة UID = مفتاح هوية موثوق، يضمن العثور دائمًا على الموضوع الصحيح، حتى لو كان الوصف قديمًا أو صاخبًا.

هذا يحقق توازنًا جيدًا: التغييرات المهمة تظهر في الأحدث، والتغييرات غير المهمة تبقى غير مرئية.