🇬🇧 English Version: Read the original article in English here.

ماكينة الحزم المحمولة: ملفات الـ ZIP المعزولة وترقيع APEXLang التلقائي 📦⚙️

الجزء الرابع من السلسلة التقنية الشاملة: أتمتة التوزيع، حزم الـ ZIP، والترقيع الذري في Oracle APEX.

⚡ الخلاصة في كلمتين (TL;DR)

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

مش محتاج تنزل تشتري مسامير ناقصة من السبتية، ومش محتاج تفتح يوتيوب عشان تدور على فيديو هندي بيشرح التركيب. كل حاجة محتاجها عشان تركب المكتب—أو تفكه كله وترجعه في الكرتونة لو مطلعش على مقاس أوضتك—موجودة جوه نفس الصندوق المقفول.

ده الإحساس اللي المفروض تحسه لما توزع نظام تصميم في بيئات الشركات. لكن في تطوير أوراكل أبيكس التقليدي، لما تحب تنقل ثيم بين 10 تطبيقات، بتلاقي نفسك بتنقل أكواد عشوائية من ملفات وورد، وبترفع ملفات CSS يدوي، وتدعي ربنا إن مفيش حد نسي رابط الخطوط، وتفضل مرعوب من اليوم اللي هتطلب منك فيه الإدارة تشيل الثيم ده!

في الجزء الرابع من سلسلتنا APEX Theme Factory، هندخل مصنع التجميع: ماكينة الحزم المحمولة. هنتعلم إزاي الثيمات بتتحول لملفات ZIP معزولة بالكامل، وإزاي بايثون وتنسيق APEXLang بيعدلوا ملفات تصدير APEX 26.1 بنعومة بدون لمس كود البزنس، وإزاي صممنا شبكة أمان تكشف أي تضارب وتعمل تراجع كامل وفوري بضغطة زر واحدة. 🚀

📦 مستودع كود المشروع: كود المحرك، وحزم الثيمات، وسكربتات التثبيت متاحة بالكامل على github.com/ash2osh/APEX_THEME_FACTORY.

📦 تشريح حزمة الثيم المحمولة

جوه مشروع APEX_THEME_FACTORY، كل ثيم بيتجمع في ملف أرشيف مضغوط ومستقل بذاته تماماً:

dist/carbon-volt/carbon-volt-1.1.0.zip
├── install.sh                  # سكريبت التثبيت لأنظمة لينكس وماك (بايثون 3.10+)
├── install.ps1                 # سكريبت التثبيت لأنظمة ويندوز (PowerShell) مع كشف بايثون
├── uninstall.sh                # سكريبت الحذف الذاتي لأنظمة لينكس وماك مع التحقق من السلامة
├── uninstall.ps1               # سكريبت الحذف الذاتي لأنظمة ويندوز (PowerShell)
├── restore.sh                  # سكريبت استرجاع الطوارئ بضغطة واحدة (لينكس وماك)
├── restore.ps1                 # سكريبت استرجاع الطوارئ لأنظمة ويندوز (PowerShell)
├── theme.json                  # بيانات وهوية الثيم الرسمية
├── theme.recipe.json           # وصفة القياسات والحركات من الإصدار v2
├── MANUAL-INSTALL.md           # دليل التثبيت اليدوي في Page Designer لو معندكش شل
├── css/
│   ├── theme.css               # نقطة الدخول المجمعة
│   ├── tokens.css              # المتغيرات المعزولة (html.app-theme-carbon-volt)
│   └── apex/                   # ملفات المكونات (الأزرار، الحقول، النوافذ)
├── fonts/                      # خطوط WOFF2 ذاتية الاستضافة بالكامل
├── licenses/                   # الرخص القانونية للخطوط ورخصة المشروع (MIT)
├── preview/cover.jpg           # صورة المعاينة بدقة 960 بكسل
└── lib/theme_factory/          # محرك APEXLang الداخلي (بدون pip install خالص!)

الضمانات الثلاث الأساسية للحزمة:

صفر اعتماد على شبكات الإنترنت الخارجية (Zero CDN): كتير من أنظمة الشركات والبنوك والمؤسسات الحكومية شغالة على شبكات داخلية معزولة تماماً عن الإنترنت (Air-gapped Networks). لو ربطت خطوط Google Fonts أو سيرفر خارجي، الشاشات هتعلق وتفتح ببطء شديد. كل حزمة عندنا بتحتوي على خطوط WOFF2 الأصلية بتاعتها، وتم التحقق من سلامتها بتوقيع بايتات wOF2 الرسمي.
محرك تشغيل مدمج بالكامل: المجلد المضغوط جواه مكتبة البايثون المساعدة الخاصة بيه في مجلد lib/. مش هتحتاج تسطب بايثون فيرتشوال إنفيرومنت، ولا هتحتاج تعمل pip install لأي مكتبة على سيرفر الداتابيز.
بصمات تشفير SHA-256 لمنع التلاعب: كل ملف جوه الحزمة بيتحسب له كود هاش تشفيري. لو ملف اتقطع أثناء التحميل أو اتعدل بالغلط، أداة التثبيت بتكشف ده فوراً وترفض تلمس قاعدة البيانات.

🤖 الترقيع التلقائي لملفات APEXLang بدون تخريب

إزاي أداة التثبيت بتعدل تطبيق أوراكل أبيكس من غير ما تلخبط الشاشات أو تعطل كود البزنس؟

في إصداري Oracle APEX 26.1 و 26.2، أصبح تصدير التطبيقات بيتم بتنسيق جديد اسمه APEXLang—وده تنسيق تركيبي واضح بيحول ملف الـ SQL القديم لملفات هيكلية منظمة شبه الـ YAML (application.apx, theme.apx, pages/page_00000.apx).

أداة التثبيت بتنفذ مسار عمل جراحي دقيق بيتكون من 6 مراحل في خط التثبيت:

┌────────────────────────────────────────────────────────────────────────┐
│                        مسار التثبيت المحمي بالكامل                     │
└──────────────────────────────────┬─────────────────────────────────────┘
                                   │
                                   ▼
┌────────────────────────────────────────────────────────────────────────┐
│ 1. فحص المتطلبات: إصدار APEX 26.1 أو 26.2 وثيم 42 ونمط Iris (رمز خروج 3)│
└──────────────────────────────────┬─────────────────────────────────────┘
                                   │
                                   ▼
┌────────────────────────────────────────────────────────────────────────┐
│ 2. التصدير والتجهيز: تصدير التطبيق لمجلد مؤقت بتنسيق APEXLang           │
└──────────────────────────────────┬─────────────────────────────────────┘
                                   │
                                   ▼
┌────────────────────────────────────────────────────────────────────────┐
│ 3. الترقيع الهيكلي: إضافة مسارات الـ CSS ومنطقتي التمهيد في Page 0      │
└──────────────────────────────────┬─────────────────────────────────────┘
                                   │
                                   ▼
┌────────────────────────────────────────────────────────────────────────┐
│ 4. فحص الانحراف (Drift): التأكد إن مفيش مطور عدل التطبيق في نفس اللحظة  │
└──────────────────────────────────┬─────────────────────────────────────┘
                                   │
                                   ▼
┌────────────────────────────────────────────────────────────────────────┐
│ 5. النسخ الاحتياطي الذري: حفظ نسخة كاملة جوه theme-factory-backups/    │
└──────────────────────────────────┬─────────────────────────────────────┘
                                   │
                                   ▼
┌────────────────────────────────────────────────────────────────────────┐
│ 6. الاستيراد والتحقق: استيراد التطبيق والتحقق من كلاسات الـ DOM المباشرة│
└────────────────────────────────────────────────────────────────────────┘

الأماكن اللي الأداة بتعدلها تحديداً:

التعديل دقيق ومحدود ومحسوب بالمسطرة:

الملفات الثابتة للتطبيق (Static Files): بيتم رفع الملفات تحت مسار منظم #APP_FILES#theme-factory/packages/<name>/<version>/.
روابط ملفات الـ CSS: بيتم حقن رابط ملف الـ theme.css جوه خصائص واجهة المستخدم في application.apx.
مناطق الصفحة 0 (Page 0 Regions): بيتم حقن المنطقتين بتوع التمهيد (theme_factory_bootstrap و theme_factory_bootstrap_dialog).
شريط التنقل (Navigation Bar): لو اخترت خيار --with-switcher، بيتم إضافة عناصر قائمة ثابتة للتبديل.

الأداة لا تلمس إطلاقاً جداولك، ولا استعلامات الـ SQL، ولا إجراءات الـ PL/SQL، ولا صلاحيات الأمان الخاصة بنظامك!

🛡️ شبكة الأمان وأكواد الخروج (Exit Codes)

الأداة مصممة بنظام أمان صارم مستوحى من أنظمة التشغيل الحرجة:

كود الخروج	سبب التوقف	رد فعل الأداة
`0`	نجاح تام	تمت العملية بنجاح (أو انتهت التجربة الجافة بدون أخطاء).
`3`	عدم تطابق المتطلبات	بتوقف فوراً لو إصدار أبيكس مش 26.1 أو 26.2 أو الثيم مش Iris.
`4`	انحراف الداتابيز (Drift)	بتوقف لو مطور تاني عدل في التطبيق أثناء تجهيز التثبيت.
`5`	فشل التحقق في SQLcl	خطأ في تجميع ملفات التصدير، وقاعدة البيانات بتفضل سليمة.
`6`	عدم تطابق ما بعد الاستيراد	التحقق النهائي أثبت إن النتيجة مش مطابقة لما تم تجهيزه.
`7`	إلغاء المستخدم	المستخدم كتب رقم تطبيق غلط وقت التأكيد اليدوي.

درع أمان التطبيقات متعددة اللغات (`--discard-translations`)

معلومة تقنية دقيقة ومهمة جداً لبيئات الشركات الكبيرة: استيراد تطبيقات أوراكل أبيكس القياسي عبر SQLcl بيمسح النصوص المترجمة (Translated Application Strings) لو التطبيق متعدد اللغات. عشان كدة أداة التثبيت بتفحص التطبيق المستهدف بدقة وقت الفحص المبدئي (Preflight).

لو لقت التطبيق فيه نصوص مترجمة، الأداة بترفض تكمل فوراً وبتقفل كإجراء أمان صارم لحماية بياناتك، إلا لو المطور حدد خيار --discard-translations صراحة. والتطبيقات اللي محتاجة تحافظ على ترجماتها كاملة بدون فقدان بتتبع خطوات التثبيت اليدوي المشروحة في ملف MANUAL-INSTALL.md. بالإضافة لكدة، ولأن أداة SQLcl تاريخياً بتُرجع أحياناً كود خروج 0 حتى لو حصل خطأ داخلي في الاستيراد، أداة التثبيت بتتحقق بنفسها من رمز النجاح الرسمي الصادر من أوراكل قبل ما تعتمد أي تسجيل!

تشغيل التجربة الجافة الآمنة (Dry Run):

بشكل افتراضي، تشغيل أمر ./install.sh (أو .\install.ps1 على أنظمة ويندوز) من غير ما تديله خيار --apply بيعمل تجربة جافة 100%:

# تشغيل تجربة جافة على لينكس / ماك (مش بيكتب ولا بايت واحد جوه الداتابيز)
./install.sh \
  --connection docker-demo \
  --workspace DEMO \
  --app-id 102

# تشغيل تجربة جافة على ويندوز عبر PowerShell
.\install.ps1 `
  -Connection docker-demo `
  -Workspace DEMO `
  -AppId 102

الأداة بتصدر التطبيق في الذاكرة، وتركب التعديلات، وتعمل تحقق كامل في SQLcl، وتطبع لك تقرير مفصل بكل حاجة كانت هتحصل:

[Dry-Run] Target APEX Application: 102 (Universal Theme 26.1 Reference)
[Dry-Run] Verified: APEX 26.1.4, Theme 42, Style Iris
[Dry-Run] Static files to register: 8 files (theme.css, tokens.css, fonts...)
[Dry-Run] Page 0 Regions to inject: 2 regions (Standard Banner + Modal Position 01)
[Dry-Run] Backup destination: ./theme-factory-backups/DEMO-102/20261103T120000Z/
[Dry-Run] Result: All validations PASSED. Re-run with --apply to commit.

وفقط لما تكتب خيار --apply صراحة، الأداة بتطلب منك تكتب رقم التطبيق للتأكيد، وبتاخد نسخة احتياطية غير قابلة للتعديل قبل ما تعمل الاستيراد النهائي.

🔄 التراجع التام بدون بقايا: أمر الاسترجاع الذري

لو في أي وقت قررت تحذف ثيم، مش هتحتاج تدور على الملفات يدوي:

# حذف آمن ومعتمد على سجل التثبيت التشفيري (لينكس / ماك)
./uninstall.sh --connection docker-demo --workspace DEMO --app-id 102 --apply

# حذف آمن عبر PowerShell على ويندوز
.\uninstall.ps1 -Connection docker-demo -Workspace DEMO -AppId 102 -Apply

سكريبت الحذف بيقرا ملف registry.json، ويتحقق من كود الـ SHA-256 لكل ملف. لو لقى مطور عدل في ملف بإيده جوه أبيكس، بيرفض يحذفه عشان ميضيعش مجهوده!

وعندك كمان زرار الطوارئ الكامل لاسترجاع التطبيق بضغطة واحدة لأقرب نسخة احتياطية زي ما كان قبل التثبيت بالثانية:

# استرجاع فوري بضغطة واحدة على لينكس / ماك
./restore.sh \
  --connection docker-demo \
  --workspace DEMO \
  --app-id 102 \
  --backup ./theme-factory-backups/DEMO-102/20261103T120000Z \
  --apply --discard-later-changes

# استرجاع فوري بضغطة واحدة على ويندوز عبر PowerShell
.\restore.ps1 `
  -Connection docker-demo `
  -Workspace DEMO `
  -AppId 102 `
  -Backup .\theme-factory-backups\DEMO-102\20261103T120000Z `
  -Apply -DiscardLaterChanges

🏢 بيئات العمل المعزولة؟ دليل `MANUAL-INSTALL.md`

لو شغال في بنك أو جهة حكومية بتمنع تشغيل سكريبتات بايثون أو استخدام SQLcl من أجهزة المطورين: كل حزمة بتيجي مع ملف اسمه MANUAL-INSTALL.md جواه 3 خطوات بسيطة من شاشة الـ App Builder في المتصفح:

الخطوة 1: ارفع ملفات الثيم الثابتة
         ادخل على Shared Components -> Static Application Files.
         اضغط Upload Files وارفع محتويات مجلدي /css و /fonts.

الخطوة 2: ضيف رابط ملف الـ CSS
         ادخل على Shared Components -> User Interface Attributes.
         في خانة CSS File URLs ضيف:
         #APP_FILES#theme-factory/packages/carbon-volt/1.1.0/theme.css

الخطوة 3: أنشئ منطقة تمهيد في الصفحة 0
         افتح Page 0 واعمل Static Content Region في موضع #BANNER#.
         وحط كود التمهيد المتزامن من ملف bootstrap.html.

سواء اخترت الأتمتة الكاملة بالـ CLI أو الشغل اليدوي بالماوس في المتصفح، النتيجة النهائية واحدة وشغالة بنفس الكفاءة!

⏭️ المقال القادم: بناء أداة تبديل الثيمات المخصصة

دلوقتي الثيمات بقت متثبتة بنجاح جوه التطبيق. بس المستخدمين إزاي هيبدلوا بين الثيمات دي في واجهة الاستخدام؟

في الجزء الخامس من السلسلة، هنتعلم بناء أداة تبديل الثيمات المخصصة: هنغوص جوه واجهة برمجة window.ApexThemeFactory، ونعترض قائمة Navigation Bar الرسمية في أبيكس، ونتعلم إزاي روابط Hash بتحمينا من أخطاء الـ Friendly URLs، ونبني أزرار حديثة باستخدام Alpine.js! 🎛️🚀

💡 ابدأ مع APEX Theme Factory الآن: تقدر تعمل Clone للمستودع، وتجرب الثيمات الجاهزة (carbon-volt، iris-dark، وغيرها)، وتستخدم أداة التثبيت الآلية: 🔗 https://github.com/ash2osh/APEX_THEME_FACTORY