|
| 1 | +# توثيق إصلاحات المرحلة الأولى (Stage 1: Critical Issues & Stability) |
| 2 | +**مشروع البيان (Albayan)** |
| 3 | +**الفرع:** `fixes-stage1-critical` (مستنسخ من `albayan_beta`) |
| 4 | +**التاريخ:** 10 أكتوبر 2026 |
| 5 | + |
| 6 | +--- |
| 7 | + |
| 8 | +## 📋 نظرة عامة |
| 9 | +تختص المرحلة الأولى بمعالجة **المشاكل الحرجة (Critical Bugs)** التي كانت تتسبب في انهيار التطبيق (Crash)، أو تجمد الخيوط البرمجية (Thread Hang / Infinite Loop)، أو منع البرنامج نهائياً من الفتح والإقلاع، أو تلف وتكرار الملفات الصوتية أثناء التنزيل. |
| 10 | + |
| 11 | +تم تطبيق الإصلاحات واختبار صحة الصياغة البرمجية (Syntax Verification) بنجاح لجميع الملفات المعدلة. |
| 12 | + |
| 13 | +--- |
| 14 | + |
| 15 | +## 📑 جدول المشاكل المعالجة في المرحلة الأولى |
| 16 | + |
| 17 | +| # | المشكلة | الملف المعني | التصنيف | الحالة | |
| 18 | +|---|---|---|---|---| |
| 19 | +| 1 | قفل البرنامج ومنع تشغيله نهائياً بعد إغلاق غير سليم (Stale Shared Memory) | `main.py` | 🔴 حرج (Critical) | ✅ تم الحل | |
| 20 | +| 2 | انهيار البرنامج بالعودية اللانهائية (`RecursionError`) عند التنقل للآيات | `core_functions/quran/view_content.py` | 🔴 حرج (Critical) | ✅ تم الحل | |
| 21 | +| 3 | انهيار مشغل السور بنوع `TypeError` / `NoneType` عند فلترة البحث | `ui/sura_player_ui/sura_player_ui.py`<br>`core_functions/Reciters.py` | 🔴 حرج (Critical) | ✅ تم الحل | |
| 22 | +| 4 | انهيار مكتبة BASS ومنع تشغيل الصوت لوجود كروت صوت معطلة | `utils/audio_player/bass_init.py` | 🔴 حرج (Critical) | ✅ تم الحل | |
| 23 | +| 5 | تجمد أداة التنزيل في حلقة مفرغة لانهائية عند حذف الملفات المؤقتة | `core_functions/downloader/worker.py` | 🔴 حرج (Critical) | ✅ تم الحل | |
| 24 | +| 6 | تلف الملفات الصوتية عند استئناف التنزيل (HTTP 200 vs 206) واستدعاء الدالة | `core_functions/downloader/worker.py` | 🔴 حرج (Critical) | ✅ تم الحل | |
| 25 | + |
| 26 | +--- |
| 27 | + |
| 28 | +## 🔍 التفاصيل الفنية لكل مشكلة وطريقة علاجها |
| 29 | + |
| 30 | +### 1. قفل البرنامج ومنع تشغيله نهائياً عند وجود بقايا نسخة سابقة |
| 31 | +- **المكان:** [`main.py`](file:///c:/Users/Admin/Documents/GitHub/albayan/main.py#L58-L85) |
| 32 | +- **طبيعة المشكلة:** |
| 33 | + تعتمد فئة `SingleInstanceApplication` على `QSharedMemory` للتأكد من تشغيل نسخة واحدة من التطبيق. في حال إغلاق البرنامج فجأة (Crash)، أو إنهاء العملية من مدير المهام (Task Manager)، أو انقطاع الكهرباء، تظل الذاكرة المشتركة معلقة في نظام التشغيل بنظام Windows. |
| 34 | + عند محاولة المستخدم فتح البرنامج مجدداً: |
| 35 | + 1. تنجح دالة `shared_memory.attach()` معتقدة بوجود نسخة أخرى تعمل. |
| 36 | + 2. تحاول دالة `notify_existing_instance()` الاتصال بالخادم المحلي `QLocalSocket.connectToServer()`. |
| 37 | + 3. يفشل الاتصال لأن العملية السابقة قد انتهت بالفعل وغير موجودة. |
| 38 | + 4. كان الكود يقوم مباشرة باستدعاء `sys.exit(0)` والخروج الصامت دون أي إجراء تصحيحي! |
| 39 | + 5. النتيجة: يصبح من المستحيل فتح برنامج البيان على جهاز المستخدم إلا بعد إعادة تشغيل Windows بالكامل! |
| 40 | +- **التأثير والخطورة:** |
| 41 | + 🔴 **حرج جداً** — يمنع المستخدم نهائياً من تشغيل التطبيق. |
| 42 | +- **كيف تم علاجها:** |
| 43 | + 1. تعديل `notify_existing_instance()` لتعيد قيمة منطقية (`True` في حال نجاح الاتصال وإظهار النافذة، و `False` في حال الفشل والمهلة). |
| 44 | + 2. في حال فشل الاتصال، يقوم التطبيق تلقائياً بالتعافي الذاتي (Self-Recovery): |
| 45 | + - فصل الذاكرة المعلقة القديمة `self.shared_memory.detach()`. |
| 46 | + - تنظيف مقبس الخادم المحلي القديم `QLocalServer.removeServer(self.server_name)`. |
| 47 | + - إعادة إنشاء الذاكرة المشتركة وبدء الخادم المحلي بصورة طبيعية دون إغلاق البرنامج. |
| 48 | + 3. ربط إشارة `app.aboutToQuit` بدالة تنظيف `clean_up()` لفصل الذاكرة وإغلاق الخادم بنظافة عند إغلاق البرنامج في الحالات العادية. |
| 49 | + 4. تنظيف الخادم المحلي المعلق دائماً قبل محاولة الاستماع `listen` لتجنب خطأ "Address in use". |
| 50 | + |
| 51 | +--- |
| 52 | + |
| 53 | +### 2. الانهيار بالعودية اللانهائية (`RecursionError`) في عرض الآيات |
| 54 | +- **المكان:** [`core_functions/quran/view_content.py`](file:///c:/Users/Admin/Documents/GitHub/albayan/core_functions/quran/view_content.py#L95-L115) |
| 55 | +- **طبيعة المشكلة:** |
| 56 | + دالة `get_by_position(position)` كانت مكتوبة بالشكل التالي: |
| 57 | + ```python |
| 58 | + ayah_row = self.session.query(AyahViewMap).filter(...).first() |
| 59 | + ayah = self._row_to_ayah(ayah_row) if ayah_row else None |
| 60 | + return ayah or self.get_by_position(position - 1) |
| 61 | + ``` |
| 62 | + عندما يكون المؤشر في بداية النص، أو قبل أول آية، أو عند موضع `position <= 0`، لا يتم العثور على أي آية مطابقة، فتستمر الدالة في استدعاء نفسها بشكل تنازلي: `0, -1, -2, -3 ...` دون أي شرط توقف (Base Case)! |
| 63 | + يصل بايثون سريعاً إلى الحد الأقصى للعمق المسموح به (1000 استدعاء)، وينهار التطبيق فوراً بخطأ: |
| 64 | + `RecursionError: maximum recursion depth exceeded while calling a Python object`. |
| 65 | +- **التأثير والخطورة:** |
| 66 | + 🔴 **حرج** — انهيار التطبيق وإغلاقه الفوري أثناء تصفح القرآن أو النقر بالفأرة على أطراف النص. |
| 67 | +- **كيف تم علاجها:** |
| 68 | + 1. إضافة شرط حدّي فوري: إذا كان `position <= 0` يتم إرجاع أول آية في العرض `self.start_ayah`. |
| 69 | + 2. استبدال البحث العودي البطيء (الذي كان ينفذ استعلام قاعدة بيانات لكل حرف للخلف) باستعلام SQL واحد مباشر يبحث عن الآية السابقة فوراً في حال كان المؤشر في مسافة فاصلة: |
| 70 | + ```python |
| 71 | + prev_row = ( |
| 72 | + self.session.query(AyahViewMap) |
| 73 | + .filter(AyahViewMap.last_position < position) |
| 74 | + .order_by(AyahViewMap.last_position.desc()) |
| 75 | + .first() |
| 76 | + ) |
| 77 | + ``` |
| 78 | + 3. في حال عدم وجود أي آية سابقة، يتم الرجوع التلقائي إلى `self.start_ayah`. |
| 79 | + 4. حل المشكلة نهائياً ومنع الاستدعاء التكراري تماماً مع تسريع الاستعلامات من O(N queries) إلى O(1 query). |
| 80 | + |
| 81 | +--- |
| 82 | + |
| 83 | +### 3. انهيار مشغل السور (`TypeError: unsupported format string`) عند فلترة البحث |
| 84 | +- **المكان:** |
| 85 | + - [`ui/sura_player_ui/sura_player_ui.py`](file:///c:/Users/Admin/Documents/GitHub/albayan/ui/sura_player_ui/sura_player_ui.py#L288-L365) |
| 86 | + - [`core_functions/Reciters.py`](file:///c:/Users/Admin/Documents/GitHub/albayan/core_functions/Reciters.py#L120-L140) |
| 87 | +- **طبيعة المشكلة:** |
| 88 | + عندما يقوم المستخدم بالبحث أو كتابة نص في قائمة السور أو القراء دون وجود نتيجة مطابقة، تُعيد القائمة المنسدلة `currentData()` القيمة `None`. |
| 89 | + عند الضغط على تشغيل أو مفتاح Enter: |
| 90 | + 1. تُمرر القيمة `None` إلى دالة `get_url(reciter_id, surah_number)`. |
| 91 | + 2. في السطر `f"{base_url}/{surah_number:03}.mp3"`، يحاول بايثون تطبيق التنسيق `:03` على كائن `None`، مما يرفع استثناء قاتلاً: |
| 92 | + `TypeError: unsupported format string passed to NoneType.__format__`. |
| 93 | + 3. ينهار مشغل السور والتطبيق فوراً. |
| 94 | + 4. كذلك في `update_current_reciter()`، تمرير `reciter_id = None` كان يسبب استعلاماً خاطئاً. |
| 95 | +- **التأثير والخطورة:** |
| 96 | + 🔴 **حرج** — ينهار التطبيق بمجرد كتابة اسم غير موجود في مربع البحث والضغط على تشغيل. |
| 97 | +- **كيف تم علاجها:** |
| 98 | + 1. في `sura_player_ui.py`: إضافة فحص وقائي في بداية `play_current_surah()`: |
| 99 | + ```python |
| 100 | + if reciter_id is None or surah_number is None: |
| 101 | + logger.warning("Cannot play: reciter or surah is not selected.") |
| 102 | + return |
| 103 | + ``` |
| 104 | + 2. التحقق من وجود الرابط `url` الناتج قبل بدء خيط الصوت `audio_player_thread`. |
| 105 | + 3. إضافة فحص وقائي في `update_current_reciter()` لمنع الاستعلام بـ `None`. |
| 106 | + 4. في `core_functions/Reciters.py`: إضافة حماية في `get_url()` و `check_local_file()` لترجع `None` بسلام بدلاً من محاولة التنسيق أو الوصول لقاعدة البيانات. |
| 107 | + |
| 108 | +--- |
| 109 | + |
| 110 | +### 4. فشل تشغيل الصوت وانهيار BASS عند وجود كروت صوت معطلة أو مفصولة |
| 111 | +- **المكان:** [`utils/audio_player/bass_init.py`](file:///c:/Users/Admin/Documents/GitHub/albayan/utils/audio_player/bass_init.py#L105-L145) |
| 112 | +- **طبيعة المشكلة:** |
| 113 | + في دالة التهيئة `BassInitializer.initialize()`، كان الكود يدور في حلقة على جميع أجهزة الصوت التي يتعرف عليها النظام: |
| 114 | + ```python |
| 115 | + for card in self.get_sound_cards(): |
| 116 | + if not self.bass.BASS_Init(card.index, 44100, 0, 0, 0): |
| 117 | + raise PlaybackInitializationError(...) |
| 118 | + ``` |
| 119 | + إذا وُجد في جهاز المستخدم أي كرت صوت معطل (مثل: كرت صوت وهمي غير نشط، مخرج شاشة HDMI غير موصل، أو سماعة بلوتوث مسجلة ومفصولة)، تفشل دالة `BASS_Init` للكرت المعني. |
| 120 | + بسبب الرفع الفوري للاستثناء `raise PlaybackInitializationError`، ينهار نظام الصوت بالكامل ويفشل تشغيل البرنامج، حتى وإن كان كرت الصوت الافتراضي والسماعات الرئيسية تعمل بكفاءة تامة! |
| 121 | +- **التأثير والخطورة:** |
| 122 | + 🔴 **حرج** — منع التطبيق من إخراج الصوت أو العمل على أجهزة المستخدمين التي تحوي منافذ صوت ثانوية غير مفعلة. |
| 123 | +- **كيف تم علاجها:** |
| 124 | + 1. فحص خاصية `card.is_enabled` وتخطي أي كرت صوت معطل تلقائياً دون محاولة تهيئته. |
| 125 | + 2. التعامل مع كود الخطأ 14 (`BASS_ERROR_ALREADY`) باعتباره نجاحاً (الجهاز مهيأ مسبقاً). |
| 126 | + 3. تسجيل تحذير فقط في السجل (`logger.warning`) عند تعذر تهيئة جهاز محدد دون إيقاف باقي الأجهزة. |
| 127 | + 4. توفير مسار بديل تلقائي للجهاز الافتراضي العام (`device index: -1`) إذا تعذر تهيئة الأجهزة الفردية. |
| 128 | + 5. قصر إطلاق الاستثناء فقط وحصراً على الحالة التي يتعذر فيها تهيئة **أي جهاز صوت على الإطلاق**. |
| 129 | + |
| 130 | +--- |
| 131 | + |
| 132 | +### 5. التجمد في حلقة مفرغة لانهائية عند حذف الملفات المؤقتة في أداة التنزيل |
| 133 | +- **المكان:** [`core_functions/downloader/worker.py`](file:///c:/Users/Admin/Documents/GitHub/albayan/core_functions/downloader/worker.py#L204-L245) |
| 134 | +- **طبيعة المشكلة:** |
| 135 | + دالة `delete_temp_file()` كانت تستخدم حلقة مفرغة `while True`: |
| 136 | + ```python |
| 137 | + while True: |
| 138 | + try: |
| 139 | + os.unlink(self.temp_path) |
| 140 | + break |
| 141 | + except PermissionError: |
| 142 | + QThread.msleep(100) |
| 143 | + ``` |
| 144 | + عند قيام المستخدم بإلغاء التنزيل (Cancel)، تُستدعى دالة `cancel()` التي كانت تقوم بحذف الملف المؤقت فوراً بينما الخيط المنفذ ما يزال فاتحاً للملف (`with open(...) as f`)! |
| 145 | + في نظام Windows، محاولة حذف ملف مفتوح من عملية أو خيط آخر تنتج حتماً `PermissionError`. |
| 146 | + النتيجة: يظل الخيط محبوساً إلى الأبد داخل `while True:` ينام 100 ملي ثانية ويتكرر، مما يجمد واجهة المستخدم أو خيوط التنزيل ولا ينتهي أبداً! |
| 147 | +- **التأثير والخطورة:** |
| 148 | + 🔴 **حرج** — تجمد خيوط المعالجة، تسريب الموارد، وتعليق البرنامج عند إلغاء أي تنزيل. |
| 149 | +- **كيف تم علاجها:** |
| 150 | + 1. استبدال `while True` بعدد محاولات محدد (`max_retries: int = 5`) مع التقاط الأخطاء وتسجيلها بأمان دون تعليق. |
| 151 | + 2. في دالة `cancel()`: إذا كان خيط التنزيل ما زال يعمل (`self.is_running()`)، لا يتم حذف الملف فوراً بل يُرفع علم الإلغاء (`self._cancelled = True`)، مما يجعل حلقة التنزيل تكسر (`break`) وتغلق مقبض الملف أولاً، ثم يتم استدعاء الحذف بأمان بعد الإغلاق التام للملف. |
| 152 | + 3. حذف الملف المؤقت فقط إذا لم يكن الخيط يعمل، مما يمنع تعارض الحذف مع المقابض المفتوحة تماماً. |
| 153 | + |
| 154 | +--- |
| 155 | + |
| 156 | +### 6. تلف وتضاعف حجم التلاوات عند استئناف التنزيل واستدعاء الدالة الخاطئ |
| 157 | +- **المكان:** [`core_functions/downloader/worker.py`](file:///c:/Users/Admin/Documents/GitHub/albayan/core_functions/downloader/worker.py#L55-L145) |
| 158 | +- **طبيعة المشكلة:** |
| 159 | + تضمنت عملية التنزيل خطأين خطيرين: |
| 160 | + 1. **تلف التلاوات عند الاستئناف:** |
| 161 | + عند وجود ملف جزئي `.part`، يرسل البرنامج ترويسة `Range: bytes=X-` ويفتح الملف بوضعية الإلحاق `file_mode = "ab"`. |
| 162 | + لكن خوادم التنزيل أحياناً لا تدعم الـ Range أو تتجاهل الترويسة وتعيد استجابة كاملة `200 OK` (بدلاً من `206 Partial Content`). |
| 163 | + في هذه الحالة، يبدأ الخادم بإرسال الملف من البايت 0، بينما الكود يفتحه بوضع `"ab"`، فيقوم بلصق الملف كاملاً في نهاية الملف المؤقت السابق! |
| 164 | + النتيجة: تلف الملف الصوتي كلياً وتضاعف حجمه (مثلاً يصبح 20MB بدلاً من 10MB) وتكرار بداية التلاوة بشكل مشوه. |
| 165 | + 2. **خطأ عدم استدعاء دالة التحقق:** |
| 166 | + في السطر 79: `if self.can_report_download:` كُتبت الدالة ككائن دون أقواس استدعاء `()`. |
| 167 | + في بايثون، أي كائن دالة يُعتبر `True` دائماً، حتى لو كان التنزيل متوقفاً مؤقتاً أو ملغياً! |
| 168 | +- **التأثير والخطورة:** |
| 169 | + 🔴 **حرج** — تلف ملفات التلاوات الصوتية المحملة على قرص المستخدم وتشوهها، وتحديث حالات وهمية أثناء الإيقاف المؤقت. |
| 170 | +- **كيف تم علاجها:** |
| 171 | + 1. فحص كود الاستجابة الصادر من الخادم بدقة: |
| 172 | + - إذا كانت الاستجابة `206 Partial Content`: يتم استخدام وضع الإلحاق `"ab"` وحساب الحجم الكلي `total_bytes = downloaded_bytes + content_length`. |
| 173 | + - إذا كانت الاستجابة `200 OK`: يتم تصفير البايتات المحملة `downloaded_bytes = 0` وفتح الملف من البداية بوضع الكتابة الجديدة `"wb"`. |
| 174 | + 2. التعامل مع خطأ `416 Range Not Satisfiable` بإعادة التنزيل تلقائياً من البداية. |
| 175 | + 3. تصحيح استدعاء الدالة بإضافة الأقواس: `if self.can_report_download():`. |
| 176 | + 4. استخدام مدير السياق `with r:` لضمان إغلاق جلسة HTTP التابعة لمكتبة `requests` بنظافة فور انتهاء أو إلغاء التنزيل. |
| 177 | + |
| 178 | +--- |
| 179 | + |
| 180 | +## 🧪 نتائج التحقق والاختبار (Verification) |
| 181 | + |
| 182 | +تم فحص صياغة جميع الملفات المعدلة عبر مترجم بايثون (`python -m py_compile`): |
| 183 | +- ✅ `main.py` — نجاح بدون أخطاء. |
| 184 | +- ✅ `core_functions/quran/view_content.py` — نجاح بدون أخطاء. |
| 185 | +- ✅ `core_functions/Reciters.py` — نجاح بدون أخطاء. |
| 186 | +- ✅ `ui/sura_player_ui/sura_player_ui.py` — نجاح بدون أخطاء. |
| 187 | +- ✅ `utils/audio_player/bass_init.py` — نجاح بدون أخطاء. |
| 188 | +- ✅ `core_functions/downloader/worker.py` — نجاح بدون أخطاء. |
| 189 | + |
| 190 | +--- |
| 191 | + |
| 192 | +## 📌 الخطوة التالية |
| 193 | +بعد اكتمال إصلاحات المرحلة الأولى وتوثيقها، المشروع جاهز للانتقال إلى **المرحلة الثانية (Stage 2: Medium Priority / Functional Enhancements)** والتي تتضمن: |
| 194 | +1. تحسين إعدادات بدء التشغيل مع Windows (`Startup.py` واستخدام مسار exe الصحيح). |
| 195 | +2. معالجة مشكلة تزامن قاعدة بيانات التنزيل والمهام المتوازية. |
| 196 | +3. إصلاح أخطاء تصريف كروت الصوت ذات الأسماء المعقدة. |
| 197 | +4. تحسينات تجربة البحث والواجهة. |
0 commit comments