🇬🇧 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 التقليدي، تصدير الكود غالباً بيقع بين نارين:

1. الكتلة الصماء الواحدة (f100.sql): ملف SQL واحد عملاق فيه إعدادات الـ Workspace، والـ Themes، وخطط الأمان، والـ 80 صفحة بتوع التطبيق مرصوصين فوق بعض في برج من 150,000 سطر كود!
2. التقسيم الإجرائي القديم (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
            );
        }
    }
}

لاحظ الفرق الشاسع:

1. صفر أرقام هيكس عشوائية: أسماء واضحة ومنطقية (P12_CUSTOMER_EMAIL, BTN_SUBMIT_ORDER) بدل أرقام زي 4918239019283741.
2. تسلسل بصري حقيقي (Visual Hierarchy): بلمحة عين بتشوف إن الصفحة فيها منطقتين (Regions)، وكل منطقة فيها حقول وزراير، وزرار الدفع بينادي كود PL/SQL صريح.
3. منطق بيزنس صافي: كل دوشة السباكة لمحرك أبيكس اختفت، ومتبقاش غير التصميم المعماري والكود اللي يهمك بجد.

---

🤝 ليه وكيل البرمجة بالذكاء الاصطناعي بيعشق لغة 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 وهو واثق، وعارف بالظبط إيه اللي اتغير في المشروع.

---

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

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

تقدر تبدأ بالخطوات دي:

1. ابدأ بالتقسيم على مستوى الصفحات: اتأكد إن سكربتات التصدير بتاعتك بتستخدم خيار التجزئة (زي apex export -split أو أوامر SQLcl الرسمية) عشان كل صفحة تعيش في ملف مستقل.
2. التحويل لصيغة مقروءة للبشر: سواء بسكربتات بايثون أو أدوات DSL من المجتمع التقني، حول الأغلفة المليانة سباكة لشكل وصفي بسيط ومباشر.
3. أتمتة التجميع (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).