# دليل بناء ونشر برنامج "مُستأجِر" لنظام Windows 10 / 11

يوفر هذا الدليل الخطوات الهندسية الكاملة لتحويل مشروع **مُستأجِر (Mostager)** إلى تطبيق سطح مكتب مستقل لنظام Windows بصيغة **`Setup.exe`** احترافي، دون الحاجة لوجود بايثون أو أي مكتبات على أجهزة المستخدمين، وبدون ظهور نافذة الأوامر السوداء (CMD).

---

## 🏗️ 1. المعمارية الهندسية للتطبيق على Windows

| المكون | التقنية المستخدمة | الدور الهندسي |
| :--- | :--- | :--- |
| **محرك سطح المكتب (GUI Shell)** | **`pywebview` + Microsoft Edge WebView2** | فتح التطبيق في نافذة برنامج ويندوز أصلية بدون شريط عناوين متصفح، وبأعلى أداء ممكن بدون استهلاك موارد ضخم مثل Electron. |
| **الواجهة الخلفية (Backend)** | **Flask + SQLite3 + APScheduler** | يعمل السيرفر محلياً في خيط معزول (Daemon Thread) على منفذ داخلي آمن (`127.0.0.1`). |
| **حزمة التجميع (Packager)** | **PyInstaller 6.x (64-Bit)** | دمج بايثون وكافة الاعتماديات والخطوط والقوالب داخل ملف تنفيذي واحد `mostager.exe`. |
| **نظام التثبيت (Installer)** | **Inno Setup 6** | إنشاء ملف التثبيت التجاري **`Setup.exe`** مع اختصارات سطح المكتب وقائمة Start وحذف البرنامج من لوحة التحكم. |
| **تخزين البيانات الدائمة** | **`%APPDATA%\Mostager\`** | فصل ملف قاعدة البيانات `database.db` ومرفقات المستأجرين `uploads/` وملفات السجلات `mostager.log` بعيداً عن مجلد `Program Files` لضمان: <br>1. عدم حدوث أخطاء صلاحيات (Permission Denied).<br>2. **الحفاظ على جميع بيانات المستأجرين عند تثبيت تحديث جديد للبرنامج**. |

---

## 🚀 2. طريقة البناء السحابي التلقائي من جهاز Mac (عبر GitHub Actions)

نظراً لأن تجميع برامج ويندوز التنفيذية يحتاج إلى بيئة تشغيل ويندوز رسمية لاستخراج ملفات DLL المناسبة، تم تجهيز خط بناء سحابي متكامل داخل مستودع المشروع:
📁 **`.github/workflows/build-windows.yml`**

يعمل هذا الخط تلقائياً على خوادم **`windows-latest`** في سحابة GitHub، ويقوم بتثبيت بايثون وتجميع البرنامج وإنشاء ملف **`Setup.exe`** وإتاحته للتحميل في غضون 3 دقائق.

### الخطوات العملية لرفع المشروع وتشغيل البناء:

#### أ. تهيئة المستودع ورفعه إلى GitHub من جهازك (Mac):
افتح مبنى الأوامر (Terminal) في مجلد المشروع ونفّذ:
```bash
# 1. تهيئة مستودع Git إذا لم يكن مهيئاً
git init

# 2. إضافة جميع الملفات
git add .

# 3. حفظ التغييرات
git commit -m "إعداد حزمة التثبيت ونظام ويندوز لبرنامج مستأجر v2.5"

# 4. ربط المستودع بحسابك على GitHub (استبدل الرابط برابط مستودعك الخاص)
git remote add origin https://github.com/USERNAME/mostager.git

# 5. رفع الكود إلى الفرع الرئيسي
git branch -M main
git push -u origin main
```

#### ب. تشغيل البناء وتحميل ملف التثبيت:
1. ادخل إلى صفحة مستودعك على GitHub من المتصفح.
2. اضغط على تبويب **Actions** في الشريط العلوي.
3. ستجد سير العمل: **"Build Mostager Windows Desktop (Setup.exe)"** قيد التشغيل تلقائياً، أو يمكنك الضغط على **Run workflow** لتشغيله يدوياً في أي وقت بنقرة واحدة.
4. انتظر حوالي دقيقتين حتى تظهر علامة النجاح الخضراء ✅.
5. ادخل على اسم التشغيل الأخير، وستجد في الأسفل قسم **Artifacts** يحتوي على:
   * **`Mostager-Windows-Packages`**
6. اضغط عليه لتحميل الملف المضغوط، والذي يحتوي داخله على:
   * 🎯 **`Setup.exe`**: مثبت ويندوز الاحترافي الجاهز للتثبيت بنقرة مزدوجة.
   * 📦 **`Mostager-Setup-v2.5.0.exe`**: نسخة المثبت المسماة برقم الإصدار.
   * 💼 **`Mostager-Portable-v2.5.0.zip`**: نسخة محمولة تعمل بدون تثبيت للمعاينة السريعة.

---

## 💻 3. طريقة البناء المحلي على جهاز Windows (اختياري)

إذا توفر لديك جهاز كمبيوتر يعمل بنظام Windows وأردت البناء عليه مباشرة:

1. تأكد من تثبيت **Python 3.10 أو 3.11** مع تحديد خيار `Add python.exe to PATH`.
2. تأكد من تثبيت برنامج [Inno Setup 6](https://jrsoftware.org/isdl.php).
3. افتح مجلد المشروع وانقر نقراً مزدوجاً على الملف:
   📁 **`build_windows.bat`**
4. سيتولى السكربت تثبيت المكتبات وتجميع ملف `mostager.exe` ثم استدعاء Inno Setup لإنتاج:
   * `dist_setup\Setup.exe`

---

## 🔒 4. استراتيجية حماية البيانات واستمراريتها عند التحديثات

واحدة من أكبر المشاكل التي تواجه برامج ويندوز هي فقدان بيانات العملاء عند تثبيت إصدار أحدث. تم حل هذه المعضلة عبر الآلية التالية:

1. **فصل الملفات التنفيذية عن مجلد البيانات**:
   * ملفات البرنامج البرمجية تُثبت داخل:
     `C:\Program Files\Mostager\`
   * بينما قاعدة بيانات المستأجرين والمرفقات واللوجات تُحفظ تلقائياً داخل:
     `C:\Users\<اسم المستخدم>\AppData\Roaming\Mostager\`
2. **عند تثبيت إصدار جديد (Update)**:
   * يقوم `Setup.exe` الجديد بتحديث الملفات داخل `Program Files` فقط.
   * لا يمس إطلاقاً مجلد `AppData`، فتظل جميع بيانات المستأجرين والعقود والشيكات والحسابات كما هي 100%.
3. **عند حذف البرنامج (Uninstall)**:
   * يقوم معالج إلغاء التثبيت بسؤال المستخدم صراحة:
     > *"هل تريد حذف قاعدة بيانات المستأجرين والعقود والصور المحفوظة أيضاً؟"*
   * الخيار الافتراضي هو **"لا"**، لضمان عدم ضياع البيانات بالخطأ.

---

## 📋 5. قائمة الملفات التي تم إنشاؤها لنسخة Windows

* 📄 **`main_exe.py`**: مشغل التطبيق المخصص لويندوز مع ربط AppData والتعامل الذكي مع المنافذ وEdge WebView2.
* 📄 **`mostager.spec`**: ملف إعدادات PyInstaller لدمج القوالب، قاعدة البيانات، والملفات الثابتة والأيقونات.
* 📄 **`app.ico`**: أيقونة البرنامج الرسمية متعددة الأحجام (من 16x16 وحتى 256x256).
* 📁 **`installer/mostager.iss`**: سكربت Inno Setup الشامل باللغة العربية والإنجليزية.
* 📁 **`installer/wizard_large.bmp` & `wizard_small.bmp`**: صور شاشة الترحيب والتثبيت بهوية مُستأجر.
* 📁 **`.github/workflows/build-windows.yml`**: نظام البناء السحابي المؤتمت (CI/CD).
* 📄 **`build_windows.bat`**: سكربت البناء بنقرة واحدة على أجهزة ويندوز.

---

## 🧪 6. الفحوصات والاختبارات المنفذة

تم إجراء الفحوصات الفنية التالية على الكود والملفات:
1. **فحص الترجمة البرمجية (Bytecode Compilation)**: اجتازت جميع ملفات بايثون (`app.py`, `main_exe.py`, `config.py`, `whats360_service.py`) فحص الترجمة بنجاح بدون أي أخطاء صيغة (Code: 0).
2. **فحص سلامة ملف Spec (AST Parsing)**: تم التحقق من سلامة بناء `mostager.spec` وصحة مصفوفات الـ datas والـ hiddenimports.
3. **فحص صور ومقاسات التثبيت**: تم التحقق من مقاسات الأيقونة `app.ico` وصور المثبت `wizard_large.bmp` (164x314) و `wizard_small.bmp` (55x58).
4. **فحص دورة حياة المنفذ والبيانات**: تم اختبار دالة اكتشاف المنافذ المتاحة واختبار تحويل مسار التخزين إلى AppData في بيئة العمل.
