Arxi بوابة القرار أصل أساسي
Docs
وثائق بوابة القرار

تقييم بوابة حتمي وقابل لإعادة التشغيل مع قرارات قابلة للتدقيق.

وثائق Asset Core

كتاب تأليف الشروط

نظرة سريعة

ما: تعريف الشروط التي تقيم بشكل حتمي وتتحقق بشكل نظيف لماذا: الشروط تربط البوابات بالأدلة؛ الدقة مهمة من: المطورون والمشغلون الذين يؤلفون سيناريوهات بوابة القرار المتطلبات المسبقة: evidence_flow_and_execution_model.md

ما هي الحالة؟

شرط هو فحص دليل:

{
  "condition_id": "tests_ok",
  "query": {
    "provider_id": "json",
    "check_id": "path",
    "params": { "file": "report.json", "jsonpath": "$.summary.failed" }
  },
  "comparator": "equals",
  "expected": 0,
  "policy_tags": []
}

يتكون من:

  1. استعلام: ما الأدلة التي يجب جلبها.
  2. المقارن: كيفية المقارنة.
  3. القيمة المتوقعة: القيمة التي يتم المقارنة بها (إذا لزم الأمر).

نتائج الولايات الثلاث

المقارنات تعيد TriState:

  • صحيح
  • خاطئ
  • غير معروف

قواعد رئيسية (بالضبط):

  • إذا كانت EvidenceResult.value مفقودة، فإن النتيجة هي unknown (باستثناء exists/not_exists).
  • إذا كانت expected مفقودة، فإن النتيجة هي unknown (باستثناء exists/not_exists).
  • equals / not_equals تعيد false/true عند عدم تطابق النوع.
  • الطلب، الترتيبي، يحتوي، in_set، deep_* يرجع unknown عند عدم تطابق النوع.

مرجع المقارنات

القواعد العامة

  • exists/not_exists تحقق وجود EvidenceResult.value، وليس JSON null.
  • JSON null هو قيمة موجودة (لذا فإن exists تعيد true).

جدول المقارنة

المقارنأنواع الأدلةالمطلوب المتوقعسلوك عدم تطابق النوع
equalsأي قيمة JSON، بايتاتنعميرجع false
not_equalsأي قيمة JSON، بايتاتنعميرجع true
greater_than / >= / < / <=رقم أو سلسلة تاريخ/وقت RFC3339نعمunknown
lex_*سلسلةنعمunknown
containsسلسلة أو مصفوفةنعمunknown
in_setJSON عددينعم (مصفوفة)unknown
deep_equals / deep_not_equalsكائن أو مصفوفةنعمunknown
exists / not_existsأيلاn/a

التفاصيل

المساواة (equals, not_equals)

  • الأرقام تقارن عبر المساواة المدركة للعشرية (10 == 10.0).
  • بالنسبة لأنواع البيانات غير الرقمية، يتم استخدام المساواة في JSON.

الترتيب (greater_than، إلخ)

  • يقبل الأرقام أو سلاسل التاريخ/الوقت وفقًا لمعيار RFC3339 (بما في ذلك التاريخ فقط YYYY-MM-DD).
  • أي أنواع أخرى -> unknown.

المعجم (lex_*)

  • سلاسل فقط؛ تقارن نقاط الشيفرة في يونيكود.
  • يتطلب تكوينًا صريحًا + اختيار مخطط (انظر “التحقق الصارم”).

يحتوي على

  • سلسلة: تطابق جزء من السلسلة.
  • Array: يجب أن تحتوي مصفوفة الأدلة على جميع عناصر المصفوفة المتوقعة.

في المجموعة (in_set)

  • يجب أن يكون المتوقّع مصفوفة.
  • يجب أن تكون الأدلة متجهة (ليست مصفوفة/كائن).

التساوي العميق

  • الكائنات/المصفوفات فقط؛ أنواع غير متطابقة -> unknown.
  • يتطلب تكوينًا صريحًا + اختيار المخطط.

بايتات

  • فقط equals / not_equals محددة.
  • يجب أن يكون المتوقّع مصفوفة JSON من الأعداد الصحيحة 0..255.

التحقق الصارم (مفعل افتراضيًا)

قرار بوابة القرار يتحقق من الشروط في وقت scenario_define:

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

المقارنات الخاصة تتطلب كلا:

  1. علامات التكوين (validation.enable_lexicographic / validation.enable_deep_equals)، و
  2. الاشتراك الصريح في المخطط عبر x-decision-gate.allowed_comparators (التحقق المسبق) أو العقد allowed_comparators.

إذا فشلت عملية التحقق، يتم رفض scenario_define أو precheck.

أنماط المزود

مزود الوقت

  • التحقق: الآن، بعد، قبل.
  • بعد/قبل تقبل timestamp كـ unix millis أو RFC3339 string.
  • بعد هو أكبر من بشكل صارم؛ قبل هو أقل من بشكل صارم.

مزود env

  • تحقق: get.
  • المفتاح المفقود يُرجع value = None بدون خطأ.
  • المفاتيح المحظورة أو غير الصالحة تعيد خطأ مزود الخدمة (provider_error عند حدود الأداة).

موفر json

  • تحقق: path.
  • إرجاع عدم المطابقة في JSONPath error.code = "jsonpath_not_found" و value = None.

مزود http

  • التحقق: status, body_hash.
  • status يُرجع حالة HTTP عددية.
  • body_hash يُرجع كائن HashDigest { algorithm, value }.
  • body_hash يسمح فقط بـ exists / not_exists (حسب العقد).

تجنب المجهول

لتقليل النتائج unknown:

  1. قدم expected لجميع المقارنات باستثناء exists/not_exists.
  2. مطابقة الأنواع بدقة لمقارنات غير المساواة.
  3. استخدم عقود المزودين لتأكيد المقارنات المسموح بها.

إفصاح الأدلة

قيم الأدلة لا تُرجع بواسطة scenario_next بشكل افتراضي. استخدم feedback: "evidence" إذا كان مسموحًا، أو افحص الأدلة عبر:

  • استخدم evidence_query (وفقًا لسياسة الكشف)، أو
  • قم بتصدير حزمة تشغيل باستخدام runpack_export.

سياسة الإفصاح مُعَدَّة في decision-gate.toml:

[evidence]
allow_raw_values = false
require_provider_opt_in = true

[[providers]]
name = "json"
type = "builtin"
allow_raw = true

allow_raw هو علم config خاص بكل مزود (ليس جزءًا من عقد المزود). أسماء المزودين فريدة؛ المعرفات المدمجة (time, env, json, http) محجوزة.

قائمة التحقق

  • معرفات الحالة فريدة ضمن السيناريو.
  • يتطابق اسم فحص المزود مع عقد المزود.
  • يُسمح باستخدام المقارنات في مخطط النتائج.
  • نوع القيمة المتوقعة يتطابق مع نوع الدليل.
  • policy_tags موجود (مطلوب حسب المخطط، قد يكون فارغًا).

المراجع المتقاطعة