Skip to content

errors.md

Latest commit

 

History

History
221 lines (163 loc) · 14.3 KB

errors.md

File metadata and controls

221 lines (163 loc) · 14.3 KB
Raw

🐛 سجل الأخطاء والتطوير

يوثق هذا الملف المشاكل المعروفة، حلولها، ورحلة تطوير مشروع Git & GitHub Helper Smart Pro.

🚧 رحلة التطوير والإصلاحات (v4.x)

1. مشكلة صلاحيات المسؤول (Administrator Privileges)

  • المشكلة: كانت أوامر Git والعمليات على الملفات تفشل أحياناً عند الوصول إلى مجلدات النظام أو تعديل الإعدادات.
  • الحل: تم تطبيق آلية "الرفع الذاتي" (#region Elevate to Administrator) في بداية السكربت. يقوم السكربت الآن بالتحقق تلقائياً من صلاحيات المسؤول ويعيد تشغيل نفسه باستخدام runas إذا لزم الأمر.

2. استراتيجية اكتشاف المحرر (Editor Detection)

  • المشكلة: كان لدى المستخدمين محررات Antigravity أو VS Code مثبتة في مواقع مخصصة أو أقراص مختلفة (D:, E:)، ولم يتمكن السكربت من العثور عليها باستخدام المسارات القياسية.
  • الحل (v4.2): تم تطوير خوارزمية "بحث ذكي":
    • فحص جميع الأقراص المنطقية الثابتة (C:, D:, إلخ).
    • التحقق من مسارات التثبيت الشائعة (Program Files, AppData, Scoop).
    • استخدام بحث تكراري محدود العمق لضمان الدقة.

3. بيئة Git غير المهيأة (الاتصال الأول)

  • المشكلة: المستخدمون الجدد أو التثبيتات الجديدة للنظام غالباً ما تفتقر إلى اسم المستخدم والبريد الإلكتروني العام لـ Git، مما يتسبب في فشل أوامر الـ commit بصمت أو ظهور أخطاء.
  • الحل (تحديث v4.2): تم إضافة فحص Test-GitUserConfigured.
    • إذا لم يتم العثور على إعدادات، يظهر خيار قائمة جديد "1) First connection: GitHub" ديناميكياً.
    • يأخذ مدخلات المستخدم وينفذ git config --global بشكل آمن ومحلي.
    • تعيد القائمة ترتيب نفسها تلقائياً لإخفاء هذا الخيار بمجرد الانتهاء من الإعداد.

4. فهرسة القائمة الديناميكية

  • المشكلة: الاعتماد على أرقام ثابتة للقائمة يجعل من الصعب إدراج عناصر شرطية مثل "First connection".
  • الحل: تم تطبيق حاسبة فهرس ديناميكية Get-MenuIndex تقوم بإزاحة عناصر القائمة (يصبح Clone رقم 2 بدلاً من 1) اعتماداً على حالة إعداد المستخدم.

🎨 مشاكل الإصدار 5.0 GUI (WPF/XAML)

5. أخطاء تحليل XAML (XamlReader Parse Errors)

  • المشكلة: عند تحميل الواجهة الرسومية، قد تظهر أخطاء تحليل XAML بسبب أحرف خاصة أو صياغة غير صحيحة في ملف التصميم.
  • الحل (v5.0):
    • استخدام try-catch حول [Windows.Markup.XamlReader]::Load() لالتقاط الأخطاء وعرضها.
    • استخدام & بدلاً من & في النصوص داخل XAML.
    • التحقق من إغلاق جميع الوسوم بشكل صحيح قبل التشغيل.

6. تجميد الواجهة أثناء عمليات Git (UI Freeze)

  • المشكلة: عند تنفيذ أوامر Git مثل push أو pull، تتجمد الواجهة ولا تستجيب للمستخدم حتى انتهاء العملية.
  • الحل (v5.0):
    • استخدام [System.Windows.Forms.Application]::DoEvents() بعد كل خطوة لتحديث الواجهة.
    • تقسيم عمليات "Magic Push" إلى خطوات منفصلة مع رسائل سجل لكل خطوة.
    • ⚠️ قيد قائم: الحل الأمثل يتطلب استخدام Runspace أو BackgroundJobs لتشغيل الأوامر في خلفية منفصلة (لم يُطبق بعد).

7. عدم اكتشاف المستودعات في Dashboard

  • المشكلة: عند فتح لوحة التحكم (Dashboard)، لا تظهر المستودعات أو تكون القائمة فارغة رغم وجود مجلدات .git.
  • الحل (v5.0):
    • تم تحسين دالة Get-GitRepositoriesUnderPath لاستخدام -Force لإظهار المجلدات المخفية.
    • إضافة -ErrorAction SilentlyContinue لتجاوز المجلدات المحظورة.
    • البحث يبدأ من $PWD.Path (المجلد الحالي عند تشغيل السكربت).

8. مشكلة Remote موجود مسبقاً (Remote Already Exists)

  • المشكلة: عند تنفيذ "Magic Push" على مستودع يحتوي بالفعل على origin، يظهر خطأ fatal: remote origin already exists.
  • الحل (v5.0):
    • يتم التقاط الخطأ باستخدام try-catch وعرض تحذير في السجل بدلاً من إيقاف العملية.
    • ⚠️ تحسين مقترح: إضافة فحص مسبق باستخدام git remote -v وتخطي الخطوة إذا كان الـ remote موجوداً.

9. عدم تحديث ComboBox بعد اختيار المجلد

  • المشكلة: عند الضغط على زر "Browse" واختيار مجلد، قد لا يتم تحديث العرض في واجهة المستخدم.
  • الحل (v5.0):
    • تم ربط $Global:SelectedPathMagic مع txtSelectedPathMagic.Text مباشرة.
    • إعادة ضبط cmbMagicRepos.SelectedIndex = 0 بعد اختيار مجلد يدوياً.

10. أنماط XAML تتعارض (Style Conflicts)

  • المشكلة: أزرار الشريط الجانبي (Sidebar) تأخذ نمط الأزرار العامة بدلاً من نمطها المخصص.
  • الحل (v5.0):
    • استخدام x:Key="SidebarButton" لتعريف نمط مخصص.
    • تطبيق النمط صراحةً على كل زر: Style="{StaticResource SidebarButton}".

⚡ مرجع سريع - أخطاء يجب تجنبها دائماً

Caution

قبل أي تعديل على الكود، راجع هذه القائمة!

❌ لا تفعل ✅ افعل بدلاً منه
LetterSpacing="2" في TextBlock احذفها - غير مدعومة
ControlTemplate.Triggers مع Emoji استخدم خلفية ثابتة بدون hover
"$Variable: text" في PowerShell "$($Variable): text"
& في نصوص XAML &
عمليات Git بدون DoEvents() أضف [System.Windows.Forms.Application]::DoEvents()

🔧 مشاكل XAML شائعة وحلولها

المشكلة الحل
بطء الأداء في القوائم الكبيرة استخدم VirtualizingStackPanel لتقليل استهلاك المعالج.
أخطاء الربط (Binding Errors) تفقد نافذة Output لرؤية أخطاء الـ DataContext.
واجهات غير متجاوبة (Frozen UI) شغّل العمليات الثقيلة بعيداً عن UI Thread باستخدام Async.
تداخل العناصر (Overlapping) استخدم Grid مع RowDefinitions بأبعاد نسبية *.

⚠️ القيود الحالية المعروفة

11. اختفاء الأيقونات عند التبديل بين البرامج (Icons Disappearing)

  • المشكلة: عند التبديل من البرنامج إلى برنامج آخر ثم العودة، تختفي بعض الأيقونات أو النصوص في الشريط الجانبي.
  • السبب: مشكلة في WPF rendering عند فقدان/استعادة focus للنافذة.
  • الحل (v6.6):
    • إضافة SnapsToDevicePixels="True" و UseLayoutRounding="True" للنافذة الرئيسية.
    • إضافة TextOptions.TextFormattingMode="Display" و TextOptions.TextRenderingMode="ClearType".
    • استخدام InvalidateVisual() في حدث Window.Activated لإعادة رسم العناصر.
    • إضافة SnapsToDevicePixels="True" للـ Sidebar Border.

12. تبديل الثيم يغير جزء فقط من الواجهة (Partial Theme Update)

  • المشكلة: عند الضغط على زر تبديل الثيم، يتغير لون الخلفية الرئيسية فقط بينما تبقى باقي العناصر بألوانها القديمة.
  • السبب: دالة Toggle-Theme كانت تغير فقط $window.Background.
  • الحل (v6.6):
    • تحديث Set-DarkTheme و Set-LightTheme لتشمل جميع العناصر:
      • Sidebar background
      • Header text color
      • Log area (background, border, text color)
      • Input fields (background, foreground)
      • Sidebar buttons background
      • Theme toggle button

13. Git Setup يستخدم الإعدادات العامة (Global Config)

  • المشكلة: إعدادات Git (الاسم والبريد) تُحفظ بشكل عام (--global) مما يؤثر على جميع المستودعات.
  • المتطلب: المستخدم يريد خصوصية تامة - الإعدادات تكون محلية للمستودع فقط.
  • الحل (v6.6):
    • تغيير git config --global إلى git config --local.
    • إضافة فحص لوجود مجلد .git قبل الحفظ.
    • إذا لم يوجد مستودع، يتم التحذير والحفظ بشكل عام كـ fallback.
    • تحديث واجهة المستخدم لتوضيح أن الإعدادات محلية وخاصة.

14. نصوص غير واضحة في Light Mode

  • المشكلة: عند التحويل إلى Light Mode، نصوص الأزرار في الشريط الجانبي تصبح غير مقروءة (رمادي على رمادي).
  • السبب: تغيير خلفية الـ Sidebar إلى لون فاتح مع بقاء النص بلون فاتح.
  • الحل (v6.6):
    • إبقاء الشريط الجانبي (Sidebar) بخلفية داكنة حتى في Light Mode.
    • ضمان أن نصوص الأزرار دائماً بيضاء (Foreground = White).
    • تغيير فقط المنطقة الرئيسية (Main Content) إلى الوضع الفاتح.
    • هذا يوفر تباين أفضل وقراءة أسهل.

15. خطأ null-valued expression في Timer.Stop()

  • المشكلة: عند إخفاء Toast Notification، يظهر خطأ:

    You cannot call a method on a null-valued expression.
At line:506 char:9 + $timer.Stop()

  • السبب: المتغير $timer داخل script block يُقيّم في نطاق مختلف، لذا يكون null.

  • الحل (v6.6.1):

    • استخدام $this داخل الـ script block للإشارة إلى الـ timer نفسه.
    • التغيير: $timer.Stop() → $this.Stop()

  • ملاحظة: في PowerShell، $this داخل script block يشير إلى الكائن الذي يُطلق الحدث.

قيود الإصدارات السابقة (v4.x)

  • إصدار PowerShell: يتطلب PS 5.1+؛ قد يواجه مشاكل توافق طفيفة جداً على أنظمة Windows 7 القديمة جداً مع PS 2.0.

  • دعم Remote واحد: حالياً تم تحسينه للعمل مع origin. الدعم للمستودعات متعددة الـ Remotes لا يزال أساسياً.

  • Async Operations: Most operations use DoEvents() for responsiveness, but full background threading is still a future enhancement for extreme loads.

📋 سجل الأخطاء المرصودة

التاريخ الخطأ المحاولة الحل
2026-01-28 XAML Parse Error 1 إصلاح & إلى &
2026-01-28 UI Freeze on Push 1 إضافة DoEvents()
2026-01-29 Empty Dashboard 1 إضافة -Force للبحث
2026-01-29 Remote Already Exists 1 try-catch مع تحذير
2026-01-29 GUI Modernization & Features - تطبيق Fluent Design، إضافة Clone، Bulk Sync، وTheme Awareness
2026-01-29 Parser Error (Line 391) 1 تغليف المتغير بـ $() داخل النص
2026-01-29 Unknown member 'LetterSpacing' 1 حذف الخاصية غير المدعومة في WPF
2026-01-29 Sidebar Icons Glitch (Emoji) 2 إزالة hover triggers بالكامل وجعل الأزرار ثابتة
2026-01-29 Script فقط يعمل من مجلده 1 استخدام Split-Path -Parent $PSCommandPath بدلاً من $PWD
2026-01-29 Parser Error مع مسارات عربية (PS 5.1) 1 استخدام 8.3 Short Path عبر Scripting.FileSystemObject
2026-01-29 Emoji في Log Messages (PS 5.1) 1 استبدال Emoji بـ ASCII tags مثل [OK], [ERROR], [SCAN]
2026-01-29 Foreground colors في الأزرار 2 تسبب مشاكل العرض، تم إزالتها من Git Setup, Help, Exit
2026-01-29 v6.0 - تحسينات واجهة - Progress Bar, Toast Notifications, Theme Toggle
2026-01-29 v6.5 - ميزات Git متقدمة - Branch Management, Stash Support, Keyboard Shortcuts
2026-01-29 Icons Disappearing on Focus Change 1 إضافة SnapsToDevicePixels, UseLayoutRounding, و InvalidateVisual() عند تفعيل النافذة
2026-01-29 Theme Toggle Partial Update 1 تحديث جميع عناصر الواجهة (Sidebar, Log, Inputs, Buttons) عند تبديل الثيم
2026-01-29 Git Setup Privacy (Global Config) 1 تغيير من --global إلى --local للخصوصية التامة
2026-01-29 Light Mode Text Unreadable 1 إبقاء Sidebar بخلفية داكنة مع نص أبيض في Light Mode للوضوح
2026-01-29 Timer.Stop() Null Reference 1 استخدام $this.Stop() داخل script block بدلاً من $timer.Stop()

⌨️ اختصارات لوحة المفاتيح (v6.5+)

الاختصار الوظيفة
Ctrl+P Push
Ctrl+L Pull
Ctrl+D Dashboard
Ctrl+S Sync All
F5 Refresh Dashboard

آخر تحديث: 2026-01-29 v6.6.1