bz

📱 دليل تطوير واجهات HTML كـ تطبيقات Android (Kivy + WebView)

هذا المستند هو عصارة تجربة مكثفة وتوثيق شامل لجميع المشاكل (Bugs) والأخطاء التي واجهتنا أثناء بناء تطبيق “حاسبة المحمودية” من الصفر وحتى مرحلة الاستقرار التام. الهدف من هذا الملف: توفير مرجع دائم للمطورين لتجنب نفس الأخطاء وتوفير ساعات من البحث عند بناء تطبيقات جديدة تعتمد على نفس المعمارية (تحويل HTML محلي إلى APK عبر Kivy).

---

🛠 المشاكل التقنية والحلول الجذرية

1️⃣ انهيار التطبيق عند فتح “لوحة المفاتيح” (Keyboard Crash)

• الخطأ: التطبيق يُغلق تلقائياً بمجرد لمس أي حقل كتابة (Input).
• السبب: يقوم نظام أندرويد بإعادة قياس مساحة الشاشة عند ظهور لوحة المفاتيح وفشل القياس لعدم وجود LayoutParams صحيحة.
• الحل: فرض FrameLayout$LayoutParams في كود بايثون وضبط adjustResize في ملف الإعدادات.

2️⃣ خطأ “الملف غير موجود” (File Not Found)

• السبب: Kivy يفك ضغط الملفات في مجلد داخلي ديناميكي.
• الحل: استخدام المسارات الديناميكية في بايثون عبر os.path.abspath(__file__) للوصول لملف الـ HTML.

3️⃣ حجب الأمان لملفات الـ Local

• الحل: تفعيل setAllowFileAccess(True) وكافة صلاحيات الوصول للملفات المحلية داخل كود WebView في main.py.

4️⃣ فشل عملية البناء في GitHub Actions

• السبب: استهلاك الرام العالي وتعارض إصدارات الجافا.
• الحل: فرض استخدام Java 17 في ملف الـ Workflow والتركيز على معمارية arm64-v8a فقط لتسريع البناء.

5️⃣ شلل النوافذ والتفاعل (System Dialogs & Touch Issues)

• المشكلة: alert(), confirm(), و prompt() محظورة في WebView. وميزة “النقر المزدوج” لا تعمل على اللمس.
• الحل الجذري:
  1. Custom Modals: بناء هياكل HTML داخلية (modal-overlay) والتحكم في ظهورها برمجياً.
  2. الاستبدال الشامل:
     • بدلاً من confirm: استخدم confirmClearModal.
     • بدلاً من prompt: استخدم renameWorkspaceModal.
     • بدلاً من alert: استخدم دالة showNotification().
  3. التوافق مع اللمس: استبدال أي dblclick بأيقونة تعديل (✏️) تعمل بالنقر المفرد.

6️⃣ ضياع الكود وتكرار المعرفات (Code Overwrite & Duplicate IDs)

• المشكلة: تعطل وظائف (مثل زر “عزز”) بعد تحديثات الكود.
• السبب: تكرار معرفات الـ id يؤدي لإمساك السكريبت بالعنصر الأول فقط، أو حذف أجزاء بالخطأ أثناء الدمج.
• تنبيهات للمطور:
  • قاعدة المعرف الوحيد: لا تكرر الـ id أبداً؛ المعرف يجب أن يكون فريداً لكل عنصر تفاعلي.
  • فحص الـ DOM: تأكد دائماً من وجود العناصر الأساسية (restockBtn, resetAllBtn) بعد أي عملية تعديل كبيرة في الـ HTML.
  • منطق الجرد المستمر: يجب ربط عمليات الحذف برمجياً بإعادة الوحدات للمخزن وتحديث التكلفة الإجمالية للحفاظ على دقة الحسابات.

---

تم توثيق هذا الملف لضمان استقرار “حاسبة المحمودية” كـ تطبيق أندرويد متكامل - أبريل 2026.