السمات (Traits)

تعريفات السمات وأنواع آلات الحالة في Orb

---

كيف تعمل السمات في بنية Orb - آلات الحالة (State Machines)، الحراس (Guards)، التأثيرات (Effects)، والتواصل عبر الوحدات المدارية.

ذو صلة: الكيانات

---

نظرة عامة

في Orb، السمة (Trait) هي آلة حالة (State Machine) تحدد السلوك لكيان ما. التركيبة الأساسية هي:

Orbital Unit = Entity + Traits + Pages

بينما تحدد الكيانات شكل البيانات، تحدد السمات كيف تتغير تلك البيانات عبر الزمن من خلال الحالات (States)، الانتقالات (Transitions)، الحراس (Guards)، والتأثيرات (Effects).

---

تعريف السمة (Trait)

تُعرَّف السمة (Trait) في برنامج .orb بالبنية التالية:

{
  "اسم": "TaskManagement",
  "فئة": "interaction",
  "كيان_مرتبط": "Task",
  "وصف": "Manages task lifecycle and status changes",
  "يصدر": [
    {
      "حدث": "TASK_COMPLETED",
      "نطاق": "external"
    }
  ],
  "يستمع": [
    {
      "حدث": "USER_ASSIGNED",
      "محفزات": "ASSIGN"
    }
  ],
  "آلة_حالة": {
    "حالات": [
      {
        "اسم": "idle",
        "أولي": true
      },
      {
        "اسم": "active"
      },
      {
        "اسم": "completed",
        "نهائي": true
      }
    ],
    "أحداث": [
      {
        "مفتاح": "START",
        "اسم": "Start Task"
      },
      {
        "مفتاح": "COMPLETE",
        "اسم": "Complete Task"
      }
    ],
    "انتقالات": [
      {
        "من": "idle",
        "إلى": "active",
        "حدث": "START",
        "تأثيرات": [
          [
            "تعيين",
            "@كيان.id",
            "status",
            "active"
          ]
        ]
      },
      {
        "من": "active",
        "إلى": "completed",
        "حدث": "COMPLETE",
        "حارس": [
          "يساوي",
          "@كيان.assigneeId",
          "@مستخدم.id"
        ],
        "تأثيرات": [
          [
            "تعيين",
            "@كيان.id",
            "status",
            "completed"
          ],
          [
            "بث",
            "TASK_COMPLETED",
            {
              "taskId": "@كيان.id"
            }
          ]
        ]
      }
    ]
  }
}

خصائص السمة (Trait)

الخاصية	مطلوبة	الوصف
name	نعم	معرِّف السمة (PascalCase)
category	لا	فئة السمة (انظر أدناه)
linkedEntity	لا	الكيان الذي تعمل عليه هذه السمة
description	لا	وصف مقروء للبشر
emits	لا	الأحداث التي يمكن لهذه السمة إرسالها
listens	لا	الأحداث التي تستمع إليها هذه السمة
stateMachine	نعم	تعريف آلة الحالة (State Machine)
ticks	لا	تأثيرات مجدولة/دورية
config	لا	مخطط الإعدادات

---

فئات السمات (Trait Categories)

تُصنف السمات حسب غرضها الأساسي:

الفئة	الغرض	التأثيرات النموذجية
interaction	معالجة أحداث واجهة المستخدم على جانب العميل	render-ui، navigate، notify
integration	عمليات جانب الخادم	persist، fetch، call-service
lifecycle	إدارة دورة حياة الكيان	persist، emit
gameCore	حلقة اللعبة والفيزياء	set، emit، ticks
gameEntity	سلوكيات كيانات اللعبة	set، emit، render-ui
gameUi	واجهة اللعبة، HUD، عناصر التحكم	render-ui، notify

أمثلة الفئات

سمة التفاعل (Interaction Trait) - تعالج أحداث الواجهة:

{
  "اسم": "FormInteraction",
  "فئة": "interaction",
  "آلة_حالة": {
    "انتقالات": [
      {
        "حدث": "SUBMIT",
        "تأثيرات": [
          [
            "عرض_واجهة",
            "main",
            {
              "نوع": "form",
              "loading": true
            }
          ],
          [
            "بث",
            "FORM_SUBMITTED",
            "@حمولة"
          ]
        ]
      }
    ]
  }
}

سمة التكامل (Integration Trait) - تعالج عمليات الخادم:

{
  "اسم": "DataPersistence",
  "فئة": "integration",
  "آلة_حالة": {
    "انتقالات": [
      {
        "حدث": "SAVE",
        "تأثيرات": [
          [
            "حفظ",
            "update",
            "Task",
            "@كيان.id",
            "@حمولة"
          ],
          [
            "بث",
            "DATA_SAVED",
            {
              "معرف": "@كيان.id"
            }
          ]
        ]
      }
    ]
  }
}

---

آلة الحالة (State Machine)

كل سمة لها آلة حالة تحدد سلوكها.

الحالات (States)

تمثل الحالات الأوضاع الممكنة للسمة:

{
  "حالات": [
    {
      "اسم": "idle",
      "أولي": true,
      "وصف": "Waiting for input"
    },
    {
      "اسم": "loading",
      "وصف": "Fetching data"
    },
    {
      "اسم": "active",
      "وصف": "Ready for interaction"
    },
    {
      "اسم": "error",
      "نهائي": true,
      "وصف": "Error state"
    }
  ]
}

الخاصية	الوصف
name	معرِّف الحالة (أحرف صغيرة)
isInitial	حالة البداية (واحدة مطلوبة بالضبط)
isTerminal	لا توجد انتقالات خارجية متوقعة
description	وصف مقروء للبشر

الأحداث (Events)

الأحداث تُحفِّز انتقالات الحالة:

{
  "أحداث": [
    {
      "مفتاح": "INIT",
      "اسم": "Initialize"
    },
    {
      "مفتاح": "SUBMIT",
      "اسم": "Submit Form",
      "حمولة": [
        {
          "اسم": "email",
          "نوع": "نص",
          "مطلوب": true
        },
        {
          "اسم": "name",
          "نوع": "نص",
          "مطلوب": true
        }
      ]
    },
    {
      "مفتاح": "ERROR",
      "اسم": "Error Occurred"
    }
  ]
}

الخاصية	الوصف
key	معرِّف الحدث (UPPER_SNAKE_CASE)
name	اسم العرض
payload	مخطط الحمولة المتوقعة

الانتقالات (Transitions)

الانتقالات تحدد كيف تتغير الحالات استجابةً للأحداث:

{
  "انتقالات": [
    {
      "من": "idle",
      "إلى": "loading",
      "حدث": "SUBMIT",
      "حارس": [
        "و",
        [
          "لا_يساوي",
          "@حمولة.email",
          ""
        ],
        [
          "لا_يساوي",
          "@حمولة.name",
          ""
        ]
      ],
      "تأثيرات": [
        [
          "تعيين",
          "@كيان.id",
          "email",
          "@حمولة.email"
        ],
        [
          "حفظ",
          "create",
          "User",
          "@حمولة"
        ]
      ]
    },
    {
      "من": [
        "loading",
        "active"
      ],
      "إلى": "error",
      "حدث": "ERROR"
    }
  ]
}

الخاصية	الوصف
from	حالة المصدر - سلسلة نصية أو مصفوفة
to	حالة الهدف (دائماً واحدة)
event	مفتاح الحدث المُحفِّز
guard	شرط يجب تحققه (اختياري)
effects	تأثيرات تُنفَّذ عند الانتقال (اختياري)

انتقالات متعددة المصادر: استخدم مصفوفة لـ from للتعامل مع نفس الحدث من حالات متعددة:

{
  "من": [
    "idle",
    "error"
  ],
  "إلى": "loading",
  "حدث": "RETRY"
}

---

الحراس (Guards)

الحراس (Guards) هي شروط يجب أن تُقيَّم إلى true ليحدث الانتقال (Transition). تستخدم صيغة تعبيرات S-expression.

عوامل الحراس

الفئة	العوامل
المقارنة	=، !=، <، >، <=، >=
المنطق	and، or، not
الرياضيات	+، -، *، /، %
المصفوفات	count، includes، every، some

أمثلة الحراس

// مساواة بسيطة
["=", "@entity.status", "active"]

// شرط مركب
["and",
  ["!=", "@payload.email", ""],
  ["!=", "@payload.name", ""]
]

// مقارنة رقمية
[">=", "@entity.balance", "@payload.amount"]

// فحص مصفوفة
[">", ["count", "@entity.items"], 0]

// صلاحية المستخدم
["=", "@entity.ownerId", "@user.id"]

// حارس معقد
["and",
  ["=", "@entity.status", "pending"],
  ["or",
    ["=", "@user.role", "admin"],
    ["=", "@entity.assigneeId", "@user.id"]
  ]
]

ربط الحراس

يمكن للحراس الإشارة إلى البيانات عبر الربط (انظر ربط الكيانات):

الربط	الوصف
@entity.field	قيمة حقل الكيان الحالي
@payload.field	حقل حمولة الحدث
@state	اسم حالة السمة الحالية
@user.id	معرِّف المستخدم المصادق
@now	الطابع الزمني الحالي

فشل الحارس (Guard)

إذا قُيِّم الحارس (Guard) إلى false:

1. يُحظر الانتقال (Transition)
2. لا تُنفَّذ أي تأثيرات
3. تبقى الحالة دون تغيير
4. الاستجابة تشير إلى transitioned: false

---

التأثيرات (Effects)

التأثيرات (Effects) هي إجراءات تُنفَّذ عند حدوث انتقال (Transition). تستخدم صيغة تعبيرات S-expression.

أنواع التأثيرات

التأثير	الخادم	العميل	الغرض
render-ui	يُتجاهل	يُنفَّذ	عرض نمط في فتحة واجهة المستخدم
navigate	يُتجاهل	يُنفَّذ	التنقل بين المسارات
notify	يُتجاهل	يُنفَّذ	عرض إشعار/رسالة
fetch	يُنفَّذ	يُتجاهل	استعلام قاعدة البيانات
persist	يُنفَّذ	يُتجاهل	إنشاء/تحديث/حذف البيانات
call-service	يُنفَّذ	يُتجاهل	استدعاء واجهة برمجية خارجية
emit	يُنفَّذ	يُنفَّذ	نشر حدث
set	يُنفَّذ	يُنفَّذ	تعديل حقل الكيان (يدعم الزيادة/النقصان عبر تعبيرات S-expression)

نموذج التنفيذ المزدوج

تُنفَّذ السمات على كل من العميل والخادم في وقت واحد:

┌─────────────────────────────────────────────────────────────┐
│  Client                          Server                     │
│  ───────                         ──────                     │
│  render-ui  ✓                    render-ui  → clientEffects │
│  navigate   ✓                    navigate   → clientEffects │
│  notify     ✓                    notify     → clientEffects │
│  fetch      ✗                    fetch      ✓ (queries DB)  │
│  persist    ✗                    persist    ✓ (writes DB)   │
│  call-service ✗                  call-service ✓ (API call)  │
│  emit       ✓ (EventBus)         emit       ✓ (cross-orbital)│
│  set        ✓                    set        ✓               │
└─────────────────────────────────────────────────────────────┘

أمثلة التأثيرات

render-ui - عرض نمط واجهة المستخدم:

[
  "عرض_واجهة",
  "main",
  {
    "نوع": "entity-table",
    "كيان": "Task",
    "columns": [
      "title",
      "status",
      "dueDate"
    ]
  }
]

persist - عمليات قاعدة البيانات:

// إنشاء
["persist", "create", "Task", "@payload"]

// تحديث
["persist", "update", "Task", "@entity.id", { "status": "completed" }]

// حذف
["persist", "delete", "Task", "@entity.id"]

fetch - استعلام البيانات:

[
  "جلب",
  "Task",
  {
    "status": "active",
    "assigneeId": "@مستخدم.id"
  }
]

emit - نشر حدث:

[
  "بث",
  "TASK_COMPLETED",
  {
    "taskId": "@كيان.id",
    "completedBy": "@مستخدم.id"
  }
]

set - تعديل حقل:

["set", "@entity.id", "status", "active"]
["set", "@entity.id", "updatedAt", "@now"]
// الزيادة/النقصان باستخدام عوامل الرياضيات:
["set", "@entity.id", "score", ["+", "@entity.score", 10]]  // زيادة بـ 10
["set", "@entity.id", "health", ["-", "@entity.health", 5]]  // نقصان بـ 5

ملاحظة: increment و decrement ليسا أنواع تأثيرات منفصلة. استخدم تأثير set مع عوامل الرياضيات في تعبيرات S-expression (+، -) لتعديل الحقول الرقمية.

navigate - تغيير المسار:

[
  "انتقال",
  "/tasks/@entity.id"
]

notify - عرض إشعار:

[
  "إشعار",
  "Task completed successfully",
  "success"
]

call-service - واجهة برمجية خارجية:

[
  "استدعاء_خدمة",
  "email",
  "send",
  {
    "إلى": "@كيان.email",
    "subject": "Task Assigned",
    "body": "You have been assigned a new task."
  }
]

---

linkedEntity - ربط السمة بالكيان

خاصية linkedEntity تحدد الكيان الذي تعمل عليه السمة.

الكيان الأساسي

كل وحدة مدارية لها كيان أساسي. السمات بدون linkedEntity تستخدم هذا الكيان:

{
  "name": "TaskManagement",
  "entity": { "name": "Task", "fields": [...] },
  "traits": [
    { "name": "StatusTrait" }  // تستخدم كيان Task
  ]
}

linkedEntity الصريح

حدد linkedEntity للعمل على كيان مختلف:

{
  "اسم": "TaskManagement",
  "كيان": {
    "اسم": "Task"
  },
  "سمات": [
    {
      "اسم": "StatusTrait",
      "كيان_مرتبط": "Task"
    },
    {
      "اسم": "CommentTrait",
      "كيان_مرتبط": "Comment"
    },
    {
      "اسم": "PlayerStatsTrait",
      "كيان_مرتبط": "Player"
    }
  ]
}

لماذا linkedEntity؟

1. سمات قابلة لإعادة الاستخدام - سمة عامة يمكنها العمل مع أي كيان
2. عمليات عبر الكيانات - العمل على كيانات مرتبطة
3. أمان الأنواع - المُصرِّف يتحقق من مراجع حقول الكيان
4. تبعيات واضحة - الربط الصريح يحسن المقروئية

انظر ربط الكيانات لمزيد من التفاصيل.

---

التواصل عبر الأحداث (emit/listen)

تتواصل السمات من خلال الأحداث، مما يمكّن الربط الفضفاض بين الوحدات المدارية.

إرسال الأحداث (Emitting Events)

أعلن الأحداث التي يمكن للسمة إرسالها:

{
  "اسم": "OrderFlow",
  "يصدر": [
    {
      "حدث": "ORDER_CONFIRMED",
      "نطاق": "external",
      "وصف": "Fired when order is confirmed",
      "حمولة": [
        {
          "اسم": "orderId",
          "نوع": "نص"
        },
        {
          "اسم": "items",
          "نوع": "array"
        }
      ]
    }
  ]
}

الإرسال في التأثيرات:

[
  "بث",
  "ORDER_CONFIRMED",
  {
    "orderId": "@كيان.id",
    "عناصر": "@كيان.items"
  }
]

الاستماع للأحداث (Listening for Events)

أعلن الأحداث التي تستمع إليها السمة:

{
  "اسم": "InventorySync",
  "يستمع": [
    {
      "حدث": "ORDER_CONFIRMED",
      "محفزات": "RESERVE_STOCK",
      "نطاق": "external",
      "تخطيط_الحمولة": {
        "عناصر": "@حمولة.items"
      },
      "حارس": [
        "أكبر_من",
        [
          "count",
          "@حمولة.items"
        ],
        0
      ]
    }
  ]
}

الخاصية	الوصف
event	اسم الحدث للاستماع إليه
triggers	الحدث الداخلي المُحفَّز (الافتراضي هو اسم الحدث)
scope	internal (نفس الوحدة المدارية) أو external (عبر الوحدات المدارية)
payloadMapping	تحويل الحمولة الواردة
guard	شرط اختياري لتصفية الأحداث

نطاق الحدث (Event Scope)

النطاق	الوصف
internal	أحداث داخل نفس الوحدة المدارية فقط
external	الأحداث يمكنها عبور حدود الوحدات المدارية

مسار التواصل عبر الوحدات المدارية

┌──────────────────┐         ┌──────────────────┐
│  OrderManagement │         │ InventoryManagement│
│                  │         │                  │
│  ┌────────────┐  │  emit   │  ┌────────────┐  │
│  │ OrderFlow  │──┼────────►│  │InventorySync│  │
│  └────────────┘  │ ORDER_  │  └────────────┘  │
│                  │CONFIRMED│                  │
└──────────────────┘         └──────────────────┘

1. سمة OrderFlow تُرسل ORDER_CONFIRMED (نطاق خارجي)
2. ناقل الأحداث يبث لجميع السمات المستمعة
3. InventorySync تستقبل الحدث وتحوّل الحمولة
4. حدث RESERVE_STOCK يُحفَّز على InventorySync
5. آلة الحالة تعالج الانتقال بشكل طبيعي

---

النبضات (Ticks) - التأثيرات المجدولة

النبضات تُشغّل تأثيرات بشكل دوري، حتى بدون تفاعل المستخدم.

تعريف النبضة

{
  "نبضات": [
    {
      "اسم": "cleanup_expired",
      "فاصل_زمني": "60000",
      "حارس": [
        "أكبر_من",
        [
          "count",
          "@كيان.expiredSessions"
        ],
        0
      ],
      "تأثيرات": [
        [
          "حفظ",
          "delete",
          "Session",
          {
            "expiresAt": [
              "أصغر_من",
              "@الآن"
            ]
          }
        ]
      ],
      "وصف": "Clean up expired sessions every minute"
    },
    {
      "اسم": "sync_status",
      "فاصل_زمني": "5000",
      "تأثيرات": [
        [
          "جلب",
          "ExternalStatus",
          {}
        ],
        [
          "تعيين",
          "@كيان.id",
          "lastSync",
          "@الآن"
        ]
      ]
    }
  ]
}

خصائص النبضة

الخاصية	الوصف
name	معرِّف النبضة
interval	بالمللي ثانية، أو سلسلة نصية مثل "5s"، "1m"
guard	شرط (النبضة تُتخطى إذا كان خطأ)
effects	التأثيرات المُنفَّذة
appliesTo	معرِّفات كيان محددة (اختياري)
description	وصف بشري

أنماط النبضات الشائعة

التنظيف:

{
  "اسم": "cleanup",
  "فاصل_زمني": "300000",
  "تأثيرات": [
    [
      "حفظ",
      "delete",
      "TempData",
      {
        "تاريخ_الإنشاء": [
          "أصغر_من",
          [
            "طرح",
            "@الآن",
            86400000
          ]
        ]
      }
    ]
  ]
}

المزامنة الدورية:

{
  "اسم": "sync",
  "فاصل_زمني": "10000",
  "تأثيرات": [
    [
      "استدعاء_خدمة",
      "external-api",
      "fetch-updates",
      {}
    ],
    [
      "بث",
      "DATA_SYNCED",
      {
        "timestamp": "@الآن"
      }
    ]
  ]
}

حلقة اللعبة:

{
  "اسم": "game_tick",
  "فاصل_زمني": "16",
  "تأثيرات": [
    [
      "تعيين",
      "@كيان.id",
      "position",
      [
        "جمع",
        "@كيان.position",
        "@كيان.velocity"
      ]
    ],
    [
      "عرض_واجهة",
      "canvas",
      {
        "نوع": "game-canvas"
      }
    ]
  ]
}

---

مراجع السمات مقابل السمات المضمّنة

يمكن تعريف السمات مضمّنة أو الإشارة إليها من مصادر خارجية.

التعريف المضمّن

تعريف السمة مباشرة في الوحدة المدارية:

{
  "orbital": "TaskManagement",
  "traits": [
    {
      "name": "StatusTrait",
      "stateMachine": {
        "states": [...],
        "transitions": [...]
      }
    }
  ]
}

التعريف بالمرجع

الإشارة إلى سمة من المكتبة القياسية أو الاستيرادات:

{
  "مدار": "TaskManagement",
  "يستخدم": [
    {
      "من": "std/behaviors/crud",
      "كـ": "CRUD"
    }
  ],
  "سمات": [
    {
      "مرجع": "CRUD.traits.CRUDManagement",
      "كيان_مرتبط": "Task",
      "تكوين": {
        "allowDelete": true,
        "حذف_ناعم": false
      }
    }
  ]
}

خصائص المرجع

الخاصية	الوصف
ref	مسار السمة (مثال: "Alias.traits.TraitName")
linkedEntity	تجاوز ربط الكيان
config	تجاوز الإعدادات

متى تستخدم المراجع

• أنماط قابلة لإعادة الاستخدام - CRUD، المصادقة، التصفح
• سلوكيات قياسية - من std/behaviors/
• المشاركة عبر المشاريع - الاستيراد من برامج أخرى
• مدفوعة بالإعدادات - نفس السمة، إعدادات مختلفة

---

مثال كامل

سمة كاملة توضح جميع الميزات:

{
  "اسم": "CheckoutFlow",
  "فئة": "integration",
  "كيان_مرتبط": "Order",
  "وصف": "Handles the checkout process from cart to confirmation",
  "يصدر": [
    {
      "حدث": "ORDER_PLACED",
      "نطاق": "external",
      "حمولة": [
        {
          "اسم": "orderId",
          "نوع": "نص"
        },
        {
          "اسم": "total",
          "نوع": "رقم"
        }
      ]
    },
    {
      "حدث": "PAYMENT_FAILED",
      "نطاق": "internal"
    }
  ],
  "يستمع": [
    {
      "حدث": "CART_UPDATED",
      "محفزات": "RECALCULATE",
      "نطاق": "internal"
    },
    {
      "حدث": "INVENTORY_RESERVED",
      "محفزات": "CONFIRM_STOCK",
      "نطاق": "external"
    }
  ],
  "آلة_حالة": {
    "حالات": [
      {
        "اسم": "cart",
        "أولي": true,
        "وصف": "Shopping cart"
      },
      {
        "اسم": "checkout",
        "وصف": "Entering shipping/payment"
      },
      {
        "اسم": "processing",
        "وصف": "Processing payment"
      },
      {
        "اسم": "confirmed",
        "وصف": "Order confirmed"
      },
      {
        "اسم": "failed",
        "نهائي": true,
        "وصف": "Order failed"
      }
    ],
    "أحداث": [
      {
        "مفتاح": "PROCEED",
        "اسم": "Proceed to Checkout"
      },
      {
        "مفتاح": "SUBMIT",
        "اسم": "Submit Order",
        "حمولة": [
          {
            "اسم": "paymentMethod",
            "نوع": "نص",
            "مطلوب": true
          }
        ]
      },
      {
        "مفتاح": "PAYMENT_SUCCESS",
        "اسم": "Payment Succeeded"
      },
      {
        "مفتاح": "PAYMENT_FAILED",
        "اسم": "Payment Failed"
      },
      {
        "مفتاح": "RECALCULATE",
        "اسم": "Recalculate Totals"
      },
      {
        "مفتاح": "CONFIRM_STOCK",
        "اسم": "Stock Confirmed"
      }
    ],
    "انتقالات": [
      {
        "من": "cart",
        "إلى": "checkout",
        "حدث": "PROCEED",
        "حارس": [
          "أكبر_من",
          [
            "count",
            "@كيان.items"
          ],
          0
        ],
        "تأثيرات": [
          [
            "عرض_واجهة",
            "main",
            {
              "نوع": "form",
              "schema": "checkout"
            }
          ]
        ]
      },
      {
        "من": "checkout",
        "إلى": "processing",
        "حدث": "SUBMIT",
        "حارس": [
          "و",
          [
            "لا_يساوي",
            "@حمولة.paymentMethod",
            ""
          ],
          [
            "أكبر_أو_يساوي",
            "@كيان.total",
            0
          ]
        ],
        "تأثيرات": [
          [
            "تعيين",
            "@كيان.id",
            "paymentMethod",
            "@حمولة.paymentMethod"
          ],
          [
            "تعيين",
            "@كيان.id",
            "status",
            "processing"
          ],
          [
            "استدعاء_خدمة",
            "payment",
            "charge",
            {
              "amount": "@كيان.total",
              "method": "@حمولة.paymentMethod"
            }
          ],
          [
            "عرض_واجهة",
            "main",
            {
              "نوع": "stats",
              "loading": true
            }
          ]
        ]
      },
      {
        "من": "processing",
        "إلى": "confirmed",
        "حدث": "PAYMENT_SUCCESS",
        "تأثيرات": [
          [
            "تعيين",
            "@كيان.id",
            "status",
            "confirmed"
          ],
          [
            "تعيين",
            "@كيان.id",
            "confirmedAt",
            "@الآن"
          ],
          [
            "حفظ",
            "update",
            "Order",
            "@كيان.id",
            "@كيان"
          ],
          [
            "بث",
            "ORDER_PLACED",
            {
              "orderId": "@كيان.id",
              "total": "@كيان.total"
            }
          ],
          [
            "إشعار",
            "Order confirmed!",
            "success"
          ],
          [
            "انتقال",
            "/orders/@entity.id"
          ]
        ]
      },
      {
        "من": "processing",
        "إلى": "failed",
        "حدث": "PAYMENT_FAILED",
        "تأثيرات": [
          [
            "تعيين",
            "@كيان.id",
            "status",
            "failed"
          ],
          [
            "بث",
            "PAYMENT_FAILED",
            {
              "orderId": "@كيان.id"
            }
          ],
          [
            "إشعار",
            "Payment failed. Please try again.",
            "error"
          ]
        ]
      },
      {
        "من": [
          "cart",
          "checkout"
        ],
        "إلى": "cart",
        "حدث": "RECALCULATE",
        "تأثيرات": [
          [
            "تعيين",
            "@كيان.id",
            "total",
            [
              "مصفوفة/تقليص",
              "@كيان.items",
              [
                "لامدا",
                [
                  "sum",
                  "item"
                ],
                [
                  "جمع",
                  "@sum",
                  "@item.price"
                ]
              ],
              0
            ]
          ]
        ]
      }
    ]
  },
  "نبضات": [
    {
      "اسم": "expire_abandoned",
      "فاصل_زمني": "300000",
      "حارس": [
        "و",
        [
          "يساوي",
          "@حالة",
          "checkout"
        ],
        [
          "أصغر_من",
          "@كيان.updatedAt",
          [
            "طرح",
            "@الآن",
            1800000
          ]
        ]
      ],
      "تأثيرات": [
        [
          "تعيين",
          "@كيان.id",
          "status",
          "abandoned"
        ],
        [
          "حفظ",
          "update",
          "Order",
          "@كيان.id",
          {
            "status": "abandoned"
          }
        ]
      ]
    }
  ]
}

---

ملخص

يوفر نظام السمات في Orb:

1. آلات الحالة (State Machines) - تحديد الحالات الممكنة والانتقالات
2. الحراس (Guards) - حماية الانتقالات بشروط منطقية
3. التأثيرات (Effects) - تنفيذ إجراءات عند الانتقال (واجهة المستخدم، قاعدة البيانات، الأحداث)
4. التنفيذ المزدوج - تأثيرات الخادم (persist، fetch) + تأثيرات العميل (render، navigate)
5. التواصل عبر الأحداث - إرسال/استماع للرسائل عبر السمات والوحدات المدارية
6. النبضات (Ticks) - تأثيرات دورية مجدولة
7. linkedEntity - ربط صريح ببيانات الكيان
8. الفئات - تصنيف السمات حسب الغرض (interaction، integration، game)
9. إعادة الاستخدام - الإشارة إلى سمات من مكتبات أو تعريفها مضمّنة

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

---

تاريخ إنشاء المستند: 2026-02-02 بناءً على تحليل قاعدة كود orbital-rust وحزم البناء