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

قالب أوراكل أبيكس يفرمل الـ AI Coding Agents ويخليهم تحت السيطرة 🐕⚡

الجزء الأول من سلسلة “أبيكس تحت السيطرة”.

3 أيام بناء، 36 كوميت (Commits)، وقالب مشروع معمول بحب ومزاج عالي.

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

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

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

🎯 السؤال اللي محير الملايين: الوكيل الذكي يلمس إيه وميلمسش إيه؟

إنك تبرمج وتشتغل سوى مع مساعد ذكي ده شيء ساحر ولطيف جداً—لحد ما تلاقي الوكيل قرر فجأة إن معنى “تحسين أداء الاستعلام” هو إنه يعيد كتابة نص جداول الداتابيز الساعة 2 بالليل!

وأنا ببني القالب ده لتطوير Oracle APEX مع وكلاء الذكاء الاصطناعي، كل قرار معماري (Architectural Decision) كان بيرجع لنفس السؤال الجوهري: هو إيه بالظبط اللي مسموح للوكيل الذكي إنه يمد إيده عليه؟

تعالوا آخدكم في جولة سريعة نشوف حلينا الحكاية دي إزاي.

🏗️ 1. قاعدة ذهبية واحدة بتحدد شكل المشروع كله

مشاريع Oracle APEX عندها عادة شهيرة إنها تخلط الحاجات اللي بتكتبها بإيدك مع الحاجات اللي السيرفر بيولدها أوتوماتيك.

عشان المساعد الذكي ميتشتتش ولا يتلخبط، القالب بيفصل بين الحاجات دي فصل فيزيائي واضح وصريح:

apps/<parsing-schema>/<app-id>/   ← ✏️ Source: ده كودك الحقيقي. عدل فيه براحتك.
database/<schema>/                ← 🪞 Mirror: ممنوع اللمس تماماً! (نسخة DBMS_METADATA للعرض فقط)
ai_generate/YYYY-MM-DD/           ← 🚀 Staging: سكربتات SQL و PL/SQL جاهزة للـ Deployment بتواريخها.
scratch/                          ← 🗑️ Disposable: ملعب تجارب مؤقت (معموله Gitignore).

شكل الشغل بيمشي إزاي:

فولدر apps/ بيشيل الـ APEXlang export (متقسم ملف مستقل لكل صفحة). ده سورس كود حقيقي تقدر أنت والمساعد الذكي تعدلوا فيه مباشرة.
فولدر database/ ده عامل زي فاترينة المتحف! نسخة DBMS_METADATA للجداول والـ Packages جاية طازة من أوراكل. تتفرج عليها وتقرا منها، بس إيدك متلمسهاش!
فولدر ai_generate/ ده المطبخ اللي الوكيل الذكي بيحط فيه سكربتات الـ SQL والـ PL/SQL الجديدة المتولدة، ومختومة باليوم والساعة. أنت بتراجعها بعينك، تشغلها بالـ Pipeline الرسمي، وبعدين تعمل Refresh لفاترينة الـ database/.
ملف AGENTS.md: القواعد دي مكتوبة بصوت عالي وواضح في ملف AGENTS.md، واللي كل وكلاء البرمجة الذكية الحديثة بتقراه وبتحترمه تلقائياً.

🛡️ 2. اتصالات داتابيز مستحيل تعك فيها (Database Safety Guards)

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

القالب بيحدد 3 بروفايلات اتصال منفصلة ومقفولة بالضبة والمفتاح:

Tables: لجداول الـ Schema وأوامر الـ DDL.
Code: للـ Packages، والـ Functions، والـ Triggers.
APEX Parsing Schema: لبيانات وميتاداتا التطبيق.

 [ الـ Coding Agent بتاعك ]
         │
         ▼  (بيحاول يشغل كود SQL...)
 ┌───────────────────────────────────────────────┐
 ┌ 🛑 كشف أمان: scripts/check_db_target.sh       │
 │  ✓ فحص اسم الداتابيز والـ Service            │
 │  ✓ التأكد من اليوزر والـ Schema من ملف الـ .env│
 │  ✓ إجبار بيئات الـ Production على وضع READ-ONLY│
 └───────────────────────────────────────────────┘
         │
         ▼
 [ تنفيذ آمن ومضمون جوه أوراكل ]

مزايا الأمان اللي اتبنت جوه القالب:

مفيش Connect Strings على المكشوف: القالب بيتعامل بس بأسماء Saved SQLcl Connections. لو الـ Agent فكر يخمن connection string هيتفرمل فوراً.
تحقق صارم من البيئة: قبل ما أي سطر SQL يتنفذ، السكربت بيراجع اسم الداتابيز، والخدمة، واليوزر، والـ Schema مع القيم المسجلة في ملف .env.
حارس الـ Production: أي بيئة متعلم عليها إنها Production بتكون Read-Only بشكل إجباري (SELECT بس، مفيش DML، مفيش DDL، ومفيش COMMIT). وعشان تكتب في أي بيئة تانية لازم تفعل حارس الأمان بأمر صريح:

scripts/check_db_target.sh write tables

مفيش أي حاجة هتشغله أوتوماتيك مكانك—وده صلب فكرة الأمان!

🧳 3. تصدير ذري (Atomic Exports بدون كوابيس نص-المشروع)

عمرك جربت تعمل export لمشروع APEX والسكربت هنج في النص، وساب لك فولدر المشروع كأن إعصار دخل مكتبة؟!

المشكلة دي قفلناها تماماً:

Staged Exports: كل عملية تصدير بتنزل كاملة الأول في فولدر تجارب مؤقت scratch/. ومش بتتنقل لفولدر السورس الحقيقي إلا بعد ما SQLcl يأكد خروج ناجح 100%.
حماية الشجرة الملوثة (Dirty Tree Protection): لو عندك أي تعديلات لسه معملتلهاش git commit في فولدر التطبيق، المزامنة بتقف فوراً ومترضاش تمسح شقاك وتعبك.
تسمية بالأرقام الثابتة: الفولدرات متسمية بأرقام الـ APEX_APP_ID الثابتة مش بالـ Aliases (اللي البني آدمين بيغيروها على مزاجهم كل شوية).
توحيد نهايات السطور (LF Endings): كل ملفات .apx متثبتة على نظام LF في .gitattributes، عشان كومبيلر الـ APEXlang يفضل مبسوط سواء شغال على Windows أو Mac أو Linux.

🗺️ 4. جي بي إس داخلي بدل اللف والـ Grep على الفاضي

تعالوا نشوف الموقف الكوميدي اللي كلنا مرينا بيه مع وكلاء الذكاء الاصطناعي (AI Agents) كالآتي:

أنت: “بقولك إيه، هو مين اللي بيقرا من جدول OOW_DEMO_SALES_HISTORY؟”
الوكيل الذكي: “سيبني بقى أعمل grep على كل ملف في الـ Repo من أوله لآخره، وأحرق لك الـ API Limits كلها، وأسحب 50 ألف سطر في الكونتكست، وفي الآخر أخمن إجابة نص كم!”

بدل ما يفضل يلف في الشوارع ويسأل طوب الأرض، القالب بيزود الوكيل الذكي بـ Knowledge Graph هندسي محدد بدقة.

 [ Page 10 Region ] ──(reads_from)──► [ DDL: ORDERS_TABLE ]
         │
         └──(secured_by)──► [ Auth Scheme: IS_ADMIN ]

باستخدام أداة Graphify ومستخرج APEXlang مخصص، القالب بيحلل ملفات الـ .apx ويطلع منها علاقات هندسية حقيقية:

contains
navigates_to
secured_by
reads_from
writes_to
calls

في التطبيقات التجريبية، السكربت بيولد 627 عقدة (نود) و 835 علاقة في ثواني معدودة — بدون أي هبد أو تخمين من نماذج الذكاء الاصطناعي. ولما المساعد الذكي (الـ Agent) يسأل عن جدول، استعلامه بينط فوراً على النود المظبوطة وملف الـ DDL الخاص بيها.

🧠 5. ذاكرة بتعيش حتى بعد ما تقفل الشات (Persistent Context)

كل مطور عارف حرقة الدم لما المساعد الذكي ينسى كل اللي اتفقتوا عليه لمجرد إنك فتحت شات جديد أو الجلسة خلصت.

عشان نحل المأساة دي، القالب بيوفر فولدر app_context/<app-id>/—وهو عبارة عن قاعدة معرفة مصغرة بتعيش للأبد لكل تطبيق:

ملاحظات المعمارية والـ Gotchas.
ملخصات منطق البيزنس (Business Logic).
الحركات الغريبة في التطبيق (مثلاً: “افتكر دايماً إن عناصر سلة الشراء متخزنة في APEX Collection مش جدول عادي”).

ده الفرق الحقيقي بين وكيل ذكي محتاج تشرح له القصة من أول وجديد كل يوم الصبح، وبين زميل شاطر قاعد معاك على المكتب بكوباية الشاي وجاهز ينطلق فوراً! ☕

🚀 جاهز تجربه في مشروعاتك؟

الموضوع مش هياخد منك دقيقتين:

اعمل Clone للـ Repository:
شغل أمر /init مع الـ Coding Agent بتاعك: هيمشي معاك خطوة بخطوة، يكتب ملف الـ .env، ويفحص بيئتك بالكامل.

استخرج الـ Knowledge Graph:

python3 setup_graphify_apx.py
graphify extract . --force

📦 مستودع المشروع على GitHub: github.com/ash2osh/APEX_PROJECT_TEMPLATE

جربه على تطبيق Oracle APEX حقيقي، ومستني أسمع رأيكم وتجاربكم!

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