---
read_when:
    - التخطيط لعملية تحديث شاملة لتطبيق OpenClaw
    - تحديث معايير تنفيذ الواجهة الأمامية لأعمال التطبيق أو Control UI
    - تحويل مراجعة شاملة لجودة المنتج إلى عمل هندسي مرحلي
summary: خطة شاملة لتحديث التطبيق مع تحديثات مهارات تسليم الواجهة الأمامية
title: خطة تحديث التطبيق
x-i18n:
    generated_at: "2026-04-25T13:57:31Z"
    model: gpt-5.4
    provider: openai
    source_hash: 667a133cb867bb1d4d09e097925704c8b77d20ca6117a62a4c60d29ab1097283
    source_path: reference/application-modernization-plan.md
    workflow: 15
---

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

## الهدف

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

## المبادئ

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

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

اجرد حالة التطبيق الحالية قبل التغيير.

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

تعريف الاكتمال:

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

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

أعطِ الأولوية للتدفقات المرئية وأزل الالتباس.

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

التحقق الموصى به:

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

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

حسّن قابلية الصيانة من دون إعادة كتابة واسعة.

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

الضوابط المطلوبة:

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

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

استهدف الألم المقاس بدلًا من التحسين النظري الواسع.

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

تعريف الاكتمال:

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

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

ارفع مستوى الصحة عند نقاط الحدود التي يعتمد عليها المستخدمون ومؤلفو Plugins.

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

التحقق الموصى به:

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

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

أبقِ الوثائق المواجهة للمستخدم متوافقة مع السلوك.

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

تعريف الاكتمال:

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

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

ابدأ بتمرير محدود على Control UI والإعداد الأولي:

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

يوفر ذلك قيمة عالية للمستخدم مع مخاطر بنية محدودة.

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

استخدم هذا القسم لتحديث `SKILL.md` المركّز على الواجهة الأمامية والمرفق مع
مهمة التحديث. إذا كنت ستتبنى هذا الإرشاد كمهارة OpenClaw محلية للمستودع،
فأنشئ `.agents/skills/openclaw-frontend/SKILL.md` أولًا، واحتفظ بالـ frontmatter
الذي ينتمي إلى تلك المهارة الهدف، ثم أضف أو استبدل إرشادات الجسم بالمحتوى
التالي.

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

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

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

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

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

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

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

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

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

اذكر:

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