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

لماذا تستخدم TrueFoundry النماذج المدفوعة بالمخطط

غالبًا ما تمثل نماذج TrueFoundry بيانات وصفية - كائنات YAML/JSON يمكنك تطبيقها أيضًا باستخدام واجهة سطر الأوامر (CLI) (tfy apply -f ...). قد يتم تعديل نفس الكائن في واجهة المستخدم، أو تنزيله كـ YAML، أو إرساله إلى واجهة برمجة التطبيقات (API).

يمنح النهج المدفوع بالمخطط TrueFoundry ما يلي:

• مصدر واحد للحقيقة لهيكل النموذج (يتم تحميله من الواجهة الخلفية لكل نوع مورد).
• سلوك متسق عبر عمليات النشر، والمجموعات، والسياسات، والنماذج، والأسرار، ونماذج الإعدادات، أو أي نموذج آخر في المنصة.
• حقول متداخلة وشرطية دون إعادة كتابة منطق النموذج في كل شاشة.
• أدوات واجهة مستخدم (Widgets) خاصة بالمجال (محدد المجموعات، محدد الأسرار، حدود الموارد) مدمجة في بيئة تشغيل مشتركة.

النموذج الذهني: يصف المخطط شكل البيانات وكيفية تعديلها؛ ويحول FormBuilder هذا الوصف إلى نموذج عملي.

1. مخطط النموذج:

مخطط النموذج هو مصفوفة من تعريفات الحقول. كل حقل هو كائن له بعض الخصائص المهمة:

إليك مثال عام مبسط - ليس مخطط TrueFoundry حقيقيًا، ولكنه قريب من كيفية تفكير المنتج في التكوين:

[
  {
    "sort": 1,
    "jsonKey": "name",
    "label": "Service Name",
    "uiType": "Input",
    "validate": { "required": true, "pattern": "^[a-z0-9-]+$" }
  },
  {
    "sort": 2,
    "jsonKey": "image",
    "label": "Image",
    "uiType": "Group",
    "subParameters": [
      {
        "jsonKey": "type",
        "label": "Source",
        "uiType": "Radio",
        "validate": {
          "required": true,
          "defaultValue": "build",
          "options": [
            { "label": "Build", "value": "build" },
            { "label": "Existing image", "value": "existing" }
          ]
        }
      },
      {
        "jsonKey": "uri",
        "label": "Image URI",
        "uiType": "Input",
        "conditions": [
 		{ "jsonKey": "image.type", "op": "==", "value": "existing"  }
  ],
        "validate": { "required": true }
      }
    ]
  }
]

البيانات الوصفية/التكوين الناتج عند الإرسال:

{
  "name": "my-service",
  "image": { "type": "existing", "uri": "registry.io/app:v1" }
}

2. كيفية ربط المكونات وعرض الحقول

يتم العرض في مسار عمل صغير، والتدفق هو:

يتصفح FormBuilder شجرة المخطط ويختار مكون React لكل عقدة بناءً على uiType.

أنواع المكونات:

• أساسي: إدخال، اختيار، زر اختيار، مفتاح تبديل، رقم
• هيكلي: مجموعة (قسم)، هياكل (قائمة قابلة للتكرار)، KV / ENV (مفتاح-قيمة)
• خاص بالمجال: ClusterSelect، SecretSelect، Resources، ModelSelect، PermissionsMatrix، حقول MCP، وغيرها

الشروط: إذا كان image.type لا يساوي "existing"، فإن حقل URI لا يتم تحميله أبدًا. مع shouldUnregister: true، فإنه يغادر حالة النموذج أيضًا، وبذلك لا يمكن للقيم المخفية أن تتسرب إلى الحمولة.

منطق التعيين في الكود:

// FormComponentMap
const ComponentType = FormComponents[schema.uiType]
const CustomComp = CustomComponentsMap?.[schema.uiType]

if (!enabledByCondition) return null

return CustomComp
  ? <CustomComp schema={schema} />
  : <ComponentType schema={schema} />

3. كيفية التعامل مع حالة النموذج

يستخدم FormBuilder مكتبة react-hook-form كمحرك لحالته. هذا الاختيار يؤثر على كيفية تصرف المنتج.

التهيئة/استخدام المكونات - إنشاء وتعديل:

<FormBuilder
  schema={schema}
  defaultValues={existingManifest}   // edit: pre-fill; create: empty/template
  onSubmit={(manifest) => createOrUpdate({ manifest })}
/>

إعداد النموذج:

const methods = useForm({
  mode: 'onChange',          // validate as user types
  defaultValues,
  shouldUnregister: true,    // hidden fields drop out of state
})

تسجيل الحقول - يرتبط كل إدخال بمساره الخاص:

// Inside a text field component
const { register } = useFormContext()

<input
  {...register(schema.jsonKey, registerProps)}
  defaultValue={defaultValue}
/>

سياق إضافي - تمرير بيانات وقت التشغيل الخاصة بالنموذج بشكل منفصل عن قيم الحقول:

<FormBuilder
  schema={schema}
  extraContext={{
    workspace,
    cluster,
    serviceAccountOptions,  // dynamic dropdown options
    dataTestPrefix: 'create-cluster',
  }}
/>

كائن واحد، مسارات متداخلة:

توجد جميع قيم الحقول في كائن نموذج واحد. يسجل كل حقل تحت مسار jsonKey الكامل الخاص به:

• الاسم ← سلسلة نصية على المستوى الأعلى
• image.type ← قيمة متداخلة
• ports.0.container_port ← العنصر الأول في مصفوفة

عند تعديل حقل، فإنك تقوم بتعديل هذا الكائن المشترك. عند الإرسال، يقرأ FormBuilder الكائن بأكمله ويمرره إلى معالج النموذج (الذي عادةً ما يستدعي واجهة برمجة تطبيقات TrueFoundry أو ينتج YAML).

القيم الافتراضية ووضع التعديل:

عند فتح نموذج لإنشاء شيء ما، قد تكون defaultValues فارغة أو تأتي من قالب.

عند التحرير، تكون defaultValues عادةً هي البيان الحالي. تُملأ حقول النموذج مسبقًا من هذا الكائن. يتم وضع علامة "غير قابل للتغيير" على بعض الحقول في وضع التحرير (مثل اسم المورد) بحيث تظهر للقراءة فقط.

تتم إزالة الحقول المخفية من الحالة:

تستخدم نماذج TrueFoundry الخاصية shouldUnregister: true. وهذا يعني:

• إذا كان الحقل مخفيًا بشرط، فإنه يتم إلغاء تسجيله من حالة النموذج
• لا تتسرب قيمته إلى الحمولة المرسلة

هذا مهم للنماذج الشرطية: أنت ترسل فقط ما يمكن للمستخدم رؤيته وتعديله بالفعل.

4. كيفية عمل التحقق

يتم التحقق في نماذج TrueFoundry على طبقتين.

الطبقة 1: التحقق من المخطط (إعلاني)

يمكن لكتلة التحقق لكل حقل أن تحدد:

• مطلوب
• الحد الأدنى / الحد الأقصى (النطاق المسموح به للقيمة العددية الصحيحة)
• الحد الأدنى للطول / الحد الأقصى للطول (طول السلسلة النصية أو المصفوفة)
• النمط (تعبير نمطي) مع رسالة مخصصة
• القيمة الافتراضية
• غير قابل للتغيير (للقراءة فقط في وضع التحرير)

يتم تحويل هذه القواعد إلى قواعد تحقق خاصة بـ react-hook-form. تظهر الأخطاء مباشرة بجانب الحقل. يتم تشغيل التحقق عند التغيير (الوضع: 'onChange')، حتى يتلقى المستخدمون ملاحظات فورية أثناء الكتابة، وليس فقط عند الإرسال.

الطبقة 2: التحقق المخصص وغير المتزامن

يمكن للمخططات أيضًا إرفاق دالة تحقق مخصصة، تُستخدم عادةً لـ:

• تفرد الاسم ("كيان بهذا الاسم موجود بالفعل")
• عمليات تحقق مدعومة بواجهة برمجة التطبيقات قبل الإرسال
• قواعد الربط بين الحقول داخل مكون مخصص
• تُرفق الشاشات هذه القواعد في وقت التشغيل باستخدام أدوات مساعدة مثل "إرفاق التحقق باسم الحقل". تعرض واجهة المستخدم مؤشر تحميل أثناء تشغيل التحقق غير المتزامن (مثل فحص الاسم المؤجل).

useAttachValidation(schema, {
  name: async (name) => {
    const taken = await checkNameExists(name)
    return taken ? 'Name already exists' : true
  },
})

لنجمع كل ذلك: تجربتك كمستخدم

عند فتح "إنشاء مجموعة"، "نشر خدمة"، "إضافة نموذج"، أو "إدارة الأسرار":

• يقوم TrueFoundry بتحميل (أو بناء) مخطط لهذا المورد
• يعرض FormBuilder كل عقدة مخطط كمكون الإدخال المطلوب
• تُحدّث تعديلاتك كائن نموذج متداخلاً واحدًا
• يتم التحقق بشكل مستمر ومرة أخرى عند الإرسال
• الكائن النهائي هو بيان (manifest) - بنفس الشكل الذي ستستخدمه في YAML أو واجهة سطر الأوامر (CLI)

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