InstallPayload، ولكن يتم التصريح عنها بدوال تعريف خاصة بها — definePostInstallLogicFunction() وdefinePreInstallLogicFunction() — وتعمل خارج نموذج المشغّل المعتاد (HTTP، وcron، وأحداث قاعدة البيانات).
يمكن لكل تطبيق تعريف دالة واحدة على الأكثر لما قبل التثبيت ودالة واحدة على الأكثر لما بعد التثبيت. سيُنتِج إنشاء ملف البيان خطأً إذا تم اكتشاف أكثر من واحدة من أيٍّ منهما.
definePostInstallLogicFunction
تعمل بعد تطبيق ترحيل البيانات الوصفية لمساحة العمل
definePostInstallLogicFunction
تعمل بعد تطبيق ترحيل البيانات الوصفية لمساحة العمل
تعمل دالة ما بعد التثبيت تلقائيًا بمجرد انتهاء تثبيت تطبيقك على مساحة عمل. ينفّذه الخادم بعد مزامنة البيانات الوصفية للتطبيق وإنشاء عميل SDK، بحيث تكون مساحة العمل جاهزة تمامًا للاستخدام ويكون المخطط الجديد مطبَّقًا. تشمل حالات الاستخدام النموذجية تهيئة البيانات الافتراضية، وإنشاء السجلات الأولية، وتكوين إعدادات مساحة العمل، أو توفير الموارد على خدمات جهات خارجية.يمكنك أيضًا تنفيذ دالة ما بعد التثبيت يدويًا في أي وقت باستخدام CLI:النقاط الرئيسية:
src/logic-functions/post-install.ts
- تستخدم دوال ما بعد التثبيت
definePostInstallLogicFunction()— إصدارًا متخصصًا يستبعد إعدادات المُشغِّل (cronTriggerSettingsوdatabaseEventTriggerSettingsوhttpRouteTriggerSettingsوtoolTriggerSettingsوworkflowActionTriggerSettings). - يتلقى المعالج
InstallPayloadيحتوي على{ previousVersion?: string; newVersion: string }— حيث إنnewVersionهو الإصدار الجاري تثبيته، وpreviousVersionهو الإصدار الذي كان مُثبّتًا سابقًا (أوundefinedعند التثبيت الأولي). استخدم هذه القيم للتمييز بين عمليات التثبيت الجديدة والترقيات ولتشغيل منطق الترحيل الخاص بالإصدار. - موعد تشغيل الخطاف: في عمليات التثبيت الجديدة فقط، افتراضيًا. مرّر
shouldRunOnVersionUpgrade: trueإذا كنت تريد تشغيله أيضًا عند ترقية التطبيق من إصدار سابق. عند إغفاله، تكون القيمة الافتراضية للعلمfalse، وتتجاوز الترقيات هذا الخطاف. - نموذج التنفيذ — غير متزامن افتراضيًا، والتزامني اختياري: يتحكّم العلم
shouldRunSynchronouslyفي كيفية تنفيذ ما بعد التثبيت.shouldRunSynchronously: false(الإعداد الافتراضي) — يتم إدراج الخطاف في قائمة الرسائل معretryLimit: 3ويعمل بشكل غير متزامن داخل عامل عمل. يعود ردّ التثبيت بمجرد وضع المهمة في الطابور، لذا فإن معالجًا بطيئًا أو متعطلًا لا يحجب المستدعي. سيُجرِّب العامل إعادة المحاولة حتى ثلاث مرات. استخدم هذا للمهام طويلة التشغيل — بَذر مجموعات بيانات كبيرة، استدعاء واجهات برمجة تطبيقات خارجية بطيئة، تهيئة موارد خارجية، أو أي شيء قد يتجاوز نافذة استجابة HTTP المعقولة.shouldRunSynchronously: true— يُنفّذ الخطاف ضمن تدفّق التثبيت مباشرةً (نفس المنفِّذ كما قبل التثبيت). يَحجُب طلب التثبيت حتى ينتهي المعالج، وإذا رمى استثناءً، سيتلقى مستدعي التثبيتPOST_INSTALL_ERROR. لا توجد محاولات إعادة تلقائية. استخدم هذا للمهام السريعة التي يجب إكمالها قبل الاستجابة — مثل إظهار خطأ تحقق للمستخدم، أو إعداد سريع سيعتمد عليه العميل مباشرةً بعد عودة نداء التثبيت. ضع في اعتبارك أن ترحيل البيانات الوصفية يكون قد طُبِّق بالفعل عند تشغيل ما بعد التثبيت، لذلك فإن فشل الوضع المتزامن لا يعيد التغييرات على المخطط إلى الوراء — بل يكتفي بإبراز الخطأ.
- تأكّد من أن معالجك قابل للتنفيذ المتكرر دون آثار جانبية. في الوضع غير المتزامن قد تُعيد قائمة الانتظار المحاولة حتى ثلاث مرات؛ وفي أي من الوضعين قد يعمل الخطاف مجددًا أثناء الترقيات عند ضبط
shouldRunOnVersionUpgrade: true. - متغيرات البيئة
APPLICATION_IDوAPP_ACCESS_TOKENوAPI_URLمتاحة داخل المعالج (كما في أي دالة منطق أخرى)، لذا يمكنك استدعاء واجهة Twenty API باستخدام رمز وصول للتطبيق مقيّد بنطاق تطبيقك. - يُسمح بدالة ما بعد التثبيت واحدة فقط لكل تطبيق. سيُنتج إنشاء ملف البيان خطأً إذا تم اكتشاف أكثر من واحدة.
- تُرفَق خصائص الدالة
universalIdentifierوshouldRunOnVersionUpgradeوshouldRunSynchronouslyتلقائيًا ببيان التطبيق ضمن الحقلpostInstallLogicFunctionأثناء عملية البناء — ولا تحتاج إلى الإشارة إليها فيdefineApplication(). - تم تعيين مهلة افتراضية إلى 300 ثانية (5 دقائق) للسماح بمهام الإعداد الأطول مثل تهيئة البيانات.
- لا يُنفَّذ في وضع التطوير: عند تسجيل تطبيق محليًا (عبر
yarn twenty dev)، يتجاوز الخادم تدفّق التثبيت بالكامل ويُزامن الملفات مباشرةً عبر مراقِب CLI — لذا لن يعمل ما بعد التثبيت في وضع التطوير مطلقًا، بغضّ النظر عنshouldRunSynchronously. استخدمyarn twenty dev:function:exec --postInstallلتشغيله يدويًا على مساحة عمل قيد التشغيل.
definePreInstallLogicFunction
تعمل قبل تطبيق ترحيل البيانات الوصفية لمساحة العمل
definePreInstallLogicFunction
تعمل قبل تطبيق ترحيل البيانات الوصفية لمساحة العمل
تعمل دالة ما قبل التثبيت تلقائيًا أثناء التثبيت، قبل تطبيق ترحيل البيانات الوصفية لمساحة العمل. تتشارك نفس بنية الحمولة مع ما بعد التثبيت (يمكنك أيضًا تنفيذ دالة ما قبل التثبيت يدويًا في أي وقت باستخدام CLI:النقاط الرئيسية:
InstallPayload)، لكنها موضوعة أبكر في تدفّق التثبيت كي تجهّز حالة يعتمد عليها الترحيل القادم — ومن الاستخدامات الشائعة: نسخ البيانات احتياطيًا، التحقق من التوافق مع المخطط الجديد، أو أرشفة السجلات التي ستُعاد هيكلتها أو ستُحذف.src/logic-functions/pre-install.ts
- تستخدم دوال ما قبل التثبيت
definePreInstallLogicFunction()— نفس الإعدادات المتخصصة كما في ما بعد التثبيت، لكنها مرتبطة بموضع مختلف ضمن دورة الحياة. - يتلقّى كلٌّ من معالجي ما قبل التثبيت وما بعد التثبيت النوع نفسه
InstallPayload:{ previousVersion?: string; newVersion: string }. استورده مرة واحدة وأعد استخدامه لكلا الخطافين. - موعد تشغيل الخطاف: موضوع مباشرةً قبل ترحيل البيانات الوصفية لمساحة العمل (
synchronizeFromManifest). قبل التنفيذ، يُشغِّل الخادم مزامنة “pared-down sync” ذات طابع إضافي فقط تقوم بتسجيل دالة ما قبل التثبيت للإصدار الجديد في البيانات الوصفية لمساحة العمل — دون لمس أي شيء آخر — ثم يُنفّذها. لأن هذه المزامنة «إضافية فقط»، تبقى كائنات وحقول وبيانات الإصدار السابق سليمة عند تشغيل معالجك: يمكنك قراءة حالة ما قبل الترحيل ونسخها احتياطيًا بأمان. - نموذج التنفيذ: يُنفَّذ ما قبل التثبيت بشكل متزامن ويحجب عملية التثبيت. إذا رمى المعالج استثناءً، تُلغى عملية التثبيت قبل تطبيق أي تغييرات على المخطط — وتبقى مساحة العمل على الإصدار السابق بحالة متّسقة. هذا مقصود: ما قبل التثبيت هو فرصتك الأخيرة لرفض ترقية تنطوي على مخاطر.
- كما هو الحال مع ما بعد التثبيت، يُسمح بدالة ما قبل التثبيت واحدة فقط لكل تطبيق. تُربَط تلقائيًا ببيان التطبيق تحت
preInstallLogicFunctionأثناء عملية البناء. - لا يُنفَّذ في وضع التطوير: كما في ما بعد التثبيت — يتم تجاوز تدفّق التثبيت بالكامل للتطبيقات المسجّلة محليًا، لذا لن يعمل ما قبل التثبيت مطلقًا عند
yarn twenty dev. استخدمyarn twenty dev:function:exec --preInstallلتشغيله يدويًا.
ما قبل التثبيت مقابل ما بعد التثبيت: متى تستخدم أيّهما
اختيار خطاف التثبيت المناسب
ما قبل التثبيت مقابل ما بعد التثبيت: متى تستخدم أيّهما
اختيار خطاف التثبيت المناسب
كلا الخطافين جزء من تدفّق التثبيت نفسه ويتلقّيان نفس استخدم قاعدة عامة:
InstallPayload. الاختلاف يكمن في موعد تشغيلهما نسبةً إلى ترحيل البيانات الوصفية لمساحة العمل، وهذا يغيّر البيانات التي يمكنهما التعامل معها بأمان.ما قبل التثبيت دائمًا متزامن (يحجب التثبيت ويمكنه إحباطه). ما بعد التثبيت غير متزامن افتراضيًا — يُدرج على عامل مع محاولات إعادة تلقائية — لكن يمكن التبديل إلى تنفيذ متزامن عبر shouldRunSynchronously: true. راجع الأكورديون definePostInstallLogicFunction أعلاه لمعرفة متى تستخدم كل وضع.استخدم post-install لأي شيء يتطلّب وجود المخطط الجديد. وهذا هو السيناريو الشائع:- بَذر بيانات افتراضية (إنشاء سجلات أولية وعروض افتراضية ومحتوى تجريبي) للكائنات والحقول المضافة حديثًا.
- تسجيل خطافات الويب مع خدمات أطراف ثالثة بعد أن حصل التطبيق على بيانات الاعتماد الخاصة به.
- استدعاء واجهة برمجة التطبيقات الخاصة بك لإكمال إعداد يعتمد على البيانات الوصفية المتزامنة.
- منطق قابل للتنفيذ المتكرر دون آثار جانبية لتحقيق “تأكّد من وجود هذا” والذي ينبغي مواءمة الحالة في كل ترقية — بالاقتران مع
shouldRunOnVersionUpgrade: true.
PostCard افتراضي بعد التثبيت:src/logic-functions/post-install.ts
pre-install عندما قد يُتلف الترحيل أو يدمّر البيانات الحالية. لأن ما قبل التثبيت يعمل مقابل المخطط السابق وفشله يُرجِع الترقية إلى الوراء، فهو المكان المناسب لأي شيء محفوف بالمخاطر:- نسخ البيانات احتياطيًا قبل حذفها أو إعادة هيكلتها — مثل إزالة حقل في v2 وتحتاج إلى نسخ قيمه إلى حقل آخر أو تصديرها إلى التخزين قبل تشغيل الترحيل.
- أرشفة السجلات التي سيبطلها قيد جديد — مثل أن يصبح حقل ما
NOT NULLوتحتاج أولًا إلى حذف الصفوف ذات القيم الفارغة أو إصلاحها. - التحقق من التوافق ورفض الترقية إذا تعذّر ترحيل البيانات الحالية بسلاسة — ارمِ من داخل المعالج وسيُلغى التثبيت دون تطبيق أي تغييرات. هذا أكثر أمانًا من اكتشاف عدم التوافق في منتصف الترحيل.
- إعادة تسمية البيانات أو إعادة تعيين مفاتيحها قبل تغيير في المخطط قد يؤدي إلى فقدان الارتباط.
src/logic-functions/pre-install.ts
| ترغب في… | استخدام |
|---|---|
| بذر بيانات افتراضية، تهيئة مساحة العمل، تسجيل موارد خارجية | post-install |
| تشغيل بذر طويل الأمد أو استدعاءات أطراف ثالثة لا ينبغي أن تحجب استجابة التثبيت | post-install (الإعداد الافتراضي — shouldRunSynchronously: false، مع محاولات إعادة من العامل) |
| تشغيل إعداد سريع سيعتمد عليه المستدعي مباشرةً بعد عودة نداء التثبيت | post-install مع shouldRunSynchronously: true |
| قراءة البيانات أو نسخها احتياطيًا والتي قد يفقدها الترحيل القادم | pre-install |
| رفض ترقية قد تُفسد البيانات الحالية | pre-install (ارمِ من المعالج) |
| تنفيذ مواءمة في كل ترقية | post-install مع shouldRunOnVersionUpgrade: true |
| تنفيذ إعداد لمرة واحدة في التثبيت الأول فقط | post-install مع shouldRunOnVersionUpgrade: false (الإعداد الافتراضي) |
إذا ساورك الشك، فاجعل الافتراضي هو post-install. الجأ إلى ما قبل التثبيت فقط عندما يكون الترحيل نفسه هدّامًا وتحتاج إلى التقاط الحالة السابقة قبل أن تزول.