أحمد شريف | أوراكل أبيكس والذكاء الاصطناعي · مقالات، شروحات، وحيل برمجية

حفظ الثيمات على مستوى المؤسسة في Oracle APEX: قاعدة البيانات، الملفات الشخصية، والوميض الصفري 🏨🔐

Sun, 08 Nov 2026 00:00:00 GMT

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

حفظ الثيمات على مستوى المؤسسة في Oracle APEX: قاعدة البيانات، الملفات الشخصية، والوميض الصفري 🏨🔐

الجزء السادس (مسك الختام) من السلسلة التقنية الشاملة: الربط مع قاعدة البيانات والمزامنة الفورية في Oracle APEX.

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

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

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

التجربة المتناسقة دي هي بالضبط اللي بيستناها مستخدمين أنظمة الشركات والمؤسسات. التخزين المحلي في المتصفح localStorage ممتاز لجهاز واحد، بس موظف الشركة بيتنقل بين كمبيوتر المكتب، واللابتوب في الاجتماعات، والتابلت في المخازن. وعايز ثيمه المفضل يفضل متسجل في هويته المؤسسية (:APP_USER) في كل حتة.

في مسك الختام لسلسلتنا APEX Theme Factory، هنربط واجهات المستخدم الحديثة مع هندسة قاعدة بيانات أوراكل العميقة. هنتعلم إزاي نخزن تفضيلات المستخدمين عبر حزمة APEX_UTIL.SET_PREFERENCE، ونعمل مزامنة سريعة في الخلفية بتقنية Ajax، ونحقق المعجزة: حقن الثيم من السيرفر بدون أي وميض أبيض (Zero-FOUC Hydration) باستخدام عناصر التطبيق (Application Items). 🚀

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

🌐 واقع بيئات الشركات: ليه التخزين المحلي لوحده ميكفيش؟

في الجزأين الثالث والخامس من السلسلة اعتمدنا على localStorage في المتصفح. للتشغيل على جهاز واحد، الحل ده مثالي وسريع جداً: صفر استهلاك لقاعدة البيانات، وصفر زمن تأخير شبكة، وسرعة تشغيل في أقل من 2 ميلي ثانية.

لكن في بيئات العمل الحقيقية للشركات:

التنقل بين الأجهزة: الممرض في المستشفى بيسجل دخول على شاشة الاستقبال في عنبر أ، وبعدها بنصف ساعة بيسجل دخول على تابلت في عنبر ب. كود المتصفح المحلي ملوش أي وسيلة ينقل التفضيل بين جهازين منفصلين.
بيئات الأجهزة الافتراضية (Citrix / VDI): بنوك كتير ومؤسسات حكومية بتشغل أنظمة VDI بتمسح ذاكرة التخزين المؤقت للمتصفح (Cache) بالكامل مع كل تسجيل خروج يومي للموظف.
التحكم والامتثال للمسؤولين: فرق الدعم الفني وتكنولوجيا المعلومات مش بيعرفوا يفحصوا أو يفرضوا ثيمات مريحة لمتحدي الإعاقة البصرية لو التفضيلات محبوسة جوه هارد ديسك المستخدم.

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

🗄️ المعمارية الهندسية: الجسر المؤسسي في 4 مراحل

المخطط ده بيوضح إزاي Theme Factory بيربط شاشات المتصفح مع سطور قاعدة بيانات أوراكل:

┌────────────────────────────────────────────────────────┐
│ 1. تسجيل دخول المستخدم (:APP_USER)                      │
│    إجراء ما بعد المصادقة يقرا التفضيل ويحطه في         │
│    عنصر التطبيق العام: &F_USER_THEME.                  │
└───────────────────────────┬────────────────────────────┘
                            │
                            ▼
┌────────────────────────────────────────────────────────┐
│ 2. الحقن المسبق من السيرفر (Server-Side Hydration)     │
│    كود التمهيد في Page 0 يستلم &F_USER_THEME!ATTR.     │
│    الصفحة بتوصل للمتصفح وهي جاهزة بالثيم المظلم فورا!  │
└───────────────────────────┬────────────────────────────┘
                            │
                            ▼
┌────────────────────────────────────────────────────────┐
│ 3. تفاعل المستخدم (اختيار ثيم جديد من الشاشة)          │
│    استدعاء window.ApexThemeFactory.use('carbon-volt')  │
│    تحديث التخزين المحلي للسرعة الفورية على الجهاز      │
└───────────────────────────┬────────────────────────────┘
                            │
                            ▼
┌────────────────────────────────────────────────────────┐
│ 4. مزامنة الخلفية غير المتزامنة (Ajax Callback)        │
│    إرسال طلب صامت لإجراء PL/SQL في الصفحة رقم 0        │
│    حفظ الاختيار في الداتابيز عبر APEX_UTIL.SET_PREFERENCE│
└────────────────────────────────────────────────────────┘

🛠️ الخطوة 1: تخزين التفضيل في قاعدة بيانات أوراكل

أوراكل أبيكس بتقدّم محرك تفضيلات جاهز وفائق الأداء ومفهرس داخلياً من خلال حزمة APEX_UTIL. المحرك ده بيعزل التفضيلات تلقائياً لكل تطبيق ولكل مستخدم:

-- تجربة حفظ وقراءة تفضيل الثيم في ورشة العمل كالتالي:
BEGIN
  -- حفظ تفضيل الثيم للمستخدم المسجل حالياً
  apex_util.set_preference(
    p_preference => 'USER_THEME',
    p_value      => 'carbon-volt',
    p_user       => :APP_USER
  );
  
  -- قراءة التفضيل المخزن
  dbms_output.put_line(
    'الثيم المخزن في الداتابيز: ' || apex_util.get_preference('USER_THEME', :APP_USER)
  );
END;
/

(ملحوظة: لو نظام شركتك بيعتمد على جداول مخصصة لحسابات المستخدمين مع شاشات رقابة وتدقيق، تقدر ببساطة تستبدل حزمة apex_util بأمر تحديث صريح: UPDATE app_user_profiles SET theme = ...).

⚡ الخطوة 2: إجراء الـ Ajax الصامت في الصفحة 0

لما المستخدم يغير الثيم من شاشة الإعدادات، مش عايزين نعمل إعادة إرسال كاملة للصفحة (Full Page Submit) تلخبط موضع التمرير أو تقفل حقول مفتوحة. إحنا بنبعت طلب Ajax خفيف في الخلفية.

خطوات الإعداد جوه Page Designer كالتالي:

افتح الصفحة رقم 0 (Global Page).
تحت قسم Processing، اضغط كليك يمين على Ajax Callback واختار Create Process.
اضبط الإجراء كالتالي:
- الاسم: SET_USER_THEME_AJAX
- كود الـ PL/SQL:

DECLARE
  l_theme VARCHAR2(100) := apex_application.g_x01;
BEGIN
  -- التحقق من القائمة المعتمدة لمنع أي حقن برمجي غير مصرح به
  IF l_theme IN ('carbon-volt', 'citrus-pop', 'cobalt-press', 
                 'estate-slate', 'estate-slate-dark', 'linen', 
                 'solarized-dark', 'velvet-signal', 'iris') THEN
                 
    -- حفظ التفضيل الرسمي في قاعدة بيانات أوراكل أبيكس
    apex_util.set_preference(
      p_preference => 'USER_THEME',
      p_value      => l_theme,
      p_user       => :APP_USER
    );
    
    -- تحديث عنصر الجلسة الحالي عشان يفضل متطابق
    :F_USER_THEME := l_theme;
    
    -- إرجاع رسالة نجاح بصيغة JSON
    apex_json.open_object;
    apex_json.write('status', 'SUCCESS');
    apex_json.write('theme', l_theme);
    apex_json.close_object;
  ELSE
    apex_json.open_object;
    apex_json.write('status', 'ERROR');
    apex_json.write('message', 'اسم الثيم غير مصرح به.');
    apex_json.close_object;
  END IF;
EXCEPTION
  WHEN OTHERS THEN
    apex_json.open_object;
    apex_json.write('status', 'ERROR');
    apex_json.write('message', SQLERRM);
    apex_json.close_object;
END;

كود الربط في ملفات الـ JavaScript كالتالي:

دلوقتي بنربط أداة تبديل الثيمات بحيث أول ما المستخدم ينادي دالة use، نبعت طلب الـ Ajax الصامت ده:

// مزامنة اختيار الثيم مع قاعدة البيانات بدون مقاطعة المستخدم
function persistThemeToDatabase(themeName) {
  if (typeof apex === "undefined" || !apex.server) return;

  apex.server.process(
    "SET_USER_THEME_AJAX",
    {
      x01: themeName
    },
    {
      dataType: "json",
      success: function (data) {
        if (data.status === "SUCCESS") {
          console.log("[Theme Factory] تم حفظ التفضيل بنجاح في قاعدة البيانات:", data.theme);
        }
      },
      error: function (jqXHR, textStatus, errorThrown) {
        console.warn("[Theme Factory] تعذر الاتصال بالسيرفر للحفظ:", errorThrown);
      }
    }
  );
}

🔑 الخطوة 3: تجهيز الجلسة لحظة تسجيل الدخول

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

بنقرا تفضيله من الداتابيز ونحطه في عنصر تطبيق عام (Application Item) أثناء عملية تسجيل الدخول:

في المكونات المشتركة (Shared Components)، أنشئ عنصر تطبيق جديد:
- الاسم: F_USER_THEME
- النطاق: Application
في مخططات المصادقة (Authentication Schemes)، افتح المخطط النشط:
- في خانة Post-Authentication Procedure Name، ضيف الكود التالي:

PROCEDURE post_auth_load_theme IS
  l_pref VARCHAR2(100);
BEGIN
  -- قراءة التفضيل المسجل للمستخدم في قاعدة البيانات
  l_pref := apex_util.get_preference('USER_THEME', :APP_USER);
  
  -- لو المستخدم ملوش تفضيل سابق بنخليه يفتح على ثيم Linen الافتراضي
  :F_USER_THEME := coalesce(l_pref, 'linen');
END post_auth_load_theme;

🌟 اللمسة السحرية: حقن السيرفر الخالي من الوميض تماماً

ودلوقتي مع الضربة القاضية اللي بتجمع السلسلة المكونة من 6 أجزاء في سيمفونية واحدة متكاملة.

بناخد كود التمهيد في الصفحة 0 اللي شرحناه في الجزء الثالث، ونخليه يقرا عنصر التطبيق مباشرة عبر علامات استبدال أبيكس:

<!-- APEX_THEME_FACTORY_MANAGED:BEGIN:BOOTSTRAP -->
<script>
window.APEX_THEME_FACTORY_CONFIG = {
  appId: 102,
  /* السيرفر بيعوض بقيمة الداتابيز مباشرة جوه ملف الـ HTML الأول! */
  defaultTheme: "&F_USER_THEME!ATTR.",
  switcherEnabled: true,
  themes: __THEMES_JSON__
};

(function (doc, config) {
  "use strict";
  var root = doc.documentElement;
  var key = "apex.themeFactory." + config.appId;
  
  // 1. استخدام الثيم المعتمد من الداتابيز واللي واصل في أول بايت من السيرفر
  var selected = config.defaultTheme || "linen";

  // 2. استخدام التخزين المحلي لو المستخدم عدل حاجة أوفلاين
  try {
    var stored = window.localStorage.getItem(key);
    if (stored) { selected = stored; }
  } catch (e) {}

  // 3. تركيب كلاس الثيم على <html> في أقل من 2 ميلي ثانية قبل الرسم
  if (selected && selected !== "iris") {
    root.classList.add("app-theme-" + selected);
  }
  root.dataset.appThemeCurrent = selected;
}(document, window.APEX_THEME_FACTORY_CONFIG));
</script>
<!-- APEX_THEME_FACTORY_MANAGED:END:BOOTSTRAP -->

ليه الحركة دي بتمثل قمة النضج الهندسي؟

صفر وميض في أول زيارة من أي جهاز: لما المستخدم يفتح التطبيق من جهاز آيباد جديد، حزمة الـ HTML اللي بتتبعت من سيرفر ORDS واصلة ومكتوب جواها مسبقاً defaultTheme: "carbon-volt". المتصفح بيلحق يركب الكلاس على <html> قبل ما محرك التفسير يوصل حتى لوسم الـ <body>!
استقرار فوري بدون إنترنت: لو الاتصال قطع أو الموظف شغال في بيئة معزولة، التخزين المحلي بيكمل المسيرة بسلاسة تامة.
صفر تكلفة صيانة مستقبلية: كل الشغل محطوط بأمان في الصفحة 0 وملفات الـ CSS. شاشاتك وتقاريرك وجداولك وبرمجياتك الأساسية بتفضل نظيفة وسليمة 100%!

🏁 ختام السلسلة الشاملة وملخص الرحلة

على مدار المقالات الستة دي، سافرنا سوا من عشوائية التنسيقات التقليدية الملحومة، لحد ما بنينا محرك تصميم عالمي يليق بكبرى الشركات:

الجزء 1: بدلة الحرباء — الهروب من قيود Theme Roller وبناء حزم ثيمات مستقلة فوق Universal Theme 42.
الجزء 2: قلعة العزل الحصينة — معمارية التوكنز ثلاثية الطبقات، حماية الحركة بأعلى أسبقية تنسيق، وإنقاذ أيقونات Font APEX.
الجزء 3: سر الوميض الصفري — القضاء التام على وميض الشاشات المزعج في أقل من 2 ميلي ثانية وتغطية النوافذ المنبثقة.
الجزء 4: ماكينة الحزم المحمولة — تجميع خطوط WOFF2 بدون اعتمادات خارجية، والترقيع الذري لملفات APEXLang مع أمان التراجع.
الجزء 5: بناء محول الثيمات — اعتراض قائمة Navigation Bar، والتحكم في روابط الـ Hash، وتصميم أزرار Alpine.js العصرية.
الجزء 6: حفظ الثيمات على مستوى المؤسسة — ربط التفضيلات بحساب المستخدم في الداتابيز عبر APEX_UTIL والحقن السحابي الخالي من الوميض.

دلوقتي معاك الكتالوج الهندسي الكامل لبناء، ونشر، وصيانة أنظمة تصميم استثنائية في أوراكل أبيكس تدوم لسنين بدون تراكم أي ديون برمجية. انطلق وابنِ برمجيات مبهرة تسعد مستخدميك! 🚀

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

بناء أداة تبديل الثيمات المخصصة في Oracle APEX: ودجز الواجهة، Alpine.js، وعناصر النماذج 🎛️✨

Sat, 07 Nov 2026 00:00:00 GMT

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

بناء أداة تبديل الثيمات المخصصة في Oracle APEX: ودجز الواجهة، Alpine.js، وعناصر النماذج 🎛️✨

الجزء الخامس من السلسلة التقنية الشاملة: تصميم عناصر التحكم وتطوير واجهات المستخدم التفاعلية في Oracle APEX.

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

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

ده الإحساس اللي بيوصل لمستخدمين تطبيقات الشركات لما تحط لهم أداة تبديل ثيمات عشوائية. القائمة المنسدلة في شريط التنقل العلوي (Navigation Bar) كويسة وشغالة، بس المستخدمين دلوقتي مستنيين عناصر تحكم بصرية حديثة ومريحة: بطاقات ملونة في صفحة الملف الشخصي، وأزرار كبسولات تفاعلية (Pills)، وعناصر نماذج قياسية جوه شاشات الإعدادات.

في الجزء الخامس من سلسلتنا APEX Theme Factory، هنستلم قمرة القيادة في واجهة المستخدم. هنشرح بالتفصيل محرك الجافاسكريبت window.ApexThemeFactory، ونكتشف إزاي روابط الـ Hash بتحمينا من أخطاء الـ Checksum في روابط أبيكس الذكية (Friendly URLs)، ونعترض ودجت القوائم الرسمية في أبيكس، ونبني أزرار حديثة باستخدام Alpine.js 3.x وعناصر نماذج أبيكس القياسية. 🚀

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

🕹️ استكشاف كود `window.ApexThemeFactory`

لما كود التمهيد بيشتغل في الصفحة رقم 0، بيثبت كائن تحكم برمجي خفيف ومحمي على الكائن العام window:

/* واجهة التحكم البرمجية في المتصفح */
window.ApexThemeFactory = Object.freeze({
  // بيرجع اسم الثيم النشط حالياً (زي 'carbon-volt' أو 'linen')
  current: function () { ... },

  // بيرجع مصفوفة بكل الثيمات المثبتة في التطبيق مع عناوينها
  choices: function () { ... },

  // بيفعل الثيم المطلوب ويحدث التخزين المحلي وينضف رابط الصفحة ويعيد التحميل
  use: function (name) { ... }
});

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

// 1. شوف إيه الثيم النشط دلوقتي
console.log(window.ApexThemeFactory.current());
// النتيجة: "linen"

// 2. اعرض كل الثيمات المتاحة في جدول منظم
console.table(window.ApexThemeFactory.choices());

// 3. بدل لثيم Carbon Volt بلمسة واحدة
window.ApexThemeFactory.use("carbon-volt");

لما بتنادي الدالة window.ApexThemeFactory.use('carbon-volt')، المحرك بينفذ الخطوات التالية:

بيتحقق إن اسم الثيم موجود فعلاً في قائمة الثيمات المصرح بها في التطبيق.
بيسجل الاختيار في التخزين المحلي: localStorage.setItem('apex.themeFactory.102', 'carbon-volt').
لو المستخدم اختار الثيم الافتراضي للنظام (زي linen)، الكود بيمسح المفتاح من الـ localStorage، عشان لو مدير النظام غير الثيم الافتراضي بعد أسبوع، المستخدم ياخد التحديث الجديد فوراً!
بينضف أي زوائد #theme= من رابط المتصفح ويعيد تحميل الصفحة بنعومة.

🛡️ سر روابط الـ Hash والحماية من أخطاء الـ Checksum

ليه Theme Factory بيدعم تبديل الثيمات عبر الهاش #theme=carbon-volt بدل استخدام المعاملات العادية زي ?theme=carbon-volt؟

أي مطور اشتغل مع روابط أبيكس الذكية الحديثة (Friendly URLs) عارف شاشة الخطأ الشهيرة دي:

HTTP 400 Bad Request
"The request could not be processed because the checksum is invalid."

في أوراكل أبيكس، خاصية حماية حالة الجلسة (Session State Protection - SSP) بتنشئ توقيع تشفيري (Checksum) لكل المعاملات اللي بتتبعت في الرابط. لو ضفت معامل جديد زي ?theme=dark من غير ما تكون مشفره من السيرفر، محرك أبيكس بيرفض الطلب فوراً باعتباره محاولة اختراق أمني!

حل الهاش السحري في جهة العميل:

https://mycorp.com/ords/r/demo/ut/dashboard#theme=carbon-volt
                                            ▲
                                            └── هاش محلي جوه المتصفح فقط

أجزاء الـ Hash في الرابط (أي حاجة بعد علامة #) مبتتبعتش للسيرفر أو قاعدة البيانات إطلاقاً! المتصفح بيحتفظ بيها جواه فقط.

كود التمهيد في الصفحة رقم 0 بيقرا الهاش ده محلياً قبل ما يقرا التخزين المحلي. بكده فرق الدعم والمبيعات والتسويق يقدروا يبعتوا روابط مباشرة بتفتح شاشات معينة بثيم محدد وبدون أي خطأ Checksum على الإطلاق!

لو ثبت حزم الثيمات بخيار --with-switcher، إزاي Theme Factory بيحول عنصر شريط التنقل لقائمة راديو متفاعلة؟

الكود بيستمع لحدث رسمي بيطلقه الثيم الموحد لما يجهز اسمه theme42ready.apexThemeFactory. ولما الحدث ده يحصل، بيعترض القائمة الداخلية ويحولها لقائمة خيارات راديو (Radio Group) متصلة بواجهة الـ API كالآتي:

/* كود اعتراض القائمة من الملف theme-factory-runtime.js */
apex.jQuery(window)
  .off("theme42ready.apexThemeFactory")
  .on("theme42ready.apexThemeFactory", function () {
    var $ = apex.jQuery;
    var button = $(".t-NavigationBar-item.theme-factory-managed-switcher [data-menu]").first();
    var menu = button.length ? $("#" + button.attr("data-menu")) : $();
    
    if (!menu.length) return;

    // حقن مجموعة راديو تفاعلية جوه ودجت قائمة أبيكس الرسمية!
    menu.menu("option", "items", [{
      type: "radioGroup",
      get: window.ApexThemeFactory.current,
      set: window.ApexThemeFactory.use,
      choices: window.ApexThemeFactory.choices()
    }]);
  });

الحركة دي بتحول القائمة العادية لقائمة راديو ذكية، عليها علامة صح جنب الثيم المختار حالياً، ومتوافقة 100% مع لوحة المفاتيح ومعايير إمكانية الوصول لذوي الاحتياجات الخاصة!

🎨 النمط الأول: أزرار كبسولات حديثة باستخدام Alpine.js 3.x

عايز تبني واجهة شيك وعصرية جوه شاشة الملف الشخصي للمستخدم؟ تقدر تعمل أزرار كبسولات (Pills) تفاعلية باستخدام مكتبة Alpine.js 3.x جوه منطقة محتوى ثابت في أبيكس:

<!-- حط الكود ده جوه Static Content Region في شاشة إعدادات المستخدم أو الملف الشخصي -->
<div x-data="themePicker()" class="app-theme-picker">
  <label class="app-theme-picker__label">تخصيص المظهر البصري:</label>
  <div class="app-theme-picker__group">
    <template x-for="theme in themes" :key="theme.value">
      <button 
        type="button"
        class="app-theme-picker__pill"
        :class="{ 'is-active': currentTheme === theme.value }"
        @click="switchTheme(theme.value)">
        <span class="app-theme-picker__indicator" :data-theme="theme.value"></span>
        <span x-text="theme.label"></span>
      </button>
    </template>
  </div>
</div>

<script>
function themePicker() {
  return {
    currentTheme: window.ApexThemeFactory ? window.ApexThemeFactory.current() : 'iris',
    themes: window.ApexThemeFactory ? window.ApexThemeFactory.choices() : [],
    switchTheme(themeName) {
      if (this.currentTheme === themeName) return;
      this.currentTheme = themeName;
      window.ApexThemeFactory.use(themeName);
    }
  };
}
</script>

وحط كود الـ CSS المنسق ده في خانة Inline CSS الخاصة بالصفحة:

.app-theme-picker {
  padding: 1rem;
  background: var(--app-surface-card);
  border: 1px solid var(--app-border-color);
  border-radius: var(--app-radius-md);
}
.app-theme-picker__label {
  display: block;
  font-weight: var(--app-font-weight-semibold);
  margin-bottom: 0.75rem;
  color: var(--app-text-primary);
}
.app-theme-picker__group {
  display: flex;
  flex-wrap: wrap;
  gap: 0.5rem;
}
.app-theme-picker__pill {
  display: inline-flex;
  align-items: center;
  gap: 0.5rem;
  padding: 0.5rem 1rem;
  border: 1px solid var(--app-border-color);
  background: var(--app-surface-input);
  color: var(--app-text-primary);
  border-radius: 9999px;
  cursor: pointer;
  transition: all var(--app-motion-duration) ease;
}
.app-theme-picker__pill:hover {
  transform: var(--app-hover-transform);
  border-color: var(--app-border-strong);
}
.app-theme-picker__pill.is-active {
  border-color: var(--app-color-primary);
  background: var(--app-surface-selected);
  font-weight: var(--app-font-weight-semibold);
}
.app-theme-picker__indicator {
  width: 10px;
  height: 10px;
  border-radius: 50%;
  background: var(--app-color-primary);
}

📋 النمط الثاني: عناصر نماذج أبيكس الرسمية والأوامر الديناميكية

لو بتفضل مكونات أوراكل أبيكس القياسية من غير مكتبات إضافية، تقدر تبرمج قائمة منسدلة أو مجموعة أزرار راديو في 3 خطوات سهلة:

الخطوة 1: أنشئ عنصر جديد جوه الصفحة:
         - الاسم: P10_THEME_SELECTOR
         - النوع: Select List (أو Radio Group)
         - نوع القيم: Static Values
         - كود القيم الثابتة:
           STATIC:Carbon Volt;carbon-volt,Citrus Pop;citrus-pop,Solarized Dark;solarized-dark,Linen;linen,Iris;iris

الخطوة 2: اضبط القيمة الافتراضية (Default Value) كالتالي:
         - النوع: JavaScript Expression
         - الكود: window.ApexThemeFactory ? window.ApexThemeFactory.current() : 'iris'

الخطوة 3: أضف أمر ديناميكي (Dynamic Action) عند التغيير:
         - الحدث: Change
         - الإجراء: Execute JavaScript Code
         - الكود:
           window.ApexThemeFactory.use(this.data);

أول ما المستخدم يختار أي قيمة، الأمر الديناميكي بينادي دالة use تلقائياً بدون ما تشغل بالك بتفاصيل التخزين!

⏭️ المقال القادم: حفظ الثيمات على مستوى قاعدة البيانات

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

في الجزء السادس والأخير من السلسلة (مسك الختام!)، هنتعلم حفظ الثيمات على مستوى المؤسسة: ربط التفضيلات بحساب المستخدم (:APP_USER) في قاعدة البيانات، واستدعاءات Ajax المباشرة، وحقن الكلاس في الصفحة الأولى بدون وميض وبسرعة البرق! 🏨🔐🚀

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

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

Fri, 06 Nov 2026 00:00:00 GMT

🇬🇧 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

سر الوميض الصفري: القضاء على الفلاش الأبيض بتمهيد Page 0 في Oracle APEX ⚡🎭

Thu, 05 Nov 2026 00:00:00 GMT

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

سر الوميض الصفري: القضاء على الفلاش الأبيض بتمهيد Page 0 في Oracle APEX ⚡🎭

الجزء الثالث من السلسلة التقنية الشاملة: تسريع الأداء ومنع وميض الشاشات المزعج في Oracle APEX.

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

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

بعدها بثانيتين، يقوم طاقم العمال ضارب كشافات نيون بيضاء عملاقة بقوة 50,000 شمعة في وشوش الجمهور مباشرة، وبعدين يجروا يركبوا جيلاتين أزرق وداكن على الكشافات عشان يعملوا الجو المرعب! الصدمة دي بتعمي عيون الجمهور وتجيب لهم صداع نصفي قبل ما الممثلين ينطقوا كلمة واحدة!

الصدمة البصرية دي هي بالظبط اللي بيعاني منها مستخدمين نظامك لما تعمل ثيم داكن باستخدام الأوامر الديناميكية (Dynamic Actions) أو أكواد $(document).ready(). المتصفح بيرسم خلفية نمط Iris البيضاء الناصعة الأول، ويستنى الصفحة تخلص تحميل، وبعدين يشغل كود الجافاسكريبت عشان يقلب الصفحة سودة! النتيجة؟ وميض أبيض مؤلم للعين لمدة 200 ميلي ثانية مع كل دوسة ماوس!

في الجزء التالت من سلسلتنا APEX Theme Factory، هنقضي على الوميض المزعج (FOUC) للأبد. هنتعلم سر الوميض الصفري: إزاي بنحقن سطر كود متزامن فائق الخفة في الصفحة 0 (Page 0) بيظبط إضاءة المشهد في أقل من 2 ميلي ثانية قبل ما المتصفح يرسم أول بكسل على الشاشة، ومع تغطية كاملة للصفحات العادية والنوافذ المنبثقة (Modal Dialogs) معاً. 🚀

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

⚡ التشريح الدقيق للوميض المزعج (FOUC)

عشان نفهم ليه أساليب التبديل التقليدية بتعمل فلاش ووميض مزعج، لازم نبص على مسار المعالجة والرسم جوه المتصفح (Critical Rendering Path):

❌ كابوس الوميض غير المتزامن (Dynamic Actions / document.ready)
───────────────────────────────────────────────────────────────────────────
1. طلب الصفحة GET /ords/r/demo/ut/dashboard
2. استلام ملف الـ HTML وتطبيق الـ CSS الافتراضي (خلفية Iris فاتحة #fbf9f8)
3. 💥 الرسم الأول (First Paint): المتصفح يرسم الشاشة باللون الأبيض الناصع!
4. اكتمال بناء شجرة الصفحة (DOMContentLoaded)
5. تشغيل كود JavaScript: قراءة التفضيل وإضافة كلاس .app-theme-carbon-volt
6. 🔄 إعادة الرسم (Second Paint): المتصفح يعيد الحسابات ويقلب الشاشة داكنة (#12151c)
── المدة الإجمالية للوميض: من 150 لـ 350 ميلي ثانية بتخطف البصر ──────────

✅ سر الوميض الصفري في Theme Factory (تشغيل متزامن في Page 0)
───────────────────────────────────────────────────────────────────────────
1. طلب الصفحة GET /ords/r/demo/ut/dashboard
2. المتصفح يقابل كود التمهيد المتزامن فوراً في Page 0
3. ⚡ كود سريع في أقل من 2 ميلي ثانية يقرا التفضيل ويحط الكلاس على <html>
4. المتصفح يكمل قراءة باقي الصفحة والكلاس الداكن راكب بالفعل
5. 🎨 الرسم الأول (First Paint): المتصفح يرسم النمط المظلم مباشرة من أول فريم!

لما بتعتمد على إعداد Execute when Page Loads أو الأوامر الديناميكية في Page Designer، كودك بيتنفذ في الخطوة رقم 5، بعد ما المتصفح يكون رسم الشاشة بالكامل باللون الأبيض في الخطوة 3!

عشان نمنع الوميض ده بدون ما نحمل على السيرفر، لازم الكود بتاعنا يتنفذ بشكل متزامن (Synchronously) أثناء قراءة الـ HTML وقبل أول لقطة رسم للمتصفح.

📜 محرك التمهيد السريع (2 ميلي ثانية)

في Theme Factory بنستخدم سطر تمهيد خفيف ومجرب وموجود جوه القالب الرسمي للمشروع في الملف installer/templates/bootstrap.html.tmpl:

<!-- APEX_THEME_FACTORY_MANAGED:BEGIN:BOOTSTRAP -->
<script>
window.APEX_THEME_FACTORY_CONFIG = {
  appId: 102,
  defaultTheme: "linen",
  switcherEnabled: true,
  themes: [
    {"name": "carbon-volt", "title": "Carbon Volt"},
    {"name": "citrus-pop", "title": "Citrus Pop"},
    {"name": "solarized-dark", "title": "Solarized Dark"},
    {"name": "linen", "title": "Linen"}
  ]
};

(function (doc, config) {
  "use strict";
  var root = doc.documentElement;
  var key = "apex.themeFactory." + config.appId;
  var allowed = ["iris"].concat(config.themes.map(function (theme) { return theme.name; }));
  var selected = config.defaultTheme;

  if (config.switcherEnabled) {
    try {
      selected = window.localStorage.getItem(key) || selected;
      /* مسح أي قيم قديمة أو محذوفة من التخزين المحلي */
      if (allowed.indexOf(selected) === -1) {
        window.localStorage.removeItem(key);
        selected = config.defaultTheme;
      }
    } catch (e) {
      /* معالجة وضع التصفح الخفي في سفاري */
      selected = config.defaultTheme;
    }
  }

  /* إزالة أي كلاس ثيم قديم وإضافة الكلاس المعتمد الحالي */
  Array.prototype.slice.call(root.classList).forEach(function (name) {
    if (name.indexOf("app-theme-") === 0) { root.classList.remove(name); }
  });

  if (selected !== "iris") { 
    root.classList.add("app-theme-" + selected); 
  }
  
  root.dataset.appThemeDefault = config.defaultTheme;
  root.dataset.appThemeCurrent = selected;
}(document, window.APEX_THEME_FACTORY_CONFIG));
</script>
<!-- APEX_THEME_FACTORY_MANAGED:END:BOOTSTRAP -->

ليه السطر ده خارق ومحصن من الأخطاء؟

بدون أي مكتبات خارجية: بيعتمد على جافاسكريبت أصلي خام (Pure Vanilla ES5). مش بيستنى jQuery ولا دوال أبيكس ولا ملفات الخطوط.
سرعة التنفيذ: في كل الاختبارات القياسية على كروم وفايرفوكس وسفاري، زمن تشغيل الكود ده بيتراوح بين 0.8 ميلي ثانية إلى 1.8 ميلي ثانية فقط!
تنظيف التخزين التلقائي: لو المستخدم كان مخزن ثيم قديم تم حذفه من التطبيق، الكود بيمسح المفتاح التالف تلقائياً ويرجع للثيم الافتراضي config.defaultTheme.
حماية وضع التصفح الخفي (Safari Private Browsing): في متصفح سفاري بالوضع الخاص، محاولة الوصول لـ localStorage أحياناً بترمي خطأ أمني (QUOTA_EXCEEDED_ERR). كود الـ try/catch بيعالج ده بسلاسة ويشغل الثيم الافتراضي بدون أي توقف.

ودلوقتي مع اللغز اللي بيوقع 99% من مطوري أبيكس لما يركبوا كود تمهيد في الشاشات.

المطور بيفتح Page 0 (Global Page) ويعمل منطقة محتوى ثابت (Static Content Region) ويحط فيها الكود، ويختار موضع القالب: #BANNER# (أو رأس الصفحة Top of Page).

يجرب الشاشات والتقارير الرئيسية العادية.. يلاقي النمط المظلم شغال بدون وميض وبسرعة الصاروخ، ويفرح جداً!

وفجأة، مستخدم يدوس على زرار يفتح نافذة منبثقة (Modal Dialog) عشان يعدل بيانات عميل..

بوم! 💥 شاشة بيضاء بتنفجر في وشه كأن فلاش كاميرا ضرب في عينيه!

┌────────────────────────────────────────────────────────┐
│  قالب الصفحات العادية في Universal Theme 42            │
│  [#HEADER#]                                            │
│  [#BANNER#]  <-- الكود بيتنفذ بنجاح والصفحة بتتلون     │
│  [#BODY#]                                              │
└────────────────────────────────────────────────────────┘

┌────────────────────────────────────────────────────────┐
│  قالب النوافذ المنبثقة (Modal Dialog Page)             │
│  [#HEADER#]                                            │
│  منفذ #BANNER# غير موجود أصلاً في قالب النوافذ!        │
│  [#BODY#]                                              │
│  النتيجة: الكود مش بيتنفذ خالص والنافذة بتفضل بيضاء!   │
└────────────────────────────────────────────────────────┘

السر في Universal Theme 42 هو إن قوالب النوافذ المنبثقة (Modal Dialogs) لا تحتوي على الموضع #BANNER# إطلاقاً!

وبما إن النافذة المنبثقة بتشتغل جوه إطار مستقل (<iframe>) وله جذر وثيقة خاص بيه، لو الكود محطوط في #BANNER# بس، النافذة مش هتاخد كلاس الثيم أبداً وهتفتح بيضاء زي اللوح!

الحل الهندسي: حقن متزامن في موضعين مكملين

في Theme Factory بنحل المعضلة دي بإنشاء منطقتين في الصفحة 0:

معرف المنطقة	موضع القالب المختار	نوع القالب المستهدف	الدور والغرض
`theme_factory_bootstrap`	`#BANNER#`	قوالب الصفحات العادية	يغطي الشاشات والتقارير الرئيسية
`theme_factory_bootstrap_dialog`	`#REGION_POSITION_01#`	قوالب النوافذ المنبثقة	يغطي كل النوافذ المنبثقة والـ Wizards

المنطقتين شايلين نفس كود التمهيد. لما الصفحة ترن:

لو صفحة عادية: موضع #BANNER# بيتنفذ وموضع الحوار بيكون خامل.
لو نافذة منبثقة: موضع #REGION_POSITION_01# بيتنفذ فوراً جوه الـ iframe.

تغطية شاملة بنسبة 100%، وبدون أي وميض أبيض في أي بكسل في التطبيق!

🛡️ طريقة التركيب اليدوي جوه Page Designer

لو عايز تركب الكود ده يدوي جوه شاشة تصميم الصفحات في أوراكل أبيكس:

الخطوة 1: افتح الصفحة رقم 0 (Shared Components -> Global Page).
الخطوة 2: أنشئ منطقة جديدة (Create Region):
         - العنوان: Theme Factory Bootstrap
         - النوع: Static Content
         - القالب: Blank with Attributes (بدون قالب خارجي)
         - موضع التخطيط: Region Position 01 (أو Banner حسب الصفحة)
الخطوة 3: حط كود الـ <script> في مربع Source HTML.
الخطوة 4: في خانة شروط السيرفر (Server-side Condition) كالتالي:
         - خليها None (يعني المنطقة تشتغل دايماً في كل الصفحات).

(ملحوظة: لو بتستخدم أداة التثبيت الآلية بالأوامر اللي هنشرحها في الجزء الرابع، الأداة بتبرمج المنطقتين تلقائياً وبدون أي تدخل يدوي منك!)

⏭️ المقال القادم: ماكينة الحزم المحمولة

دلوقتي عندنا قلعة CSS حصينة، وتمهيد فوري بيقضي على الوميض في أقل من 2 ميلي ثانية. بس السؤال: إزاي نجمع الكلام ده كله في حزمة واحدة يقدر أي مطور يثبتها بضغطة زر في 50 تطبيق في ثواني؟

في الجزء الرابع من السلسلة، هنشرح ماكينة الحزم المحمولة: ملفات ZIP المعزولة، وإدارة خطوط WOFF2 بدون اعتمادات خارجية، وتعديل ملفات APEXLang بضمانات التراجع الذري! 📦🚀

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

قلعة العزل الحصينة: إزاي html.app-theme-* بيقضي على فوضى الـ CSS في Oracle APEX 🏰🛡️

Wed, 04 Nov 2026 00:00:00 GMT

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

قلعة العزل الحصينة: إزاي html.app-theme-* بيقضي على فوضى الـ CSS في Oracle APEX 🏰🛡️

الجزء الثاني من السلسلة التقنية الشاملة: هندسة متغيرات الـ CSS وعزل النطاق في Oracle APEX.

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

تخيل عمارة سكنية فخمة فيها 100 شقة، والمهندس العبقري اللي بناها قرر يوفر تكاليف الأسلاك، فعمل مفتاح كهرباء عمومي واحد كبير في مدخل العمارة تحت! جه الساكن اللي في شقة 4B حب يقرا كتاب الساعة 2 بعد منتصف الليل، فنزل داس على المفتاح العمومي.. وفجأة: أنوار الديسكو ولعت، وخلاطات المطابخ اشتغلت، ورشاشات الحريق رشت مياه على كل السكان في الـ 100 شقة في نفس اللحظة!

دي بالضبط المأساة اللي بتحصل لما تكتب أكواد CSS عامة أو تعدل متغيرات الـ :root في Oracle APEX. بتكون فاكر إنك بتعدل حواف جدول تقارير تفاعلي في شاشة جدول التقارير التفاعلي، فتتفاجئ إنك بوظت ألوان النوافذ المنبثقة (Modal Dialogs) وقوائم التنقل في الشاشة الرئيسية!

في الجزء التاني من سلسلتنا APEX Theme Factory، هنبني قلعة العزل الحصينة. هنتعلم إزاي نبني هيكل متغيرات CSS ثلاثي الطبقات معزول تماماً تحت كلاس html.app-theme-<name>، ونتحكم في أسبقية التنسيق (Specificity) من غير ولا علامة !important واحدة، ونحمي تجربة الاستخدام بحاجز تقليل الحركة، ونتفادى الفخ القاتل اللي بيمسح أيقونات Font APEX ويحولها لمربعات مكسورة. 🚀

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

🏢 كارت الشقة الذكي: ليه الـ CSS العام بيخرب أنظمة الشركات؟

في بيئات عمل أوراكل أبيكس، المطورين كتير بيقعوا في فخ كتابة أكواد زي دي:

/* ❌ مفتاح المدخل العمومي: الكود اللي بيدمر نظامك بالبطيء */
:root {
  --ut-body-background-color: #12151c; /* بيبوظ النوافذ المنبثقة */
}

* {
  font-family: 'Inter', sans-serif !important; /* بيمسح أيقونات Font APEX تماماً */
}

.t-Button {
  border-radius: 9999px !important; /* بيكسر الأزرار الصغيرة ومجموعات الأزرار */
}

أول ما الكود ده يوصل لسيرفر الإنتاج (Production)، بتحصل كوارث فورية:

النوافذ المنبثقة بتبقى غير مقروءة: النافذة بتاخد خلفية داكنة من الـ :root، بس النصوص والأزرار بتفضل بلونها الافتراضي، فتلاقي خطوط بيضاء أو رصاصي فاتح على أسطح رمادية وتختفي القراءة تماماً.
أيقونات Font APEX بتتبخر: لأن النجمة * بتستهدف كل عنصر في الصفحة مع !important، خط الأيقونات بيتغير لخط الكتابة العادي، وتتحول كل أيقونات البحث والحذف لمربعات Unicode فارغة ومكسورة!
كوابيس الترقية: لما أوراكل تنزل إصدار جديد، أكواد !important بتاعتك بتصطدم مع الهيكل الجديد، وتضيع أيام طويلة في ترقيع الشاشات.

تعالوا نشوف إزاي بنهندس قلعة العزل الذكية بدون أي تضارب.

🪜 معمارية التوكنز ثلاثية الطبقات

في Theme Factory بنقسم متغيرات الـ CSS لـ 3 طبقات أساسية ومستقلة:

┌────────────────────────────────────────────────────────┐
│  الطبقة 1: الذرات الأصلية لنمط Iris (--ut-*, --a-*)    │
│  (الأساس المتين والقابل للقراءة من Universal Theme 42) │
└───────────────────────────┬────────────────────────────┘
                            │ يتم تغليفه بواسطة
                            ▼
┌────────────────────────────────────────────────────────┐
│  الطبقة 2: متغيرات التطبيق الدلالية (--app-*)          │
│  (أدوار مجردة: أسطح، نصوص، حواف، إطارات التركيز)      │
└───────────────────────────┬────────────────────────────┘
                            │ يتم استهلاكه بواسطة
                            ▼
┌────────────────────────────────────────────────────────┐
│  الطبقة 3: حزم الثيمات المعزولة (html.app-theme-<name>)│
│  (ألوان محددة: Carbon Volt، Citrus Pop، Linen)         │
└────────────────────────────────────────────────────────┘

1. المتغيرات الأساسية (`foundation/tokens.css`)

في ملف الأساس، بنعلن عن كل أدوار الـ --app-* على مستوى الـ :root عبر ربطها بمتغيرات Iris الأصلية:

/* ملف الأساس: الربط مع قيم Iris الافتراضية */
:root {
  --app-color-primary:     var(--ut-palette-primary);
  --app-surface-page:      var(--ut-body-background-color);
  --app-surface-card:      var(--ut-component-background-color);
  --app-surface-chrome:    var(--ut-header-background-color);
  --app-text-primary:      var(--ut-body-text-color);
  --app-text-secondary:    var(--ut-component-text-muted-color);
  --app-border-color:      var(--ut-component-border-color);
  --app-radius-md:         var(--ut-border-radius-md);
  --app-control-h:         2rem;
  --app-motion-duration:   150ms;
  --app-hover-transform:   translateY(-1px);
}

2. فروقات حزمة الثيم (`sample-themes/carbon-volt/css/tokens.css`)

لما ثيم زي Carbon Volt يشتغل، هو بيغير بس قيم --app-* تحت الكلاس الخاص بيه فقط:

/* حزمة الثيم المعزولة: ثيم Carbon Volt */
html.app-theme-carbon-volt {
  color-scheme: dark;

  /* مساحات وأسطح الشاشات */
  --app-surface-page:      #12151c;
  --app-surface-card:      #1a1e28;
  --app-surface-chrome:    #0d0f14;
  --app-surface-input:     #141720;
  --app-surface-hover:     #222735;
  --app-surface-selected:  #2a3142;

  /* النصوص وألوان التمييز */
  --app-text-primary:      #f0f2f5;
  --app-text-secondary:    #8e96a4;
  --app-color-primary:     #c4f042; /* أخضر ليموني كهربائي */
  --app-color-info:        #00d4ff; /* أزرق سماوي للبيانات */

  /* الحواف والإطارات */
  --app-border-color:      rgba(255, 255, 255, 0.08);
  --app-border-strong:     rgba(255, 255, 255, 0.22);
  --app-radius-sm:         2px;
  --app-radius-md:         4px;
}

لاحظ وجود السطر color-scheme: dark;. السطر ده سحري لأنه بيدي إشارة لمحرك المتصفح إنه يقلب أشرطة التمرير (Scrollbars)، وتحديدات حقول الإدخال، وتقويمات التواريخ للوضع المظلم تلقائياً بدون أي أكواد إضافية.

🎯 إعادة تعيين ذرات Iris الأصلية بدون `!important`

إزاي نخلي مكونات أبيكس القياسية (زي البطاقات والجداول والحاويات) تاخد المتغيرات دي بنعومة ومن غير خناقات الـ !important؟

الثيم الموحد Universal Theme 42 بيعتمد على المتغيرات. لما بنعيد ربط المتغيرات دي على محدد body.apex-theme-iris جوه نطاق الثيم بتاعنا، بنغير القيم الأساسية ونسمح لكلاسات أبيكس الجاهزة (.t-Button--hot, .u-color-1) إنها تفضل شغالة بأولويتها الطبيعية:

/* إعادة توجيه متغيرات مكونات Iris بأمان جوه ثيم Carbon Volt */
html.app-theme-carbon-volt body.apex-theme-iris {
  /* مساحات الحاويات والصفحات */
  --ut-body-background-color:       var(--app-surface-page);
  --ut-component-background-color:  var(--app-surface-card);
  --ut-component-border-color:      var(--app-border-color);
  
  /* ألوان النصوص */
  --ut-body-text-color:             var(--app-text-primary);
  --ut-component-text-title-color:  var(--app-text-primary);
  --ut-component-text-muted-color:  var(--app-text-secondary);

  /* اللون الأساسي وإطار التركيز */
  --ut-palette-primary:             var(--app-color-primary);
  --ut-focus-outline-color:         var(--app-color-primary);
}

♿ درع إمكانية الوصول: حماية تقليل الحركة بأعلى أسبقية تنسيق

في أنظمة الشركات الكبرى، معايير إمكانية الوصول (Accessibility) إلزامية قانونياً وتقنياً. المستخدمين اللي بيعانوا من حساسية الحركة أو مشاكل التوازن ممكن يتعبوا جداً من الحركات والتأثيرات الانتقالية السريعة.

إزاي نجبر كل الثيمات إنها تحترم إعداد تقليل الحركة prefers-reduced-motion من غير ما نعتمد على ضمير مصمم الثيم؟

بنستخدم محدد CSS مضاعف الفئات (:root:root) عشان نضمن أسبقية تنسيق قاطعة:

/* درع الأساس: يتفوق حسابياً على أي كلاس فرعي للثيمات */
@media (prefers-reduced-motion: reduce) {
  :root:root[class*="app-theme-"] {
    --app-motion-duration: 0ms !important;
    --app-hover-transform: none !important;
    --app-hover-shadow:    none !important;
  }
}

لأن كل مكونات Theme Factory بتتحرك حصرياً من خلال المتغيرين --app-motion-duration و --app-hover-transform، السطر ده بيجمد أي حركة في الشاشة فوراً ويحولها لثبات تام ومريح للمستخدم.

🚫 الفخ القاتل: إزاي الخطوط المخصصة بتمسح أيقونات Font APEX؟

أشهر فخ بيقع فيه مطوري أبيكس لما يركبوا خط عربي أو إنجليزي جديد:

/* ❌ مدمر الأيقونات الأوتوماتيكي */
html.app-theme-carbon-volt * {
  font-family: "Noto Kufi Arabic", sans-serif;
}

في أوراكل أبيكس، الأيقونات مش ملفات صور ولا SVG—دي رموز خطية بتعتمد على خط Font APEX من خلال كلاسات زي .fa و .t-Icon. لما بتطبق الخط بالنجمة *، المتصفح بيمسح جدول رموز الأيقونات ويحط مكانه خط النصوص، فتتحول علامة العدسة وسلة المهملات لمربعات بيضاء ممسوحة!

الحل في Theme Factory: تحديد أدوار الخطوط بدقة

بنفصل الخطوط لـ 3 أدوار رئيسية: خط النصوص، وخط العناوين، وخط الأكواد البرمجية:

/* ✅ استهداف آمن للخطوط مع عزل أيقونات Font APEX */
html.app-theme-carbon-volt {
  --app-font-family-body:    "Noto Kufi Arabic", -apple-system, sans-serif;
  --app-font-family-heading: "Noto Kufi Arabic", -apple-system, sans-serif;
  --app-font-family-mono:    "SFMono-Regular", Consolas, monospace;
}

/* تطبيق الخط على عناصر النصوص فقط، وممنوع استخدام النجمة * */
html.app-theme-carbon-volt body {
  font-family: var(--app-font-family-body);
}

html.app-theme-carbon-volt h1,
html.app-theme-carbon-volt h2,
html.app-theme-carbon-volt h3,
html.app-theme-carbon-volt .t-Region-title {
  font-family: var(--app-font-family-heading);
}

/* حماية صريحة لأيقونات أبيكس الرسمية */
html.app-theme-carbon-volt .apex-icons-fontapex,
html.app-theme-carbon-volt .fa,
html.app-theme-carbon-volt .t-Icon {
  font-family: "Font APEX 2.5.1", "FontAPEX" !important;
}

📦 تطبيق عملي: تلوين البطاقات والحقول العائمة

تعالوا نشوف كود واقعي من داخل ثيم Carbon Volt بيوضح إزاي بنلون بطاقات الـ Cards وحقول الإدخال ذات العناوين العائمة (Floating Labels):

/* تلوين بطاقات الـ Cards جوه النطاق المعزول */
html.app-theme-carbon-volt .t-Card {
  background-color: var(--app-surface-card);
  border: 1px solid var(--app-border-color);
  border-radius: var(--app-radius-md);
  transition: transform var(--app-motion-duration) ease,
              box-shadow var(--app-motion-duration) ease;
}

html.app-theme-carbon-volt .t-Card:hover {
  transform: var(--app-hover-transform);
  border-color: var(--app-border-strong);
  box-shadow: 0 8px 24px -8px rgba(0, 0, 0, 0.5);
}

/* ضبط العناوين العائمة لحقول الإدخال عند التنشيط */
html.app-theme-carbon-volt .t-Form-fieldContainer--floatingLabel.is-active .t-Form-label {
  color: var(--app-color-primary);
  background-color: var(--app-surface-card);
}

كل سطر تنسيق بيبدأ صراحة بـ html.app-theme-carbon-volt. لو المستخدم حب يغير الثيم أو يرجع للشكل الافتراضي، كل الأسطر دي بتصبح غير فعالة وكأنها غير موجودة بالمرة!

⏭️ المقال القادم: القضاء على الوميض الأبيض المزعج!

دلوقتي ملفات الـ CSS بتاعتنا بقت محصنة جوه قلعة منيعة. بس بيظهر تحدي جديد وخطير: المتصفح إمتى هيضيف الكلاس ده على الصفحة؟

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

في الجزء الثالث من السلسلة، هنكشف سر الوميض الصفري: إزاي سطر كود بسيط ومتزامن في Page 0 بيغير شكل الصفحة في أقل من 2 ميلي ثانية قبل ما ستارة المسرح تفتح! تابعوا معانا! 🚀

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

بدلة الحرباء: ليه تخصيص الثيمات التقليدي في Oracle APEX بيحبسك؟ (وإزاي تفلت منه) 🦎👔

Tue, 03 Nov 2026 00:00:00 GMT

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

بدلة الحرباء: ليه تخصيص الثيمات التقليدي في Oracle APEX بيحبسك؟ (وإزاي تفلت منه) 🦎👔

الجزء الأول من السلسلة التقنية الشاملة: بناء وإدارة أنظمة التصميم المتقدمة في Oracle APEX.

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

تخيل رحت اشتريت بدلة توكسيدو إيطالي فاخرة بـ 3,000 دولار. أول يوم في الفرح شكلها يجنن ومضبوطة بالمللي. بس المفاجأة إن الترزي بعد ما لبسهالك، راح لاحم الجاكيت والصديري والبنطلون في جلد جسمك بـ “سوبر جلو” حديدي دائم!

حبيت تروح تجري على البحر الصبح؟ هتجري بالتوكسيدو. نزلت تغير زيت عربيتك في ورشة الحرفيين؟ هتغير الزيت بالتوكسيدو والبيبيون. معزوم على شواء في عز أغسطس؟ مبروك عليك صوف صامد في حرارة 42 درجة مئوية!

ده بالضبط اللي بيحصل لما تقرر تعدل وتعمل تخصيص لمظهر تطبيقاتك في Oracle APEX باستخدام أداة Theme Roller التقليدية. بتلاقي نفسك حابس كل الشاشات، وكل المستخدمين، وكل النوافذ المنبثقة (Modal Dialogs) جوه ملف CSS ضخم ملحوم في التطبيق للأبد.

في أول مقال من سلسلتنا الجديدة APEX Theme Factory، هنكسر قيد “البدلة الملحومة”. هنتعلم إزاي نحول الثيمات من مجرد وشم دائم ملوش حل لـ بدلة فضاء معيارية سريعة التبديل مبنية فوق Universal Theme 42 بنمط Iris—بدون تعديل سطر كود واحد، وبدون ما نكسر اشتراك الثيم الأصلي، ومع إمكانية التراجع الكامل بضغطة زر واحدة. 🚀

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

🦎 فزورة الحرباء: حكاية دولابين ملابس

كل مطور في بيئات الشركات بيصطدم في مرحلة ما بـ “فخ دولاب الملابس”:

┌────────────────────────────────────────┐       ┌────────────────────────────────────────┐
│      التخصيص التقليدي في أبيكس         │       │          محرك APEX Theme Factory       │
│         (البدلة الملحومة بالأمير)      │       │        (بدلة الفضاء المعيارية)         │
├────────────────────────────────────────┤       ├────────────────────────────────────────┤
│ • ملف CSS متضخم جوه Theme Roller       │       │ • حزم معزولة بنطاق محدد على <html>     │
│ • تلوث عشوائي لعناصر :root عالمياً     │       │ • متغيرات تصميم مخصصة (--app-*)        │
│ • شكل واحد إجباري لكل المستخدمين       │       │ • تبديل فوري لكل مستخدم وجهاز          │
│ • رعب من كسر اشتراك Universal Theme    │       │ • احتفاظ كامل باشتراك الثيم 42         │
│ • الحذف محتاج دعاء وستر ربنا           │       │ • تجربة جافة (Dry-Run) وحذف ذري آمن    │
└────────────────────────────────────────┘       └────────────────────────────────────────┘

في الواقع العملي للشركات، مستخدمين نظامك مش شغالين في نفس الظروف:

مشرف المخازن في الوردية الليلية: محتاج نمط مظلم فائق التباين (Dark Mode) عشان شاشات التابلت ماتعميش عينيه في عتمة المستودع.
محاسب التكاليف والمراجعة: محتاج واجهة ناصعة وهادية شبه الورق (Linen)، مع خطوط جداول دقيقة تسهل مطابقة آلاف الفواتير في شاشات التقارير التفاعلية (Interactive Grids).
الإدارة التنفيذية ومجلس الإدارة: محتاجين واجهة كحلي مع بطاقات مؤشرات أداء لامعة (Telemetry Cards) تناسب شاشات العرض الكبيرة في غرف الاجتماعات.

تاريخياً، عشان تعمل كده في أوراكل أبيكس كنت بتضطر تعمل كذا نسخة من نفس التطبيق، أو تحشر تعديلات CSS بتعمل تضارب عنيف مع كل ترقية جديدة لنظام أبيكس.

🪤 الأفخاخ التلاتة في تلوين أبيكس التقليدي

1. كتلة الـ Theme Roller الصامتة

أداة Theme Roller لما بتغير فيها ألوان أو حواف بيتم تجميع ملف CSS ضخم وربطه بالتطبيق. ولو حبيت تعمل تعديل إضافي، بتضطر تفتح صندوق الـ Custom CSS وتحط أكوادك هناك.

في ظرف شهور، الصندوق ده بيتحول لـ “مقبرة برمجية” فيها أكتر من 2,000 سطر مليانين علامات !important، ومحددات عناصر قديمة، وألوان Hex صلبة. وأول ما أوراكل تنزل ترقية جديدة لأبيكس، المحددات دي بتفرقع وتخرب تنسيق الأزرار والقوائم.

2. معضلة اشتراك الـ Universal Theme 42

الثيم الموحد Universal Theme 42 هو أحد أعظم مزايا أوراكل أبيكس. الاشتراك فيه (Subscription) بيضمن إن شاشاتك تاخد أحدث تحسينات الأمان، وسرعة الأداء، وإمكانية الوصول لمتحدي الإعاقة (Accessibility - a11y) مع كل تحديث جديد.

لكن المطور اللي بيحاول يغير القوالب (Templates) بنفسه بيكسر الاشتراك ده فجأة، وساعتها بيبقى معزول في جزيرة فنية لوحده ومضطر يصين كل قوالب الـ HTML والـ JavaScript بإيديه.

3. صدمة نمط Iris في APEX 26.1

مع إصدار Oracle APEX 26.1، ظهر النمط الأحدث Iris. نمط متطور جداً وجديد هندسياً، وبيعتمد على مئات المتغيرات البرمجية من الـ CSS Tokens كالتالي:

أكتر من 1,000 ذرة داخلية للمكونات (--a-*).
أكتر من 400 توكن أساسي لألوان ومسافات الثيم (--ut-*).
أكتر من 100 توكن للأدوات المساعدة (--u-*).

/* قراءة المتغيرات البرمجية المباشرة من نمط Iris في APEX 26.1 */
:root {
  --ut-color-scheme: light;
  --ut-palette-primary: #00688c;
  --ut-body-background-color: #fbf9f8;
  --ut-component-background-color: #fff;
  --a-base-font-weight-semibold: 500;
}

المفاجأة هنا إن Iris بينزل بنمط فاتح فقط (Light-Only)!

مفيش أي سطر للنمط المظلم (Dark Mode) جوه ملف Iris.min.css. ولو حاولت تعمل ثيم مظلم عبر تغيير --ut-body-background-color على مستوى الـ :root، هتلاقي النوافذ المنبثقة وشاشات الـ Popup LOV باظت وبقى الكلام فيها غير مقروء تماماً!

🛡️ الحل: محرك APEX Theme Factory

فكرة APEX Theme Factory بتعتمد على فلسفة هندسية بسيطة ولكنها عبقرية: بدل ما تلمس الـ Theme Roller أو تبوظ جداول قاعدة البيانات، إحنا بنعامل الثيمات كـ حزم برمجية مستقلة ومحمولة (Portable Packages):

sample-themes/carbon-volt/
├── theme.json          # مواصفات الحزمة والمعلومات الأساسية
├── theme.recipe.json   # وصفة التصميم وقواعد القياسات التفاعلية
├── css/
│   ├── theme.css       # نقطة الدخول المعزولة
│   ├── tokens.css      # خرائط المتغيرات المخصصة
│   └── apex/           # قواعد المكونات (العناوين، الحقول، النوافذ)
├── fonts/              # خطوط WOFF2 ذاتية الاستضافة بالكامل
└── preview/cover.jpg   # صورة المعاينة بدقة 960 بكسل

الأركان الأربعة للهيكل المعماري الجديد:

عزل النطاق الصارم (html.app-theme-<name>): الثيم مش بيشتغل إلا لما الكلاس الخاص بيه يتضاف على مستوى جذر الصفحة (<html>). لو شلت الكلاس، التطبيق بيرجع لـ Iris الأصلي 100% في نفس اللحظة بدون أي شوائب في ملفات الـ CSS العامة.
التمهيد الفوري بدون وميض (Zero-Flicker Pre-Paint Bootstrap): بدل ما نستنى الصفحة تخلص تحميل وبعدين ننادي كود JavaScript يغير الألوان فيحصل وميض أبيض يخطف العين، بنحط سطر تمهيد متزامن في Page 0 بيقرا التفضيل ويحط كلاس الثيم في أقل من 2 ميلي ثانية قبل ما المتصفح يرسم أول بكسل على الشاشة.
حزم ذاتية الاحتواء بدون اعتماد على سيرفرات خارجية: كل ثيم بيطلع في ملف ZIP مقفول تماماً. جواه خطوط الـ WOFF2 الخاصة بيه، فمفيش أي طلبات بتروح لـ Google Fonts أو CDNs خارجية. وتقدر تثبته أو تحذفه بأمر سطر أوامر آمن، أو من خلال 3 خطوات يدوية جوه Page Designer لو معندكش صلاحيات شل.
حماية اشتراك الـ Universal Theme 42 بنسبة 100%: لأن الشغل كله بيتم على طبقة الـ CSS و Page 0 فقط، تطبيقك بيفضل محتفظ باشتراكه الرسمي في Universal Theme بدون أي مساس.

🎨 استكشف الثيمات التمانية الجاهزة في المشروع

المشروع بييجي مع 8 ثيمات جاهزة ومجربة إنتاجياً بتغطي كل الأذواق الهندسية:

اسم حزمة الثيم	الاتجاه الفني	خطوط الطباعة	طبيعة السطح والتباين
Carbon Volt	جرافيت تقني داكن مع لمسات ليموني فسفوري وسماوي	Noto Kufi / Mono	داكن عالي التباين (`#12151c`)
Citrus Pop	مساحات مائية مبهجة مع بطاقات عائمة ولمسات برتقالي يوسفي	Tajawal	فاتح منعش (`#f0fbf9`)
Cobalt Press	ملمس ورق صحفي دافئ مع خطوط كحلي كلاسيكية وعناوين قرمزية	Cairo	فاتح هادئ (`#faf8f5`)
Estate Slate	رمادي مؤسسي دقيق للأعمال الإدارية مع لمسات كهرمانية خافتة	IBM Plex Sans Arabic	فاتح دقيق (`#f8f9fa`)
Estate Slate Dark	رمادي صخري مظلم للأنظمة الحساسة مع لمسات زمردية باردة	IBM Plex Sans Arabic	داكن مؤسسي (`#161a22`)
Linen	بساطة مطلقة مع إطارات فائقة النعومة وتناسق تام مع منتجات أبل	System UI / Iris	فاتح ناصع (`#ffffff`)
Solarized Dark	عمق تقني مستوحى من شاشات الـ Terminal الاحترافية	IBM Plex Mono	داكن مريح للعين (`#002b36`)
Velvet Signal	أسطح باذنجانية فاخرة مع حواف دائرية وإشارات بنفسجية متوهجة	Alexandria	داكن عصري (`#1b1622`)

🛠️ خطتنا في المقالات القادمة

في المقالات الخمسة الجاية من السلسلة دي، هنفكك كل جزء في المحرك ده بالتفصيل العملي:

الجزء الثاني (المقال الثاني): قلعة عزل الـ CSS — إزاي نتحكم في متغيرات --app-* ونتفادى كارثة مسح أيقونات Font APEX.
الجزء الثالث (المقال الثالث): سر الوميض الصفري — إزاي بنمنع الوميض الأبيض المزعج من خلال حقن كود سريع في Page 0.
الجزء الرابع (المقال الرابع): ماكينة الحزم المحمولة — أرشفة ملفات الـ ZIP، وحقن قوالب الـ APEXLang مع أمان التراجع التلقائي.
الجزء الخامس (المقال الخامس): بناء أداة تبديل الثيمات المخصصة — اعتراض قائمة Navigation Bar، والتعامل مع روابط Hash في الـ Friendly URLs، وربط مكونات Alpine.js.
الجزء السادس (مسك الختام): حفظ الثيمات على مستوى المؤسسة — ربط تفضيلات المستخدم مع قاعدة البيانات (:APP_USER) واستدعاءات Ajax المباشرة.

جاهز تقلع بدلة التوكسيدو الملحومة وتلبس بدلة فضاء خارقة سريعة التبديل؟ نتقابل في المقال الجاي عشان نبني قلعة الـ CSS الحصينة! 🚀

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

حملة تنظيف الربيع في APEX 26.1: أرشفة المهام التاريخية بدون كسر التدقيق 🗄️🧹

Mon, 26 Oct 2026 00:00:00 GMT

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

حملة تنظيف الربيع في APEX 26.1 — أرشفة المهام التاريخية بدون كسر التدقيق 🗄️🧹

الجزء السابع (مسك الختام) من سلسلة “إدارة الـ Workflows الضخمة في أوراكل أبيكس”.

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

لو فضلت محتفظ بكل فاتورة كهرباء، وكل إيصال فيزا، وكل إقرار ضريبي من آخر 12 سنة متكومين جوه درج مكتبك اللي بتفتحه كل يوم، في الآخر مش هتعرف تشد الدرج 2 سم عشان تطلع قلم تكتب بيه!

في ختام السلسلة دي، هنتعلم إزاي ندمج الـ Human Task Archiving APIs الجديدة في Oracle APEX 26.1 مع استراتيجيات تقسيم الجداول الشهرية (Interval Range Partitioning) في قاعدة بيانات أوراكل.

ده بيحافظ على جداول التشغيل اليومية خفيفة، وصاروخية، ومضغوطة الحجم—وفي نفس الوقت بيضمن إن سجلات التدقيق التاريخية تفضل متاحة 100% لمفتشي الامتثال والرقابة القانونية للشركة.

🗄️ درج المكتب الشغال ضد الخزنة المحصنة المكيفة

كل نظام Workflows وموافقات في الشركات بيصطدم في النهاية بـ قانون تراكم البيانات (Law of Data Accumulation):

السنة الأولى (مرحلة العسل): النظام بتاعك بيدير 500 مهمة وموافقة نشطة بس. الجداول صغيرة جداً، وفهارس الـ B-Tree كلها مرتاحة جوه رامات الداتابيز (Buffer Cache)، وكل استعلام بيفتح في أقل من 10 ميلي ثانية.
السنة الثالثة (مرحلة الغرز في الطين): شركتك نفذت أكتر من 3,500,000 مسار عمل منتهي. الجداول بقى حجمها 45 جيجابايت! صيانة الفهارس مع كل عملية Insert بدأت تسبب بطء ملحوظ في الـ I/O، والنسخ الاحتياطي اليومي بقى يمتد لبعد الفجر، وبحث المدراء في الشاشات بقى يجر الداتابيز كلها لتحت!

ليه مستحيل تقول “يا عم نشغل أمر `DELETE` وخلاص”؟!

في أنظمة الشركات الكبرى، مينفعش تدخل تضرب DELETE FROM wf_requests WHERE status = 'COMPLETED':

المتطلبات القانونية والضريبية: مصلحة الضرائب، ومفتشو الأيزو، والرقابة المالية بيلزموا الشركات بالاحتفاظ بسجلات الموافقات وتفاصيل القرارات لمدد من 7 لـ 10 سنين!
نزاهة التدقيق والمراجعة (Audit Integrity): كل كومنت، وكل توقيع إلكتروني، وكل تاريخ تفويض لازم يفضل موجود ومحفوظ بحالته الأصلية.

الحل مش الحذف؛ الحل هو أرشفة دورة الحياة (Lifecycle Archival). جداول التشغيل اليومية تشيل بس الشغل الحي، والأرشيف التاريخي يروح لخزنة الأرشيف المحمية.

✨ إيه الجديد في أرشفة Oracle APEX 26.1؟

بداية من إصدار Oracle APEX 26.1، أوراكل أدركت عنق الزجاجة ده وقدمت دوال رسمية ومدمجة لإدارة دورة حياة الـ Human Tasks والـ Workflows كالآتي:

apex_task.archive
apex_workflow.archive

-- تشغيل الأرشفة البرمجية في APEX 26.1
begin
    apex_task.archive (
        p_task_id      => 108429,
        p_archive_type => apex_task.c_archive_completed
    );
end;
/

المزايا اللي بتقدمها أرشفة APEX 26.1 الرسمية:

النقل لمخزن الأرشيف البارد (Cold Storage): بتنقل المهام المقفولة برة طوابير التشغيل النشطة لمخازن أرشيف داخلية معزولة.
Views مخصصة للأرشيف التاريخي: المهام المؤرشفة بتفضل متاحة للاستعلام عبر APEX_TASK_ARCHIVE و APEX_WORKFLOW_ARCHIVE. شاشات التقارير التاريخية تقدر تستعلم منها براحتها بدون ما تلمس شاشة المهام النشطة أو تأثر على سرعتها!
استعادة رشاقة الفهارس: الفهارس النشطة على جداول أبيكس بترجع صغيرة وخفيفة وشايلة بس الطلبات المفتوحة.

🏗️ على مستوى الداتابيز: التقسيم الشهري الآلي (Interval Partitioning)

لسجلات العمليات الكبيرة (زي جدول app_data.wf_task_event_log)، بندمج أرشفة أبيكس مع تقسيم الجداول الشهري الآلي في أوراكل:

-- ====================================================================
-- جدول: app_data.wf_task_event_log (مقسم شهرياً بالـ Interval)
-- ====================================================================

create table app_data.wf_task_event_log (
    event_id         number generated always as identity,
    request_id       number not null,
    task_id          number,
    action_type      varchar2(50) not null,
    previous_status  varchar2(50),
    new_status       varchar2(50) not null,
    action_user      varchar2(100) not null,
    action_comments  varchar2(4000),
    event_timestamp  timestamp with local time zone default current_timestamp not null
)
partition by range (event_timestamp) 
interval (numtoyminterval(1, 'month')) (
    partition p_initial values less than (timestamp '2025-01-01 00:00:00')
);

-- فهارس محلية معزولة لكل بارتشن
create index app_data.wf_task_event_req_lidx 
    on app_data.wf_task_event_log(request_id) local;

🚀 القوى الخارقة لتقسيم الـ Interval Partitioning

ليه التقسيم ده يعتبر سلاح سري في قواعد بيانات المؤسسات؟

1. ضغط البارتشنات القديمة بدون أي توقف (Zero-Downtime Compression)

في نهاية كل ربع سنة، سكربت صيانة آلي يقدر يضغط شهور السنة اللي فاتت اللي محدش بيعدل فيها:

-- ضغط بارتشن قديم لتوفير لحد 80% من مساحة الهارد ديسك
alter table app_data.wf_task_event_log 
    move partition sys_p12849 compress for oltp;

ده بيوفر مساحات هائلة في الهارد ديسك وفي نفس الوقت الداتا بتفضل مقروءة ومتاحة بالكامل للمراجعين!

2. حذف البارتشن المنتهي في أقل من 100 ميلي ثانية

لما البيانات التاريخية تخلص مدتها القانونية (مثلاً بعد مرور 7 سنين)، مش بتشغل أمر DELETE عملاق يولد جيجابايت من ملفات الـ Redo والـ Undo.

أنت بتطير البارتشن بالكامل في أقل من 100 ميلي ثانية:

alter table app_data.wf_task_event_log drop partition sys_p00481;

🤖 حزمة الصيانة التلقائية: `pkg_wf_maintenance`

دي Package صيانة احترافية ومجدولة تشتغل يوم 1 في كل شهر عبر DBMS_SCHEDULER:

create or replace package app_code.pkg_wf_maintenance as
    procedure archive_closed_tasks(p_days_old in number default 30);
end pkg_wf_maintenance;
/

create or replace package body app_code.pkg_wf_maintenance as

    procedure archive_closed_tasks(p_days_old in number default 30) is
        cursor c_expired_tasks is
            select task_id
              from apex_tasks
             where state in ('COMPLETED', 'CANCELED', 'TERMINATED')
               and completed_on < trunc(sysdate) - p_days_old;
               
        type t_id_list is table of apex_tasks.task_id%type;
        v_ids t_id_list;
        v_archived_cnt number := 0;
    begin
        open c_expired_tasks;
        loop
            fetch c_expired_tasks bulk collect into v_ids limit 500;
            exit when v_ids.count = 0;

            for i in 1 .. v_ids.count loop
                begin
                    -- استدعاء دالة الأرشفة الرسمية في APEX 26.1
                    apex_task.archive(
                        p_task_id      => v_ids(i),
                        p_archive_type => apex_task.c_archive_completed
                    );
                    v_archived_cnt := v_archived_cnt + 1;
                exception
                    when others then
                        null; -- تسجيل الخطأ والاستمرار في باقي المهام
                end;
            end loop;
            
            commit;
        end loop;
        close c_expired_tasks;

        dbms_output.put_line('تمت أرشفة ' || v_archived_cnt || ' مهمة بنجاح.');
    end archive_closed_tasks;

end pkg_wf_maintenance;
/

🏁 مسك الختام: الأعمدة السبعة لإدارة الـ Workflows الضخمة

على مدار السلسلة دي المكونة من 7 أجزاء، حولنا نظام موافقات تقيل ومخنوق لمنظومة مؤسسية صاروخية تنافس كبرى البنوك والشركات العالمية:

معمارية الـ APEX Workflows عالية الأداء:
┌────────────────────────────────────────────────────────────┐
│ 7. أرشفة دورة الحياة والتقسيم الشهري (APEX 26.1 + أوراكل) │  ← توسع مستدام للأبد
├────────────────────────────────────────────────────────────┤
│ 6. الاعتماد الجماعي بضغطة واحدة (Savepoints في الـ Grid)   │  ← سرعة قياسية للمدراء
├────────────────────────────────────────────────────────────┤
│ 5. شاشة الحرباء الذكية (أشرطة أدوات ديناميكية بـ PL/SQL)    │  ← صفحة تفاصيل واحدة
├────────────────────────────────────────────────────────────┤
│ 4. تخزين الأكشنز في الميتاداتا (جدول wf_action_config)     │  ← صفر زراير ثابتة
├────────────────────────────────────────────────────────────┤
│ 3. التزامن الفوري بالأحداث (تريجرات خفيفة بدون كرون)      │  ← لحظي بدون تأخير
├────────────────────────────────────────────────────────────┤
│ 2. كاش بونات المطبخ السريع (جدول wf_task_cache)            │  ← استعلامات تحت 50ms
├────────────────────────────────────────────────────────────┤
│ 1. فك الارتباط المعماري عن استعلامات APEX_TASKS الجاهزة    │  ← حل زحمة الـ 30k
└────────────────────────────────────────────────────────────┘

كشفنا سر زحمة الـ 30 ألف مهمة: وعرفنا ليه الاستعلام المباشر من APEX_TASKS بيخنق الداتابيز في الشركات.
بنينا حامل بونات المطبخ: جدول wf_task_cache اللي حول استعلامات الـ 15 ثانية لبحث فهارس في 20 ميلي ثانية.
زامنّا الكاش في اللحظة نفسها: بتريجرات خفيفة قضت على لاج الـ Polling بدون أي قفل للجداول.
ودعنا رص الزراير الثابتة: ونقلنا تعريفات الأكشنز لجدول ميتاداتا مرن وشيك (wf_action_config).
صممنا شاشة الحرباء: صفحة تفاصيل واحدة بتتلون وتتكيف مع صلاحيات كل موظف على الطاير.
فعلنا الاعتماد الجماعي بضغطة واحدة: مكنّا المدراء من اعتماد 50 طلب في ثانيتين بحماية الـ Savepoints.
أتقنا الأرشفة المستدامة: بدمج ميزات APEX 26.1 مع تقسيم الجداول الشهري عشان يفضل أداء النظام طيارة لسنين قدام!

مبروك عليك امتلاك المعمارية دي كاملة، وبرمجة ممتعة وناجحة للجميع! 🚀🎉✨

كتبه: أحمد شريف (Ahmed Sherif).

الختم السريع: الاعتماد الجماعي بضغطة واحدة جوه الـ Interactive Grid 📑🖊️

Thu, 22 Oct 2026 00:00:00 GMT

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

الختم السريع: الاعتماد الجماعي بضغطة واحدة جوه الـ Interactive Grid 📑🖊️

الجزء السادس من سلسلة “إدارة الـ Workflows الضخمة في أوراكل أبيكس”.

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

لو اديت مدير تنفيذي كبير قلم حبر جاف، وطلبت منه يقرا ويمضي 50 طلب شراء روتيني بسيط واحد ورا التاني، هيمضي أول أربعة، يجيله تليفون مهم، ويسيب الـ 46 التانيين مركونين في مكتبه لمدة أسبوعين!

بتزويد شاشة الـ Interactive Grid في Oracle APEX بروتين معالجة جماعي سريع (pkg_workflow_actions.ig_batch_action)، المدراء يقدروا يحددوا الـ 50 سطر بالـ Checkbox، ويدوسوا “اعتماد المحدد”، والـ 50 طلب يتنفذوا كلهم في ثانيتين اتنين بس!

هنا هنتعلم إزاي نبني محرك موافقات جماعية صلب ومحمي بـ Savepoints على مستوى كل سطر، وبـ حماية القفل التفاؤلي (Optimistic Locking) عشان لو سطر واحد فشل، ميبوظش باقي الدفعة كلها.

🖋️ قلم الحبر البطيء ضد ختم المصنع السريع

لما نيجي نصمم مسارات الموافقات في أبيكس، تفكيرنا التلقائي بيروح لشاشة تفاصيل الطلب المفردة. للقرارات الضخمة—زي شراء أصل رأسمالي بـ 250 ألف دولار—شاشة التفاصيل الكاملة إلزامية ومهمة جداً.

لكن في أي شركة كبيرة، 80% من حجم الشغل اليومي عبارة عن طلبات روتينية ومخاطرها شبه منعدمة:

طلبات شراء أدوات مكتبية بسيطة تحت 100 دولار.
اعتمادات صيانة دورية مجدولة.
بدلات سفر وإقامة متراجعة ومرفق فواتيرها مسبقاً.

قارن بين التجربتين:

تجربة قلم الحبر (الاعتماد الفردي صفحة بصفحة): افتح الطلب $\rightarrow$ استنى ثانيتين $\rightarrow$ انزل لتحت $\rightarrow$ دوس موافق $\rightarrow$ أكد الرسالة $\rightarrow$ ارجع للشاشة الرئيسية $\rightarrow$ كرر نفس المأساة 50 مرة!
الوقت المستغرق: من 12 لـ 15 دقيقة من الضغطات المتكررة وتحميل الصفحات والإرهاق الذهني.
تجربة ختم المصنع (الاعتماد الجماعي السريع): فلتر الـ Grid على “مشتريات دورية” $\rightarrow$ دوس “تحديد الكل” $\rightarrow$ دوس “اعتماد المحدد”.
الوقت المستغرق: أقل من 5 ثواني!

🛑 معضلة “الحبة المسمومة” في المعالجة الجماعية (The Poison Pill)

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

تخيل مدير علم على 50 طلب وداس “اعتماد الكل”:

الطلبات من 1 لـ 24 اعتمدت بسلام.
الطلب رقم 25 ضرب إيرور لأن ميزانية القسم ده خلصت من 10 دقايق.
في كود PL/SQL عادي مفهوش عزل للأخطاء، الإيرور غير المعالج على سطر 25 هيعمل Rollback لـ المعاملة كلها بالكامل! الـ 50 طلب هيفضلوا معلقين ومفيش حاجة هتعتمد!

المدير هيتجنن: “هو إيه اللي اتوافق عليه وإيه اللي فشل؟! ليه مفيش حاجة اتغيرت؟!”

عشان نحل المأساة دي، محركنا بيستخدم نقاط الحفظ الفردية (Row-Level Savepoints):

savepoint sp_single_record;

لو السطر رقم 25 فشل، بنعمل تراجع فقط لنقطة حفظ السطر ده لوحده، ونسجل سبب الفشل في اللوج، ونكمل عادي جداً وبدون أي توقف في معالجة السطور من 26 لـ 50!

⚙️ محرك المعالجة الخلفي: `pkg_workflow_actions.ig_batch_action`

ده كود الـ Package الاحترافي في سكيما البرمجة (app_code) كالآتي:

create or replace package app_code.pkg_workflow_actions as
    procedure ig_batch_action(
        p_request_ids in apex_t_varchar2,
        p_action_type in varchar2, -- 'APPROVE', 'REJECT'
        p_comments    in varchar2 default null,
        o_success_cnt out number,
        o_failure_cnt out number,
        o_error_log   out apex_t_varchar2
    );
end pkg_workflow_actions;
/

create or replace package body app_code.pkg_workflow_actions as

    procedure ig_batch_action(
        p_request_ids in apex_t_varchar2,
        p_action_type in varchar2,
        p_comments    in varchar2 default null,
        o_success_cnt out number,
        o_failure_cnt out number,
        o_error_log   out apex_t_varchar2
    ) is
        v_req_id     number;
        v_curr_user  varchar2(100) := coalesce(sys_context('APEX$SESSION','APP_USER'), user);
    begin
        o_success_cnt := 0;
        o_failure_cnt := 0;
        o_error_log   := apex_t_varchar2();

        for i in 1 .. p_request_ids.count loop
            v_req_id := to_number(p_request_ids(i));

            -- 1. نقطة حفظ معزولة لكل سطر منفرد
            savepoint sp_single_record;

            begin
                -- 2. فحص القفل التفاؤلي والتزامن (Lock Row Nowait)
                declare
                    v_status varchar2(50);
                begin
                    select status
                      into v_status
                      from app_data.wf_requests
                     where request_id = v_req_id
                       for update of status nowait;

                    if v_status != 'PENDING' then
                        raise_application_error(-20010, 'الطلب لم يعد معلقاً للمراجعة.');
                    end if;
                end;

                -- 3. تنفيذ التعديل ونقل الحالة
                update app_data.wf_requests
                   set status      = case p_action_type when 'APPROVE' then 'APPROVED' else 'REJECTED' end,
                       resolved_by = v_curr_user,
                       resolved_at = current_timestamp
                 where request_id = v_req_id;

                -- 4. تسجيل الحدث في سجل التدقيق (بيشغل تزامن الكاش تلقائياً)
                insert into app_data.wf_task_event_log (
                    request_id,
                    action_type,
                    previous_status,
                    new_status,
                    action_user,
                    action_comments
                ) values (
                    v_req_id,
                    p_action_type,
                    'PENDING',
                    case p_action_type when 'APPROVE' then 'APPROVED' else 'REJECTED' end,
                    v_curr_user,
                    p_comments
                );

                o_success_cnt := o_success_cnt + 1;

            exception
                when others then
                    -- 5. تراجع فقط للسطر ده بالذات!
                    rollback to sp_single_record;
                    o_failure_cnt := o_failure_cnt + 1;
                    apex_string.push(o_error_log, 'طلب رقم #' || v_req_id || ': ' || sqlerrm);
            end;
        end loop;
    end ig_batch_action;

end pkg_workflow_actions;
/

🖥️ ربط الـ Interactive Grid في شاشة APEX

عشان تشغل ده جوه الـ Interactive Grid كالآتي:

1. تفعيل اختيار السطور المتعددة

في خصائص الـ Interactive Grid كالآتي:

Row Selection: Multiple
Selection Checkbox: Enabled

في إعدادات الـ Grid: Attributes $\rightarrow$ Advanced $\rightarrow$ JavaScript Initialization Code:

function(config) {
    let $ = apex.jQuery;
    let toolbarData = $.apex.interactiveGrid.copyDefaultToolbar();
    let actionsGroup = toolbarData.toolbarFind("actions1");

    actionsGroup.controls.push({
        type: "BUTTON",
        id: "btn_batch_approve",
        label: "اعتماد المحدد",
        icon: "fa fa-check",
        hot: true,
        action: "batch-approve"
    });

    config.toolbarData = toolbarData;

    config.initActions = function(actions) {
        actions.add({
            name: "batch-approve",
            action: function(event, focusElement) {
                let grid = apex.region("tasks_ig").widget().interactiveGrid("getViews").grid;
                let selectedRecords = grid.getSelectedRecords();
                
                if (selectedRecords.length === 0) {
                    apex.message.alert("برجاء اختيار طلب واحد على الأقل للاعتماد.");
                    return;
                }

                let model = grid.model;
                let requestIds = [];
                for (let i = 0; i < selectedRecords.length; i++) {
                    requestIds.push(model.getValue(selectedRecords[i], "REQUEST_ID"));
                }

                apex.message.confirm(
                    "هل أنت متأكد من اعتماد جميع الطلبات المحددة (" + requestIds.length + " طلب)؟",
                    function(okPressed) {
                        if (okPressed) {
                            apex.server.process(
                                "PROCESS_BATCH_APPROVAL",
                                {
                                    f01: requestIds,
                                    x01: "APPROVE"
                                },
                                {
                                    success: function(data) {
                                        apex.message.showPageSuccess(
                                            "تمت العملية: تم اعتماد " + data.success_count + " بنجاح، وفشل " + 
                                            data.failure_count + "."
                                        );
                                        apex.region("tasks_ig").refresh();
                                    }
                                }
                            );
                        }
                    }
                );
            }
        });
    };

    return config;
}

🔒 صمامين الأمان ضد التضارب والتزامن

لاحظ صمامي الأمان اللي جوه كود الـ PL/SQL هنا:

for update nowait: لو فيه مدير تاني (أو سكالر آلي) بيعدل في طلب رقم 14 في نفس اللحظة، أوراكل هترمي خطأ فوري بدل ما تعلق الجلسة في الانتظار. المعالج هيلقط الخطأ، ويكتب “الطلب 14 مشغول حالياً بعملية أخرى”، ويكمل في باقي الطلبات.
التحقق من حالة الطلب الحالية: قبل ما ينفذ الاعتماد، الكود بيتأكد إن status = 'PENDING'. لو حد اعتمده قبله بثانيتين، السطر بيتفوت بأمان وبدون أي تكرار.

🧹 إيه اللي مستنينا في مسك الختام (الجزء السابع)؟

نظام الـ Workflows بتاعك في أبيكس دلوقتي طيارة وصاروخي: الكويريز بتفتح في 20 ميلي ثانية، والشاشات بتتأقلم ديناميكياً، والمدراء يقدروا يوافقوا على 50 طلب في ضغطة واحدة.

قدم الشريط 18 شهر لقدام في المستقبل.. شركتك نفذت أكتر من 2,500,000 مسار عمل منتهي.

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

في ختام السلسلة، الجزء السابع (“حملة تنظيف الربيع في APEX 26.1 — أرشفة المهام التاريخية بدون كسر التدقيق”)، هنتعلم أسرار الـ Archiving APIs الجديدة في APEX 26.1 واستراتيجيات تقسيم الجداول (Table Partitioning)!

نشوفكم في الحلقة الأخيرة الكبيرة! 🗄️🧹✨

كتبه: أحمد شريف (Ahmed Sherif).

شاشة الحرباء: الرسم الديناميكي لأشرطة الأكشنز في Oracle APEX 🦎🎚️

Sun, 18 Oct 2026 00:00:00 GMT

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

شاشة الحرباء: الرسم الديناميكي لأشرطة الأكشنز في Oracle APEX 🦎🎚️

الجزء الخامس من سلسلة “إدارة الـ Workflows الضخمة في أوراكل أبيكس”.

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

تخيل لوحة مفاتيح لخزنة إلكترونية فائقة الأمان، الأرقام والزراير فيها مبتنورش ومبتظهرش أصلاً إلا لو كارت الأمان بتاعك معاه الصلاحية إنه يدوس عليها! بالنسبة لأي شخص مش مصرح له، الزراير كأنها مش موجودة في الكون أصلاً!

في الدليل ده، هنربط جدول الميتاداتا الوصفي بتاعنا (wf_action_config) مع مصفوفة صلاحيات المستخدمين (wf_user_permissions) جوه منطقة PL/SQL Dynamic Content واحدة على صفحة تفاصيل الطلب في أبيكس.

ده بيحول صفحة أبيكس يتيمة لواجهة “حرباء (Chameleon)” متعددة الأشكال، بتغير زرايرها وألوانها وأيقوناتها ورسائل التأكيد المنبثقة لكل خطوة workflow—ومدعومة بحماية سيرفر صارمة لا يمكن اختراقها.

🦎 تأثير الحرباء: صفحة واحدة تدير المنظومة كلها

في المعماريات البدائية لأوراكل أبيكس، كتير من المطورين بيعملوا صفحة تفاصيل مستقلة لكل نوع طلب:

صفحة 10 لأوامر الشراء (Purchase Orders)
صفحة 11 للمصروفات الرأسمالية (CAPEX)
صفحة 12 لفواتير الموردين (Vendor Invoices)
صفحة 13 لطلبات العهد والأجهزة

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

لو الفريق حب يحدث التصميم العام، أو شريط التنقل (Breadcrumbs)، أو شاشة سجل الحركات، مضطر يكرر التعديل يدوياً في 4 صفحات مختلفة!
لو عندك 30 مسار عمل في الشركة، صيانة 30 صفحة مختلفة بتبقى جحيم هندسي.

في المعمارية الاحترافية للشركات، بنستخدم صفحة تفاصيل واحدة فقط بتتصرف زي الحرباء بالظبط!

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

flowchart TD
    Req["رقم الطلب والخطوة<br/>(:P10_REQUEST_ID, :P10_STEP_ID)"] --> Config["قراءة الميتاداتا<br/>app_data.wf_action_config"]
    User["اليوزر المتصل<br/>(:APP_USER)"] --> Perms["مصفوفة الصلاحيات<br/>app_security.wf_user_permissions"]
    
    Config & Perms --> Engine["منطقة PL/SQL Dynamic Content<br/>(توليد زراير الـ HTML)"]
    Engine --> UI["شريط زراير الحرباء<br/>(موافق، مرفوض، طلب استيضاح)"]
    
    UI -->|دوسة مع شاشة تأكيد| AJAX["عملية APEX AJAX بالخلفية<br/>(فحص صلاحيات السيرفر)"]
    AJAX --> Core["pkg_workflow_actions.execute_action"]

💻 محرك الرسم: منطقة PL/SQL Dynamic Content

على صفحة تفاصيل الطلب (مثلاً صفحة 10)، بنعمل Region من نوع PL/SQL Dynamic Content:

declare
    v_step_cfg   app_data.wf_action_config%rowtype;
    v_can_btn1   varchar2(1) := 'N';
    v_can_btn2   varchar2(1) := 'N';
    v_can_btn3   varchar2(1) := 'N';
    v_can_btn4   varchar2(1) := 'N';
    v_tokens     apex_t_varchar2;
    
    procedure render_button(
        p_enabled      in varchar2,
        p_authorized   in varchar2,
        p_config_str   in varchar2,
        p_action_code  in varchar2,
        p_slot_num     in number
    ) is
        v_parts apex_t_varchar2;
    begin
        if p_enabled = 'Y' and p_authorized = 'Y' and p_config_str is not null then
            v_parts := apex_string.split(p_config_str, ',');
            -- v_parts(1) = النص، (2) = كلاس اللون، (3) = الأيقونة، (4) = فلاج التأكيد
            sys.htp.p(apex_string.format(
                '<button type="button" class="t-Button %s" ' ||
                'onclick="handleWorkflowAction(%s, ''%s'', %s)">' ||
                '<span class="t-Icon fa %s" aria-hidden="true"></span>' ||
                '<span class="t-Button-label">%s</span>' ||
                '</button>',
                v_parts(2),       -- مثلاً: 'u-success' أو 'u-danger'
                p_slot_num,       -- رقم الزرار (1..4)
                p_action_code,    -- كود الأكشن: 'APPROVE'
                v_parts(4),       -- 1 (محتاج تأكيد) أو 0 (فوري)
                v_parts(3),       -- مثلاً: 'fa-check'
                apex_escape.html(v_parts(1)) -- مثلاً: 'Approve Order'
            ));
        end if;
    end render_button;

begin
    -- 1. قراءة إعدادات أكشنز الخطوة الحالية
    select * into v_step_cfg
      from app_data.wf_action_config
     where step_id = :P10_CURRENT_STEP_ID;

    -- 2. التحقق من مصفوفة صلاحيات اليوزر المتصل
    select coalesce(max(can_action1), 'N'),
           coalesce(max(can_action2), 'N'),
           coalesce(max(can_action3), 'N'),
           coalesce(max(can_action4), 'N')
      into v_can_btn1, v_can_btn2, v_can_btn3, v_can_btn4
      from app_security.wf_user_permissions
     where step_id   = :P10_CURRENT_STEP_ID
       and user_name = :APP_USER;

    -- 3. رسم حاوية زراير الـ HTML
    sys.htp.p('<div class="t-ButtonRegion-wrap"><div class="t-ButtonRegion-col t-ButtonRegion-col--right">');

    -- رسم الزراير الأربعة حسب الصلاحية والإعدادات
    render_button(v_step_cfg.has_btn1, v_can_btn1, v_step_cfg.btn1_config, v_step_cfg.btn1_action_code, 1);
    render_button(v_step_cfg.has_btn2, v_can_btn2, v_step_cfg.btn2_config, v_step_cfg.btn2_action_code, 2);
    render_button(v_step_cfg.has_btn3, v_can_btn3, v_step_cfg.btn3_config, v_step_cfg.btn3_action_code, 3);
    render_button(v_step_cfg.has_btn4, v_can_btn4, v_step_cfg.btn4_config, v_step_cfg.btn4_action_code, 4);

    sys.htp.p('</div></div>');

exception
    when no_data_found then
        sys.htp.p('<span class="u-warning-text">لا توجد إجراءات متاحة لهذه المرحلة من الطلب.</span>');
end;

🖱️ معالج الجافاسكريبت: شاشات تأكيد أنيقة وسلسة

لاحظ إن الزراير اللي اترسمت بتنادي دالة اسمها handleWorkflowAction(...). بنضيف الدالة دي في إعدادات الجافاسكريبت بالصفحة:

function handleWorkflowAction(slotNumber, actionCode, requiresConfirm) {
    const doSubmit = function() {
        apex.server.process(
            "EXECUTE_WORKFLOW_ACTION",
            {
                x01: actionCode,
                pageItems: "#P10_REQUEST_ID,#P10_CURRENT_STEP_ID,#P10_ACTION_COMMENTS"
            },
            {
                success: function(data) {
                    if (data.status === "SUCCESS") {
                        apex.message.showPageSuccess(data.message || "تم تنفيذ الإجراء بنجاح.");
                        apex.navigation.redirect(data.redirect_url || "f?p=" + apex.env.APP_ID + ":100:" + apex.env.APP_SESSION);
                    } else {
                        apex.message.clearErrors();
                        apex.message.showErrors([{
                            type: "error",
                            location: "page",
                            message: data.message || "فشل تنفيذ الإجراء."
                        }]);
                    }
                }
            }
        );
    };

    if (requiresConfirm === 1) {
        apex.message.confirm(
            "هل أنت متأكد من رغبتك في اتخاذ هذا الإجراء؟",
            function(okPressed) {
                if (okPressed) {
                    doSubmit();
                }
            }
        );
    } else {
        doSubmit();
    }
}

🔒 أمان دفاعي متعدد الطبقات: إياك تثق في متصفح العميل!

قاعدة أمنية ذهبية في هندسة البرمجيات: إخفاء الزرار عن الشاشة لا يعتبر أماناً!

مجرد إن الزرار مش مرسوم في صفحة المتصفح، ده ميمنعش مستخدم خبيث أو فضولي إنه يفتح الـ Browser Console ويجرب ينادي apex.server.process("EXECUTE_WORKFLOW_ACTION") بإيده!

عشان نقفل الباب ده بالضبة والمفتاح، عملية الـ AJAX في السيرفر بتفوض التنفيذ لـ Package الباك إند (app_code.pkg_workflow_actions.execute_action) واللي بتفرض 3 فحوصات سيرفر إلزامية:

فحص الصلاحيات الصريح: بتسأل جدول wf_user_permissions بشكل مستقل للتأكد إن :APP_USER معاه تصريح صريح للأكشن ده في الخطوة دي بالتحديد.
فحص التزامن وحالة الطلب: بتتأكد إن الطلب لسه في حالته المتوقعة، ومفيش مدير تاني سبقه واعتمد أو رفض الطلب قبله بلحظات.
تسجيل الحركة في سجل الأحداث: لو الفحوصات نجحت، بتسجل الحركة في wf_task_event_log وتنقل حالة الـ Workflow.

لو أي فحص فشل، السيرفر بيرمي خطأ غير معالج ويلغي المعاملة فوراً، واليوزر يستلم رسالة خطأ أمنية واضحة.

🚀 إيه اللي مستنينا في الجزء السادس؟

مراجعة كل طلب لوحده في شاشة الحرباء دي حاجة شيك جداً للقرارات الكبيرة زي المصروفات الرأسمالية والصفقات الضخمة.

لكن مدراء الإدارات غالباً بيدخلوا صباح يوم الإثنين يلاقوا 50 طلب روتيني متراكم في صندوق الوارد. فكرة إنه يفتح 50 صفحة ورا بعض، ويدوس موافق 50 مرة، ويأكد 50 شاشة منبثقة دي وصفة مؤكدة للإرهاق وتطفيش المستخدمين!

في الجزء السادس (“الختم السريع: الاعتماد الجماعي بضغطة واحدة جوه الـ Interactive Grid”)، هنبني محرك موافقات جماعية عالي السرعة مزود بحماية الـ Savepoints لعزل الأخطاء وحماية القفل التفاؤلي (Optimistic Locking)!

استنونا في الجزء السادس! 📑🖊️✨

كتبه: أحمد شريف (Ahmed Sherif).

وداعاً للزراير الثابتة: تخزين أكشنز الشاشات في سطور الداتابيز 🎛️📋

Wed, 14 Oct 2026 00:00:00 GMT

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

وداعاً للزراير الثابتة: تخزين أكشنز الشاشات في سطور الداتابيز 🎛️📋

الجزء الرابع من سلسلة “إدارة الـ Workflows الضخمة في أوراكل أبيكس”.

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

لو فتحت قبل كده Oracle APEX Page Designer واتصدمت بمنظر 40 زرار مرصوصين جنب بعض في الهيدر—وكل زرار فيهم وراه مكرونة من الـ Server-Side Conditions زي “يظهر بس لو الخطوة هي FINANCE_AUDIT، والأولوية HIGH، واليوزر معاه ROLE_CONTROLLER”—فأنت عشت قمة الديون التقنية (Technical Debt) بعينك!

بنقل تعريفات وتنسيقات الزراير لجدول ميتاداتا علائقي (wf_action_config)، بنحول شاشة أبيكس لوحدة تحكم برمجية ديناميكية بترسم الزراير، والألوان، والأيقونات، ورسائل التأكيد المظبوطة لكل خطوة من مئات خطوات الـ Workflows من غير ما تفتح Page Designer مرة تانية في حياتك!

هنا هنتعلم إزاي نستبدل زحمة الزراير دي ببيانات وصفية شيك ومحترمة.

🎮 ذراع الألعاب القديم الملحوم ضد الدراع الذكي القابل للبرمجة

تخيل عالم أذرع ألعاب الفيديو (Controllers) كالمثال التالي:

كابوس الدراع القديم الملحوم بـ كاوية اللحام: كل ما تنزل لعبة جديدة في السوق، تجيب كاوية القصدير، وتسيح خرم جديد في البلاستيك بتاع الدراع، وتلحم زرار أحمر في لوحة الدوائر الإلكترونية، وتكتب عليه بقلم فلوماستر “تعويذة سحرية”! بعد 6 شهور، شكل الدراع بتاعك هيبقى شبه القنفذ المشوه بـ 50 زرار بارزين في كل اتجاه!
الدراع الذكي الحديث: الدراع فيه شريط أنيق من الزراير المزودة بشاشات OLED صغيرة. لما تشغل لعبة سباق عربيات، زرار 1 ينور بالأخضر ويكتب “نيترو”. ولما تشغل لعبة ألغاز، نفس الزرار يتحول للأزرق ويكتب “تدوير القطعة”. عتاد الهاردوير ثابت مبيتغيرش؛ اللعبة هي اللي بتبعت له ملف الإعدادات بس!

في تطبيقات Oracle APEX للمؤسسات، تثبيت عشرات الزراير يدوي في Page Designer هو بالظبط كاوية اللحام في البلاستيك. بيطلع نظام هش، معقد، وصيانته كابوس.

💥 عذاب صفحة الـ 40 زرار في أبيكس

لما تبني مسارات عمل وموافقات معقدة متعددة المراحل، كل مرحلة بتتطلب زراير وإجراءات مختلفة تماماً:

خطوة مراجعة المدير: محتاجة زراير Approve، و Reject، و Request Info.
خطوة مراجعة الحسابات والمالية: محتاجة Verify Budget، و Authorize Payment، و Return to Requester.
خطوة المراجعة القانونية: محتاجة Upload Addendum، و Flag Clause، و Approve Terms.

لو بنيت ده بالطريقة التقليدية جوه شاشة أبيكس:

الـ Page Designer بيبقى مستحيل استخدامه: شجرة المكونات (Component Tree) بتتحول لحائط سد فيه 45 زرار!
الشروط بتبقى مكرونة اسباجيتي: بتنتهي بـ 45 شرط PL/SQL معقد بيفحص الـ Session State والـ Roles والمبالغ.
كوارث تضارب الـ Merge في Git: لو مطورين عدلوا في زرارين مختلفين على نفس الصفحة، ملف الـ SQL المصدر بيطلع فيه مئات سطور التضارب غير القابلة للحل!
انعدام المرونة: مجرد تغيير كلمة على زرار من “Reject” لـ “Return for Revisions” بيتطلب دورة سوفتوير كاملة: تذكرة شغل، وتعديل، وتصدير، وتيست، ونشر على السيرفر!

📋 الحل الذكي: جدول الميتاداتا `wf_action_config`

في المعمارية القابلة للتوسع، أكشنز الشاشات بتتعامل كـ سطور بيانات في جدول. بنعرف جدول لإعدادات الأكشنز في سكيما الداتا (app_data) كالآتي:

-- ====================================================================
-- جدول: app_data.wf_action_config
-- الهدف: ميتاداتا وصفية بتعرف زراير الأكشنز لكل خطوة في الـ Workflow
-- ====================================================================

create table app_data.wf_action_config (
    step_id          varchar2(50) primary key, -- مثلاً: 'PO_MANAGER_REVIEW'
    step_name        varchar2(150) not null,
    module_code      varchar2(50)  not null,   -- مثلاً: 'PROCUREMENT', 'CAPEX'
    
    -- مكان الزرار الأول
    has_btn1         varchar2(1)   default 'N' check (has_btn1 in ('Y', 'N')),
    btn1_config      varchar2(200), -- التنسيق: النص,كلاس_CSS,كلاس_الأيقونة,رسالة_تأكيد
    btn1_action_code varchar2(50),  -- مثلاً: 'APPROVE'
    
    -- مكان الزرار الثاني
    has_btn2         varchar2(1)   default 'N' check (has_btn2 in ('Y', 'N')),
    btn2_config      varchar2(200),
    btn2_action_code varchar2(50),  -- مثلاً: 'REJECT'
    
    -- مكان الزرار الثالث
    has_btn3         varchar2(1)   default 'N' check (has_btn3 in ('Y', 'N')),
    btn3_config      varchar2(200),
    btn3_action_code varchar2(50),  -- مثلاً: 'REQUEST_INFO'
    
    -- مكان الزرار الرابع
    has_btn4         varchar2(1)   default 'N' check (has_btn4 in ('Y', 'N')),
    btn4_config      varchar2(200),
    btn4_action_code varchar2(50),
    
    created_at       timestamp with local time zone default current_timestamp,
    updated_at       timestamp with local time zone default current_timestamp
);

🎨 تعريف الزراير في سطور داتا سهلة ومباشرة

بصوا بقى على السهولة والجمال لما نحدد إعدادات الشاشات كسطور داتا عادية:

-- 1. خطوة مراجعة مدير الإدارة لأمر الشراء
insert into app_data.wf_action_config (
    step_id, step_name, module_code,
    has_btn1, btn1_config, btn1_action_code,
    has_btn2, btn2_config, btn2_action_code,
    has_btn3, btn3_config, btn3_action_code
) values (
    'PO_MANAGER_REVIEW', 
    'Department Manager PO Review', 
    'PROCUREMENT',
    'Y', 'Approve Order,u-success,fa-check,1',            'APPROVE',
    'Y', 'Reject Order,u-danger,fa-times,1',             'REJECT',
    'Y', 'Request Clarification,u-warning,fa-comment,0', 'REQUEST_INFO'
);

-- 2. خطوة المراجعة المالية للمصروفات الرأسمالية (CAPEX)
insert into app_data.wf_action_config (
    step_id, step_name, module_code,
    has_btn1, btn1_config, btn1_action_code,
    has_btn2, btn2_config, btn2_action_code
) values (
    'CAPEX_FINANCE_AUDIT', 
    'Capital Expenditure Executive Audit', 
    'CAPEX',
    'Y', 'Authorize Expenditure,u-success,fa-check-circle,1', 'APPROVE',
    'Y', 'Return for Budget Revision,u-danger,fa-undo,1',     'REJECT'
);

-- 3. مطابقة فواتير الموردين في الحسابات
insert into app_data.wf_action_config (
    step_id, step_name, module_code,
    has_btn1, btn1_config, btn1_action_code,
    has_btn2, btn2_config, btn2_action_code,
    has_btn3, btn3_config, btn3_action_code
) values (
    'AP_INVOICE_MATCH', 
    'Accounts Payable 3-Way Match', 
    'INVOICING',
    'Y', 'Confirm Match & Release,u-primary,fa-link,1',   'MATCH_RELEASE',
    'Y', 'Flag Discrepancy,u-danger,fa-flag,1',           'FLAG_ERROR',
    'Y', 'Upload Supporting Dockets,u-info,fa-upload,0',  'UPLOAD_ATTACHMENT'
);

فك تشفير نص إعدادات الزرار (`btn_config`):

لاحظ النص المكون من 4 أجزاء مفصولين بفواصل:

'Approve Order,u-success,fa-check,1'
       │          │          │   └── شاشة التأكيد المنبثقة: 1=اطلب تأكيد، 0=تنفيذ فوري
       │          │          └────── أيقونة Font Awesome: fa-check
       │          └───────────────── كلاس ألوان ثيم أبيكس Universal Theme: u-success (أخضر)
       └──────────────────────────── النص المكتوب على الزرار: "Approve Order"

🌟 ليه الطريقة دي بتكسب الزراير الثابتة بالضربة القاضية؟

الميزة	زراير Page Designer الثابتة	جدول الميتاداتا `wf_action_config`
عدد الزراير على الصفحة	30 – 50 مكون مرصوصين	صفر زراير ثابتة (حاوية واحدة ديناميكية)
إضافة خطوة موافقة جديدة	ضيف زراير، واكتب شروط، وصدر الكود، واعمل Deploy	ضيف سطر واحد في جدول الداتابيز
تغيير اسم أو لون زرار	تعديل كود + Pull Request + Deployment	أمر `UPDATE` بسيط في ثانيتين بس!
رسائل التأكيد (Confirmations)	كود جافاسكريبت مخصص لكل زرار	فلاج جاهز (`1` أو `0`) بيتعالج تلقائياً
تناسق الألوان والمظهر	سهل المطورين يلخبطوا في الألوان	معايير مفروضة من الداتابيز (`u-success`, `u-danger`)
تضارب الـ Git	خناقات وتضارب مستمر في ملفات الصفحات	صفر تضارب على صفحة الـ UI

🦎 إيه اللي مستنينا في الجزء الخامس؟

الميتاداتا دلوقتي متخزنة بأمان في جداول الداتابيز. لكن إزاي Oracle APEX بتاخد السطور دي وتحولها لزراير HTML تفاعلية وشيك جداً على شاشة المستخدم وقت التشغيل؟

والأهم من كده: إزاي نتأكد إن الموظفين اللي معاهم صلاحية بس هما اللي يقدروا يشوفوا ويدوسوا على الزراير دي؟

في الجزء الخامس (“شاشة الحرباء: الرسم الديناميكي لأشرطة الأكشنز في صفحة 8”)، هنبني منطقة PL/SQL ديناميكية على صفحة تفاصيل الطلب، بتغير شكل شريط الأدوات تلقائياً في لمح البصر مع تطبيق أمان سيرفر صارم لا يمكن اختراقه!

استنونا في الجزء الخامس! 🦎🎚️✨

كتبه: أحمد شريف (Ahmed Sherif).

تزامن الكاش بالأحداث: تحديث كاش المهام بنسبة 100% فورياً بالـ Triggers 🔄🔔

Sat, 10 Oct 2026 00:00:00 GMT

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

تزامن الكاش بالأحداث: تحديث كاش المهام بنسبة 100% فورياً بالـ Triggers 🔄🔔

الجزء الثالث من سلسلة “إدارة الـ Workflows الضخمة في أوراكل أبيكس”.

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

فيه طريقتين عشان تعرف إن فنجان القهوة بتاعك جهز في كافيه زحمة الصبح: يا إما تفضل واقف قدام الباريستا وكل 15 ثانية تهتف بصوت عالي: “القهوة بتاعتي خلصت ولا لسه؟!” (طريقة الـ Polling)، أو إن الباريستا يرن جرس التنبيه الصغير في نفس اللحظة اللي فنجانك بينزل فيها على الرخامة (طريقة الـ Event-Driven Notification).

عشان نحافظ على تزامن جدول الكاش السريع (wf_task_cache) مع تنقلات مهام Oracle APEX، بنبعد تماماً عن وظائف الجدولة الدورية التقيلة (Scheduler Jobs). وبدل كدة، بنستخدم تريجرات داتابيز ذكية معتمدة على الأحداث، مربوطة بـ Packages محكمة لتحديث الكاش فورياً.

ده بيحقق دقة وتزامن بنسبة 100% في واجهات أبيكس مع صفر وظائف مجدولة، وصفر تأخير، وصفر قفل أو تضارب على الجداول (Lock Contention).

☕ فخ الـ Polling ضد نمط جرس الخدمة (Service Bell Pattern)

في معماريات الكاش، كتير من المطورين اللي مبيحبوش يوجعوا دماغهم بتزامن البيانات بيستسهلوا: يروح يعمل وظيفة DBMS_SCHEDULER تشتغل كل 5 دقائق عشان تعيد بناء جدول الكاش بالكامل من الصفر.

في بيئات الشركات الكبيرة والزحمة، الجدولة الدورية دي بتعمل مصيبتين كبار:

1. لاج “الموافقة الشبح” (Ghost Approval Lag)

مدير إدارة يفتح شاشة أبيكس، يراجع طلب شراء مهم بـ 50 ألف دولار، ويدوس موافق (Approve). الصفحة تعمل Refresh—ولأن وظيفة الكاش لسه ميعادها مجاش، الطلب يفضل ظاهر قدامه على الشاشة بحالة PENDING! المدير يتلخبط ويدوس Approve تاني، فيطلع له إيرور أو تتكرر أوامر الشراء في السيستم!

2. حرق الـ I/O والـ CPU على الفاضي

وظيفة شغالة كل 60 ثانية بتحرق في معالج وسيرفر الداتابيز 24 ساعة في اليوم، 7 أيام في الأسبوع—حتى الساعة 3 الفجر يوم الأحد والشركة كلها في إجازة ومفيش طلب واحد اتبعت من 8 ساعات!

بدل الـ Polling المرهق، بنستخدم نمط جرس الخدمة (Service Bell Pattern): أول ما أي إجراء بيحصل على الـ Workflow، الداتابيز بتحدث سطر الكاش في نفس المعاملة (Database Transaction). ولما صفحة أبيكس تفتح في متصفح المدير، بيكون جدول الكاش اتحدث وجاهز 100%!

sequenceDiagram
    autonumber
    actor User as المعتمد / المدير
    participant UI as صفحة أبيكس
    participant WF as محرك APEX Workflow
    participant Log as سجل الأحداث wf_task_event_log
    participant Trg as تريجر trg_wf_task_log_cache
    participant Cache as كاش المهام wf_task_cache

    User->>UI: بيدوس "موافق" (Approve)
    UI->>WF: تنفيذ خطوة الـ Workflow
    WF->>Log: كتابة سطر الحدث في السجل
    Log->>Trg: التريجر بيشتغل فورياً
    Trg->>Cache: تحديث الحالة لـ 'APPROVED' (أو حذفه)
    Cache-->>UI: الصفحة بتفتح في 20ms بالقائمة المحدثة

🏗️ دفتر سجل الأحداث: جدول `wf_task_event_log`

عشان نفصل العمليات بنظافة، بنسجل كل حركة بتحصل في جدول أحداث تاريخي ثابت في الـ Schema المخصصة للداتا (app_data) كالآتي:

-- ====================================================================
-- جدول: app_data.wf_task_event_log
-- الهدف: دفتر أستاذ تاريخي ثابت بيسجل كل حركة وانتقال في الـ Workflow
-- ====================================================================

create table app_data.wf_task_event_log (
    event_id         number generated always as identity primary key,
    request_id       number not null,
    task_id          number,
    action_type      varchar2(50)  not null, -- 'CREATE', 'APPROVE', 'REJECT', 'REASSIGN'
    previous_status  varchar2(50),
    new_status       varchar2(50)  not null, -- 'PENDING', 'APPROVED', 'REJECTED'
    action_user      varchar2(100) default coalesce(sys_context('APEX$SESSION','APP_USER'), user) not null,
    action_comments  varchar2(4000),
    event_timestamp  timestamp with local time zone default current_timestamp not null
);

create index app_data.wf_task_event_req_idx 
    on app_data.wf_task_event_log(request_id, event_timestamp desc);

كل تغيير في الحالة—سواء اتعمل بمحرك أبيكس التلقائي، أو بانتهاء المهلة (Timeout)، أو بضغطة زرار من موظف—بيسجل سطر في الدفتر ده.

🔔 التريجر الخفيف: دور الجرس فقط

تريجرات الداتابيز المفروض متكونش مليانة لوجيك بيزنس ولا استدعاءات تقيلة. التريجر الصح بيعمل حاجة واحدة بس: بيرن الجرس ويسلم المفاتيح لـ PL/SQL Package جاهزة ومتجمعة.

-- ====================================================================
-- تريجر: app_data.trg_wf_task_log_cache
-- ====================================================================

create or replace trigger app_data.trg_wf_task_log_cache
after insert or update on app_data.wf_task_event_log
for each row
begin
    -- تفويض فوري للـ Package المركزية لمزامنة الكاش
    app_code.pkg_task_cache.sync_task_cache(
        p_request_id => :new.request_id,
        p_task_id    => :new.task_id,
        p_action     => :new.action_type,
        p_new_status => :new.new_status,
        p_user       => :new.action_user
    );
end;
/

⚙️ منسق الكاش: Package الـ `pkg_task_cache`

تعالوا نشوف كود الـ Package اللي في سكيما البرمجة (app_code). لاحظ إزاي بتتعامل بذكاء مع الحالات المستمرة والحالات النهائية:

create or replace package app_code.pkg_task_cache as
    procedure sync_task_cache(
        p_request_id in number,
        p_task_id    in number,
        p_action     in varchar2,
        p_new_status in varchar2,
        p_user       in varchar2
    );
end pkg_task_cache;
/

create or replace package body app_code.pkg_task_cache as

    procedure sync_task_cache(
        p_request_id in number,
        p_task_id    in number,
        p_action     in varchar2,
        p_new_status in varchar2,
        p_user       in varchar2
    ) is
    begin
        -- السيناريو (أ): الوصول لحالة نهائية (انتهت المهمة)
        -- لما المهمة تعتمد أو تترفض أو تتلغي، مبقتش شغل نشط.
        -- بنمسحها فوراً من جدول الكاش السريع!
        if p_new_status in ('APPROVED', 'REJECTED', 'CANCELLED', 'EXPIRED') then
            delete from app_data.wf_task_cache
             where request_id = p_request_id;
             
        -- السيناريو (ب): انتقال لحالة نشطة جديدة (استلام، قيد التنفيذ، إعادة توجيه)
        else
            update app_data.wf_task_cache
               set status     = p_new_status,
                   task_id    = coalesce(p_task_id, task_id),
                   updated_at = current_timestamp
             where request_id = p_request_id;

            -- لو السطر مكنش لسه موجود في الكاش (مثلاً مهمة جديدة لسه متكريتة حالا)
            if sql%rowcount = 0 then
                insert into app_data.wf_task_cache (
                    request_id,
                    task_id,
                    task_group,
                    task_type,
                    status,
                    title,
                    priority,
                    requester_name,
                    potential_owners,
                    created_at,
                    updated_at
                )
                select r.request_id,
                       p_task_id,
                       r.request_group,
                       r.request_type,
                       p_new_status,
                       r.title,
                       r.priority,
                       r.requester_name,
                       r.potential_owners,
                       current_timestamp,
                       current_timestamp
                  from app_data.wf_requests r
                 where r.request_id = p_request_id;
            end if;
        end if;
    end sync_task_cache;

end pkg_task_cache;
/

🛡️ القواعد الذهبية التلاتة لتريجرات بدون أي بطء أو قفل جداول

عشان تضمن إن التزامن ده يشتغل مع آلاف العمليات المتزامنة في نفس اللحظة:

1. التعديل المستهدف لسطر واحد بمفتاح فريد (Targeted Single-Row Writes)

لاحظ إن جمل الـ UPDATE والـ DELETE بتفلتر بـ where request_id = p_request_id. ولأن request_id عليه B-Tree Index، أوراكل بتقفل بس السطر ده بالذات لأجزاء من الميلي ثانية وتسيبه فوراً.

2. إياك تستخدم `AUTONOMOUS_TRANSACTION` في تحديث الكاش!

بعض المطورين بيحاولوا يخلوا كود التريجر ده معزول بـ PRAGMA AUTONOMOUS_TRANSACTION. غلط كبير! لو المعاملة الرئيسية اتلغت (Rollback) بسبب قيد في الداتابيز، كود الكاش هيفضل محفوظ—وهتسيب مهمة “شبح” يتيمة في الكاش! وجودهم في نفس المعاملة بيضمن تكامل بيانات ACID بنسبة 100%.

3. الحذف الفوري للطلبات المنتهية

جدول كاش العمليات معمول عشان يشيل الشغل الشغال بس. أول ما المهمة تنتهي بموافقة أو رفض، طيرها من wf_task_cache. تاريخها المحفوظ متسجل للأبد في جدول الأحداث wf_task_event_log.

🚀 إيه اللي مستنينا في الجزء الرابع؟

الباك إند دلوقتي طيارة ومتزامن في اللحظة نفسها. بس ماذا عن تجربة المستخدم في الشاشات؟

لما المعتمد يفتح مهمة معينة، كل خطوة في الـ Workflow بتتطلب زراير مختلفة:

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

في الجزء الرابع (“وداعاً للزراير الثابتة: تخزين أكشنز الشاشات في سطور الداتابيز”)، هنشوف إزاي تخزين إعدادات الزراير في جدول ميتاداتا بيقضي تماماً على كابوس إدارة 40 زرار بشروط معقدة جوه APEX Page Designer!

استنونا في الجزء الرابع! 🎛️📋✨

كتبه: أحمد شريف (Ahmed Sherif).

حامل بونات المطبخ: تصميم كاش العمليات عالي السرعة 🎫⚡

Tue, 06 Oct 2026 00:00:00 GMT

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

حامل بونات المطبخ: تصميم كاش العمليات عالي السرعة 🎫⚡

الجزء الثاني من سلسلة “إدارة الـ Workflows الضخمة في أوراكل أبيكس”.

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

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

ببناء جدول كاش عمليات مخصص (wf_task_cache)، بنفرز ونخزن بس البيانات اللي شاشات المهام محتاجاها بالضبط—وبنحول استعلامات بطيئة بتاخد 15 ثانية على الـ Views الرسمية لعملية بحث فوري في الفهارس بتاخد 20 ميلي ثانية بس!

هنا هنتعلم إزاي نبني، ونفهرس، ونستعلم من جدول كاش فائق السرعة للـ Workflows جوه Oracle Database.

🍳 مخزن البضائع الخلفي ضد حامل البونات السريع

في الجزء الأول، شرحنا ليه الاستعلام المباشر من APEX_TASKS في الأعداد الكبيرة بيهد حيل الداتابيز، لأنه بيجبرها تحسب شجرة الصلاحيات وتفك الـ JSON لكل سطر في النظام.

تخيل معايا إدارة مطعم كبير:

طريقة مخزن البضائع (الاستعلام المباشر من APEX_TASKS): كل ما ترابيزة 7 تطلب ستيك مشوي، الشيف يسيب ماسك الشواء، ويدخل المكتب ورا، ويفتح درج الأرشيف بالمفتاح، ويقرا بوليصة شحن اللحمة، ويفحص شهادة الصحة، ويحسب هامش الربح! المطبخ في نص ساعة هيتأخر 3 ساعات عن الزباين!
طريقة حامل بونات المطبخ (جدول كاش العمليات wf_task_cache): الويتر بيكتب الطلب على التابلت. طابعة البونات فوق الشواية تطلع كارت صغير 5 سم يتعلق في الحامل الدوار. الكارت فيه 4 معلومات واضحة وصريحة: ترابيزة 7، ستيك ريب آي (وسط)، الساعة 7:42 م، الويتر: ماركوس.

الشيف بيبص للبونة، يسوي الستيك في 6 دقايق، يطلعه على الطبق، ويشك البونة في مسمار الأوردرات المخلصة!

في معمارية Oracle APEX بتاعتنا، جدول wf_task_cache هو بالظبط حامل البونات السريع ده.

🏗️ التصميم الهندسي لجدول `wf_task_cache`

بدل ما نخلي تقارير أبيكس تغوص في جداول الداتابيز الداخلية المعقدة (WWV_FLOW_TASKS$)، بنعمل جدول بسيط ونظيف في الـ Schema المخصصة للداتا (app_data) كالآتي:

-- ====================================================================
-- جدول: app_data.wf_task_cache
-- الهدف: كاش عمليات عالي السرعة لمهام الـ Workflow النشطة
-- ====================================================================

create table app_data.wf_task_cache (
    cache_id         number generated always as identity primary key,
    request_id       number not null,
    task_id          number,
    task_group       varchar2(100) not null, -- مثلاً: 'PURCHASE_REQUESTS', 'INVOICES'
    task_type        varchar2(200) not null, -- مثلاً: 'PO_FINANCE_APPROVAL'
    status           varchar2(50)  not null, -- 'PENDING', 'ASSIGNED', 'IN_PROGRESS'
    priority         number(2,0)   default 3 not null, -- 1=طارئ، 2=عالي، 3=عادي
    requester_id     number,
    requester_name   varchar2(250),
    title            varchar2(300) not null,
    amount           number(14,2),           -- مؤشر مالي مهم للفلترة السريعة
    potential_owners varchar2(4000),         -- لستة مسبقة الحساب باليوزرات والأدوار المسموح لها بالاعتماد
    created_at       timestamp with local time zone default current_timestamp not null,
    updated_at       timestamp with local time zone default current_timestamp not null
);

-- فهارس الأداء الحاسمة
create index app_data.wf_task_cache_grp_st_idx 
    on app_data.wf_task_cache(task_group, status, priority, created_at);

create index app_data.wf_task_cache_req_idx 
    on app_data.wf_task_cache(request_id);

create index app_data.wf_task_cache_task_idx 
    on app_data.wf_task_cache(task_id);

🧠 السلاح السري: حساب الصلاحيات مسبقاً (Pre-Aggregated Security)

أكبر سبب لبطء استعلامات المهام في أبيكس هو حساب المشاركين لحظة القراءة (Runtime Participant Calculation). لو مهمة متخصصة لجروب مدراء الحسابات FINANCE_MANAGERS، الداتابيز بتضطر تفحص جداول الأمان لكل سطر عشان تشوف هل :APP_USER عضو في الجروب ده حالياً ولا لأ!

في جدول الكاش بتاعنا، نقلنا الحسبة دي من وقت القراءة (Read Time) لـ وقت الكتابة (Write Time):

أول ما المهمة بتتكريت، كود الـ Workflow بيحسب لستة الناس المسموح لهم بالموافقة وبيخزنها في نص موحد ومفصول بفواصل:

,ADMIN,FINANCE_MANAGERS,SARAH_CONNOR,JOHN_DOE,

لاحظ الفواصل اللي في الأول وفي الآخر. بفضل الفواصل دي، نقدر نعمل بحث مطابقة دقيق في جملة الـ SQL بدون أي لخبطة بين الأسماء المتشابهة (مثلاً مطابقة JOHN جوه JOHN_DOE) كالتالي:

-- فحص أمان صاروخي ومضمون في الـ SQL
and instr(potential_owners, ',' || :APP_USER || ',') > 0

[!TIP]

⚡ اكتب مرة واحدة، واقرأ آلاف المرات!

في أنظمة الشركات، المهمة بتتكريت أو تتعدل مرة أو مرتين في حياتها. لكنها بتتقري وتتفلتر وتترتب من عشرات المدراء مئات المرات في اليوم! نقل التعقيد الحسابي لمرحلة الكتابة بيحول كل استعلام قراءة لعملية Index Scan رخيصة جداً على السيرفر!

⚡ استعلام شاشة المهام في APEX

مع وجود جدول الكاش، بنعمل View نظيفة في الـ Schema المخصصة للبرمجة (app_code) كالآتي:

create or replace view app_code.v_pending_tasks as
select c.cache_id,
       c.request_id,
       c.task_id,
       c.task_group,
       c.task_type,
       c.title,
       c.priority,
       c.amount,
       c.requester_name,
       c.potential_owners,
       c.created_at
  from app_data.wf_task_cache c
 where c.status in ('PENDING', 'ASSIGNED');

شوف بقى كويري الـ APEX Interactive Report بقى نظيف وسريع إزاي:

-- استعلام شاشة المهام في أبيكس
select request_id,
       task_id,
       task_type,
       title,
       priority,
       amount,
       requester_name,
       created_at
  from app_code.v_pending_tasks
 where task_group = :P100_TASK_GROUP
   and (
       instr(potential_owners, ',' || :APP_USER || ',') > 0
       or exists (
           select 1 
             from app_security.user_roles r
            where r.user_name = :APP_USER
              and instr(potential_owners, ',' || r.role_name || ',') > 0
       )
   );

📊 مقارنة الأداء بالأرقام: الـ View الجاهزة ضد جدول الكاش

دي أرقام حقيقية اتسجلت على داتابيز أوراكل شغالة فيها 35,000 مهمة ومسار موافقات نشط:

المقياس	الـ View الجاهزة `APEX_TASKS`	جدول الكاش السريع (`wf_task_cache`)	نسبة التحسن
وقت استجابة الشاشة	14.8 ثانية انتظار	0.024 ثانية (24 ميلي ثانية بس!)	أسرع 600 ضعف
قراءات الذاكرة (Buffer Gets)	~340,000 قراءة	45 قراءة بس	توفير 99.98% من استهلاك الـ I/O
خطة التنفيذ (Execution Plan)	Full scan + nested loops	B-Tree Index Range Seek	أفضل خطة بحث في الفهارس
استهلاك الـ CPU	بيطير لـ 90%+	مسطح تحت 2%	تأثير شبه منعدم على السيرفر
تجربة المستخدم	الصفحة بتهنج والدايرة بتلف	الشاشة بتفتح في غمضة عين	سلسة وسريعة جداً

🔄 سؤال التحديث: إزاي بنضمن إن الكاش طازة دايماً؟

أي كاش في الدنيا قوته بتعتمد على طريقة مزامنته:

لما موظف يقدم طلب شراء جديد، إزاي بينزل فوراً على حامل البونات؟
ولما المدير يدوس “موافق”، إزاي المهمة بتختفي فوراً من غير ما تسيب أشباح وراها؟

في الجزء الثالث (“تزامن الكاش بالأحداث: تحديث كاش المهام بنسبة 100% فورياً”)، هنبني Triggers خفيفة في الداتابيز وحزم مزامنة بتخلي wf_task_cache متزامن بالمللي مع أحداث الـ Workflow في اللحظة نفسها—بدون أي Cron Jobs ولا Polling دوري متعب!

استنونا في الجزء الثالث! 🔄🔔

كتبه: أحمد شريف (Ahmed Sherif).

زحمة الـ 30 ألف مهمة: ليه استعلامات APEX Workflow الجاهزة بتخبط في الحيطة؟ 🚦🐌

Fri, 02 Oct 2026 00:00:00 GMT

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

زحمة الـ 30 ألف مهمة: ليه استعلامات APEX Workflow الجاهزة بتخبط في الحيطة؟ 🚦🐌

الجزء الأول من سلسلة “إدارة الـ Workflows الضخمة في أوراكل أبيكس”.

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

لما تكون شركتك بتمشي كام طلب إداري بسيط في اليوم، محرك الـ Workflows والـ Human Tasks في Oracle APEX بيشتغل زي الفراشة وبمنتهى الخفة والجمال. لكن أول ما 500 مدير إدارة يدخلوا مع بعض صباح يوم الإثنين عشان يراجعوا طابور متراكم فيه 30,000 مهمة وموافقة مستنية، الـ CPU بتاع الداتابيز بينط فجأة لـ 100%، وشاشة المهام بتاخد من 15 لـ 30 ثانية عشان تفتح!

والسبب مش ضعف إمكانيات السيرفر ولا بطء شبكة الإنترنت. السبب الحقيقي هو “التكلفة المعمارية الباهظة” لكيفية معالجة الـ Views الرسمية الجاهزة (APEX_TASKS و APEX_TASK_PARTICIPANTS) لحسابات صلاحيات الأمان، وشجرة أدوار الموظفين، وفك تشفير معطيات الـ JSON لكل سطر في اللحظة نفسها (On the Fly).

في الدليل ده، هنشرح بالتفصيل ليه الـ Views الجاهزة دي بتخبط في حيطة سد في الشركات الضخمة—وإزاي فصل عرض الشاشات (UI Rendering) عن محرك الـ Workflow بيحل الأزمة دي للأبد.

🏨 دفتر نزلاء الفندق: تشبيه في غاية البساطة

عشان نتخيل اللي بيحصل جوه خوادم الداتابيز، تعالوا نقارن بين فندقين مختلفين تماماً:

1. بنسيون العجمي الصغير (حجم بيئات التطوير المحلية)

أنت صاحب بنسيون ريفي جميل فيه 6 أوض بس. لما يوصل نزيل جديد، موظف الاستقبال بيبص في كشكول ورقي من صفحة واحدة محطوط على المكتب.
الموظف بيلاقي اسم النزيل في ثانيتين، يديله مفتاح أوضة 3 ويبتسم في وشه. الوقت الإجمالي: 3 ثواني بس.
ده بالظبط حالك في بيئة التجارب والـ Staging — عندك 50 مهمة و 3 يوزرات بتجرب بيهم، ومفيش أي بطء ملحوظ على الإطلاق.

2. منتجع لاس فيجاس العملاق ليلة رأس السنة (حجم المؤسسات الضخمة)

تخيل بقى منتجع وكازينو ضخم فيه 5,000 جناح فندقي فاخر في ليلة رأس السنة، ومئات النزلاء بيوصلوا في كل دقيقة!
تخيل لو موظف الاستقبال معندوش كمبيوتر ولا قاعدة بيانات، وبدل كدة مضطر يقلب في مجلد يدوي من 3,000 صفحة لكل نزيل لوحده! ومع كل اسم، لازم يقوم يفتح دولاب أرشيف في أوضة تانية يتأكد النزيل ده واخد كارت VIP ولا لأ، ويكلم قسم الحسابات بالتليفون يفحص الحد الائتماني، ويكلم أمن الفندق يراجع أختام الباسبور!
طابور النزلاء هيمتد لبرة الفندق ويسد الشارع، الموظفين هينهاروا من التعب، والنزلاء هيتخانقوا واللوبي كله هيقف تماماً!

ده بالظبط اللي بيحصل لما شاشة المهام في نظام APEX بتاعك تقرر تستعلم من APEX_TASKS مباشرة على داتابيز حية فيها عشرات الآلاف من المهام!

🔬 تشريح `APEX_TASKS`: إيه اللي بيحصل وراء الكواليس؟

من أول إصدارات Oracle APEX الحديثة في 26.1 و 26.2، وفرت أوراكل محرك Workflows و Human Tasks استثنائي لإدارة مسارات الموافقات، والـ Escalations، والتفريعات المعقدة.

وعشان تعرض المهام دي للمطورين، وفرت أبيكس Views جاهزة:

APEX_TASKS: بتمثل المهام النشطة والمحجوزة والمنتهية.
APEX_TASK_PARTICIPANTS: لستة اليوزرات والمجموعات المرشحة للموافقة.
APEX_WORKFLOWS: لتتبع مسارات الـ Workflows بالكامل.

الـ Views دي اتصممت عشان تكون مرنة مع أي سيناريو في العالم. لكن المرونة المطلقة دي بتيجي على حساب تكلفة معالجة مرعبة! لما تستعلم من APEX_TASKS، الداتابيز مش مجرد بتقرأ جدول عادي، هي مجبرة تحسب 3 طبقات تقيلة جداً ديناميكياً:

الطبقة 1: فحص الصلاحيات والأطراف المشاركة (Dynamic Participant Resolution)

مين مسموح له يعتمد أو يستلم المهمة دي حالياً؟

هل هي متخصصة مباشرة لليوزر المتصل :APP_USER؟
ولا اليوزر بينتمي لجروب موافقات (زي FINANCE_CONTROLLERS)؟
ولا المدير الأساسي فوض صلاحياته لمساعده في الفترة الزمنية دي؟
وهل الهيكل الإداري بيسمح للمدير الأكبر إنه يتدخل؟

تقييم المنطق ده بيتطلب Subqueries متداخلة، و Join مع جداول الأمان الداخلية (WWV_FLOW_TASK_PARTICIPANTS$)، وفحص ديناميكي لعضويات الجروبات لكل سطر من سطور المهام المرشحة!

الطبقة 2: فك تشفير محتوى المعطيات (Context Payload Extraction)

المهام غالباً بتخزن بيانات البيزنس (زي إجمالي أمر الشراء، واسم الموظف، وبنود الفاتورة) جوه حقول JSON أو XML داخلية. فك تشفير الـ JSON المعقد ده لبيانات علائقية على آلاف السطور بيحرق الـ CPU حرق!

الطبقة 3: التحقق من ماكينة الحالات (State Machine Validation)

المحرك بيفحص باستمرار هل المهمة دي انتهت مهلتها (Timeouts) أو معادها عدا، وبيعيد حساب الأولويات والحالات على الطاير.

🐌 الاستعلام اللي بيولع في سيرفرات الـ Production

في مشروعات المؤسسات والشركات الكبيرة، مفيش حاجة اسمها شاشة مهام بكويري بسيط من 5 سطور زي بتاعة كتب التدريب.

في الحقيقة، بناء الـ Interactive Grid الشامل ده مكنش مجرد رفاهية من المطورين أو خيار تجميلي—ده كان متطلب إجباري وقاطع من الإدارة العليا ورؤساء القطاعات! القيادات ومدراء العموم رفضوا رفضاً باتاً إنهم يقعدوا يتنقلوا بين 5 شاشات مختلفة أو يكتفوا ببطاقات مهام عامة ومختصرة عشان يراجعوا طلب واحد. كان المطلب الحاسم هو وجود “لوحة قيادة مركزية ومكتظة بالبيانات (High-Density Operational Cockpit)” تفتح للمدير الصورة كاملة من شاشة واحدة:

بيانات مقدم الطلب بالكامل وإدارته،
حالة الـ Workflow والمدراء اللي لسه معتمدوش،
تفاصيل البيزنس المعقدة المتخزنة جوه باراميترات الـ Workflow،
زراير لفتح شاشات منبثقة (Modals) للكومنتات والمرفقات،
أيقونات ملونة بتحدد هل مسموح للمدير ده يلغي أو يمسح الطلب ده ولا لأ،
إمكانية البحث الجماعي الضخم (زي إنه ينسخ 50 رقم قومي أو كود موظف من الإكسيل ويلزقهم في شاشة البحث مرة واحدة!).

ولأن الـ Human Tasks الرسمية في أبيكس مبتحطش بيانات البيزنس دي في أعمدة صريحة وجاهزة، المطورين اتزنقوا واضطروا يربطوا كل الخيوط دي ببعضها جوه نفس استعلام الـ Grid على الطاير!

بصوا على الكود الواقعي اللي الفرق بتبنيه في بيئات العمل الحقيقية لتنفيذ متطلبات الإدارة—قبل ما يكتشفوا إنهم بالغلط ولعوا في الداتابيز:

-- ==============================================================================
-- نمط استعلام "كل شيء في شاشة واحدة" الشهير
-- تحذير: إياك تشغل ده على 30,000 مهمة حقيقية في الـ Production!
-- ==============================================================================
with emp_data as (
    -- 1. البحث في بيانات الموظفين
    select e.emp_id,
           e.emp_number,
           nvl(e.emp_name_ar, e.emp_name_en) as emp_name,
           e.emp_status,
           e.category_type,
           e.national_id,
           e.employment_start_date,
           app_code.emp_pkg.get_department_name(e.emp_id) as department_name
      from app_data.employees e
),
task_payload_data as (
    -- 2. استخراج وفك بيانات الـ JSON لباراميترات المهام لكل سطر
    select tl.task_id as tsk_id,
           tl.workflow_id,
           json_value(tl.task_parameters_data, '$[*]?(@.param_static_id=="REQ_ID").param_value' returning varchar2(4000)) as req_id,
           json_value(tl.task_parameters_data, '$[*]?(@.param_static_id=="EMP_NO").param_value' returning varchar2(4000)) as emp_no,
           json_value(tl.task_parameters_data, '$[*]?(@.param_static_id=="MASTER_PK_ID").param_value' returning varchar2(4000)) as master_pk_id,
           al.main_action_id,
           decode(tl.state_code, 'COMPLETED', null, sl.pending_approvers) as pending_approvers,
           ra.action_id as action_id_raw,
           nvl(app_code.wf_pkg.get_action_desc(ra.action_id), ra.action_id) as action_desc,
           ra.status,
           ra.sub_status
      from app_data.wf_task_log tl
      left join app_data.wf_action_log al 
        on al.wf_id = tl.workflow_id
      join apex_task_parameters atp 
        on atp.task_id = tl.task_id 
       and atp.param_static_id = 'P_ACTION_ID'
      left join app_data.wf_action_sub_log sl 
        on tl.task_id = sl.task_id 
       and al.current_sub_id = sl.sub_id
      left join app_data.request_actions ra 
        on ra.action_id = al.main_action_id
     where :P100_ACTION_ID = atp.param_value
)
-------------------------- الاستعلام الرئيسي للـ INTERACTIVE GRID --------------------------
select e.*,
       tasks.*,
       td.*,
       -- 3. نداءات دوال PL/SQL سكلر لكل سطر عشان لينكات الكومنتات والمرفقات
       decode(td.main_action_id, null, '#', 
              app_code.doc_pkg.get_comments_url(
                  p_doc_type    => 'REQUEST_ACTION',
                  p_doc_id      => td.main_action_id,
                  p_emp_id      => e.emp_id,
                  p_action_id   => td.main_action_id,
                  p_from_page   => 4,
                  p_app_session => :APP_SESSION
              )) as comment_url,
       decode(td.main_action_id, null, '#', 
              app_code.doc_pkg.get_attach_url(
                  p_doc_type    => 'REQUEST_ACTION',
                  p_doc_id      => td.main_action_id,
                  p_app_session => :APP_SESSION,
                  p_emp_id      => e.emp_id,
                  p_from_page   => 312
              )) as attach_url,
       case 
         when app_security.auth_pkg.user_can_follow_action(:APP_USER, :P100_ACTION_ID) = 'YES' 
         then '<span class="fa fa-times-circle u-danger-text" aria-hidden="true"></span>'
         else '' 
       end as delete_icon
  from (
       -- 4. استدعاء دالة المهام الرسمية Pipelined Table Function
       select t1.*, 'a' as join_dummy
         from table(apex_approval.get_tasks(
                      p_context            => 'MY_TASKS',
                      p_show_expired_tasks => 'Y'
                    )) t1
       ) tasks
  left join task_payload_data td 
    on td.tsk_id = tasks.task_id
  -- 5. الربط مع جداول الموظفين بتعبيرات Regex الشرطية
  left join emp_data e 
    on e.emp_number = case 
                        when regexp_like(td.emp_no, '^[0-9]+$') then td.emp_no
                        else null
                      end
 where (:P100_TASK_DEF_STATIC_ID = tasks.task_def_static_id)
   and nvl(:P100_REQ_ID, '-') = nvl(td.req_id, '-')
   -- 6. الفحص متعدد المستويات لصلاحيات الفئات
   and (
         e.category_type is null
         or (
              e.category_type = nvl(:SESSION_CATEGORY, 'ALL')
              or (
                   nvl(:SESSION_CATEGORY, 'ALL') = 'ALL'
                   and e.category_type in (
                       select category_type
                         from app_security.user_permitted_categories
                        where user_name = :APP_USER
                          and category_type <> 'ALL'
                   )
              )
         )
       )
   -- 7. البحث الجماعي بلستة أرقام موظفين ملزوقة في الشاشة
   and (
         :P100_SEARCH_VALUES is null
         or (
              :P100_SEARCH_TYPE = 'EMP_NUMBERS'
              and e.emp_number in (
                  select column_value as id_num
                    from the (
                        select cast(app_code.string_utils_pkg.split_ids(
                                      rtrim(replace(replace(:P100_SEARCH_VALUES, chr(13), ''), chr(10), ','), ',')
                                    ) as app_code.id_table_t)
                          from dual
                    )
              )
         )
         or (
              :P100_SEARCH_TYPE = 'NATIONAL_ID'
              and e.national_id in (
                  select column_value as id_num
                    from the (
                        select cast(app_code.string_utils_pkg.split_ids(
                                      rtrim(replace(replace(:P100_SEARCH_VALUES, chr(13), ''), chr(10), ','), ',')
                                    ) as app_code.id_table_t)
                          from dual
                    )
              )
         )
       );

ليه الاستعلام ده بينهار تماماً عند 30 ألف مهمة؟

لما تجربه في بيئة التجارب بـ 20 مهمة، بيخلص في 120 ميلي ثانية وتفرح بيه! لكن أول ما يروح للـ Production مع 30,000 مهمة ومئات المدراء المتزامنين، ست اختناقات معمارية بيتجمعوا مع بعض عشان يسببوا كارثة أداء حتمية:

الصندوق الأسود لدوال الـ Pipelined Table (TABLE(apex_approval.get_tasks(...))): محرك تحسين الاستعلامات (CBO) مبيقدرش يشوف اللي جوه دوال الـ Pipelined في PL/SQL. مبيقدرش يحسب إحصائيات الداتا ولا توزيعها، فبيفترض أرقام افتراضية عشوائية. والأخطر من كده، شروط الـ WHERE الخارجية مستحيل تنزل جوه استعلام المحرك الداخلي (No Predicate Pushdown)!
فك الـ JSON على الطاير لكل سطر (JSON_VALUE): لأن باراميترات المهام (REQ_ID, EMP_NO, MASTER_PK_ID) متسلسلة جوه نصوص JSON، الكويري مضطر يحلل نصوص JSON لآلاف السطور في كل فتحة شاشة. بنتكلم في أكتر من 90,000 عملية فك JSON مع كل ريفريش!
الربط مع الجداول بتعبيرات الـ Regex (REGEXP_LIKE): لأن بيانات الـ JSON المستخرجة مجرد نصوص غير مفحوصة، الربط مع جدول employees بيتطلب فحوصات Regex وتحويل أنواع. ده بيلغي تماماً استخدام فهارس الـ B-Tree العادية، ويجبر الداتابيز تعمل Full Table Scans مدمرة!
التبديل بين المحركات سطر بسطر (Scalar PL/SQL Context-Switching): استدعاء دوال الـ PL/SQL في جملة الـ SELECT بيسبب آلاف التبديلات المتكررة (Context Switches) بين محرك الـ SQL ومحرك الـ PL/SQL.
الضربة القاضية: فخ التقسيم والترتيب في الـ Interactive Grid: في أبيكس، شاشات الـ Interactive Grid بتغلف أي استعلام بمنطق ترقيم الصفحات (Pagination). أول ما مدير يدوس على رأس أي عمود عشان يرتب المهام (مثلاً بتاريخ الإنشاء أو اسم الموظف)، الداتابيز متقدرش تستخدم اختصارات الـ Pagination. لازم تشغل كل دوال الـ Table functions، وتفك كل نصوص الـ JSON، وتعمل كل الـ Joins، وتنفذ دوال الـ PL/SQL، وترتب الـ 30,000 سطر كلهم في الـ TEMP Tablespace—وبعدين ترمي 29,950 سطر في الزبالة عشان تعرض للمدير أول 50 بس!

🎯 أعراض زحمة الـ 30 ألف مهمة

لو بيئة عملك بتعاني من المشكلة دي، هتلاحظ العلامات الحمراء دي فوراً:

العَرَض	اللي بتشوفه بعينك	السبب الجوهري الحقيقي
شاشات مهام تقيلة ومهنجة	صفحة المهام بتفضل تلف من 12 لـ 25 ثانية قبل ما تفتح.	حسابات الأمان الديناميكية لكل سطر من آلاف المهام غير المفهرسة.
ارتفاع جنوني في الـ CPU	الـ CPU بتاع سيرفر الداتابيز بيوصل 95–100% صباح الإثنين.	مئات المدراء بيشغلوا استعلامات متزامنة بتعمل Joins معقدة مع جداول أبيكس الداخلية.
هنجة وتجميد عند البحث والترتيب	الفلترة برقم الموظف أو الترتيب بالتاريخ بيطلع Gateway Timeout.	عجز محرك التحسين عن دفع شروط البحث داخل دوال الـ Table.
تطفيش المستخدمين	المدراء بيبطلوا يفتحوا شاشة أبيكس ويطالبوا بموافقات يدوي بالإيميل!	بطء وتجربة استخدام مستحيلة في الواجهة.

💡 الحل المعماري: فصل العرض عن ماكينة الحالات (Decoupling)

هل ده معناه إن محرك الـ Workflows في Oracle APEX فيه عيب؟ أبداً على الإطلاق!

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

الغلطة كلها كانت في إننا طلبنا من المحرك ده إنه يشتغل كمان كمحرك بحث سريع وفوري لشاشات العرض والـ Grids!

الحل الهندسي المعتمد عالمياً هو الفصل المعماري (Architectural Decoupling):

خلي محرك APEX Workflows يدير العمليات، وتنقل الحالات، وشروط البيزنس في الخلفية.
أنشئ جدول كاش عمليات خفيف ومفهرس بالمللي (wf_task_cache) معمول مخصوص عشان يغذي شاشات الـ UI في أقل من 50 ميلي ثانية!

flowchart LR
    Engine["محرك Oracle APEX Workflow<br/>(إدارة الحالات والخطوات والشروط)"] 
    -->|Trigger معتمد على الأحداث| 
    Cache["جدول كاش العمليات السريع<br/>(wf_task_cache)<br/>مفهرس وجاهز للعرض"]
    Cache 
    -->|استعلام فهارس في أقل من 50ms| 
    Cockpit["شاشة مهام أبيكس التفاعلية<br/>(Interactive Grid / Report)"]

🚀 إيه اللي مستنينا في الجزء الثاني؟

إزاي نصمم جدول كاش العمليات ده عشان يستوعب ملايين المهام بكل سلاسة ويخلي استعلامات شاشات أبيكس تفتح في غمضة عين وبأقل من 50 ميلي ثانية؟

في الجزء الثاني (“حامل بونات المطبخ: تصميم كاش العمليات عالي السرعة”)، هنبني هيكل جدول wf_task_cache بالكامل، وهندرس استراتيجية الفهارس الذكية، وهنشوف إزاي نكتب استعلامات شاشات بتفتح في فمتو ثانية!

استنونا في الجزء الثاني! 🎫⚡

كتبه: أحمد شريف (Ahmed Sherif).

رقم الشقة الناقص: ليه لازم تحدد الـ Workspace صراحةً في الـ APEX Deployments؟ 🏢📦

Mon, 28 Sep 2026 00:00:00 GMT

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

رقم الشقة الناقص: ليه لازم تحدد الـ Workspace صراحةً في الـ APEX Deployments؟ 🏢📦

لما كابتن الدليفري يوصل بعربيتك عند عمارة السيرفر، يهرش في شعره ويقولك: “هو أنا هسلم App 101 لـ أنهي شقة بالظبط؟!”

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

تخيل طلبت ركنة أو صالون جديد أونلاين، وكتبت في العنوان: “برج الصفوة، الدور الخامس، شقة 502”.

للوهلة الأولى العنوان يبدو كامل ومفهوم.. لحد ما كابتن الدليفري يوصل الموقع ويكتشف إن الكومباوند فيه 3 أبراج توأم بنفس الاسم والتصميم، وكل برج فيهم فيه دور خامس وشقة 502! وطبعاً مفيش رقم أو حرف للبرج على البوليصة. الكابتن هيرفع إيده، مستحيل يجازف ويخمن، وهيختم الشحنة فوراً: “تعذر التسليم: العنوان غير محدد بدقة”.

في عالم Oracle APEX والـ split-source deployments، أداة SQLcl بتعمل معاك نفس الموقف بالظبط لما تسيب الـ Target Workspace عايم من غير تحديد. ورغم إنك ممكن تتغر وتجري ورا حلول سريعة بـ PL/SQL (واللي ممكن تشتغل على جهازك الشخصي بس تفرقع وش في السيرفرات الحقيقية!)، الحل الجذري والاحترافي أبسط بكتير: اعمل ملفات إعدادات منفصلة لكل بيئة عمل (dev.json, staging.json, prod.json) محدد فيها اسم الـ Workspace صراحةً، وارفعها على Git مباشرة.

🚚 ورطة كابتن الدليفري (The Delivery Driver Dilemma)

في شغل Oracle APEX الحديث، كلنا بنحب نعمل export للتطبيقات بصيغة الـ Source Code المقسم (.apx files) عن طريق SQLcl أو إضافة VS Code الرسمية. الطريقة دي بتخلي الـ Git diffs نظيفة وسهلة، وتتبع التعديلات طبيعي، وبتخلي أتمتة الـ CI/CD متعة حقيقية.

أول ما بتعمل export للتطبيق، SQLcl بتنشئ لك ملف إعدادات deployment افتراضي داخل مشروعك اسمه deployments/default.json. في أغلب الأوقات بيكون شكله بسيط جداً زي كده:

{
  "app" : {
    "id" : 101,
    "databaseSession" : {
      "parsingSchema" : "APP_SCHEMA"
    }
  }
}

تبص للملف تقول: “عظمة أوي! إيه المشكلة يعني؟ ما أنا مديله كل حاجة:”

Application ID: 101
Parsing Schema: APP_SCHEMA

وعلى داتابيز التطوير المحلية (Local Sandbox) اللي مفيهاش غير Workspace واحدة يتيمة، كل حاجة بتشتغل زي الفل والـ deployment بيمر بنجاح باهر.

لكن الصدمة بتبدأ أول ما تترقى وتتصل بداتابيز الـ Development المشتركة للشركة أو سيرفر الـ Staging، وتيجي تنفذ أمر الاستيراد apex import، وفجأة… بوووووم! 💥

[APEXLangCommandHandlers] [ERROR] 
Multiple workspaces available, use the workspaceId or the workspace option.

الـ CI/CD Pipeline يقف فجأة، و“بوت الدليفري” يرفض إنه يرمي الكود في أي مكان بالبركة!

🕵️‍♂️ وراء الكواليس: ليه SQLcl رفعت إيديها ووقفت؟

ليه SQLcl ضربت إيرور ومكملتش تثبيت التطبيق؟

لما SQLcl بتيجي تستورد تطبيق APEX من ملفات مجزأة (Split files)، بتحتاج في أول خطوة تثبت حاجة اسمها APEX Workspace Context (معرف الأمان الداخلي للـ Workspace أو الـ Security Group ID)، وده بيحصل قبل ما تنشئ أو تعدل أي صفحة من صفحات التطبيق.

لو ملف الـ deployments/default.json مش محدد فيه اسم الـ Workspace بشكل صريح، SQLcl بتحاول تعمل فيها ذكية وتكتشفه تلقائياً. في الخلفية، بتروح تنفذ استعلام بسيط على جداول الداتابيز:

SELECT workspace FROM apex_workspaces;

في أي داتابيز حقيقية لشركة أو مؤسسة، مستحيل يوزر المطورين يكون مربوط بـ Workspace واحدة بس. غالباً الاستعلام هيرجع لستة محترمة:

DEV_WORKSPACE
FINANCE_WORKSPACE
HR_WORKSPACE
INTERNAL

لما الـ query يرجع أكتر من سطر، SQLcl بترفض التخمين تماماً. لأنها لو خمّنت ونزلت التطبيق في الـ Workspace الغلط، ممكن تمسح شغل زميلك أو تكسر صلاحيات أمان حساسة.

عشان كده بتقفلها في وشك بأمان تام وتقولك: Multiple workspaces available, use the workspaceId or the workspace option.

⚠️ الفخ المغري: حل الـ PL/SQL السريع (بيشتغل عندك ويفرقع في السيرفر!)

كتير من المطورين لما بيقابلوا الإيرور ده، أول فكرة بتيجي في بالهم هي “الترقيع” السريع عن طريق تشغيل كود PL/SQL قبل عملية الاستيراد (Import) كالآتي:

BEGIN
  -- "يا عم أنا هثبت له الـ Workspace ID بإيدي وخلاص!"
  APEX_UTIL.SET_SECURITY_GROUP_ID(1234567890123456);
END;
/

هل الحل ده بيشتغل؟ أيوه.. بس في بيئات معينة جداً!

لو جربت الترقيعة دي على جهازك جوه Docker Container محلي، أو داتابيز تجارب داخل فيها بيوزر الـ DBA الخارق (ADMIN أو SYS)، هتحس إنك عبقري والمشكلة اتحلت في ثواني.

بس تعالى نفهم ليه هو اشتغل في بيئتك المحلية:

صلاحيات السوبر مان: الحساب اللي أنت داخل بيه واخد صلاحية APEX_ADMINISTRATOR_ROLE، ودي بتديه الحق إنه يغير ويدخل أي Workspace على مزاجه.
الربط المباشر موجود: يوزر السيشن بتاع الداتابيز (USERENV('SESSION_USER')) متعرف ومربوط مسبقاً كـ schema مسموح بيها في جدول APEX_WORKSPACE_SCHEMAS لنفس الـ Workspace.

وليه نفس الحل ده بيفرقع في وشك فوراً في بيئات الـ CI/CD المشتركة 💥

أول ما الكود ده يخرج من جهازك ويروح لداتابيز تانية، أو سيرفر Staging مقفول بصلاحيات محدودة، أو أوتوميشن Pipeline، هتخبط في الحيطة دي:

ORA-20987: APEX - Security Group ID (your workspace identity) is invalid.
ORA-06512: at "APEX_260100.WWV_FLOW_SECURITY", line 3145

والسبب بسيط جداً:

الأمان المشدد (Strict Security): في بيئات التيست والإنتاج (Production)، يوزرات الـ Deployment المخصصة للـ CI/CD (زي CI_DEPLOYER) بتكون محدودة الصلاحيات ومش واخدة APEX_ADMINISTRATOR_ROLE. نظام الأمان الداخلي في APEX (WWV_FLOW_SECURITY) بيكتشف المحاولة دي وبيعتبرها اختراق وبيوقف العملية فوراً.
الأرقام دي مش محمولة (Non-Portable IDs): رقم الـ Workspace ID ده مش رقم ثابت، ده مجرد Database Sequence رقمي. يعني الـ Workspace اللي اسمها DEV_WORKSPACE ممكن يكون الـ ID بتاعها 1234567890123456 في بيئة الـ DEV، لكن في الـ STAGING أو الـ PROD هيكون رقم عشوائي تاني خالص! فكرة إنك تكتب أرقام IDs ثابتة (Hardcoded) جوه السكربتات دي أسرع وصفة لخراب أي Pipeline.

عشان كده، الاعتماد على SET_SECURITY_GROUP_ID اليدوي هو مجرد “مسكن مؤقت” مش حل DevOps احترافي.

🔑 الحل الصح والمحترم: ملفات Deployment مستقلة في Git لكل بيئة

بدل ما نعتمد على ملف default.json واحد كل شوية حد يعدل فيه، أو نجري ورا سكربتات PL/SQL هشة بتتغير من سيرفر لسيرفر، الحل الأفضل والمعتمد عالمياً هو: إنشاء ملف إعدادات deployment مستقل لكل بيئة عمل، ورفعه على Git مع الكود.

هيكل المشروع لكل البيئات (Multi-Environment Structure)

داخل مشروع الـ APEX split-source، أداة SQLcl بتتعرف تلقائياً على فولدر اسمه deployments/. بجانب ملف default.json، تقدر تنشئ ملفات واضحة وصريحة لكل سيرفر هترفع عليه:

my-apex-project/
├── src/
│   └── ... (ملفات السورس كود النظيفة .apx)
└── deployments/
    ├── dev.json         ──► بيئة التطوير والـ Dev Schema
    ├── staging.json     ──► بيئة الاختبار والـ QA Schema
    └── prod.json        ──► بيئة الإنتاج والـ Live Schema

كل بيئة هيكون ليها “عقد” واضح ومحفوظ في الـ Version Control.

1. ملف `deployments/dev.json` (بيئة التطوير)

{
  "workspace" : {
    "name" : "DEV_WORKSPACE"
  },
  "app" : {
    "id" : 101,
    "databaseSession" : {
      "parsingSchema" : "APP_DEV"
    }
  }
}

2. ملف `deployments/staging.json` (بيئة الاختبار والتجهيز)

{
  "workspace" : {
    "name" : "STAGE_WORKSPACE"
  },
  "app" : {
    "id" : 201,
    "databaseSession" : {
      "parsingSchema" : "APP_STAGE"
    }
  }
}

3. ملف `deployments/prod.json` (بيئة الإنتاج الحية)

{
  "workspace" : {
    "name" : "PROD_WORKSPACE"
  },
  "app" : {
    "id" : 100,
    "databaseSession" : {
      "parsingSchema" : "APP_DATA"
    }
  }
}

  ┌─────────────────────────────────────────────────────────────┐
  │                 DEPLOYMENTS / <ENV>.JSON                    │
  ├─────────────────────────────────────────────────────────────┤
  │  🏢 workspace.name    ──► اسم الـ Workspace الصريح للبيئة دي │
  │  📦 app.id            ──► رقم التطبيق المستهدف              │
  │  ⚙️ parsingSchema     ──► الـ Schema المالكة للداتا هنا     │
  └─────────────────────────────────────────────────────────────┘

ليه الحل ده بيكسب دايماً؟ 🏆

حاسم ومفيهوش أي لبس (Zero Ambiguity): لأنك حددت "workspace": { "name": "..." } بالاسم الصريح، SQLcl عمرها ما هتحتاج تسأل الداتابيز ولا تخمن. ودعنا للأبد مشهد “مندوب الدليفري الحيران في الباركينج”.
تتبع كامل ومراجعة كود (Auditability & PRs): إعدادات الـ deployment بقت كود عايش جوه Git جنب السورس كود. أي تغيير في اسم Schema أو Workspace هيتراجع في Pull Request ويتسجل مين اللي عمله وليه.
مش محتاج صلاحيات DBA خطيرة: لأن SQLcl بتستخدم دوال الـ APEX Deployment الرسمية بالاسم الصريح، حساب الـ CI/CD مش محتاج APEX_ADMINISTRATOR_ROLE ولا محتاج يوجع دماغه بأرقام الـ IDs المتغيرة.
أتمتة سهلة وسلسة في الـ CI/CD: في أي Pipeline آلي (GitHub Actions, GitLab CI, Azure Pipelines, Jenkins)، اختيار البيئة بيبقى سطر واحد في غاية السهولة:

# في خطوة الـ Deployment في الـ CI/CD Pipeline:
# 1. تفعيل ملف البيئة المستهدفة واستبداله كـ default.json
cp deployments/${TARGET_ENV}.json deployments/default.json

# 2. تشغيل الـ Deployment فوراً وبدون أي مشاكل عبر SQLcl
sql -s user/password@target_db <<EOF
apex import
exit;
EOF

🛡️ شيك ليست (Checklist) ذهبية لـ APEX Deployments سالكة

في المرة الجاية وأنت بتبني أو بتعدل مشروع APEX، اتأكد من النقط دي:

إنشاء ملفات مخصصة لكل بيئة في Git: احفظ dev.json و staging.json و prod.json جوه فولدر deployments/ في الـ Repo.
كتابة workspace.name صراحةً دايماً: اذكر اسم الـ Workspace بالاسم في كل ملف عشان SQLcl متضطرش تخمن أبداً.
ضبط الـ parsingSchema الصحيحة: اتأكد إن الـ Schema المكتوبة بتطابق اليوزر المخصص للداتا في البيئة دي (APP_DEV, APP_STAGE, APP_DATA).
التحقق من صلاحية يوزر الـ Deployer: اتأكد إن يوزر الـ Deployment مصرح له بالتعامل مع الـ Workspace Schema من خلال إدارة APEX العادية ومن غير ما تديله أدوار DBA مفتوحة.

🎯 ملخص الكلام

زي ما كابتن الدليفري محتاج اسم الشارع ورقم البرج ورقم الشقة عشان يسلمك العفش بأمان، أداة SQLcl محتاجة رقم التطبيق (App ID) ومعاه اسم الـ Workspace عشان تنزل كود الـ APEX بتاعك في مكانه الصح والمظبوط.

بلاش الاعتماد على حيل PL/SQL المؤقتة اللي بتشتغل على جهازك وتخذلك في السيرفرات الحقيقية. ثبت ملفات الـ deployment لكل بيئة في الـ Git، وهتضمن إن الـ CI/CD Pipelines بتاعتك تكون صلبة، مستقرة، وشغالة من أول مرة وبدون أي مفاجآت! 🚀✨

إطلاق الصاروخ بالمفتاحين: حراس أمان SQLcl المحكمة للـ Deployments 🔑🚀

Thu, 24 Sep 2026 00:00:00 GMT

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

إطلاق الصاروخ بالمفتاحين: حراس أمان SQLcl المحكمة للـ Deployments 🔑🚀

الجزء السابع (مسك الختام) من سلسلة “مطور APEX المدعوم بالذكاء الاصطناعي”.

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

إنك تدي لـ AI Coding Assistant أو لسكربت آلي اتصال داتابيز مفتوح بصلاحيات DBA خارقة، ده بالظبط زي ما تدي طفل صغير في إيده منشار خشب كهربائي شغال وتقوله “قصقص لنا شوية ورد من الجنينة”! مجرد سوء فهم بسيط، وهتلاقي شجرة الـ Production اتقصت من قاعها ومبقاش ليها أثر!

في ختام السلسلة دي، هنشوف إزاي نبني شبكة أمان لا تخترق عن طريق دمج 3 اتصالات SQLcl معزولة الصلاحيات مع فحوصات تأكيد هوية البيئة والـ Schema قبل تشغيل أي سطر كود.

المعمارية دي مستوحاة من غرف تحكم الغواصات الحربية، حيث إطلاق الصاروخ بيتطلب مفتاحين منفصلين بيلفهم ضابطين في نفس اللحظة—عشان نضمن إن لا AI شارد ولا مطور مرهق الساعة 3 الفجر يقدر ينفذ سكربت بالغلط على الداتابيز الحية!

💥 ورطة المنشار الكهربائي: الصلاحيات في عصر الذكاء الاصطناعي

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

الصبح بيشوف إحصائيات الجداول.
الظهر بيجرب استعلام SELECT سريع.
العصر بيشغل سكربت ALTER TABLE تجريبي.
وبالليل بيصلح Bug طارئة في السيرفر!

لو إنسان غلط بالاتصال ده، ممكن في أسوأ الظروف يمسح جدول بالغلط.

لكن تخيل بقى لما تحط في المعادلة AI Agent ذاتي التوجيه بيكتب وينفذ أكواد بسرعة 100 سطر في الثانية! لو الـ Agent ده شغال بيوزر DBA مفتوح وهبد أمر DROP TABLE ORDERS CASCADE CONSTRAINTS PURGE، خطة طوارئ الكوارث (Disaster Recovery) هتشتغل قبل ما تلحق تمد إيدك وتدوس Ctrl+C!

وكلاء الذكاء الاصطناعي أدوات تسريع مذهلة، بس بيشتغلوا بنظام احتمالي (Probabilistic). وحسب مبدأ أقل صلاحيات ممكنة (Principle of Least Privilege)، مستحيل الـ Agent ياخد صلاحية أكبر من الحد الأدنى الصارم للمهمة اللي رايح يعملها حالا.

🔑 مبدأ كروت الأمان الثلاثة (The 3 Keycards)

عشان نخلي عمليات الداتابيز آمنة بنسبة 100%، استبدلنا المفتاح السحري الواحد بـ 3 اتصالات مسماة ومعزولة الصلاحيات جوه SQLcl:

1. READER_SQLCL_CONNECTION   → 🔍 كارت القراءة فقط (للبحث والاستعلامات)
2. DEPLOYER_SQLCL_CONNECTION → 🛠️ كارت المطور المحدود (DDL/DML جوه DEV بس)
3. METADATA_SQLCL_CONNECTION → 🪞 كارت المراية (لتشغيل DBMS_METADATA فقط)

تعالوا نشوف حدود كل كارت فيهم:

الكارت 1: القارئ (`READER_SQLCL_CONNECTION`)

الصلاحية: واخد صلاحية SELECT فقط على جداول التطبيق وقواميس الداتابيز (ALL_TABLES, ALL_DEPENDENCIES).
عمليات الـ DDL والـ DML: ممنوعة منعاً باتاً. مستحيل يعمل INSERT أو UPDATE أو DROP.
بيشتغل إمتى: لما الـ AI بيحقق في bug، أو بيفحص العلاقات، أو بيتأكد من أنواع الأعمدة. حتى لو الـ AI اتجنن وطلع أمر مسح، محرك أوراكل هيرميه في وشه بإيرور ORA-01031: insufficient privileges.

الكارت 2: الناشر (`DEPLOYER_SQLCL_CONNECTION`)

الصلاحية: واخد صلاحيات كتابة مقفولة بالمللي جوه سكيما التطوير فقط (زي APP_CODE).
بيشتغل إمتى: لما توافق على السكربتات المجهزة في ai_generate/YYYY-MM-DD/ وتشغلها على جهازك أو سيرفر الـ Dev. معندوش أي وصول لسيرفرات الـ Production أو الـ Staging.

الكارت 3: مراية الميتاداتا (`METADATA_SQLCL_CONNECTION`)

الصلاحية: يوزر مخصص ومقيد لتشغيل حزم DBMS_METADATA وسحب ملفات التصدير عبر SQLcl.
بيشتغل إمتى: بيشتغل أوتوماتيكياً في خلفية سكربتات المزامنة لتحديث فاترينة database/<schema>/.

بحفظ الاتصالات دي في مخزن SQLcl المشفر (conn -save <name>)، السكربتات بتتنقل بين الاتصالات بالأسماء المستعارة من غير ما تعرض باسووردات على المكشوف في الشات:

sql /nolog
conn -save DEV_READER my_reader_user/secret_pass@dev_db
conn -save DEV_DEPLOYER my_code_user/secret_pass@dev_db

🚀 كونسول الغواصة المزدوج: فحوصات تأكيد السكيما قبل التنفيذ

إنك تعمل اتصالات بأسماء مستعارة ده شيء عظيم، بس إيه اللي يضمن إن سكربت مخصص لداتابيز APP_DEV ميروحش يتنفذ بالغلط على APP_PROD؟

في الغواصات الحربية، إطلاق الصاروخ بيتطلب إن اتنين ضباط يلفوا مفتاحين فيزيائيين بعيد عن بعض في نفس الوقت. ولا واحد فيهم يقدر يضرب لوحده.

في الـ Pipeline بتاعنا، بنطبق نفس الأمان الصارم ده بإضافة بلوك فحص واختبار أمان إجباري (Pre-Flight Assertion Guard) في أول كل سكربت Migration بيتولد في ai_generate/:

-- ====================================================================
-- سكربت: ai_generate/2026-09-05/01_deploy_customer_loyalty.sql
-- بلوك اختبار وتأكيد الأمان قبل تنفيذ أي سطر
-- ====================================================================

-- 1. لو حصل أي خطأ.. اخرج فوراً واعمل Rollback لكل حاجة!
whenever sqlerror exit failure rollback;
set serveroutput on;

declare
    c_expected_schema constant varchar2(30) := 'APP_CODE';
    c_forbidden_db    constant varchar2(30) := 'PROD_DB';
    
    v_current_schema  varchar2(30);
    v_current_db      varchar2(30);
begin
    -- استخراج بيانات السيشن النشطة حالياً
    select sys_context('USERENV', 'CURRENT_SCHEMA'),
           sys_context('USERENV', 'DB_NAME')
      into v_current_schema,
           v_current_db
      from dual;

    -- الفحص 1: رفض قاطع لو الداتابيز هي الـ Production المحمية
    if upper(v_current_db) = c_forbidden_db then
        raise_application_error(-20001,
            '🚨 إنذار أحمر! محاولة تنفيذ سكربت على داتابيز الـ Production المحمية: ' || 
            v_current_db || '. تم إيقاف العملية فوراً!');
    end if;

    -- الفحص 2: التأكد من مطابقة السكيما المتصلة بالسكيما المستهدفة
    if upper(v_current_schema) != c_expected_schema then
        raise_application_error(-20002,
            '⚠️ تضارب في السكيما! السكربت مصمم لـ [' || c_expected_schema || 
            '] وأنت متصل حالياً بـ [' || v_current_schema || ']. تم إلغاء العملية.');
    end if;

    dbms_output.put_line('====================================================');
    dbms_output.put_line('✓ فحص الأمان نجح: متصل بـ ' || v_current_schema || ' على داتابيز ' || v_current_db);
    dbms_output.put_line('====================================================');
end;
/

-- ====================================================================
-- كود الـ DDL أو الـ DML الحقيقي بيبدأ هنا بعد نجاح الفحص
-- ====================================================================
ALTER TABLE CUSTOMERS ADD (
    LOYALTY_POINTS NUMBER(10,0) DEFAULT 0 NOT NULL,
    LOYALTY_TIER   VARCHAR2(20) DEFAULT 'BRONZE' NOT NULL
);

إيه اللي بيحصل لما يقع خطأ؟

لو حد بالغلط شغل السكربت ده وهو متصل بداتابيز تانية:

كشف فوري في أجزاء من الثانية: الأسطر الأولى بتفحص CURRENT_SCHEMA و DB_NAME. لو مفيش تطابق، كود الـ PL/SQL بيرمي خطأ غير معالج (ORA-20001 أو ORA-20002).
تراجع فوري وخروج آمن (Instant Rollback & Exit): لأن أول سطر في الملف مكتوب فيه whenever sqlerror exit failure rollback، أداة SQLcl بتلقط الخطأ فوراً، وتلغي أي تعديل معلق، وتقفل الجلسة وتخرج بكود فشل.
ولا سطر كود بيتنفذ: أمر الـ ALTER TABLE اللي مكتوب تحت مستحيل يتقرأ أو يدخل محرك الداتابيز أصلاً!

داتابيز الإنتاج بتاعتك محمية ومستحيل تنضرب بالخطأ! 🛡️

🏁 الأعمدة السبعة لمطور Oracle APEX المدعوم بالذكاء الاصطناعي

على مدار السلسلة دي المكونة من 7 أجزاء، بنينا نموذج عمل هندسي متكامل للمؤسسات:

معمارية مطور APEX الحديث:
┌──────────────────────────────────────────────────────────┐
│ 7. حراس الـ Deployments بالمفتاحين وفحوصات SQLcl         │  ← أمان حديدي
├──────────────────────────────────────────────────────────┤
│ 6. جلسة التعارف والذاكرة الدائمة بفولدر app_context/    │  ← صفر زهايمر
├──────────────────────────────────────────────────────────┤
│ 5. تقسيم المعمل النظيف لـ 4 مناطق (Apps / Mirror / Stage)│  ← مفيش خلط
├──────────────────────────────────────────────────────────┤
│ 4. استعلامات الجراف بدون هدر عبر Graphify CLI            │  ← توفير 90% توكنز
├──────────────────────────────────────────────────────────┤
│ 3. الـ AST Architectural Knowledge Graph                 │  ← الحقيقة المعمارية
├──────────────────────────────────────────────────────────┤
│ 2. التقسيم الذكي بلغة APEXlang (.apx)                    │  ← Git Diffs نظيفة
├──────────────────────────────────────────────────────────┤
│ 1. الهروب من فخ ملفات الـ SQL الضخمة والتوكنز            │  ← سرعة وتوفير
└──────────────────────────────────────────────────────────┘

هربنا من فخ التوكنز: بطلنا نرمي 150 ألف سطر للـ AI ووفرنا فواتير الـ API من الجذور.
اتعلمنا APEXlang (.apx): فككنا التطبيقات لملفات مقروءة وواضحة للبشر والذكاء الاصطناعي.
بنينا الـ Knowledge Graph: رسمنا شاشاتنا وزرايرنا وجداولنا في شبكة علاقات هندسية قطعية.
استعلمنا بدون هدر: استخدمنا Graphify عشان نسحب الـ 10 نود المطلوبين بالمللي لكل ميزة.
فرضنا معمارية المعمل النظيف: 4 فولدرات فيزيائية بتمنع خلط الكود الحي بمرايات الداتابيز وتجارب الـ AI.
قضينا على زهايمر الـ LLMs: فولدر app_context/ وأمر /init بيخلوا الـ AI جاهز في 30 ثانية.
حمينا الـ Deployments: بنينا حراس الأمان المزدوجة في SQLcl لمنع أي أخطاء في الـ Production.

🛠️ ابنيها بنفسك، أو انطلق بالقالب الجاهز

كل تقنية ومعمارية اتشرحت في السلسلة دي هي مبادئ هندسية مفتوحة (Open Engineering Principles). تقدر تطبقها فوراً في مشروعاتك القائمة، سواء شغال بـ Git أو Jenkins أو GitLab CI أو Cursor أو غيرهم.

لكن لو عايز تنطلق بنموذج مجرب وناجح الأعمدة السبعة فيه متظبطة وشغالة وجاهزة للانطلاق فوراً:

👉 شوف APEX Project Template المفتوح المصدر على GitHub!

جواه هتلاقي:

تقسيم المعمل النظيف لـ 4 فولدرات جاهز.
سكربتات استخراج الـ AST والـ Graphify جاهزة (setup_graphify_apx.py).
قوالب app_context/<app-id>/ وأمر التهيئة السريع /init.
حراس الأمان لـ SQLcl والاتصالات المعزولة مسبقاً.

سواء عملت Clone للقالب أو اقتبست منه أفكار لمشروعك، دلوقتي بقى معاك الأدوات الحقيقية عشان تبني تطبيقات Oracle APEX أسرع، وأنظف، وأكثر استقراراً من أي وقت مضى.

برمجة ممتعة للجميع، ومرحباً بكم في مستقبل تطوير Oracle APEX مع الذكاء الاصطناعي! 🚀✨

كتبه: أحمد شريف (Ahmed Sherif).

جلسة التعارف من أول يوم: إزاي تدي الـ AI ذاكرة دائمة بفولدر app_context/ 📓🧠

Sun, 20 Sep 2026 00:00:00 GMT

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

جلسة التعارف من أول يوم: إزاي تدي الـ AI ذاكرة دائمة بفولدر app_context/ 📓🧠

الجزء السادس من سلسلة “مطور APEX المدعوم بالذكاء الاصطناعي”.

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

الشغل مع مساعد ذكاء اصطناعي معندوش سياق دائم للمشروع، عامل بالظبط زي ما تعين استشاري كبير عبقري بس بيصحى كل يوم الصبح ناسي كل حاجة حصلت في حياته! كل يوم محتاج تشرح له من الصفر مكنة القهوة فين، وأنهي Schema اللي فيها بيانات العملاء، وليه أسامي الجداول في شركتنا لازم تبدأ بـ HR_!

بدل ما تقعد تنسخ وتلزق ديباجة برومبت طويلة ومملة في بداية كل شات جديد، تقدر تنشئ فولدر app_context/<app-id>/ وتربطه بـ طقس تهيئة سريع عبر أمر /init.

الحركة دي بتسلم الـ Agent بتاعك “دوسيه ترحيب وذاكرة مؤسسية” بتحول أي جلسة شات فاضية لشريك برمجة فاهم كل تكة في معمارية نظامك في أقل من 30 ثانية!

🤯 يوم اليرموك اليومي مع مساعدي الذكاء الاصطناعي

لو قضيت أكتر من أسبوعين بتبرمج بمساعدة أدوات الـ AI، فأنت أكيد حافظ الحوار اليومي السخيف ده:

جلسة رقم 1 (يوم الإثنين):
أنت: "اعمل لي شاشة طلب كارت موظف جديد في صفحة 20."
الـ Agent: "من عينيّا! هعمل جدول T_BADGES بعمود Identity بيزيد تلقائي..."
أنت: "لأ يا عم الحج! حسب معايير شركتنا، كل جداول الـ HR بتستخدم Sequence اسمه HR_SEQ_، 
      ولازم أعمدة التدقيق الإلزامية (CREATED_BY, CREATED_ON)، 
      وتسمية الـ Packages بنظام PKG_HR_<MODULE>_API!"
الـ Agent: "أعتذر جداً عن الخطأ! هعيد كتابة الكود حسب معاييركم..."

(تقفل الشات، تنام، وتفتح شات جديد خالص صباح يوم الثلاثاء)

جلسة رقم 2 (يوم الثلاثاء):
أنت: "دلوقتي اعمل لي شاشة الموافقات المنبثقة في صفحة 21."
الـ Agent: "تمام جداً! هعمل جدول T_APPROVALS بعمود Identity بيزيد تلقائي..."
أنت: "🤦‍♂️ هو إحنا هنعيد نفس الموشح كل يوم الصبح؟!"

التكرار اللانهائي ده بيحرق أعصابك، وبيشتت تركيزك، وبيحرق رصيد التوكنز. نموذج الذكاء الاصطناعي مش قاصد يعاندك ولا كسلان—هو ببساطة شغال بنظام (Stateless)؛ كل جلسة جديدة بتبدأ بصفحة بيضاء تماماً وميعرفش أي حاجة عن ماضيك معاه.

قوالب الـ System Prompts في واجهات الشات بتساعد شوية، بس بتقدم بسرعة، وبتتوه بين فروع الـ Git، ومبتتشاركش بين أعضاء الفريق.

عشان نحل المشكلة دي للأبد، بنتعامل مع السياق كأنه كود برمجي (Context as Code).

📓 دوسيه الترحيب: فولدر `app_context/<app-id>/`

في شغل السوفتوير الحديث المدعوم بالذكاء الاصطناعي، كل تطبيق في مستودعك لازم يحتفظ بـ “دوسيه توثيق حي” جوه فولدر app_context/<app-id>/:

my-apex-project/
└── app_context/
    └── 100/                          ← رقم تطبيق أبيكس (نظام الـ ERP أو الـ HR)
        ├── APP_ARCHITECTURE.md      ← المعمارية العامة ونظام الأمان والصلاحيات
        ├── DATABASE_MODEL.md        ← الـ Schemas، معايير التسمية، والجداول
        ├── BUSINESS_RULES.md        ← قيود البيزنس والحدود المالية الثابتة
        └── CONVENTIONS.md           ← معايير كتابة الكود وتسمية عناصر أبيكس

دي مش مواصفات ميتة من 500 صفحة؛ دي ملفات Markdown مركزة جداً ومكتوبة بنقاط سريعة بتحدد قواعد اللعبة للتطبيق ده تحديداً.

تعالوا نشوف كل ملف فيهم بيشيل إيه:

1. ملف `APP_ARCHITECTURE.md` (الرسم المعماري)

بيحدد التطبيق مبني إزاي، نظام الأمان، وشجرة القوائم:

# تطبيق 100: بوابة إدارة الطلبات والمبيعات
- **إصدار أبيكس المستهدف**: APEX 26.1 (Universal Theme)
- **المصادقة الأساسية**: نظام مصادقة مخصص (`PKG_AUTH.AUTHENTICATE`)
- **خطط الصلاحيات (Authorization Schemes)**:
  - `AUTH_ADMIN`: بيتطلب دور `ROLE_ADMIN` في جدول `APP_USERS`
  - `AUTH_SALES_REP`: الدور الافتراضي لكل الموظفين
- **مكونات عامة في التطبيق**:
  - صفحة 0 (Global Page): فيها شريط التنبيهات الموحد للرسائل الإدارية
  - قائمة التنقل: قائمة ديناميكية معتمدة على `USER_PERMISSIONS_V`

2. ملف `DATABASE_MODEL.md` (معايير الداتابيز)

بيثبت حدود الـ Schemas، ملكية الجداول، وطريقة توليد المفاتيح:

# معايير قاعدة البيانات والـ Schemas
- **معمارية الـ Dual-Schema المزدوجة**:
  - `APP_CODE`: مالك كود البرمجة (الـ Packages، والـ Views، ويوزر الـ Deployer)
  - `APP_DATA`: مالك البيانات والجداول (Tables، Indexes، Sequences)
- **معيار المفتاح الأساسي (PK)**: عمود `NUMBER(18,0)` بيتغذى من Sequence صريح عبر Trigger (`SEQ_<TABLE_NAME>`)
- **أعمدة التدقيق الإلزامية في كل الجداول بدون استثناء**:
  - `CREATED_ON DATE DEFAULT SYSDATE NOT NULL`
  - `CREATED_BY VARCHAR2(100) DEFAULT NVL(V('APP_USER'), USER) NOT NULL`
  - `UPDATED_ON DATE`
  - `UPDATED_BY VARCHAR2(100)`
- **قاعدة الحذف المنطقي (Soft-Delete)**: الجداول الحساسة بتستخدم `IS_DELETED CHAR(1) DEFAULT 'N' CHECK (IS_DELETED IN ('Y', 'N'))`

3. ملف `BUSINESS_RULES.md` (قواعد البيزنس الثابتة)

بيسجل شروط البيزنس عشان الـ AI ميهبدش منطق يخالف سياسة الشركة:

# قواعد ومنطق البيزنس الجوهرية
1. **شرائح الخصومات للعملاء**:
   - خصم حتى 15%: بيعتمد أوتوماتيكياً بدون مراجعة.
   - خصم من 15% وحتى 30%: بيتطلب موافقة صريحة من مدير المبيعات.
   - خصم أكتر من 30%: ممنوع تماماً؛ ويرمي Exception برقم `-20050`.
2. **دورة حياة الأوردر (Order State Machine)**:
   - `DRAFT` ──> `SUBMITTED` ──> `APPROVED` ──> `FULFILLED`
   - مستحيل الأوردر ينط من مسودة `DRAFT` لمعتمد `APPROVED` مباشرة.

4. ملف `CONVENTIONS.md` (دليل الأسلوب وتسمية العناصر)

بيقفل أي نقاش أو تضارب في التسمية، وبيخلي أي كود طالع كأن أشطر مهندس Senior في الفريق هو اللي كاتبه:

# معايير التسمية في APEX و PL/SQL
- **حقول الصفحات**: `P<PAGE>_<PURPOSE>` (مثال: `P12_CUSTOMER_NAME`, `P12_ORDER_TOTAL`)
- **الزراير**: `BTN_<ACTION>` (مثال: `BTN_SUBMIT`, `BTN_CANCEL`, `BTN_APPLY_DISCOUNT`)
- **الـ Dynamic Actions**: `DA_<EVENT>_<TARGET>` (مثال: `DA_CHANGE_DISCOUNT_CODE`)
- **عمليات الصفحات**: `PROC_<ACTION>` (مثال: `PROC_SAVE_ORDER_HEADER`)
- **أسماء الـ Packages**: `PKG_<MODULE>_API` (مثال: `PKG_CHECKOUT_API`)

🚀 بروتوكول الـ `/init`: تأهيل في 30 ثانية

بعد ما جهزت الدوسيه ده، إزاي توكله للـ Agent من غير ما تفضل تقص وتلزق كل مرة؟

بتعمل طقس تهيئة بسيط جداً: أمر /init.

كل ما تفتح شات جديد في Cursor أو Antigravity أو التيرمينال، كل اللي بتعمله إنك بتكتب:

/init

الـ Agent بيشغل روتين التهيئة القياسي:

قراءة ملف .env: بيعرف التطبيق النشط (100) والـ Schema المستهدفة (APP_CODE).
فحص app_context/100/: بيقرا الملفات الأربعة المعمارية.
التأكد من الـ Knowledge Graph: بيتأكد إن شبكة العلاقات محدثة.
طباعة شاشة التأكيد الخضراء:

[تم تجهيز الـ Agent بنجاح]:
✓ التطبيق المحمل: 100 ("بوابة إدارة الطلبات والمبيعات")
✓ الـ Schemas النشطة: APP_CODE (للبرمجة) | APP_DATA (للداتا)
✓ المعايير المفروضة: تريجرات الـ Sequences، أعمدة الـ Audit، بادئات P<PAGE>_*
✓ قواعد البيزنس مفعلة: شرائح موافقات الخصم ودورة حياة الأوردر
✓ حالة الـ Knowledge Graph: تم فهرسة 412 Node و 980 علاقة
أنا جاهز لتعليماتك يا فنان!

من اللحظة دي، أي حقل الـ Agent هيبنيه هيبدأ بـ P12_، وأي جدول هيعمله هيحتوي على أعمدة الـ Audit الأربعة، وأي شرط خصم هيطبق شرائح البيزنس المظبوطة—من أول محاولة وبدون أي أخطاء!

🎁 المكسب المزدوج: ذاكرة للذكاء الاصطناعي وتأهيل سريع للبشر!

أحلى ما في دوسيه app_context/ إنه بيضرب عصفورين بحجر واحد:

نفس الملفات الأربعة اللي بتدي للـ AI ذاكرة خارقة، بتحل واحدة من أكبر عقد الشركات البرمجية: تأهيل المطورين الجدد (Developer Onboarding).

لما ينضم لفريقك مطور Junior جديد أو استشاري خارجي، بدل ما تقعد معاه أسبوعين تشرح له معايير التسمية وجداول الداتابيز، بتديه فولدر app_context/<app-id>/. في خلال ساعة واحدة بس، بيبقى فاهم معمارية المشروع وقواعد البيزنس كأنه شغال معاكم من سنتين!

🛠️ إزاي تضيف فولدر السياق لمشروعك؟

مش هياخد منك 15 دقيقة:

أنشئ الفولدر: ضيف app_context/ في الـ Root.
اكتب الملفات الأربعة: APP_ARCHITECTURE.md، و DATABASE_MODEL.md، و BUSINESS_RULES.md، و CONVENTIONS.md.
اربطه بتعليمات الـ Agent: جوه ملف القواعد (مثل AGENTS.md) كالآتي:

“لما اليوزر يكتب /init، اقرأ ملف .env، وحمل كل ملفات الـ Markdown في app_context/<app-id>/، وأكد تحميل السياق قبل ما تبدأ البرمجة.”

[!TIP]

📦 عايز قوالب سياق جاهزة؟

مستودع APEX Project Template بيحتوي على قوالب Markdown جاهزة لفولدر app_context/ مع سكربت /init وقواعد الـ Agents متظبطة. تقدر تاخدها كوبي وبيست في مشروعك وتعدل عليها فوراً!

🚀 إيه اللي مستنينا في مسك الختام (الجزء السابع)؟

دلوقتي كودنا بقى مقسم لملفات .apx نظيفة، وعلاقاتنا مرسومة في Knowledge Graph، ومناطق المعمل النظيف معزولة، والـ Agent بقى معاه ذاكرة حديدية مابتنساش.

مفاضلش غير قطعة واحدة أخيرة وحاسمة جداً: زرار إطلاق الصاروخ للـ Deployment.

إزاي نسمح للـ AI أو لسكربتات الـ CI/CD تشغل الـ Migrations عبر SQLcl من غير الرعب القاتل إن سكربت تجارب يضرب في داتابيز الـ Production الحية؟

في ختام السلسلة، الجزء السابع (“إطلاق الصاروخ بالمفتاحين: حراس أمان SQLcl المحكمة”)، هنبني Pipeline مزدوج المفاتيح باتصالات معزولة الصلاحيات وفحوصات هوية آلية تحميك من أي خطأ بشري أو ذكاء اصطناعي!

نشوفكم في الحلقة الأخيرة الكبيرة! 🔑🚀✨

كتبه: أحمد شريف (Ahmed Sherif).

عزل المعمل النظيف: ليه سورس كودك، ومرايات الداتابيز، وتجارب الـ AI مستحيل يختلطوا؟ 🧼🚪

Wed, 16 Sep 2026 00:00:00 GMT

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

عزل المعمل النظيف: ليه سورس كودك، ومرايات الداتابيز، وتجارب الـ AI مستحيل يختلطوا؟ 🧼🚪

الجزء الخامس من سلسلة “مطور APEX المدعوم بالذكاء الاصطناعي”.

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

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

لما تيجي تبرمج مع وكلاء البرمجة بالذكاء الاصطناعي، أنت محتاج نفس الانضباط الفيزيائي الصارم ده بالمللي. لو رميت كل ملفات التطبيق، وملفات سحب الـ DDL، وسكربتات الـ AI الجديدة في فولدر واحد عايم، الـ Agent عاجلاً أو آجلاً هيدخل يعدل في ملفات المراية بإيده، أو يعيد كتابة سكربتات migrations قديمة، أو يرفع ملفات تجارب عشوائية على الـ Git!

بتطبيق معمارية المعمل النظيف ذات الـ 4 مناطق، بتبني حائط صد فيزيائي لا يمكن اختراقه بين سورس كود التطبيق الحي، ومرايات الداتابيز المخصصة للقراءة فقط، وحجرات تجارب الـ AI المعزولة للمراجعة البشرية.

🏥 كابوس الفولدر المفتوح على البحري (The Flat Directory)

كل مطور اشتغل مع مساعد ذكي ذاتي التوجيه في مشروع ملوش حدود فيزيائية واضحة عاش لحظة “العرق الساقع” دي:

أنت بتطلب من الوكيل الذكي (الـ Agent) الآتي:

“محتاجين نضيف عمود MIDDLE_NAME في جدول CUSTOMERS، ونحدث شاشة تعديل بيانات العميل.”

الـ Agent يرد بكل نشاط وحماس:

“كله تمام يا باشا! حدثت لك تعريفات الداتابيز بالكامل!”

تفتح الـ Git Diff وأنت متوقع تشوف سكربت Migration جديد وشيك، فتتصدم بالمشهد العبثي:

تشويه المراية (Mirror Mutation): الـ Agent فتح ملف database/tables/CUSTOMERS.sql—اللي المفروض يكون نسخة قراءة فقط جاية طازة من DBMS_METADATA—ودخل كتب العمود الجديد بإيده جوه الملف! الداتابيز الحقيقية محدش لمسها، بس الـ Git دلوقتي بيدعي إن الجدول اتخلق بالعمود ده من أول يوم في التاريخ!
تعديل السكربتات التاريخية القديمة: أو الأسوأ من كده: الـ Agent لقى ملف migrations/001_initial_schema.sql معمول من سنتين، فدخل عدل فيه وحط العمود الجديد هناك، وبوظ كل سجلات تتبع الـ Deployments!
تلوث المستودع بالكراكيب: الفولدر الرئيسي بقى ماليان ملفات تجارب عشوائية زي test_query.sql و temp_output.json وسكربتات بايثون مكسورة رماها الـ Agent وهو شغال.

ليه ده بيحصل؟ لأن نماذج الذكاء الاصطناعي مبيفهموش الحدود غير المرئية. لو الملف موجود في الفولدر والـ Agent معاه صلاحية كتابة، هيعتبره سورس كود يقدر يعدل فيه براحته!

عشان كده إحنا مبنعتمدش على التنبيهات الضعيفة في الـ Prompt زي “أرجوك متعدلش في فولدر المراية”. إحنا بنفرض حدود فيزيائية للمعمل النظيف.

🚪 معمارية المعمل النظيف ذات الـ 4 فولدرات (Cleanroom Architecture)

سواء بتدير تطبيق أبيكس صغير أو نظام مؤسسي عملاق، تقسيم المستودع لـ 4 مناطق فيزيائية مستقلة بيضمنلك الأمان والراحة التامة:

my-apex-project/
├── apps/<schema>/<app-id>/         ← ✏️ المنطقة 1: سورس كود شاشات أبيكس الحية (.apx)
├── database/<schema>/              ← 🪞 المنطقة 2: فاترينة المراية (للقراءة فقط من DBMS_METADATA)
├── ai_generate/YYYY-MM-DD/         ← 🚀 المنطقة 3: غرفة العزل ومطبخ السكربتات للمراجعة البشرية
└── scratch/                        ← 🗑️ المنطقة 4: سلة التجارب المؤقتة (مهملة في الـ Git)

تعالوا نعمل جولة سريعة جوه كل منطقة ونشوف إزاي بتحمي شغلك.

المنطقة 1: `apps/` (ورشة العمل الحية)

ده المكان اللي بيعيش فيه سورس كود شاشات تطبيق أبيكس.

إيه اللي موجود هنا: ملفات لغة APEXlang (.apx) المقسمة، ومكونات الـ Shared Components، والقوائم، وإعدادات التطبيق.
مين اللي بيعدل هنا: أنت والـ AI بتعدلوا هنا مباشرة لما تبنوا صفحات جديدة أو تعدلوا في شاشات موجودة.
ليه المكان ده آمن: لأن كل صفحة معزولة تماماً في ملفها المستقل (زي page_00012.apx)، فمستحيل تعديل صفحة 12 يخبط بالخطأ في صفحة 40!

المنطقة 2: `database/` (المراية المحرمة: للعرض فقط!)

الفولدر ده هو الانعكاس الرقمي الصافي لداتابيز أوراكل الحية.

إيه اللي موجود هنا: سحب كامل ونظيف لتعريفات الجداول، والـ Views، والـ Package Specs، والـ Triggers (مسحوبة عبر DBMS_METADATA).
القاعدة الحديدية: ممنوع نهائياً على أي إنسان أو AI إنه يعدل ملف جوه database/ بإيده!
بيتحدث إزاي: بيتحدث فقط وحصرياً عبر سكربتات التصدير الآلية بعد ما الـ Migrations تتراجع وتتنفذ على الداتابيز الحقيقية.
حماية الحدود: حط قاعدة في الـ Git pre-commit hooks ترفض أي تعديل يدوي في الفولدر ده.

المنطقة 3: `ai_generate/YYYY-MM-DD/` (غرفة العزل والمراجعة)

لما الـ AI ينشئ جدول جديد، أو يكتب سكربت ALTER TABLE، أو يبرمج Package Body جديدة، يحط الملفات فين؟

ممنوع يرميها على الداتابيز مباشرة، وممنوع يقرب من فولدر المراية database/. بيكتبها جوه فولدر عزل مؤرخ باليوم:

ai_generate/2026-09-05/
├── 01_add_middle_name_to_customers.sql
├── 02_pkg_customer_api_body.sql
└── deployment_manifest.txt

ليه غرفة العزل دي فكرة عبقرية؟

مراجعة بشرية مع كوباية الشاي: تقدر تفحص كود الـ SQL سطر سطر قبل ما يتنفذ على الداتابيز.
سجل تدقيق تاريخي لا يتغير: لو بعد 3 شهور حد سأل “هو العمود ده اتضاف ليه ومين اللي عمله؟”، تلاقي السكربت والملف بتاريخه المحفوظ في الـ Git.
تراجع بدون أي خساير (Effortless Rollback): لو جربت فكرة ومطلعتش حلوة، امسح فولدر ai_generate/2026-09-05/ في ثانية، وكود مشروعك الأصلي يفضل نظيف 100%!

المنطقة 4: `scratch/` (سلة التجارب المؤقتة)

كل مطور وكل AI Agent محتاج مكتب متكركب يجرب فيه تعبيرات الـ Regex، ويرمي فيه ردود JSON مؤقتة من APIs، أو يجرب سكربتات سريعة.

إيه اللي هنا: ملفات تجارب عشوائية، لوجات مؤقتة، ومخرجات جراف تمهيدية.
حالتها في الـ Git: معمولها Gitignore بنسبة 100%.
القاعدة الذهبية: أي حاجة جوه scratch/ تقدر تدلتها في أي لحظة من غير ما تقلق على مشروعك.

🔄 دورة حياة الميزة خطوة بخطوة

تعالوا نشوف إزاي التقسيم ده بيحول مهمة تطوير بالذكاء الاصطناعي من مخاطرة مرعبة لـ Pipeline هندسي محكم:

sequenceDiagram
    autonumber
    actor Dev as المطور البشري
    participant Agent as الـ AI Coding Agent
    participant Stage as ai_generate/YYYY-MM-DD/
    participant DB as داتابيز أوراكل
    participant Mirror as database/<schema>/

    Dev->>Agent: "ضيف عمود LOYALTY_POINTS لجدول CUSTOMERS"
    Agent->>Stage: بيكتب سكربت 01_alter_customers.sql
    Dev->>Stage: بيراجع كود الـ SQL ويوافق عليه
    Dev->>DB: بينفذ السكربت عبر SQLcl
    Dev->>Mirror: بيشغل سكربت المزامنة التلقائية
    Mirror-->>Dev: تحديث database/customers.sql بملف DDL طازة

الطلب: طلبت من الـ AI إضافة عمود وتحديث شاشة العميل.
الكتابة في غرفة العزل: الـ Agent بيكتب السكربت في ai_generate/2026-09-05/.
المراجعة البشرية: أنت بتراجع الكود، وتتأكد من الـ Data Types والـ Constraints.
التنفيذ: بتنفذ السكربت على داتابيز التطوير باستخدام SQLcl وحراس الأمان.
مزامنة المراية: سكربت التصدير الآلي بيشتغل ويسحب ميتاداتا الجدول الجديد في database/.
الـ Git Commit: بترفع التعديل المعتمد والمراية المحدثة في كوميت واحدة نظيفة ومحترمة.

صفر كوارث. صفر تضارب في الداتابيز. وصفر تهييس من الـ AI يلمس الـ Production!

🛡️ إزاي تطبق المعمل النظيف في أي مشروع؟

مش محتاج أدوات مدفوعة نهائياً:

أنشئ الفولدرات الأربعة: apps/، و database/، و ai_generate/، و scratch/.
ظبط ملف .gitignore: ضيف /scratch/ وأي ملفات أسرار محلية.
عرف وصايا الـ Agent بوضوح: جوه ملف القواعد (مثل AGENTS.md أو .cursorrules) كالآتي:
- “ممنوع تماماً تعديل أي ملف جوه database/.”
- “كل سكربتات الـ SQL والـ Migrations الجديدة تتكتب حصراً في ai_generate/<YYYY-MM-DD>/.”
- “تعديلات الشاشات تكون جوه فولدر apps/ فقط.”

[!TIP]

📦 عايز مشروع متظبط وجاهز بالمعمل النظيف؟

مستودع APEX Project Template المفتوح المصدر بيجي ومعاه المعمل النظيف ده متظبط بالكامل بسكربتات المزامنة وقواعد الـ Agents. تقدر تستخدمه فوراً وتبني عليه بثقة تامة!

🚀 إيه اللي مستنينا في الجزء السادس؟

دلوقتي بعد ما قفلنا حدود المشروع الفيزيائية، بنقابل مشكلة تانية مشهورة جداً في الشغل مع الذكاء الاصطناعي: زهايمر الـ LLM.

كل ما تفتح شات جديد، الـ AI بينسى أسماء الـ Schemas، وتسمية المتغيرات، ورقم التطبيق اللي شغالين عليه!

في الجزء السادس (“جلسة التعارف: منح الـ AI ذاكرة دائمة بفولدر app_context/”)، هنشوف إزاي ملفات السياق الموجهة وأمر التهيئة /init بيمحوا الزهايمر ده للأبد!

استنونا في الجزء السادس! 📓✨

كتبه: أحمد شريف (Ahmed Sherif).

سياق بدون هدر: استعلام اعتماديات أبيكس عبر Graphify بدقة جراحية 🎯⚡

Sat, 12 Sep 2026 00:00:00 GMT

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

سياق بدون هدر: استعلام اعتماديات أبيكس عبر Graphify بدقة جراحية 🎯⚡

الجزء الرابع من سلسلة “مطور APEX المدعوم بالذكاء الاصطناعي”.

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

لما تروح مكتبة أبحاث جامعية عشان تدور على مرجع عن الفخار الروماني، أنت أكيد مش عايز أمين المكتبة يزق لك 20 ترولي تقيل عليهم 500 كتاب ويدلقهم فوق مكتبك! أنت عايز كارت الفهرس الصغير اللي يقولك: “الممر رقم 4، الرف ب، الكتاب رقم 12”.

البرمجة مع الذكاء الاصطناعي نفس الشيء بالظبط: إنك تسحب فولدرات كاملة أو نصوص Packages عملاقة في شات الـ AI، ده المقابل الرقمي لدلق 20 ترولي كتب على مكتبك. بيكركب ذاكرة النموذج، وينفخ فاتورة التوكنز، وبيطلع أخطاء كارثية وغير متوقعة.

باستخدام أداة Graphify (أو أي أداة استعلام جراف بنيتها لمشروعك)، الـ Agent بيسأل الجراف المعماري مباشرة—ويسحب الـ 10 نودز (Nodes) اللي محتاجهم بالمللي في أقل من 25 ميلي ثانية. هنا هنشوف إزاي هندسة السياق بدون هدر (Zero-Waste Context) بتشتغل على أرض الواقع.

📚 ورطة ترولي الكتب: التكلفة الحقيقية للبحث العشوائي بالـ Grep

تعالوا نشوف إيه اللي بيحصل في جلسة برمجة عادية مع الـ AI من غير Knowledge Graph بالتفصيل:

أنت بتسأل الـ AI بتاعك:

“لما العميل يدوس على زرار ‘تأكيد الطلب’ في صفحة 12، كود الخصم بيتراجع فين، وأنهي جداول بتتعدل بالظبط؟”

شوف بقى الـ AI وهو بيغرق في شبر مية:

البحث الهمجي بالـ Grep: الـ Agent يشغل أمر grep -rn "DISCOUNT" . على المستودع كله من أوله لآخره.
كومة القش من النتائج الكاذبة (False Positives): يلاقي 142 سطر متفرقين في 28 ملف: سكربتات قديمة اتلغت، كومنتات من 3 سنين، ملفات تيست، وجداول فواتير ملهاش علاقة بالموضوع!
دلق التوكنز في الشات: يسحب 10 ملفات من دول في الـ Context Window، ويحرق 35,000 توكن قبل ما يكتب سطر كود واحد!
استنتاج وهمي وهبد صريح: من كتر الكومنتات القديمة والدوشة، الموديل يفترض بالغلط إن الخصم بيتحسب بكود جافاسكريبت على المتصفح، ويفوت تماماً الـ Package الحقيقية في الداتابيز!

تعالوا نقارن ده بـ Agent معاه أدوات استعلام الجراف:

graphify path "BTN_SUBMIT_ORDER" "ORDERS"

في 18 ميلي ثانية بس، الجراف بيرد عليه:

مسار مؤكد (4 خطوات):
[زرار: BTN_SUBMIT_ORDER]
  └── triggers ──> [Process: PROC_SAVE_ORDER]
        └── calls ──> [Package: PKG_CHECKOUT.PROCESS_ORDER]
              └── writes ──> [جدول: ORDERS]

الـ Agent دلوقتي معاه حقيقة هندسية مؤكدة 100% في 42 توكن بس! مفيش رغي، مفيش نتائج مزيفة، وصفر تخمين.

🎯 الأنماط التلاتة الأساسية لاستعلام الجراف

أثناء بناء وتعديل تطبيقات Oracle APEX، وكيل البرمجة بالذكاء الاصطناعي بيحتاج 3 أنواع رئيسية من الرؤية المعمارية:

1. استكشاف الجيران المحيطين (`graphify query`)

لما الـ Agent يطلب منه تعديل صفحة معينة، مش محتاج يعرف أي حاجة عن الـ 79 صفحة التانيين. هو محتاج بس يفهم المكونات المباشرة اللي عايشة في نفس الصفحة:

graphify query "Page_12" --depth 1

النتيجة:
- Page_12 (صفحة: "Order Checkout")
  ├── Region_CustomerInfo (منطقة)
  │   ├── P12_CUSTOMER_NAME (حقل نص)
  │   └── P12_CUSTOMER_EMAIL (حقل إيميل)
  └── Region_CartSummary (منطقة)
      ├── P12_CART_TOTAL (حقل رقم)
      ├── BTN_APPLY_DISCOUNT (زرار) ──[TRIGGERS]──> PROC_APPLY_PROMO
      └── BTN_SUBMIT_ORDER (زرار)   ──[TRIGGERS]──> PROC_SAVE_ORDER

في أقل من 80 توكن، الـ Agent عرف:

المناطق (Regions) اللي موجودة في الصفحة.
الحقول التابعة لكل منطقة.
الزراير والـ Processes المرتبطة بيها.

2. تتبع مسار تدفق البيانات (`graphify path`)

في أنظمة أبيكس للمؤسسات، دوسة الزرار بتشغل Process، والـ Process بتنادي Package، والـ Package بتكتب في جدول داتابيز.

عشان تعرف الداتا بتسافر إزاي من شاشة المتصفح لحد قرص التخزين، أمر graphify path بيكشف لك مسار السلسلة بالكامل:

graphify path "BTN_APPLY_DISCOUNT" "DISCOUNT_LOGS"

المسار بالكامل:
[BTN_APPLY_DISCOUNT] 
  ──[TRIGGERS]──> [PROC_APPLY_PROMO] 
  ──[CALLS]──> [PKG_PROMO.VALIDATE_CODE] 
  ──[WRITES]──> [DISCOUNT_LOGS]

الـ Agent بيشوف فوراً إن PKG_PROMO.VALIDATE_CODE بتسجل محاولات الخصم في جدول DISCOUNT_LOGS. مش محتاج يخمن ولا يسألك اللوجات دي بتروح فين.

3. تحليل نطاق التأثير والتوابع (`graphify callers`)

أرعب لحظة في شغل قواعد البيانات هي لما تيجي تعدل جدول مشترك أو تغير باراميتر في Package شغالة في كل حتة:

“لو عدلت شكل دالة PKG_CUSTOMER_API.GET_BALANCE، إيه اللي هيفرقع في وشنا؟”

من غير جراف، يا إما هتقعد تشغل كويريهات معقدة على جدول ALL_DEPENDENCIES، أو تدعي ربنا إن مفيش شاشة تبوظ في الـ Production! مع Graphify، الـ Agent بيكتب سطر واحد:

graphify callers "PKG_CUSTOMER_API.GET_BALANCE"

الشاشات والبرامج اللي بتنادي PKG_CUSTOMER_API.GET_BALANCE:
├── صفحة 04 (لوحة تحكم العميل) ──> Region_BalanceSummary
├── صفحة 12 (شاشة الشراء)       ──> Process_CheckCreditLimit
└── باكيدج الفواتير PKG_INVOICING.GENERATE_MONTHLY

في ثواني معدودة، الـ Agent بيطلع لك تقرير أثر كامل (Blast Radius Report) وعارف بالظبط إيه الشاشات اللي لازم يختبرها قبل ما يرفع الكود!

⚡ لغة الأرقام الحقيقية: بالجراف ضد من غير جراف

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

المقياس	البحث النصي الهمجي (Grep)	الاستعلام الذكي بالجراف	الفرق
الملفات المسحوبة في الـ Prompt	8 – 15 ملف كاملين	ملف واحد مستهدف + كود الجراف	85% ملفات أقل
التوكنز المستهلكة	28,000 – 45,000 توكن	650 – 1,200 توكن	توفير 97% من التوكنز
وقت التنفيذ	35 – 50 ثانية انتظار	3 – 5 ثواني بس	أسرع 10 مرات
دقة الكود المقترح	~65% (أسماء أعمدة وهمية)	~98% (علاقات AST موثقة)	كود جاهز للـ Production

🛠️ إزاي تضيف استعلام الجراف لدورة شغلك؟

تقدر تبدأ تطبق الفكر ده في أي مشروع:

أداة CLI خفيفة بلغة Python: سكربت صغير (~60 سطر) بيحمل جراف الـ AST ويوفر أوامر سريعة في التيرمينال: --query و --path و --callers.
تسجيلها كـ Agent Tools: في أدوات الـ AI الحديثة (Cursor, Antigravity, MCP Servers)، سجل الأوامر دي كـ أدوات يقدر الـ Agent يناديها تلقائياً بدل ما يقرأ الملفات عمال على بطال.
تثبيت سقف التوكنز تحت 1000 توكن: علم الـ Agent بتاعك يسأل الجراف الأول عشان يحدد الملفات اللي محتاجها بالظبط قبل ما يسحب أي كود.

[!TIP]

📦 عايز أدوات الجراف جاهزة للاستخدام؟

مستودع APEX Project Template بيجي ومعاه تكامل Graphify جاهز بالاختصارات وتعليمات الـ Agents. تقدر تاخد السكربتات وتطبقها في مشروعك الحالي فوراً!

🚀 إيه اللي مستنينا في الجزء الخامس؟

دلوقتي بعد ما الـ Agent بتاعنا بقى يقدر يتنقل بين اعتماديات التطبيق بدقة جراحية، بيظهر سؤال أمان في غاية الأهمية:

هو الـ AI مسموح له يكتب كود فين، وممنوع يقرب من إيه؟

لو سبت الـ AI في فولدر عايم من غير حواجز أمان، ممكن بحسن نية يمسح ملفات الـ DDL النظيفة، أو يعدل في سكربتات migrations قديمة، أو يرفع ملفات تجارب في الـ Git.

في الجزء الخامس (“عزل المعمل النظيف: ليه سورس كودك، ومرايات الداتابيز، وتجارب الـ AI مستحيل يختلطوا؟”)، هنتعرف على حدود الفولدرات الأربعة المعقمة اللي بتحافظ على داتابيز الـ Production بتاعتك آمنة وبتخليك تشتغل بقمة راحة البال!

استنونا في الجزء الخامس! 🧼✨

كتبه: أحمد شريف (Ahmed Sherif).

رسم ناطحة السحاب: بناء الـ AST Knowledge Graph لأوراكل أبيكس 🗺️🏗️

Tue, 08 Sep 2026 00:00:00 GMT

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

رسم ناطحة السحاب: بناء الـ AST Knowledge Graph لأوراكل أبيكس 🗺️🏗️

الجزء الثالث من سلسلة “مطور APEX المدعوم بالذكاء الاصطناعي”.

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

إنك تسيب AI Coding Agent في فولدر فيه 50 ملف وتقوله “حل لي المشكلة المعقدة دي”، ده بالظبط زي ما تنزل سائح في وسط طوكيو وتديله دليل مطبوع فيه أسامي الشوارع مترتبة أبجدياً بس من غير خريطة!

بتحليل ملفات APEX وتحويلها لـ شجرة نحو تجريدية (AST) ورفعها على Knowledge Graph معماري، بتدي للـ Agent بتاعك ماكيت هندسي ثلاثي الأبعاد للمشروع كله.

بدل ما يقعد يخمن العلاقات بالبحث النصي العشوائي، الـ Agent بيقدر يتتبع المسار الدقيق بالمللي: من دوسة الزرار في صفحة 12 لحد جداول الداتابيز اللي بتتقري وتتعدل في الخلفية!

🗺️ خريطة الـ GPS ضد دليل أسامي الشوارع المطبوع

تخيل إنك سايق رايح مستشفى في مدينة أول مرة في حياتك تزورها:

طريقة الدليل الأبجدي: تطلع كتاب تليفونات فيه 5000 اسم شارع مترتبين من الألف للياء. أنت عارف إن المستشفى في “شارع النخيل”، بس مضطر تقلب في كل الشوارع عشان تخمن أنهي شارع بيوصل له، وأنهي كوبري بيعدي النيل، والشوارع دي اتجاه واحد ولا اتنين!
طريقة خريطة الـ GPS: تبص في شاشة الملاحة. بتشوف فوراً مكانك الحالي، والملفات اللي هتدخلها بالترتيب، والكباري، ودبوس المستشفى منور بالأحمر على الخريطة في ثواني!

لما مساعدي الذكاء الاصطناعي يعتمدوا بس على البحث النصي العادي (grep) أو الـ Vector Embeddings العامة (RAG)، بيكونوا زي السائح التايه في شوارع طوكيو بالظبط.

لو سألته: “لما اليوزر يدوس على زرار ‘اعتماد استرجاع الفلوس’ (Approve Refund)، أنهي جداول بتتعدل؟”، البحث النصي هيدور على كلمة "REFUND". هيرجع لك 85 نتيجة ملهاش أي علاقة بالموضوع من ملفات قديمة وكومنتات ولوجات—وهيحرق رصيدك في التوكنز ويهبد علاقات مش موجودة!

عشان نخلي الـ AI يشتغل بدقة جراحية في مشروعات Oracle APEX، محتاجين خريطة معمارية صريحة (Explicit Structural Topology).

🌳 يعني إيه شجرة نحو تجريدية (Abstract Syntax Tree - AST)؟

قبل ما نبني الجراف، لازم نفهم الكمبيوتر بيقرا الكود إزاي.

أنت كإنسان لما بتبص على الكود بتشوف كلام وجمل. لكن الكومبيلر والمحلل (Parser) لما بيقرأ الكود، بيفككه لشجرة هرمية اسمها Abstract Syntax Tree (AST).

تخيل تطبيق Oracle APEX كأنه شجرة ضخمة متفرعة:

جذع الشجرة (Trunk): التطبيق نفسه (App ID، اسمه، نظام الأمان).
الفروع الكبيرة: الصفحات (صفحة 1، صفحة 12، صفحة 40).
الفروع الصغيرة: المناطق (Regions) جوه كل صفحة (Grids، Forms، شاشات ثابتة).
الأوراق الخضراء: العناصر المنفردة (P12_EMAIL)، والزراير (BTN_SUBMIT)، والـ Processes.
فروع اللبلاب المتسلقة: الـ Dynamic Actions ونداءات الـ PL/SQL Packages اللي بتربط عناصر الشاشة بجداول الداتابيز الحقيقية.

graph TD
    APP["تطبيق 100: إدارة الطلبات"] --> P12["صفحة 12: شاشة الدفع"]
    P12 --> R1["Region: بيانات العميل"]
    P12 --> R2["Region: ملخص الأوردر"]
    
    R1 --> I1["Item: P12_CUSTOMER_NAME"]
    R1 --> I2["Item: P12_EMAIL"]
    
    R2 --> B1["Button: BTN_SUBMIT_ORDER"]
    B1 -->|triggers| PR1["Process: تنفيذ عملية الدفع"]
    
    PR1 -->|calls| PKG["Package: PKG_CHECKOUT.PROCESS_ORDER"]
    PKG -->|writes| T1[("جدول: ORDERS")]
    PKG -->|writes| T2[("جدول: ORDER_ITEMS")]
    PKG -->|reads| T3[("جدول: CUSTOMERS")]

شايف الجمال؟ ده مش مجرد لستة ملفات مرصوصة—دي شبكة علاقات واعتماديات موجهة (Directed Dependency Graph)!

أول ما التطبيق يتحول لـ Nodes وأسهم (Edges)، الـ AI مستحيل يخمن إيه اللي بيحصل لما BTN_SUBMIT_ORDER يتداس عليه—هيمشي ورا السهم مباشرة لـ PKG_CHECKOUT ويعرف في ثانية إن جدولي ORDERS و ORDER_ITEMS هما اللي بيتعدلوا!

⚙️ تشريح الـ APEX Knowledge Graph من جوه

الجراف ده متكون من إيه بالظبط؟ بيتكون من عناصر معمارية واضحة ومحددة:

1. الـ Nodes الأساسية

Page: شاشات التطبيق الرئيسية (Page_12).
Region: المناطق الهيكلية جوه الصفحة (Region_OrderSummary).
Item: الحقول والمدخلات والمتغيرات (P12_DISCOUNT_CODE).
Button: زراير التفاعل (BTN_APPLY_DISCOUNT).
Process / DynamicAction: لوجيك التطبيق ومعالجة الأحداث.
Package / Procedure: دوال وإجراءات الـ PL/SQL في الداتابيز.
Table / View: جداول ومخازن البيانات (ORDERS, CUSTOMERS_V).

2. الأسهم والعلاقات (Directed Edges)

[Region] --CONTAINS--> [Item]
[Button] --TRIGGERS--> [Process]
[Process] --CALLS--> [Package]
[Package] --READS--> [Table]
[Package] --WRITES--> [Table]

لما تبني الجراف ده، إجابة سؤال معقد زي: “لو ضفنا عمود جديد في جدول CUSTOMERS، أنهي صفحات وزراير ممكن تتأثر؟” بتتحول لعملية بحث سريعة في الجراف بتاخد أجزاء من الثانية!

🛠️ إزاي استخراج الـ AST بيشتغل عملياً؟

إزاي بنحول ملفات APEX للشبكة الذكية دي؟

المنطق بيتلخص في 3 خطوات بسيطة:

الخطوة 1: استخراج الهيكل البصري للشاشة

الـ Parser بيمر على ملفات الصفحات ويستخرج الـ Regions والحقول والزراير:

# كود توضيحي لاستخراج مكونات الصفحة
def extract_page_components(page_ast, graph):
    page_id = f"PAGE_{page_ast.number}"
    graph.add_node(page_id, type="page", label=page_ast.title)

    for region in page_ast.regions:
        reg_id = f"REG_{region.name}"
        graph.add_node(reg_id, type="region", label=region.title)
        graph.add_edge(page_id, reg_id, rel="CONTAINS")

        for button in region.buttons:
            btn_id = f"BTN_{button.name}"
            graph.add_node(btn_id, type="button", label=button.label)
            graph.add_edge(reg_id, btn_id, rel="CONTAINS")

الخطوة 2: ربط الأحداث بالـ Processes

بعد كدة، السكربت بيبص على الزراير ويربطها بالـ Processes اللي بتشغلها:

        for proc in page_ast.processes:
            if proc.when_button_pressed == button.name:
                proc_id = f"PROC_{proc.name}"
                graph.add_node(proc_id, type="process", label=proc.name)
                graph.add_edge(btn_id, proc_id, rel="TRIGGERS")

الخطوة 3: فحص كود الـ SQL والـ PL/SQL الداخلي

وأخيراً، السكربت بيفحص الأكواد المكتوبة جوه الـ Processes والـ Packages عشان يستخرج أسماء الجداول والـ Packages المستهدفة:

        # استخراج الجداول اللي بيحصل عليها كتابة (INSERT INTO, UPDATE)
        table_writes = find_dml_targets(proc.code)
        for table in table_writes:
            graph.add_node(table, type="table", label=table)
            graph.add_edge(proc_id, table, rel="WRITES")

في ثواني معدودة، تطبيق كامل من 80 صفحة و 200 جدول بيتحول لقاعدة بيانات جراف محلية وخفيفة الوزن جداً!

💡 إزاي تطبق ده في مشروعك النهاردة؟

مش محتاج ميزانيات ضخمة ولا بنية تحتية سحابية معقدة:

ابني بأدوات بسيطة: سكربت بايثون صغير بمكتبات زي sqlite3 أو networkx كفيل إنه يحلل ملفات الصفحات والـ Packages لقائمة علاقات.
استخدم صيغ جراف خفيفة: طلع النتيجة في ملف JSON أو SQLite محلي يقدر الـ AI يستعلم منه بسطور أوامر بسيطة.
اربطه بالـ Git Hooks: خلي السكربت يشتغل أوتوماتيك مع كل تصدير أو commit عشان يفضل الجراف متزامن مع كودك على طول.

[!TIP]

📦 عايز توفر وقتك وتاخد الجراف جاهز؟

مستودع APEX Project Template بيجي ومعاه سكربت setup_graphify_apx.py وأداة Graphify جاهزين ومتظبطين بالكامل. بأمر واحد بس (python scripts/setup_graphify_apx.py)، بيحول ملفات .apx وملفات الـ DDL لجراف عالي الأداء!

🚀 إيه اللي مستنينا في الجزء الرابع؟

دلوقتي بعد ما رسمنا ناطحة سحاب أبيكس في Knowledge Graph هندسي دقيق، يا ترى الوكيل الذكي بيستخدمه إزاي في جلسات البرمجة الحقيقية؟

في الجزء الرابع (“سياق بدون هدر: استعلام اعتماديات أبيكس عبر Graphify”)، هنتعرف على أوامر التيرمينال الحقيقية (graphify query و graphify path) اللي بتخلي الـ Agent يسحب بس الـ 15 نود اللي محتاجهم—ويوفر 90% من التوكنز ويقضي على التهييس نهائياً!

استنونا في الجزء الرابع! 🎯✨

كتبه: أحمد شريف (Ahmed Sherif).

من الكتلة الصماء للتقسيم الذكي: ليه ملفات APEXlang بتغير كل حاجة؟ 📦✨

Fri, 04 Sep 2026 00:00:00 GMT

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

من الكتلة الصماء للتقسيم الذكي: ليه ملفات APEXlang بتغير كل حاجة؟ 📦✨

الجزء الثاني من سلسلة “مطور APEX المدعوم بالذكاء الاصطناعي”.

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

إنك تحاول تتبع تعديلات الـ Git أو توجه AI Coding Agent جوه ملف واحد ضخم اسمه f100.sql، ده بالظبط زي ما تكون عايش في حاوية شحن بضائع 40 قدم مفيهاش أي رفوف ولا تنظيم! محتاج تفضي عفش الحاوية كله في الشارع بس عشان تدور على مفاتيح عربيتك!

بتحويل وتفكيك تطبيقات Oracle APEX لملفات صفحة-بصفحة بلغة APEXlang (.apx) النظيفة، بتدي لفريقك البشري ولمساعدي الذكاء الاصطناعي سورس كود شفاف، ومقسم، ومثالي للمقارنة والمراجعة في الـ Git.

هنا هنشوف إزاي APEXlang بتشيل آلاف السطور من دوشة السباكة الداخلية، وتقلل فواتير التوكنز، وتخلي الشغل المشترك في فروع الـ Git ممتع وسهل بالظبط زي شغل الـ Frontend الحديث.

📦 حاوية البضائع المقفولة ضد الجراج المنظم بالمللي

في عالم Oracle APEX التقليدي، تصدير الكود غالباً بيقع بين نارين:

الكتلة الصماء الواحدة (f100.sql): ملف SQL واحد عملاق فيه إعدادات الـ Workspace، والـ Themes، وخطط الأمان، والـ 80 صفحة بتوع التطبيق مرصوصين فوق بعض في برج من 150,000 سطر كود!
التقسيم الإجرائي القديم (f100/application/...): فولدر فيه عشرات الملفات المرقمة (page_00012.sql)، بس كل ملف فيهم لسه عبارة عن حيطة سد من أوامر wwv_flow_imp_page.create_page_plug الغارقة في أرقام الـ Hexadecimal غير المفهومة.

تخيل معايا شكل تنظيم العدة والأدوات في بيتك:

الكتلة الصماء (حاوية الشحن العشوائية): الخيم، وماكينة قص الحشائش، وجرادل البوية، والشنيور كلهم مرميين ورا باب حديد تقيل. لو عايز تتأكد عندك بنطة 10 ملم ولا لأ، لازم تسحب كل الكراكيب دي برة على الأسفلت وتقعد تنبش في الكومة!
التقسيم الذكي (علب شفافة ومكتوب عليها أسماء العدة على رفوف الجدار): تدخل الجراج في ثانية تلاقي العلبة رقم 1 “الشناير والبنط”، العلبة رقم 2 “أدوات الدهان”، العلبة رقم 3 “أدوات التخييم”. تمد إيدك على علبة 1 وتاخد البنطة وتقفل الغطاء في 5 ثواني وتمشي!

لغة APEXlang (.apx) هي بالظبط الرفوف المنظمة والعلب الشفافة اللي مكتوب عليها أسماء عناصر تطبيقك بالمللي.

🔍 اتعرف على لغة APEXlang — لغة وصفية معمولة بالحب للـ Low-Code

لغة APEXlang هي لغة مخصصة (DSL) معمولة خصيصاً عشان تقراها عيون البشر وعقول وكلاء الذكاء الاصطناعي بمنتهى السلاسة والوضوح.

بدل ما تجبر الوكيل الذكي يقعد يحلل ويفك طلاسم النداءات الإجرائية، APEXlang بتوصف الشاشات بطريقة تقريرية (Declarative)—بنفس الطريقة اللي دماغنا بيفكر بيها لما بنيجي نصمم شاشة على الورق!

مقارنة وجهاً لوجه: الطريقة القديمة ضد طريقة APEXlang

تعالوا نشوف حقل نصي بسيط في صفحة “الدفع والشراء” بيتكتب إزاي في ملفات الـ SQL القديمة ومقابله في APEXlang كالآتي:

التصدير التقليدي القديم (مليان دوشة وطلاسم)

begin
wwv_flow_imp_page.create_page_item(
  p_id=>wwv_flow_imp.id(4918239019283741)
 ,p_name=>'P12_CUSTOMER_EMAIL'
 ,p_item_sequence=>20
 ,p_item_plug_id=>wwv_flow_imp.id(4918200192837400)
 ,p_prompt=>'Customer Email'
 ,p_display_as=>'NATIVE_TEXT_FIELD'
 ,p_cSize=>60
 ,p_is_required=>true
 ,p_field_template=>wwv_flow_imp.id(4918001928374611)
);
end;

تمثيل نفس الحقل بلغة APEXlang (`.apx`) (واضح، وصفي، وشيك)

// apps/order_hub/100/pages/page_00012.apx
page 12 "Order Checkout" {
    region "Customer Information" {
        item P12_CUSTOMER_NAME: text "Full Name" required;
        item P12_CUSTOMER_EMAIL: email "Customer Email" required;
        item P12_DISCOUNT_CODE: text "Promo Code";
    }

    region "Cart Summary" {
        item P12_CART_TOTAL: number "Order Total" readonly;
        button "BTN_APPLY_DISCOUNT" label "Apply Promo" hot;
        button "BTN_SUBMIT_ORDER" label "Place Order" primary;
    }

    process "Process Payment" on "BTN_SUBMIT_ORDER" {
        plsql {
            PKG_CHECKOUT.PROCESS_ORDER(
                p_cust_name  => :P12_CUSTOMER_NAME,
                p_cust_email => :P12_CUSTOMER_EMAIL,
                p_discount   => :P12_DISCOUNT_CODE,
                p_order_id   => :P12_ORDER_ID
            );
        }
    }
}

لاحظ الفرق الشاسع:

صفر أرقام هيكس عشوائية: أسماء واضحة ومنطقية (P12_CUSTOMER_EMAIL, BTN_SUBMIT_ORDER) بدل أرقام زي 4918239019283741.
تسلسل بصري حقيقي (Visual Hierarchy): بلمحة عين بتشوف إن الصفحة فيها منطقتين (Regions)، وكل منطقة فيها حقول وزراير، وزرار الدفع بينادي كود PL/SQL صريح.
منطق بيزنس صافي: كل دوشة السباكة لمحرك أبيكس اختفت، ومتبقاش غير التصميم المعماري والكود اللي يهمك بجد.

🤝 ليه وكيل البرمجة بالذكاء الاصطناعي بيعشق لغة APEXlang؟

لما تطلب من المساعد الذكي (AI Assistant) الآتي:

“ضيف لي قائمة منسدلة (Dropdown) لاختيار فئة العضوية جوه منطقة ‘بيانات العميل’ في صفحة 12، وتكون القيمة الافتراضية بتاعتها ‘BRONZE’.”

شوف الفرق في تعامل الـ Agent بين الطريقتين:

وجه المقارنة	الملف الضخم القديم `f100.sql`	الملف المقسم الحديث `page_00012.apx`
الملفات المقروءة	ملف واحد عملاق (~150,000 سطر)	ملف واحد محدد ومعزول (65 سطر بس)
التوكنز المستهلكة	~65,000 توكن	~320 توكن بس!
وقت القراءة والتفكير	من 20 لـ 40 ثانية	أقل من ثانية واحدة
دقة التعديل	احتمالية عالية جداً لكسر الـ Syntax أو الـ IDs	تعديل جراحي بالمللي وفي مكانه الصح
خطر التأثير على صفحات تانية	ممكن يبوظ صفحات تانية بالخطأ	صفر تأثير على باقي التطبيق

بدل ما يحرق ميزانيتك، الـ AI بيفتح page_00012.apx، يدخل على region "Customer Information"، ويضيف سطر واحد بس:

        item P12_LOYALTY_TIER: select "Loyalty Tier" default "BRONZE" lov "LOV_TIERS";

…وبيخلص الشغلانة في 3 ثواني وبدون أي تهييس!

🔀 تتبع التعديلات في Git (Diffs تفهمها وتقراها زي الرواية)

لسنين طويلة، تتبع ومزامنة كود Oracle APEX في الـ Git كان بمثابة صداع مزمن لفرق البرمجة. لو اتنين مطورين عدلوا في صفحة 12 وصفحة 15 في نفس التطبيق، عملية الـ Merge كانت بتتحول لكابوس:

أرقام الـ IDs اتغيرت في كل حتة.
التواريخ (Timestamps) ضربت في سطر 4 وسطر 1200 وسطر 15000.
مراجعات الـ Pull Requests كانت مستحيلة لأن مفيش بني آدم يقدر يراجع diff فيه 50 ألف سطر!

مع ملفات .apx المقسمة، الـ PRs بتتحول لشغل هندسي محترم وراقي:

  region "Customer Information" {
      item P12_CUSTOMER_NAME: text "Full Name" required;
      item P12_CUSTOMER_EMAIL: email "Customer Email" required;
+     item P12_LOYALTY_TIER: select "Loyalty Tier" default "BRONZE" lov "LOV_TIERS";
      item P12_DISCOUNT_CODE: text "Promo Code";
  }

التيم ليدر يقدر يراجع التعديل ده في 10 ثواني، يدوس Approve وهو واثق، وعارف بالظبط إيه اللي اتغير في المشروع.

🛠️ إزاي تطبق المعمارية المقسمة دي في مشروعاتك؟

مش لازم تقلب بنية شركتك كلها بين يوم وليلة عشان تستفيد من المزايا دي.

تقدر تبدأ بالخطوات دي:

ابدأ بالتقسيم على مستوى الصفحات: اتأكد إن سكربتات التصدير بتاعتك بتستخدم خيار التجزئة (زي apex export -split أو أوامر SQLcl الرسمية) عشان كل صفحة تعيش في ملف مستقل.
التحويل لصيغة مقروءة للبشر: سواء بسكربتات بايثون أو أدوات DSL من المجتمع التقني، حول الأغلفة المليانة سباكة لشكل وصفي بسيط ومباشر.
أتمتة التجميع (Compilation): وقت الـ Deployment لأوراكل أبيكس، خلي الـ CI/CD Pipeline يعيد تجميع ملفات .apx لسكربتات تثبيت APEX القياسية.

[!TIP]

📦 عايز حل جاهز ومتكامل من غير وجع دماغ؟

بص على APEX Project Template المفتوح المصدر. بيحتوي على سكربتات التفكيك الجاهزة (export_apx.py)، ومحركات التجميع، وهيكل الفولدرات المنظم بالكامل ومجاني تماماً!

🚀 إيه اللي مستنينا في الجزء الثالث؟

دلوقتي بعد ما فككنا كود التطبيق لملفات .apx نظيفة ومستقلة، التطبيقات الحقيقية مش مجرد جزر معزولة—دي شبكة علاقات معقدة بين الزراير، والـ Dynamic Actions، والـ Packages، وجداول الداتابيز!

لما الـ AI يحتاج يعدل في صفحة 12، إزاي يعرف الجداول والـ Packages المرتبطة بيها من غير ما يحتاج يفحص الداتابيز كلها؟

في الجزء الثالث (“رسم ناطحة السحاب: بناء الـ AST Knowledge Graph لأبيكس”)، هنشوف إزاي تحليل شجرة الكود (AST) بيحول ملفات تطبيقك لشبكة معرفية ثلاثية الأبعاد تفاعلية وسريعة زي الطلقة!

استنونا في الجزء التالت! 🏗️✨

كتبه: أحمد شريف (Ahmed Sherif).

غمامة الـ 50 ألف توكن: ليه رمي ملفات الـ APEX الخام للذكاء الاصطناعي بيحرق فلوسك ع الفاضي؟ 💸🙈

Tue, 01 Sep 2026 00:00:00 GMT

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

غمامة الـ 50 ألف توكن: ليه رمي ملفات الـ APEX الخام للذكاء الاصطناعي بيحرق فلوسك ع الفاضي؟ 💸🙈

الجزء الأول من سلسلة “مطور APEX المدعوم بالذكاء الاصطناعي”.

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

إنك تدي لـ AI Coding Assistant ملف تصدير Oracle APEX بصيغة الـ SQL الخام، ده بالظبط عامل زي ما تطلب من صاحبك يدور لك على وصفة كحك العيد السرية بتاعة جدتك.. بس مديله يدور جوه موسوعة قانون الضرائب المكونة من 5000 صفحة ومكتوبة بخط منمنم وقوانين معقدة!

صاحبك (الذكاء الاصطناعي) هيحرق لك رصيد التوكنز كله في سؤالين تلاتة، وهيفوّت تماماً شرط التحقق (Validation) اللي أنت بتدور عليه في الصفحة، وفي الآخر هيهبد لك كود PL/SQL خيالي ممكن يفرمت داتابيز الـ Production بتاعتك!

في الدليل ده، هنشرح بالتفصيل ليه ملفات تصدير APEX الضخمة (Monolithic) بتخنق نماذج الـ LLM، والضوضاء المعمارية المخفية اللي بتنفخ فواتير الـ API بتاعتك، والاستراتيجيات الأساسية اللي تقدر تطبقها فوراً في أي مشروع لبناء دورات عمل ذكية وسريعة زي الصاروخ.

🔍 وهم “يا عم ارمي له ملف الـ SQL وخلاص!”

تخيل المشهد ده—واللي بيحصل بالحرف مع 99% من مطوري Oracle APEX أول ما يبدأوا يجربوا أدوات الذكاء الاصطناعي التوليدي:

عندك تطبيق شغال، وليكن تطبيق 100. حابب تخلي مساعد الذكاء الاصطناعي (Claude أو GPT أو Gemini) يساعدك تبني ميزة بسيطة:

“يا عم الذكاء الاصطناعي، بص كدة على تطبيقي. في صفحة 12، لما اليوزر يدخل نسبة خصم أكبر من 20%، اطلب موافقة المدير قبل ما ينشئ الأوردر.”

ولأن Oracle APEX بتصدر التطبيقات على شكل ملفات SQL، أول فكرة بتيجي في بالك بتكون بديهية ومنطقية جداً: “الله! ما هي أبيكس أصلاً مبنية على SQL من تحت، خليني أشغل أمر apex export -applicationid 100، وأرفع ملف f100.sql ده جوه شات الـ AI أو الـ IDE، وسيبه بقى يعيش ويبهرني!”

بعد 5 ثواني بس، الواقع بيصدمك بالقلم:

انفجار التوكنز (Token Explosion): عداد التوكنز بتاعك ينط فجأة من صفر لـ 65,000 وحتى 180,000 توكن عشان سؤال واحد بس!
شلل السياق (Context Paralysis): الـ AI بيفضل متنح 45 ثانية وهو بيطحن آلاف السطور من الدوال الداخلية، وأرقام الـ Hexadecimal، وسكربتات إنشاء الـ Workspaces.
كارثة التهييس (Hallucination Disaster): بدل ما يديك Process نظيف أو Dynamic Action محترم، الموديل بيرد عليك بكود PL/SQL غريب ومخترع أعمدة مش موجودة أصلاً في جداولك، وبيحاول يعدل جداول المحرك الداخلية لأبيكس (WWV_FLOW_STEPS)!

ليه ده بيحصل كل مرة بدون استثناء؟ لأن ملف التصدير بتاع APEX مكنش معمول أصلاً عشان تقراه عين بشرية.. ولا عشان تقراه نماذج اللغة!

🔬 تشريح ملف التصدير: إيه اللي مستخبي جوه `f100.sql`؟

عشان تفهم ليه الذكاء الاصطناعي بيفشل الفشل الذريع ده لما يشوف ملف الـ Export، لازم نبص بعينينا على اللي جوه f100.sql.

أوراكل أبيكس لما بتصدر تطبيق، مش بتطلع لك مواصفات وصفية واضحة (Declarative Specification) للشاشات والتقارير. هي في الحقيقة بتولد سكربت تثبيت إجرائي (Imperative Installation Script) معمول مخصوص عشان يعيد حقن سطور الداتا جوه جداول محرك أبيكس الداخلي (APEX_260100 / WWV_FLOW).

بص كدة على العينة دي اللي بتمثل مجرد حقل نصي واحد في صفحة:

prompt --application/pages/page_00012
begin
wwv_flow_imp_page.create_page_item(
  p_id=>wwv_flow_imp.id(9817239182736192)
 ,p_name=>'P12_DISCOUNT_PCT'
 ,p_item_sequence=>30
 ,p_item_plug_id=>wwv_flow_imp.id(9817211100293812)
 ,p_prompt=>'Discount %'
 ,p_source=>'DISCOUNT_PCT'
 ,p_source_type=>'DB_COLUMN'
 ,p_display_as=>'NATIVE_NUMBER_FIELD'
 ,p_cSize=>30
 ,p_cMaxlength=>5
 ,p_tag_attributes=>'class="apex-item-number"'
 ,p_begin_on_new_line=>'Y'
 ,p_colspan=>null
 ,p_rowspan=>null
 ,p_label_alignment=>'RIGHT'
 ,p_field_alignment=>'LEFT-CENTER'
 ,p_field_template=>wwv_flow_imp.id(9817001928374611)
 ,p_is_persistent=>'Y'
 ,p_attribute_01=>'0'
 ,p_attribute_02=>'100'
 ,p_attribute_03=>'1'
);
end;
/

اضرب بقى الكود ده في 40 حقل، و 15 ريجين (Region)، و 12 أكشن ديناميكي (Dynamic Action)، و 8 بروسيسز (Processes)، وعلى مدار 50 صفحة في التطبيق. فجأة هتلاقي نفسك باصص على أكتر من 150,000 سطر من الحشو المعقد!

الـ 150 ألف سطر دول عبارة عن إيه أصلاً؟

90% سباكة داخلية لمحرك أبيكس: نداءات إجرائية غامضة (wwv_flow_imp_page, wwv_flow_imp_shared)، أرقام ID عشوائية بالهيكس، إحداثيات محاذاة الشاشة، ومؤشرات الـ Templates.
8% لزق وتنسيق عناصر: كلاسات CSS، وإحداثيات الشاشة، وترتيب العرض.
فقط 2% هو منطق البيزنس الحقيقي (Actual Business Logic): السطرين الصغيرين بتوع كود الـ PL/SQL أو الـ SQL Query اللي أنت أصلاً كنت عايز الـ AI يراجعهم ويعدل فيهم!

لما ترمي الملف ده لـ LLM، أنت بتجبره يصرف 98% من تركيزه وطاقته الاستيعابية بس عشان يفلتر الدوشة دي!

📚 التشبيه البلدي: بتدور على مقادير كيكة في قانون الضرائب!

تخيل عينت شيف حلويات عالمي عشان يراجع معاك مقادير تورتة شيكولاتة:

الطريقة العاقلة: بتديه ورقة مقادير شيك في صفحة واحدة: كوبايتين دقيق، 3 بيضات، كوباية سكر، ونص ساعة في الفرن. الشيف هيبص في ثانية ويقولك: “أنت نسيت البيكنج باودر ورشة الملح!”.
طريقة ملف الـ APEX الخام: بدل ورقة المقادير، تروح تديله:
1. كود البناء والمواصفات القياسية لمبنى المطبخ.
2. الدوائر الكهربائية والأسلاك لفرن البوتاجاز.
3. كشف شحن من 200 صفحة فيه أرقام مسلسلة لكل مضرب بيض ومعلقة.
4. ومستخبي في صفحة 347 سطر بيقول: p_ingredient => 'SUGAR', p_qty => 1.

الشيف هيتجنن، ويضيع تلات ساعات يقرا في أسلاك الكهرباء، وفي الآخر هيهبد لك نصيحة ملهاش علاقة بالحلويات: “اتأكد بس إن القاطع الكهربائي 240 فولت ميفصلش وأنت بتضرب البيض!”

ده بالظبط اللي بيحس بيه الـ AI لما تديله f100.sql!

💸 الاقتصاديات المخفية: التوكنز، وقت الاستجابة، وفقدان التركيز في النص

رمي الملفات الضخمة دي مش بس بيطلع إجابات تعبانة—ده بينفض جيبك وبيموت سرعة التطوير.

1. لغة الأرقام الصادمة

تعالوا نقارن بين الطريقتين لتطبيق APEX متوسط الحجم:

المقياس	الملف الضخم المجمع (`f100.sql`)	التنسيق المجزأ النظيف (Modular)	الفرق
عدد السطور	~120,000 سطر	~80 سطر لكل صفحة	أصغر 1,500 مرة
استهلاك التوكنز	~55,000 – 90,000 توكن	~350 – 800 توكن	توفير 99% من التوكنز
التكلفة لكل 10 أسئلة	~$3.50 – $7.00 دولار	~$0.02 – $0.05 سنت	سنتات مقابل دولارات
وقت الرد (Latency)	25 – 45 ثانية انتظار	2 – 4 ثواني بس	أسرع 10 مرات
نسبة التهييس والهبد	عالية جداً (>60%)	تكاد تنعدم (<2%)	إجابات دقيقة زي السيف

2. متلازمة “الضياع في الزحمة” (Lost in the Middle)

أبحاث الذكاء الاصطناعي أثبتت مراراً ظاهرة “منحنى الانتباه على شكل حرف U”: الموديل بيركز جداً في أول الـ Prompt وفي آخره، لكن في النص الانتباه بيقع في بئر عميق! لما شرط الـ SQL بتاعك يكون مدفون في وسط 40 ألف توكن من سباكة أبيكس، الموديل بينسى تماماً أنت سألته عن إيه.

3. فخ الملف المكسور غير القابل للاستيراد

لو سبت الـ AI يعدل مباشرة في f100.sql، الكارثة قادمة لا محالة:

فصلة منقوطة ناقصة أو كوتيشن طار من كود wwv_flow_imp هيخلي أبيكس ترفض استيراد التطبيق كله!
لو الـ AI بدّل رقم ID عشوائي (مثلاً غير 9817239182736192 لـ 9817239182736199)، عناصر كاملة هتختفي من الـ Page Designer أو تتربط في صفحات تانية غلط!

🛠️ القواعد الذهبية التلاتة لكود APEX جاهز للذكاء الاصطناعي

عشان تخلي شغلك سريع وذكي، التزم بالتلات مبادئ دول في أي مشروع:

القاعدة 1: تقسيم الكود على مستوى الصفحات (Page-Level Granularity)

ممنوع نهائياً تبعت التطبيق كله للـ AI. استخدم أدوات تقسيم التصدير لفصل كل صفحة في ملف مستقل. لما تسأل عن صفحة 12، الـ Agent ميشوفش غير صفحة 12 بس.

القاعدة 2: تنظيف دوشة الـ Hexadecimal بلغة مقروءة للبشر

الذكاء الاصطناعي بيفهم مفاهيم ومنطق وكلام—مبيفهمش شفرات Hexadecimal. تحويل صفحات أبيكس لصيغة نظيفة ومقروءة (زي لغة APEXlang / .apx) بيشيل 95% من دوشة السباكة مع الحفاظ على المنطق والتقسيم بنسبة 100%.

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

صفحة أبيكس مش عايشة لوحدها في الصحراء؛ هي بتتعامل مع جداول و Views و Packages. بدل ما ترمي كل أكواد الداتابيز في الشات، ادي للـ Agent خريطة علاقات واضحة عشان يسحب بس الجدول أو الـ Package اللي محتاجه بالظبط.

[!NOTE] مش محتاج أدوات مدفوعة عشان تبدأ تطبق المبادئ دي النهاردة. مجرد استخدام أمر التصدير المقسم في SQLcl عبر lb generate-apex أو apex export -split هي خطوة أولى ممتازة يقدر أي فريق يبدأ بيها فوراً في أي ريبو!

📦 بداية جاهزة وسريعة: قالب مشروع APEX المفتوح

رغم إنك تقدر تكتب سكربتاتك الخاصة عشان تقسم وتنظم التصدير، مش لازم تخترع العجلة من الصفر.

لو بتدور على هيكل مستودع جاهز ومجرب بيطبق نفس المعايير دي بالحرف—مع التصدير الذري، والتقسيم النظيف، وقواعد الـ Agents—تقدر تبص على APEX Project Template المفتوح المصدر بالكامل.

🚀 إيه اللي مستنينا في الجزء الثاني؟

دلوقتي بعد ما عرفنا ليه التصدير المجمع بيفشل، يا ترى شكل كود APEX النظيف والجاهز للذكاء الاصطناعي عامل إزاي؟

في الجزء الثاني (“من الكتلة الصماء للتقسيم الذكي: ليه ملفات APEXlang بتغير قواعد اللعبة؟”)، هنتعرف على لغة APEXlang (.apx): إزاي تحويل التصدير لملفات مقروءة بيغير تماماً طريقتك أنت والـ AI في قراءة وتعديل وتتبع كود أبيكس في Git!

نشوفكم في الجزء الثاني! 🚀✨

كتبه: أحمد شريف (Ahmed Sherif).

أحمد شريف | أوراكل أبيكس والذكاء الاصطناعي · مقالات، شروحات، وحيل برمجية

حفظ الثيمات على مستوى المؤسسة في Oracle APEX: قاعدة البيانات، الملفات الشخصية، والوميض الصفري 🏨🔐

حفظ الثيمات على مستوى المؤسسة في Oracle APEX: قاعدة البيانات، الملفات الشخصية، والوميض الصفري 🏨🔐

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

🌐 واقع بيئات الشركات: ليه التخزين المحلي لوحده ميكفيش؟

🗄️ المعمارية الهندسية: الجسر المؤسسي في 4 مراحل

🛠️ الخطوة 1: تخزين التفضيل في قاعدة بيانات أوراكل

⚡ الخطوة 2: إجراء الـ Ajax الصامت في الصفحة 0

خطوات الإعداد جوه Page Designer كالتالي:

كود الربط في ملفات الـ JavaScript كالتالي:

🔑 الخطوة 3: تجهيز الجلسة لحظة تسجيل الدخول

🌟 اللمسة السحرية: حقن السيرفر الخالي من الوميض تماماً

ليه الحركة دي بتمثل قمة النضج الهندسي؟

🏁 ختام السلسلة الشاملة وملخص الرحلة

بناء أداة تبديل الثيمات المخصصة في Oracle APEX: ودجز الواجهة، Alpine.js، وعناصر النماذج 🎛️✨

بناء أداة تبديل الثيمات المخصصة في Oracle APEX: ودجز الواجهة، Alpine.js، وعناصر النماذج 🎛️✨

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

🕹️ استكشاف كود window.ApexThemeFactory

🛡️ سر روابط الـ Hash والحماية من أخطاء الـ Checksum

حل الهاش السحري في جهة العميل:

🪄 اعتراض قائمة الـ Navigation Bar الأصلية في أبيكس

🎨 النمط الأول: أزرار كبسولات حديثة باستخدام Alpine.js 3.x

📋 النمط الثاني: عناصر نماذج أبيكس الرسمية والأوامر الديناميكية

⏭️ المقال القادم: حفظ الثيمات على مستوى قاعدة البيانات

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

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

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

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

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

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

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

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

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

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

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

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

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

سر الوميض الصفري: القضاء على الفلاش الأبيض بتمهيد Page 0 في Oracle APEX ⚡🎭

سر الوميض الصفري: القضاء على الفلاش الأبيض بتمهيد Page 0 في Oracle APEX ⚡🎭

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

⚡ التشريح الدقيق للوميض المزعج (FOUC)

📜 محرك التمهيد السريع (2 ميلي ثانية)

ليه السطر ده خارق ومحصن من الأخطاء؟

🎭 الفخ الخفي في النوافذ المنبثقة (Modal Dialogs)

الحل الهندسي: حقن متزامن في موضعين مكملين

🛡️ طريقة التركيب اليدوي جوه Page Designer

⏭️ المقال القادم: ماكينة الحزم المحمولة

قلعة العزل الحصينة: إزاي html.app-theme-* بيقضي على فوضى الـ CSS في Oracle APEX 🏰🛡️

قلعة العزل الحصينة: إزاي html.app-theme-* بيقضي على فوضى الـ CSS في Oracle APEX 🏰🛡️

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

🏢 كارت الشقة الذكي: ليه الـ CSS العام بيخرب أنظمة الشركات؟

🪜 معمارية التوكنز ثلاثية الطبقات

1. المتغيرات الأساسية (foundation/tokens.css)

2. فروقات حزمة الثيم (sample-themes/carbon-volt/css/tokens.css)

🎯 إعادة تعيين ذرات Iris الأصلية بدون !important

♿ درع إمكانية الوصول: حماية تقليل الحركة بأعلى أسبقية تنسيق

🚫 الفخ القاتل: إزاي الخطوط المخصصة بتمسح أيقونات Font APEX؟

الحل في Theme Factory: تحديد أدوار الخطوط بدقة

📦 تطبيق عملي: تلوين البطاقات والحقول العائمة

⏭️ المقال القادم: القضاء على الوميض الأبيض المزعج!

بدلة الحرباء: ليه تخصيص الثيمات التقليدي في Oracle APEX بيحبسك؟ (وإزاي تفلت منه) 🦎👔

بدلة الحرباء: ليه تخصيص الثيمات التقليدي في Oracle APEX بيحبسك؟ (وإزاي تفلت منه) 🦎👔

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

🦎 فزورة الحرباء: حكاية دولابين ملابس

🪤 الأفخاخ التلاتة في تلوين أبيكس التقليدي

1. كتلة الـ Theme Roller الصامتة

2. معضلة اشتراك الـ Universal Theme 42

3. صدمة نمط Iris في APEX 26.1

🛡️ الحل: محرك APEX Theme Factory

الأركان الأربعة للهيكل المعماري الجديد:

🎨 استكشف الثيمات التمانية الجاهزة في المشروع

🛠️ خطتنا في المقالات القادمة

حملة تنظيف الربيع في APEX 26.1: أرشفة المهام التاريخية بدون كسر التدقيق 🗄️🧹

حملة تنظيف الربيع في APEX 26.1 — أرشفة المهام التاريخية بدون كسر التدقيق 🗄️🧹

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

🗄️ درج المكتب الشغال ضد الخزنة المحصنة المكيفة

ليه مستحيل تقول “يا عم نشغل أمر DELETE وخلاص”؟!

✨ إيه الجديد في أرشفة Oracle APEX 26.1؟

المزايا اللي بتقدمها أرشفة APEX 26.1 الرسمية:

🏗️ على مستوى الداتابيز: التقسيم الشهري الآلي (Interval Partitioning)

🕹️ استكشاف كود `window.ApexThemeFactory`

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

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

1. المتغيرات الأساسية (`foundation/tokens.css`)

2. فروقات حزمة الثيم (`sample-themes/carbon-volt/css/tokens.css`)

🎯 إعادة تعيين ذرات Iris الأصلية بدون `!important`

ليه مستحيل تقول “يا عم نشغل أمر `DELETE` وخلاص”؟!

🤖 حزمة الصيانة التلقائية: `pkg_wf_maintenance`

⚙️ محرك المعالجة الخلفي: `pkg_workflow_actions.ig_batch_action`

📋 الحل الذكي: جدول الميتاداتا `wf_action_config`

فك تشفير نص إعدادات الزرار (`btn_config`):

🏗️ دفتر سجل الأحداث: جدول `wf_task_event_log`

⚙️ منسق الكاش: Package الـ `pkg_task_cache`

2. إياك تستخدم `AUTONOMOUS_TRANSACTION` في تحديث الكاش!

🏗️ التصميم الهندسي لجدول `wf_task_cache`

🔬 تشريح `APEX_TASKS`: إيه اللي بيحصل وراء الكواليس؟