Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

خطة تحديث التطبيق

​

الهدف

​

المبادئ

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

​

المرحلة 1: تدقيق خط الأساس

• حدّد أهم تدفقات المستخدم والأسطح البرمجية التي تملكها.
• اسرد العناصر غير المستخدمة، والإعدادات المكررة، وحالات الخطأ غير الواضحة، ومسارات التصيير المكلفة.
• التقط أوامر التحقق الحالية لكل سطح.
• صنّف المشكلات إلى: مطلوبة، أو موصى بها، أو اختيارية.
• وثّق العوائق المعروفة التي تحتاج إلى مراجعة المالك، وخصوصًا تغييرات API والأمان والإصدار وعقد Plugin.

• قائمة مشكلات واحدة مع مراجع ملفات من جذر المستودع.
• تحتوي كل مشكلة على الشدة، والسطح المالك، والأثر المتوقع على المستخدم، ومسار تحقق مقترح.
• لا تُخلط عناصر التنظيف التخيلية ضمن الإصلاحات المطلوبة.

​

المرحلة 2: تنظيف المنتج وتجربة المستخدم

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

• مسار يدوي سعيد لإعداد أول تشغيل وتشغيل المستخدم الحالي.
• اختبارات مركزة لأي منطق متعلق بالتوجيه، أو حفظ الإعدادات، أو اشتقاق الحالة.
• لقطات شاشة للمتصفح للأسطح المتجاوبة التي تغيرت.

​

المرحلة 3: تشديد بنية الواجهة الأمامية

• انقل تحويلات حالة UI المتكررة إلى مساعدات ضيقة ومكتوبة الأنواع.
• أبقِ مسؤوليات جلب البيانات، والحفظ، والعرض منفصلة.
• فضّل الخطافات والمخازن وأنماط المكونات الموجودة على التجريدات الجديدة.
• قسّم المكونات الضخمة فقط عندما يقلل ذلك الاقتران أو يوضح الاختبارات.
• تجنب إدخال حالة عامة واسعة لتفاعلات اللوحات المحلية.

• لا تغيّر السلوك العام كأثر جانبي لتقسيم الملفات.
• حافظ على سلوك إمكانية الوصول للقوائم، ومربعات الحوار، وعلامات التبويب، والتنقل بلوحة المفاتيح.
• تحقّق من أن حالات التحميل، والفراغ، والخطأ، والحالة المتفائلة ما تزال تُعرض.

​

المرحلة 4: الأداء والموثوقية

• قِس تكاليف بدء التشغيل، وانتقال المسارات، والقوائم الكبيرة، وسجل الدردشة.
• استبدل البيانات المشتقة المكلفة المتكررة بمحددات محفوظة أو مساعدات مخزنة عندما يثبت التحليل الجدوى.
• قلّل عمليات المسح الشبكي أو نظام الملفات التي يمكن تجنبها على المسارات الساخنة.
• حافظ على ترتيب حتمي لمدخلات الموجّه، والسجل، والملفات، وPlugin، والشبكة قبل بناء حمولة النموذج.
• أضف اختبارات انحدار خفيفة للمساعدات الساخنة وحدود العقود.

• يسجل كل تغيير أداء خط الأساس، والأثر المتوقع، والأثر الفعلي، و الفجوة المتبقية.
• لا يهبط أي تصحيح أداء اعتمادًا على الحدس فقط عندما يكون القياس الرخيص متاحًا.

​

المرحلة 5: تشديد الأنواع والعقود والاختبارات

• استبدل سلاسل وقت التشغيل الفضفاضة باتحادات مميزة أو قوائم أكواد مغلقة.
• تحقّق من المدخلات الخارجية باستخدام مساعدات المخططات الموجودة أو zod.
• أضف اختبارات عقود حول بيانات Plugins، وفهارس الموفّرين، ورسائل بروتوكول Gateway، وسلوك ترحيل الإعدادات.
• أبقِ مسارات التوافق داخل doctor أو تدفقات الإصلاح بدلًا من ترحيلات خفية وقت بدء التشغيل.
• تجنّب اقتران الاختبارات فقط بباطن Plugin؛ استخدم واجهات SDK والأشرطة الموثقة.

• pnpm check:changed
• اختبارات مستهدفة لكل حدّ تم تغييره.
• pnpm build عندما تتغير الحدود الكسولة أو التغليف أو الأسطح المنشورة.

​

المرحلة 6: الجاهزية للتوثيق والإصدار

• حدّث الوثائق مع تغييرات السلوك أو API أو التهيئة أو الإعداد الأولي أو Plugin.
• أضف إدخالات سجل التغييرات فقط للتغييرات المرئية للمستخدم.
• أبقِ مصطلحات Plugin موجهة للمستخدم؛ واستخدم أسماء الحزم الداخلية فقط عند الحاجة للمساهمين.
• أكّد أن تعليمات الإصدار والتثبيت ما تزال تطابق سطح الأوامر الحالي.

• يتم تحديث الوثائق ذات الصلة في الفرع نفسه مع تغييرات السلوك.
• تنجح فحوصات انحراف الوثائق أو API المولدة عند لمسها.
• يذكر التسليم أي تحقق تم تخطيه وسبب تخطيه.

​

الشريحة الأولى الموصى بها

• دقّق أسطح إعداد أول تشغيل، وجهوزية مصادقة الموفّر، وحالة Gateway، و إعداد Plugin.
• أزل الإجراءات غير المستخدمة ووضّح حالات الفشل.
• أضف أو حدّث اختبارات مركزة لاشتقاق الحالة وحفظ الإعدادات.
• شغّل pnpm check:changed.

​

تحديث مهارة الواجهة الأمامية

# معايير تسليم الواجهة الأمامية

استخدم هذه المهارة عند تنفيذ أو مراجعة أعمال React أو Next.js أو
desktop webview أو واجهات التطبيق الموجهة للمستخدم.

## قواعد التشغيل

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

## قائمة التحقق من التنفيذ

1. حدّد مهمة المستخدم الأساسية والمكوّن أو المسار الذي يملكها.
2. اقرأ أنماط المكوّنات المحلية قبل التعديل.
3. صحّح أضيق سطح يحل المشكلة.
4. أضف قيودًا متجاوبة لعناصر التحكم ذات التنسيق الثابت، وأشرطة الأدوات، والشبكات،
   والعدادات حتى لا يتسبب النص وحالات التحويم في تغيير حجم التخطيط على نحو غير متوقع.
5. أبقِ مسؤوليات تحميل البيانات واشتقاق الحالة والتصيير واضحة.
6. أضف اختبارات عندما يتغير المنطق، أو الحفظ، أو التوجيه، أو الأذونات، أو المساعدات المشتركة.
7. تحقّق من المسار السعيد الرئيسي والحالة الطرفية الأكثر صلة.

## بوابات الجودة البصرية

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

## تنسيق التسليم

اذكر:

- ما الذي تغيّر.
- ما السلوك الذي تغيّر للمستخدم.
- التحقق المطلوب الذي نجح.
- أي تحقق تم تخطيه والسبب الملموس.
- أعمال المتابعة الاختيارية، مفصولة بوضوح عن الإصلاحات المطلوبة.