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

# الهدف

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

# المبادئ

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

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

احصر التطبيق الحالي قبل تغييره.

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

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

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

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

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

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

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

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

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

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

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

الحواجز المطلوبة:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ابدأ بتمرير محدود النطاق على واجهة التحكم والإعداد الأولي:

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

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

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

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

# Frontend Delivery Standards

Use this skill when implementing or reviewing user-facing React, Next.js,
desktop webview, or app UI work.

## Operating rules

- Start from the existing product workflow and code conventions.
- Prefer the smallest correct patch that improves the current user path.
- Separate required fixes from optional polish in the handoff.
- Do not build marketing pages when the request is for an application surface.
- Keep actions visible and usable across supported viewport sizes.
- Remove dead affordances instead of leaving controls that cannot act.
- Preserve loading, empty, error, success, and permission states.
- Use existing design-system components, hooks, stores, and icons before adding
  new primitives.

## Implementation checklist

1. Identify the primary user task and the component or route that owns it.
2. Read the local component patterns before editing.
3. Patch the narrowest surface that solves the issue.
4. Add responsive constraints for fixed-format controls, toolbars, grids, and
   counters so text and hover states cannot resize the layout unexpectedly.
5. Keep data loading, state derivation, and rendering responsibilities clear.
6. Add tests when logic, persistence, routing, permissions, or shared helpers
   change.
7. Verify the main happy path and the most relevant edge case.

## Visual quality gates

- Text must fit inside its container on mobile and desktop.
- Toolbars may wrap, but controls must remain reachable.
- Buttons should use familiar icons when the icon is clearer than text.
- Cards should be used for repeated items, modals, and framed tools, not for
  every page section.
- Avoid one-note color palettes and decorative backgrounds that compete with
  operational content.
- Dense product surfaces should optimize for scanning, comparison, and repeated
  use.

## Handoff format

Report:

- What changed.
- What user behavior changed.
- Required validation that passed.
- Any validation skipped and the concrete reason.
- Optional follow-up work, clearly separated from required fixes.