#نظرة عامة على نظام السياق

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

• FlowEngineContext (السياق العالمي): فريد عالميًا، يمكن لجميع النماذج وسير العمل الوصول إليه، وهو مناسب لتسجيل الخدمات والتكوينات العالمية وما إلى ذلك.
• FlowModelContext (سياق النموذج): يُستخدم لمشاركة السياق داخل شجرة النموذج، حيث تقوم النماذج الفرعية بتفويض سياق النموذج الأب تلقائيًا، مع دعم التجاوز بنفس الاسم، وهو مناسب لعزل المنطق والبيانات على مستوى النموذج.
• FlowRuntimeContext (سياق وقت تشغيل سير العمل): يتم إنشاؤه عند كل تنفيذ لسير العمل، ويستمر طوال دورة حياة تشغيل سير العمل، وهو مناسب لنقل البيانات وتخزين المتغيرات وتسجيل حالة التشغيل داخل سير العمل. يدعم وضعين mode: 'runtime' | 'settings'، واللذان يتوافقان مع حالة التشغيل وحالة الإعدادات على التوالي.

جميع FlowEngineContext (السياق العالمي)، وFlowModelContext (سياق النموذج)، وFlowRuntimeContext (سياق وقت تشغيل سير العمل) وما إلى ذلك، هي فئات فرعية أو مثيلات لـ FlowContext.

#🗂️ مخطط الهيكل الهرمي

FlowEngineContext (السياق العالمي)
│
├── FlowModelContext (سياق النموذج)
│     ├── FlowModelContext فرعي (نموذج فرعي)
│     │     ├── FlowRuntimeContext (سياق وقت تشغيل سير العمل)
│     │     └── FlowRuntimeContext (سياق وقت تشغيل سير العمل)
│     └── FlowRuntimeContext (سياق وقت تشغيل سير العمل)
│
├── FlowModelContext (سياق النموذج)
│     └── FlowRuntimeContext (سياق وقت تشغيل سير العمل)
│
└── FlowModelContext (سياق النموذج)
      ├── FlowModelContext فرعي (نموذج فرعي)
      │     └── FlowRuntimeContext (سياق وقت تشغيل سير العمل)
      └── FlowRuntimeContext (سياق وقت تشغيل سير العمل)

• يمكن لـ FlowModelContext الوصول إلى خصائص وأساليب FlowEngineContext من خلال آلية التفويض (delegate)، مما يحقق مشاركة القدرات العالمية.
• يمكن لـ FlowModelContext الخاص بالنموذج الفرعي الوصول إلى سياق النموذج الأب (علاقة متزامنة) من خلال آلية التفويض (delegate)، مع دعم التجاوز بنفس الاسم.
• لن تنشئ نماذج الأب والابن غير المتزامنة علاقة تفويض (delegate) لتجنب تلوث الحالة.
• يصل FlowRuntimeContext دائمًا إلى FlowModelContext المقابل له من خلال آلية التفويض (delegate)، ولكنه لا يقوم بالإرسال العكسي للأعلى.

#🧭 حالة التشغيل وحالة الإعدادات (mode)

يدعم FlowRuntimeContext وضعين، يتم التمييز بينهما عبر المعلمة mode:

• mode: 'runtime' (حالة التشغيل): تُستخدم في مرحلة التنفيذ الفعلي لسير العمل، حيث تُرجع الخصائص والأساليب بيانات حقيقية. مثال:

  console.log(runtimeCtx.steps.step1.result); // 42

• mode: 'settings' (حالة الإعدادات): تُستخدم في مرحلة تصميم وتكوين سير العمل، حيث يُرجع الوصول إلى الخصائص سلسلة قالب متغير، مما يسهل اختيار التعبيرات والمتغيرات. مثال:

  console.log(settingsCtx.steps.step1.result); // '{{ ctx.steps.step1.result }}'

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

#🤖 معلومات السياق الموجهة للأدوات/النماذج الكبيرة

في بعض السيناريوهات (مثل تحرير كود RunJS في JS*Model، أو البرمجة بالذكاء الاصطناعي)، يحتاج "الطرف المستدعي" إلى فهم ما يلي دون تنفيذ الكود:

• ما هي القدرات الثابتة المتوفرة تحت ctx الحالي (وثائق واجهة برمجة التطبيقات API، المعلمات، الأمثلة، روابط الوثائق، إلخ).
• ما هي المتغيرات المتاحة في الواجهة/حالة التشغيل الحالية (مثل الهياكل الديناميكية كـ "السجل الحالي"، "سجل النافذة المنبثقة الحالي"، إلخ).
• لقطة صغيرة الحجم لبيئة التشغيل الحالية (تُستخدم لـ prompt).

#1) await ctx.getApiInfos(options?) (معلومات API الثابتة)

#2) await ctx.getVarInfos(options?) (معلومات هيكل المتغيرات)

• مبني على defineProperty(...).meta (بما في ذلك مصنع meta) لبناء هيكل المتغيرات.
• يدعم قص المسار path والتحكم في العمق maxDepth.
• يتوسع للأسفل فقط عند الحاجة.

المعلمات الشائعة:

• maxDepth: أقصى مستوى للتوسع (الافتراضي 3).
• path: string | string[]: القص، يخرج فقط الشجرة الفرعية للمسار المحدد.

#3) await ctx.getEnvInfos() (لقطة لبيئة وقت التشغيل)

هيكل العقدة (مبسط):

type EnvNode = {
  description?: string;
  getVar?: string; // يمكن استخدامه مباشرة لـ await ctx.getVar(getVar)، يبدأ بـ "ctx."
  value?: any; // قيمة ثابتة تم تحليلها/قابلة للتسلسل
  properties?: Record<string, EnvNode>;
};