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

​
أي أمر، ومتى

للتكرار اليومي المحلي ستحتاج تقريبًا دائمًا إلى yarn twenty dev. يُستخدم النشر والإصدار لإطلاق الإصدارات، وليس للحلقة المحلية.
ترغب في…أمرالملاحظات
التكرار محليًا مع المزامنة الحيةyarn twenty devيراقب ملفاتك ويجري مزامنة عند كل تغيير.
مزامنة واحدة ثم إنهاء (CI، السكربتات، الخطّافات)yarn twenty dev --onceعملية إنشاء واحدة + مزامنة، ثم إنهاء.
معاينة التغييرات بدون تطبيقهاyarn twenty dev --once --dry-runيحتسب الفرق ويطبعه؛ ولا يكتب أي شيء.
إزالة التطبيق من مساحة العمل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يحذف كل البيانات المحلية — كملاذ أخير.

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

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

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

كل عملية مزامنة تطبع التغييرات في البيانات الوصفية التي تم تطبيقها (أو التي سيتم تطبيقها، مع خيار --dry-run): 
Metadata changes: 2 created, 1 updated, 1 deleted
  created objectMetadata rocket
  created fieldMetadata timelineActivities
  updated fieldMetadata launchedAt
  deleted pageLayout legacyTab
✓ Synced
هذه أداتك الأولى للتشخيص: تُخبرك بدقة ما الكائنات والحقول والتخطيطات التي تغيّرت، بحيث يمكنك التأكد من أن المزامنة أنجزت ما توقّعته قبل التحقّق من واجهة المستخدم. عندما تفشل المزامنة على كيان واحد، يذكر الخطأ اسم الكيان المسبب للمشكلة وuniversalIdentifier الخاص به، على سبيل المثال: 
Migration action 'create' for 'fieldMetadata' (universalIdentifier: 2020...4337) failed
استخدم ذلك المعرّف للعثور على الكيان في ملف manifest الخاص بك (وإن لزم الأمر، في مساحة العمل) بدلًا من تخمين أيّها يتعارض.

​
معاينة التغييرات (تشغيل تجريبي dry run)

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

Building manifest...
Computing metadata diff (dry run, nothing will be applied)...
Metadata changes: 1 created, 1 updated
  created fieldMetadata timelineActivities
  updated objectMetadata rocket
✓ Dry run complete for My App — no changes were applied
تشغيل تجريبي:
  • لا يكتب أي شيء — لا ترحيل لبيانات وصفية، ولا تحديث لسجل التطبيق، ولا تغييرات في الأدوار/التبويبات الافتراضية، ولا توليد لعميل API.
  • يُرجع نفس الفرق الذي ستُطبِّقه مزامنة حقيقية، حتى تتمكن من مراجعة الكيانات التي سيتم إنشاؤها/تحديثها/حذفها مسبقًا.
  • يكون مفيدًا قبل إجراء تغيير محفوف بالمخاطر، أو عند مراجعة تغيير تم إنشاؤه بواسطة الذكاء الاصطناعي، أو في سكربت يجب أن يفشل إذا كان تغيير غير متوقَّع على وشك الحدوث.
يُعاين التشغيل التجريبي فقط تغييرات البيانات الوصفية، ويتطلّب أن يكون التطبيق قد تمت مزامنته مرة واحدة على الأقل (حتى تعرف به مساحة العمل). إذا شغّلته ضد تطبيق لم تتم مزامنته من قبل، سيبلغ الخادم أن التطبيق غير مُثبّت — شغّل yarn twenty dev مرة واحدة أولًا.

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

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

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

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

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

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