المزامنة والاستعادة

يدور تطوير التطبيقات محليًا حول المزامنة: يقوم الـ CLI بإعادة إنشاء ملف manifest الخاص بك ويطبّق الخادم فقط الفرق بينه وبين البيانات الوصفية الموجودة بالفعل في مساحة العمل لديك. تغطي هذه الصفحة الأمر الذي ينبغي استخدامه، وكيفية قراءة ما غيّرته المزامنة، وما الذي يجب فعله — بالترتيب — عندما تبدو الحالة المحلية غير متسقة.

أي أمر، ومتى

للتكرار اليومي المحلي ستحتاج تقريبًا دائمًا إلى yarn twenty dev. يُستخدم النشر والإصدار لإطلاق الإصدارات، وليس للحلقة المحلية.

ترغب في…	أمر	الملاحظات
التكرار محليًا مع المزامنة الحية	`yarn twenty dev`	يراقب ملفاتك ويجري مزامنة عند كل تغيير.
مزامنة واحدة ثم إنهاء (CI، السكربتات، الخطّافات)	`yarn twenty apply`	عملية إنشاء واحدة + مزامنة، ثم إنهاء. أضف `--force` لتخطي تأكيد التغيير التدميري.
معاينة التغييرات بدون تطبيقها	`yarn twenty plan`	يحتسب الفرق ويطبعه؛ ولا يكتب أي شيء.
إزالة التطبيق من مساحة العمل	`yarn twenty app:uninstall`	أضف `--yes` لتخطي رسالة التأكيد.
إرسال ملف tarball إلى خادم	`yarn twenty app:publish --private`	يتطلّب إصدارًا أعلى بشكل صارم في `package.json` — راجع قسم النشر.
النشر في السوق (npm)	`yarn twenty app:publish`	—
تثبيت / ترقية إصدار منشور	`yarn twenty app:install`	يُثبّت الإصدار المنشور حاليًا.
مسح الخادم المحلي والبدء من جديد	`yarn twenty docker:reset`	يحذف كل البيانات المحلية — كملاذ أخير.

الأوامر yarn twenty dev --once وyarn twenty dev --once --dry-run هي أسماء بديلة مهملة للأمرين yarn twenty apply وyarn twenty plan.

لا تحتاج المزامنة المحلية إلى زيادة في الإصدار

تنطبق قاعدة version المتزايدة بدقة (VERSION_ALREADY_EXISTS عند النشر، وAPP_ALREADY_INSTALLED / CANNOT_DOWNGRADE_APPLICATION عند التثبيت) على app:publish / app:install — مسار الإصدارات. يقوم yarn twenty dev بمزامنة ملف manifest في مكانه ولا يتطلّب تغيير الإصدار أبدًا، لذا لست بحاجة إلى تعديل package.json للتكرار. إذا وجدت نفسك تزيد الإصدار لاختبار تغيير محلي، فأنت تستخدم مسار الإصدارات بينما ما تريده هو حلقة التطوير.

قراءة مخرجات المزامنة

كل عملية مزامنة تطبع تغييرات البيانات الوصفية التي تم تطبيقها (أو التي سيتم تطبيقها عند استخدام plan)، على غرار Terraform — كتلة واحدة لكل كيان مع خصائصه، ثم سطر ملخص:

  # objectMetadata "rocket" will be created
  + icon          = "IconRocket"
  + labelSingular = "Rocket"
  + ...

  # fieldMetadata "launchedAt" will be updated
  ~ isNullable = false -> true

Plan: 2 to add, 1 to change, 1 to destroy.

✓ Synced My App (4 files)

هذه أداتك الأولى للتشخيص: تُخبرك بدقة ما الكائنات والحقول والتخطيطات التي تغيّرت، بحيث يمكنك التأكد من أن المزامنة أنجزت ما توقّعته قبل التحقّق من واجهة المستخدم. التغييرات التدميرية (to destroy) تُدرج مع ما تقوم بحذفه (على سبيل المثال objectMetadata "auditNote" — drops the table and all its rows) وتتطلب تأكيدًا تفاعليًا، أو استخدام --force في السكربتات. عندما تفشل المزامنة على كيان واحد، يذكر الخطأ اسم الكيان المسبب للمشكلة وuniversalIdentifier الخاص به، على سبيل المثال:

Migration action 'create' for 'fieldMetadata' (universalIdentifier: 2020...4337) failed

استخدم ذلك المعرّف للعثور على الكيان في ملف manifest الخاص بك (وإن لزم الأمر، في مساحة العمل) بدلًا من تخمين أيّها يتعارض.

معاينة التغييرات (plan)

يقوم yarn twenty plan ببناء ملف manifest الخاص بك، ويطلب من الخادم خطة الترحيل، ويطبعها — بدون تطبيق أي شيء. إنها الطريقة الآمنة للإجابة عن سؤال “ما الذي ستغيّره هذه المزامنة؟” قبل الالتزام بها.

yarn twenty plan

Building manifest...
Computing metadata plan (read-only, nothing will be applied)...

  # fieldMetadata "crewCapacity" will be created
  + ...

Plan: 1 to add, 1 to change, 0 to destroy.

✓ Plan complete for My App — no changes were applied

خطة:

لا يكتب أي شيء — لا ترحيل لبيانات وصفية، ولا تحديث لسجل التطبيق، ولا تغييرات في الأدوار/التبويبات الافتراضية، ولا توليد لعميل API.
يُرجع نفس الفرق الذي ستُطبِّقه مزامنة حقيقية، حتى تتمكن من مراجعة الكيانات التي سيتم إنشاؤها/تحديثها/حذفها مسبقًا.
يكون مفيدًا قبل إجراء تغيير محفوف بالمخاطر، أو عند مراجعة تغيير تم إنشاؤه بواسطة الذكاء الاصطناعي، أو في سكربت يجب أن يفشل إذا كان تغيير غير متوقَّع على وشك الحدوث.

تقوم الخطة فقط بمعاينة تغييرات البيانات الوصفية، ويتطلّب ذلك أن يكون التطبيق قد تمت مزامنته مرة واحدة على الأقل (حتى تعرف به مساحة العمل). إذا شغّلته ضد تطبيق لم تتم مزامنته من قبل، سيبلغ الخادم أن التطبيق غير مُثبّت — شغّل yarn twenty dev مرة واحدة أولًا.

سلّم الاستعادة

عندما تبدو البيانات الوصفية المحلية غير صحيحة، صعِّد الإجراءات بهذا الترتيب وتوقّف بمجرد زوال العائق. كل خطوة أكثر إرباكًا من التي قبلها.

أعد المزامنة. شغّل yarn twenty apply مرة أخرى. عمليات المزامنة متطابِقة الأثر (idempotent) — إعادة تشغيل ملف manifest النظيف آمنة وغالبًا ما تحل تعثرًا عابرًا.
عاين الخطة. شغّل yarn twenty plan لرؤية ما الذي تنوي المزامنة التالية تغييره بالضبط، بدون تطبيقه.
اقرأ الخطأ المسمّى. إذا فشلت المزامنة، لاحظ نوع البيانات الوصفية وuniversalIdentifier في الرسالة (انظر أعلاه) وحدّد ذلك الكيان في ملف manifest الخاص بك. يشير التعارض عادةً إلى معرّف مكرر أو مُعاد استخدامه.
إلغاء التثبيت وإعادة التثبيت. شغّل yarn twenty app:uninstall، ثم أجرِ مزامنة مرة أخرى (yarn twenty dev). هذا يعيد بناء بيانات التطبيق الوصفية من نقطة بداية نظيفة مع إبقاء باقي مساحة العمل سليمة.
إعادة تعيين كاملة (الملاذ الأخير). شغّل yarn twenty docker:reset، ثم أعد التهيئة والمزامنة.

يقوم yarn twenty docker:reset بحذف كل البيانات في النسخة المحلية لديك — كل مساحة عمل، وكل سجل، وكل تطبيق. استخدمه فقط بعد فشل الخطوات السابقة.

هل واجهت خطأ في البيانات الوصفية؟ يرجى فتح مشكلة وإرفاق رسالة الترحيل الفاشلة (بما في ذلك نوع البيانات الوصفية وuniversalIdentifier)، ومخرجات Metadata changes من عملية المزامنة، والأوامر التي شغّلتها.

تجنّب إجراء مزامنات متزامنة على مساحة عمل واحدة

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

تمييز أنواع الإخفاقات

عندما يحدث خلل ما، يتيح لك فرق البيانات الوصفية والأخطاء المسمّاة تحديد موضع الفشل:

خطأ في إنشاء ملف manifest — يفشل الـ CLI قبل إجراء المزامنة (MANIFEST_BUILD_FAILED، TYPECHECK_FAILED)؛ أصلِح كود التطبيق لديك.
خطأ في المزامنة / الترحيل — تنجح عملية الإنشاء لكن يفشل تطبيق الفرق، مع تسمية الكيان وuniversalIdentifier؛ أصلِح البيانات الوصفية المتعارِضة.
خطأ في وقت تشغيل كود التطبيق — تتم المزامنة بنجاح، ولكن دوال المنطق أو المكوّنات لديك لا تعمل بشكل صحيح أثناء وقت التشغيل؛ تحقّق من سجلات الدوال.
حالة المثيل المحلي — لا ينطبق أيّ مما سبق وما زالت مساحة العمل تبدو غير صحيحة؛ تابع النزول في سلّم الاستعادة.

نظرة عامة

التطبيقات

واجهة برمجة التطبيقات

الاستضافة الذاتية

المساهمة

المزامنة والاستعادة

أي أمر، ومتى

لا تحتاج المزامنة المحلية إلى زيادة في الإصدار

قراءة مخرجات المزامنة

معاينة التغييرات (plan)

سلّم الاستعادة

تجنّب إجراء مزامنات متزامنة على مساحة عمل واحدة

تمييز أنواع الإخفاقات

​أي أمر، ومتى

​لا تحتاج المزامنة المحلية إلى زيادة في الإصدار

​قراءة مخرجات المزامنة

​معاينة التغييرات (plan)

​سلّم الاستعادة

​تجنّب إجراء مزامنات متزامنة على مساحة عمل واحدة

​تمييز أنواع الإخفاقات

أي أمر، ومتى

لا تحتاج المزامنة المحلية إلى زيادة في الإصدار

قراءة مخرجات المزامنة

معاينة التغييرات (plan)

سلّم الاستعادة

تجنّب إجراء مزامنات متزامنة على مساحة عمل واحدة

تمييز أنواع الإخفاقات