// tier: vasic-util-secondary · order 26

task_bridge scaffoldlicense: UNVERIFIED

GoSQLite (workable-items SSoT)raksul/go-clickup (MIT dependency)HMAC-SHA256 webhook verificationcron + webhookspkg/config runtime injection boundary

Source

• vasic-digital/task_bridge

// architecture

المحتوى لوح مهامك ومصدر الحقيقة الخاص بك، متزامنان بدقة تامة — في كلا الاتجاهين.

task_bridge هو محرك مزامنة عام وغير مترابط ثنائي الاتجاه للمهام/الألواح في Go. يحافظ على تزامن مصدر الحقيقة القابل للعمل SQLite للمشروع مع وثائق المتتبع ولوح التحكم البعيد (الهدف الأول: ClickUp؛ مخطط لإضافة Jira/Linear) باستخدام منطق "آخر تعديل يفوز" الحتمي، مع تنفيذ تجريبي أولي وضمانات بعدم الإفساد مطلقًا.

وحدة فرعية في Go مستقلة عن المشروع، تقوم بمزامنة ثنائية الاتجاه بين مصدر الحقيقة القابل للعمل SQLite ↔ وثائق المتتبع ↔ لوح التحكم البعيد (ClickUp أولاً). منطق "آخر تعديل يفوز" الحتمي، تنفيذ تجريبي أولي، وتحقق عبر HMAC من خطافات الويب؛ تُحقن جميع بيانات الاعتماد والمعرفات من قبل المستهلك أثناء التشغيل.

في نهاية المطاف، تحتفظ كل فريق بسجلين للعمل نفسه: السجل الحقيقي — الكود، الوثائق، قاعدة البيانات الداخلية — والسجل الذي يراقبه المديرون، مثل لوح التحكم في ClickUp. ينفصل السجلان في اللحظة التي يُلمس فيها أي منهما، وتوفيقهما يدويًا هو بالضبط نوع المهام المملة والمعرضة للأخطاء التي لا يقوم بها أحد بشكل موثوق. بُني task_bridge لسد هذه الفجوة من خلال التعامل مع التمثيلات الثلاث كنظام واحد يُحافظ على تزامنها التام: مصدر الحقيقة القابل للعمل SQLite للمشروع، وتوثيق المتتبع، ولوح التحكم البعيد — حيث يُعد ClickUp أول لوح مدعوم، مع خطط لإضافة Jira وLinear مستقبلًا. تتم المزامنة بشكل حتمي ("آخر تعديل يفوز")، مع تنفيذ تجريبي أولي، ومصممة حول وعد واحد غير قابل للتفاوض: لن تفسد البيانات أو تفقدها أبدًا، ولن تترك أي جانب متخلفًا بصمت. في مجال قد يؤدي فيه مزامنة غير حذرة إلى الكتابة فوق أسبوع من العمل، فإن هذا النهج الآمن هو الهدف الأساسي. من الناحية المعمارية، تُعد الوحدة وحدة فرعية صارمة تُستخدم من قبل مشاريع أخرى وهي مستقلة تمامًا عن المشروع وفقًا لعقد الفصل في الدستور (§11.4.28): فهي لا تحتوي على أي قيم خاصة بالمشروع، وتُحقن جميع بيانات الاعتماد ومعرفات اللوح/المجلد وحقول مفاتيح العناصر ومسارات قاعدة البيانات من قبل المستهلك أثناء التشغيل عبر pkg/config.Config. تتكون الوحدة من طبقات واضحة: CLI (reconcile/push/pull/resolve/status/conflicts/init) وخادم دائم التشغيل (مستقبل خطافات الويب + مزامنة دورية)؛ غلاف عميل رفيع فوق مكتبة raksul/go-clickup المرخصة بموجب MIT؛ محلل يحول عناوين URL للألواح/المجلدات إلى معرفات عبر استعلامات API المباشرة (دون تخمين لقواعد URL)؛ محول بين العناصر القابلة للعمل المحلية وحقول المهام البعيدة؛ محرك مزامنة يعتمد منطق "آخر تعديل يفوز" مع نتائج صراعية للتعارضات؛ ومستقبل خطافات ويب يتحقق من توقيع X-Signature باستخدام HMAC-SHA256. إنها صريحة بشأن مستوى نضجها: هذا هو الهيكل الأساسي للمرحلة الأولى — التصميم، الواجهات، نقاط الدخول، وحدود الفصل جاهزة، لكن منطق المزامنة واستدعاءات ClickUp المباشرة لم تُنفذ بعد (كل عنصر وهمي يُرجع خطأ صريحًا بعدم التنفيذ، وفقًا لقاعدة "عدم التزييف").

تحتفظ الفرق بالحالة "الحقيقية" للعمل في الكود/الوثائق بينما يعيش المديرون على لوح تحكم مثل ClickUp — وينفصلان باستمرار. يجعل task_bridge منهما نظامًا واحدًا، مزامنًا بشكل حتمي وآمن حتى لا يصبح أي جانب متخلفًا أو خاطئًا.

المحتوى

عادةً ما يكون المزامنة الثنائية للوحات عملية تكامل لمرة واحدة ومبرمجة بشكل جامد يعيد كل فريق بناؤها بطريقة سيئة. يعيد task_bridge صياغة هذا المفهوم ك مكتبة قابلة لإعادة الاستخدام تُحقن فيها بيانات الاعتماد مع ضمانات صارمة لسلامة البيانات — التنفيذ التجريبي أولاً، وآلية "آخر تعديل يفوز" الحتمية، والأحداث المُتحقَّق منها باستخدام HMAC — مما يسمح لأي مشروع باعتماد تكامل موثوق للوحات من خلال حقن الإعدادات بدلاً من كتابة موصل هش آخر مرتبط ببنيته الداخلية.

• مزامنة ثنائية الاتجاه ثلاثية المسارات: SQLite (المصدر الوحيد للحقيقة) ↔ وثائق المتتبع ↔ اللوحة البعيدة.
• فك الارتباط الكامل (§11.4.28): لا قيم للمشروع؛ كلها تُحقن أثناء التشغيل.
• حل URL→المعرفات عبر API المباشر بدلاً من تحليل قواعد URL الهش.
• التحقق من صحة أحداث الويب هوك باستخدام HMAC-SHA256 للبث المباشر.

• سلامة البيانات عبر ثلاثة مصادر: تم حلها باستخدام آلية "آخر تعديل يفوز" الحتمية، والتنفيذ التجريبي أولاً، ونتائج صراعية واضحة للتعارضات.
• إعادة الاستخدام دون اقتران: تم حلها عبر حدود حقن pkg/config (دون تضمين تفاصيل المشروع في النسخة المُصدَّرة).
• تحديد اللوحات بشكل موثوق: تم حلها من خلال تحويل عناوين URL إلى معرفات عبر مسابير API المباشرة.
• الشفافية في البناء: تم حلها بجعل الوظائف غير المنفذة تُرجع أخطاء صريحة بعدم التنفيذ (دون استخدام بدائل وهمية).

• Go — المحرك، وCLI (cmd/task_bridge)، والخادم (cmd/task_bridged).
• SQLite — المصدر الوحيد للحقيقة للعناصر القابلة للعمل.
• raksul/go-clickup (MIT) — غلاف نقل ClickUp.
• HMAC-SHA256 — التحقق من توقيع أحداث الويب هوك.
• cron + ويب هوك — مزامنة الخادم + استقبال الأحداث المباشرة.
• pkg/config — حدود حقن بيانات الاعتماد/المعرفات أثناء التشغيل.

الشفافية في الحالة: هذا هيكل أولويته P1 — منطق المزامنة لم يُنفَّذ بعد. لا تُقدَّم على أنها نسخة جاهزة للإصدار.