البداية

دليل مطوّر تطبيقات أوكتا

هذا الدليل يخاطب المطوّرين الذين يبنون تطبيقاً يتكامل مع منصة أوكتا. يفترض إلمام أساسي بـ HTTP/JSON وبأي إطار خادم لاختيارك (Laravel، Node، Python، إلخ).

فهرس

1. أنواع التكامل
2. البدء السريع
3. نظام النطاقات (Scopes)
4. حسابات المنصّة: مَن يفتح تطبيقك
5. الشركات والمجمّعات: شجرة الجهة وبيانات مدارسها
   • المجمّع يثبّت تطبيقك في مدارسه (التثبيت المُدار)
   • تثبيت المجمّع يشمل مدارسه (المجمّع فقط أو المجمّع ومدارسه)
   • التطبيق يعمل داخل مدارس المجمّع (الكتابة في مدرسة الطالب)
6. دورة حياة التطبيق
7. التطبيق المدمج (Embedded)
8. قاعدة بيانات التطبيق (Migrations)
9. توسيع ملف الطالب (Student Profile)
10. ويدجتس صفحة الهبوط (Landing Widgets)
11. التطبيق الخارجي (External)
12. تطبيقات الإشعار (Notification)
13. تطبيقات الدفع (Payment)
14. لوحة تحكم التطبيق (App Control Panel)
15. أدوات المتصفح (Browser Tools)
16. الـ Manifest
    • صلاحيات الأدوار داخل تطبيقك (rbac_permissions)
17. الـ API
18. الـ Webhooks
19. كتالوج الإشعارات
20. الطباعة على ترويسة المدرسة (قوالب التقارير)
21. نُهج الأمان
22. الاختبار محلياً
23. التطوير بمساعدة الذكاء الاصطناعي (MCP)
24. نظام التصميم وواجهة المستخدم
25. دعم الذكاء الاصطناعي
26. تطبيق الجوال (Okta Mobile)
    • لوحة معلومات الجوال (Mobile Dashboard)
    • شاشات العرض (Okta Screen)
    • افتح ما تحتاجه وحده — toolKeyStartOn (العقد 26)
    • قراءة محتوى بطاقة NFC (العقد 26)
    • مَن رأته كاميرا التعرّف (العقد 27)
27. الرسائل الفورية (Realtime)
28. النداء المسموع (الصوت والنطق)
29. المايك ورفع الملفات (Voice & Files)
30. هوية أوكتا داخل التطبيق المصغّر (الزجاج السائل)
31. مثال: تطبيق «حضور بالمسح» (Native)
32. مثال: تطبيق تشغيل مراكز الرعاية النهارية (External)
33. أسئلة متكررة

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

عند إنشاء تطبيق جديد ستُسأل أوّل شيء عن نوع التكامل. القرار يحدد بقية الرحلة:

Embedded (مدمج)

التطبيق يُشحن داخل okta-web ككود ويعمل في نفس الـ runtime.

External (خارجي)

التطبيق مستضاف لديك ويتفاعل مع أوكتا حصراً عبر HTTP.

Notification (مزوّد إشعار)

تطبيق إشعار قابل للتوصيل (WhatsApp / SMS / Push / Slack / ...) تستهلكه المنصة عبر واجهة موحَّدة send(recipient, message) بصرف النظر عن قناة التسليم.

ثلاث طرق تسليم:

• api — أوكتا تُرسل POST إلى endpoint عندك مع HMAC.
• embedded — تشحن class داخل okta-web يُطبِّق PartnerNotificationProvider.
• hybrid — embedded بصفته الأساس، يتراجع لـ api على فشل.

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

Payment (مزوّد دفع)

مزوّد بوابة/وسيلة دفع (Tabby / Tamara / Noon Payments / ...) تثبّته الجهة مرة واحدة، ثم تدفع بقية التطبيقات المبالغ من خلاله عبر عقد charge(...) موحَّد. مثل الإشعار في الشكل، لكن الفعل هو تحصيل المبالغ لا إرسال رسائل. ثلاث طرق تسليم أيضاً: api / embedded / hybrid. استهلاك هذا العقد (إنشاء دفعة من تطبيق آخر) متاح حصراً لتطبيقات Embedded — راجع استهلاك المدفوعات من تطبيقك. التفاصيل الكاملة في قسم تطبيقات الدفع (Payment).

البدء السريع

1. أنشئ حساب شريك

سجّل من بوّابة الشركاء وأكمل بيانات الشركة. ستحصل على tenant خاص بك يستضيف كل تطبيقاتك.

2. أنشئ التطبيق الأول

من التطبيقات → إنشاء تطبيق جديد:

• اختر نوع التكامل.
• املأ المعلومات الأساسية (الاسم، الوصف، الفئة، الأيقونة).
• لـ Embedded: ستُربط GitHub لإنشاء مستودع جديد.
• لـ External: ستُدخل webhook_url و الأحداث المطلوبة.
• اختر الصلاحيات المطلوبة من كتالوج النطاقات.

3. اطلب المراجعة

عند جاهزية الإصدار، اضغط إرسال للمراجعة. الفريق التقني في أوكتا يتحقق من الـ manifest، يشغّل policy scanner على المستودع (Embedded فقط)، ويتحقق من الـ webhook URL (External). الردّ خلال 1-3 أيام عمل.

4. أُعيد المراجعة بنجاح

التطبيق يُنشر تلقائياً في متجر التطبيقات. كل مستأجر يستطيع تثبيته، ويوافق على الصلاحيات المطلوبة، ويبدأ الاستخدام.

نظام النطاقات (Scopes)

كل قطعة بيانات في أوكتا محمية بـ scope بصيغة:

<feature>.<resource>.<action>

أمثلة:

education.students.read       → قراءة الطلاب
education.students.write      → إضافة/تعديل الطلاب (لا حذف)
education.face_embeddings.read → قوالب التعرّف على الوجه (خطِر، قراءة فقط)
employees.directory.read      → قراءة الموظفين
reports.builder.read          → قراءة التقارير
reports.builder.write         → اقتراح قوالب (ترويسات) — لا تعريف تقارير

المبادئ الأساسية

1. lowercase + dot-separated بدون wildcards.
2. شريكاً يحصل فقط على read و write. الحذف لا يُمنح أبداً للشركاء.
3. الكتالوج هو المصدر الوحيد. لا تخترع scopes جديدة.
4. أوكتا يضيف نطاقات جديدة عبر تحديثات المنصة.

كتالوج النطاقات

اطلب الكتالوج الكامل من:

GET /api/partners/permissions/catalog

يعيد جميع الـ scopes المتاحة مجمَّعة حسب feature → resource. هذا هو ما تختار منه عند إنشاء تطبيقك.

مرجع النطاقات التفصيلي

كل نطاق يفتح وصولاً لمجموعة محدّدة من نقاط نهاية الـPartner-app runtime API، وكل نقطة نهاية تتحقق من الـscope تلقائياً عبر middleware app.scope:<feature>.<resource>.<action>. الـURL الأساس: /api/apps.

ملاحظة عامة على المعرّفات: كل المعرّفات في الاستجابات هي ULIDs (سلسلة مكوّنة من 26 حرفاً، Crockford base32). لا تكسِتها إلى integer ولا تقارنها بأرقام — boilerplate scanner يرفض الـPR لو حاول (ulid-cast-to-int و ulid-numeric-comparison). خزّنها كـchar(26) في جداولك، ووسِم العمود في الميغريشن بـcore_reference:<الجدول> وإلا لن يحميه الحارس — راجع المعرّفات والـcore_reference.

education.students — الطلاب

نقاط النهاية:

مثال Embedded (PHP):

use App\Services\PartnerApi\Education\Students\ListStudents;
use App\Services\PartnerApi\Education\Students\GetStudent;

$page = app(ListStudents::class)(page: 1, perPage: 50);
foreach ($page->data as $student) {
    // $student هو StudentDto
    echo $student->id;          // ULID مثل "01H..."
    echo $student->name;
    echo $student->gradeId;     // ULID للصف
    echo $student->sectionId;   // ULID للشعبة
}

$one = app(GetStudent::class)('01HXXXXXXXXXXXXXXXXXXXXXXX');

مثال External (HTTP):

curl -H "Authorization: Bearer $INSTALLATION_TOKEN" \
     -H "Accept: application/json" \
     "https://app.okta.platform/api/apps/education/students?page=1&perPage=50"

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

education.face_embeddings — قوالب التعرّف على الوجه

نطاق خطِر (is_dangerous). شاشة التثبيت تعرضه بألوان الخطر، وأدمن الجهة سيتوقّف عنده ويقرأه. اطلبه فقط إن كان تطبيقك يطابق الوجوه فعلاً، واشرح السبب في reason بلغة يفهمها مدير مدرسة.

لا يوجد .write ولن يوجد. التسجيل يتمّ في المنصة بحضور الشخص أمام مكتب الاستقبال؛ تطبيقٌ يستطيع كتابة قالب يستطيع أن يجعل أي كاميرا تتعرّف على أي شخص بأنه شخص آخر.

لماذا هو منفصل عن education.student_photos.read: يبدوان الموافقة نفسها وليسا كذلك. الصورة ما تطبعه المدرسة على البطاقة وتعرضه عند البوابة؛ القالب مفتاحٌ يطابق الطفل أمام أي كاميرا في أي مكان — وخلافاً لكلمة المرور لا يمكن إصدار بديل عنه بعد التسريب. جهةٌ وافقت على عرض الوجوه لم تقل شيئاً عن تسليم الرياضيات التي تتعرّف عليها.

نقاط النهاية:

المعاملات: model (مطلوب)، person_type (student/employee، اختياري)، page، per_page (افتراضي 50، بحد 100).

model مطلوب بلا افتراضي عمداً: AdaFace1 وArcFace_50r1 ينتجان متجهات غير قابلة للمقارنة ببعضها. لو اختارت المنصة واحداً نيابةً عنك لتسلّمت قوالب يفشل محرّكك في مطابقتها بصمت — بلا خطأ في أي مكان.

شكل الناتج:

{
  "model": "AdaFace1",
  "count": 2,
  "total": 431,
  "people": [
    {
      "person_type": "student",
      "person_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
      "model": "AdaFace1",
      "dimensions": 512,
      "captures_count": 3,
      "registered_at": "2026-08-25T09:12:44+00:00",
      "embedding": [0.0134, -0.0891, "…"]
    }
  ]
}

count ≠ total: الأول ما تحمله هذه الصفحة بعد إسقاط الطلاب المُخلى سبيلهم والصفوف غير القابلة لفكّ التشفير، والثاني ما تملكه الجهة. رقّم الصفحات بـtotal — من يشتقّه من count يتوقّف مبكراً عند أول صفحة تصادف طالباً مُخلى سبيله.

لا أسماء في الناتج. تحصل على متجهات مفهرسة بـ ULID فقط. إن أردت معرفة صاحب الوجه الذي طابقته، اطلب education.students.read أيضاً وحلّ الـ ULID هناك — منحة واحدة لا تُسلّمك اثنتين.

مثال Embedded (PHP):

use App\Services\PartnerApi\Education\FaceEmbeddings\ListFaceEmbeddings;

$page = app(ListFaceEmbeddings::class)(model: 'AdaFace1', page: 1, perPage: 50);

foreach ($page['people'] as $person) {
    $person['person_id'];   // ULID
    $person['embedding'];   // list<float>
}

مثال من تطبيق مصغّر (Dart) — لا يحتاج رمزاً خاصاً في okta_host:

final res = await Okta.get('/api/apps/education/face-embeddings?model=AdaFace1');
if (res.status == 200) {
  final people = res.body['people'];
  // people[i]['embedding'] متجه من الأعداد
}

حالات استخدام شائعة: بوّابة تتعرّف على الطلاب عند الدخول والخروج، تحضير آليّ في الفصل، مطابقة هوية قبل تسليم طالب لوليّ أمره.

المطابقة تحدث عندك لا عند المنصة. المتجهات تُسلَّم خاماً لأن المقارنة يجب أن تجري حيث الكاميرا — على بوّابة، داخل المبنى، غالباً بلا شبكة. نقطة نهاية تُعيد درجات تشابه بدلاً من متجهات كانت ستشترط الاتصال الذي لا تملكه البوّابة أصلاً.

education.subjects — المواد الدراسية

نقاط النهاية:

مثال:

use App\Services\PartnerApi\Education\Subjects\ListSubjects;

$page = app(ListSubjects::class)(page: 1, perPage: 100, gradeId: $gradeUlid);
// كل subject له ulid في .id و grade_id في .gradeId (كلاهما ULID)

حالات استخدام شائعة: ربط المواد بالمعلمين، تنظيم الجداول الزمنية، إعداد الدرجات.

education.curriculum — توزيع المنهج

للقراءة فقط. التطبيق الذي يشغّل الجدول اليومي يحتاج أن يسمّي درس الحصة، ولا شأن له بإعادة كتابة توزيع المدرسة — فلا يوجد .write هنا، لأن نطاقاً تمنحه المدرسة ولا يفعل شيئاً أسوأ من غيابه: شاشة الموافقة توحي بأنه يفعل.

نقاط النهاية:

القاعدة التي يقوم عليها العقد: أنت تملك الجدول، والمنصّة تملك التوزيع. الحصص تعيش في تطبيقك لا في okta-web، فالمنصّة لا تعرف أن الحصة التي بدأت الآن هي حصة العربي الثانية في هذا الأسبوع. تخمينها من التاريخ وحده يعني اختراع جدول وتسمية الدرس الخطأ بثقة. لذلك أنت تمرّر الرقم الذي تحسبه أصلاً في session_index، والمنصّة تمشي على أسابيع التوزيع حتى الدرس الذي يقع فيه.

GET /api/apps/education/subjects/{subject}/curriculum/session
      ?date=2026-08-25          # اختياري، الافتراضي اليوم
      &session_index=3          # ترتيب حصة هذه المادة داخل الأسبوع (1-based)

{
  "subject_id": "01K3…",
  "date": "2026-08-25",
  "session_index": 3,
  "resolved": true,
  "reason": null,
  "week": { "number": 1, "position": 1,
            "starts_on": "2026-08-23", "ends_on": "2026-08-27",
            "kind": "study", "label": null, "lessons": [ … ] },
  "lesson": {
    "position": 2, "unit": "أسرتي", "title": "الدرس الأول: حرف (م)",
    "kind": "lesson", "sessions": 3, "content": "الأهداف… الصفحات 22-27",
    "session_of_lesson": 2, "sessions_in_lesson": 3
  }
}

session_of_lesson تقول إنها الحصة الثانية من ثلاث لهذا الدرس — والمعلّم في الحصة الثالثة من درس يحتاج أن يعرف أنها الثالثة.

مفتاحان للأسبوع، والثابت منهما position. number هو الرقم الذي تقرأه المدرسة على الورقة، وهو عدّ أسابيع الدراسة وحدها: صندوق الإجازة يرسل number: null — كما تطبع وزارة التعليم تماماً: «الأسبوع ١٣»، «إجازة الخريف»، «الأسبوع ١٤» — وتعليمُ أسبوعٍ كإجازة يُنقص رقم كل أسبوع بعده واحداً. أما position فهو موضع الصندوق في الفصل بما فيه الإجازات، ولا يتحرّك. إن خزّنت إشارة إلى أسبوع فخزّن position، واعرض number ولا تبنِ عليه مفتاحاً.

لا تعامل «لا يوجد درس» كخطأ. ثلاث حالات ترجع 200 مع resolved: false وreason قابلة للفرع عليها برمجياً، ولكل واحدة بطاقة مختلفة في واجهتك:

و404 محجوزة لمعناها الحقيقي وحده: لا يوجد توزيع منشور لهذه المادة. المسودّة تُقرأ كعدم وجود توزيع لا كتوزيع فارغ — لأن توزيعاً نصف مُدخَل يبدو مكتملاً، ومن يبني عليه يخطّط فصلاً على أسبوع لم ينتهِ.

الكتاب: textbook_url فقط يعبر الواجهة. الملف المرفوع يبقى خلف دخول المدرسة — تقديمه عبر توكن صادر لتطبيقٍ لا لشخص قرار آخر لم يُتَّخذ.

حالات استخدام شائعة: عرض درس الحصة داخل الجدول اليومي، تحضير المعلّم، إشعار وليّ الأمر بما دُرِّس اليوم.

education.grades — الصفوف

نقاط النهاية:

مثال:

use App\Services\PartnerApi\Education\Grades\ListGrades;

$page = app(ListGrades::class)(page: 1, perPage: 50, onlyActive: true);
foreach ($page->data as $grade) {
    echo $grade->id;        // ULID
    echo $grade->nameAr;
    echo $grade->order;
}

حالات استخدام شائعة: dropdowns لاختيار الصف، تصفية الطلاب، تجميع التقارير حسب المرحلة.

education.sections — الشُعب

نقاط النهاية:

مثال:

use App\Services\PartnerApi\Education\Sections\ListSections;

$page = app(ListSections::class)(page: 1, perPage: 50, gradeId: $gradeUlid);

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

education.academic_years — السنوات الدراسية

حالة المسارات: مُسجَّل في الكتالوج للاستخدام المستقبلي. نقاط نهاية الـrun-time لم تُكشف بعد على /api/apps/education/academic-years — ستُضاف في إصدار قادم. اطلب هذا الـscope إذا كنت تخطط لاستخدامه قريباً.

education.terms — الفصول الدراسية

حالة المسارات: مماثل للسنوات الدراسية أعلاه — مُسجَّل في الكتالوج، نقاط النهاية ستُكشف لاحقاً.

employees.directory — الموظفون

نقاط النهاية:

مثال:

use App\Services\PartnerApi\Employees\Directory\ListEmployees;

$page = app(ListEmployees::class)(
    page: 1,
    perPage: 100,
    type: 'teacher',     // أو 'administrator', null للجميع
    onlyActive: true,
);

حالات استخدام شائعة: تعيين المعلمين على المواد، إصدار جداول المراقبين، تطبيقات HR التعليمية.

reports.builder — التقارير

التقارير نفسها بلا write: الكتالوج تُنسّقه أوكتا ولا يستطيع شريك تعريف تقرير جديد — أنت تشغّل الموجود وتأخذ مخرجاته. النطاق الثاني يخصّ القوالب وحدها.

وwrite لا يشتري الطباعة. قالبٌ ألّفه تطبيقك يصل مسودةً ولا يُطبع حتى تعتمده المدرسة، وتطبيقك لا يمسّ إلا ما ألّفه هو. التفصيل في أن يقترح تطبيقك ترويسة.

النطاق يفتح سطحين مختلفين: كتالوج التقارير (بيانات تُعيدها أوكتا)، وقوالب المدرسة (ترويسة تطبع عليها أنت محتواك). الثاني موصوف كاملاً في الطباعة على ترويسة المدرسة.

نقاط النهاية:

مثال:

use App\Services\PartnerApi\Reports\Builder\ListReports;
use App\Services\PartnerApi\Reports\Builder\RunReport;

$catalog = app(ListReports::class)();
$result = app(RunReport::class)('students.attendance.monthly', [
    'gradeId' => $gradeUlid,
    'month'   => '2026-04',
]);

حالات استخدام شائعة: لوحات إحصائية، تصدير شهري للأهالي، تقارير المعلمين الدورية.

ساعة الجهة — /api/apps/tenant/clock

بلا نطاق. كل تطبيق مثبَّت يصل إليها بتوكن التثبيت وحده، ولا شيء يُطلب من الجهة.

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

شكل الناتج:

{
  "timezone": "Asia/Riyadh",
  "offset": "+03:00",
  "now": "2026-09-02T14:31:07+03:00"
}

خزّن timezone، ولا تخزّن offset أبداً

offset وnow يصفان هذه اللحظة لا هذا المكان. الاسم وحده يحمل القواعد، فيبقى صحيحاً حين تتغيّر القواعد تحته.

وهذا ليس افتراضاً نظرياً — إحدى الدول المدعومة تعمل بالتوقيت الصيفي:

فتطبيق خزّن +02:00 لمدرسة قاهريّة في يناير يصير ساعةً كاملة خطأً في أبريل — على كل شاشة، بلا خطأ في أي سجلّ، والتاريخ صحيح والصيغة صحيحة والساعة وحدها مغلوطة. ولو خزّن "Africa/Cairo" لتحرّك معها وحده.

استعمل offset للعرض بجانب وقت، أو لتسليمه لشيء لا يقبل اسم منطقة. لا لشيء آخر.

التخزين يبقى UTC

كل طابع زمني تُسلّمه المنصّة لك، وكل طابع تُعيده أنت، هو UTC — وهذا لا يتغيّر. هذه النقطة تجيب سؤالاً آخر: ماذا يُعرَض. حوِّل عند العرض، لا عند الكتابة؛ قيمةٌ حُوِّلت وقت الدخول قيمةٌ لا يستطيع أحد مقارنتها بين مدرستين بعد ذلك، والضرر لا يظهر حتى تجتمع مدرستان في تقرير واحد.

من أين تأتي القيمة

المدرسة تختارها من إعداداتها. وإن لم تختر، تُشتقّ من دولتها حين يكون لها منطقة واحدة، وإلا فمن إعداد المنصّة. أنت تحصل على الجواب النهائي دائماً — فلا تعامل غياب اختيار صريح كحالة خاصّة.

مثال Embedded (PHP):

use App\Services\PartnerApi\Tenants\GetTenantClock;

$clock = app(GetTenantClock::class)();

$clock->timezone;   // «Asia/Riyadh» — هذا ما يُخزَّن
$clock->offset;     // «+03:00» — للعرض فقط
$clock->now;        // ISO8601 على ساعة المدرسة

// وموقتٌ مخزَّن UTC مقروءاً على ساعتها:
app(GetTenantClock::class)->at($row->created_at)?->format('Y-m-d H:i');

مثال من تطبيق مصغّر (Dart) — لا يحتاج رمزاً جديداً في okta_host ولا رفع minContract:

final res = await Okta.get('/api/apps/tenant/clock');
if (res.status == 200) {
  final zone = res.body['timezone'];   // خزّن هذا
}

حالات استخدام شائعة: طباعة أوقات الحضور كما رآها من سجّلها، تحديد ما هو «اليوم» لدى المدرسة، جدولة تذكير في الصباح المحلّي لا صباح الخادم.

لا تسألها مرّة وتخزّن now. «كم الساعة» سؤالٌ يُسأل حين يُحتاج جوابه؛ والاسم وحده هو ما يستحقّ أن يُحفَظ.

المعرّفات والـcore_reference

كل response يخرج من المنصة يستبدل numeric IDs بـULIDs. الـcore_reference هو عمود في جدولك أنت يحمل واحداً من هذه المعرّفات: سلسلة 26 حرفاً تشير إلى صف في جدول منصّة على okta-web (students, subjects, grades, sections, tenants, tenant_employees, users).

لماذا لا يوجد قيد FK حقيقي: الصف المُشار إليه يعيش في قاعدة بيانات أخرى على okta-web، وPostgres لا يعرف قيود مفاتيح أجنبية عابرة لقواعد البيانات. فما تخزّنه هو char(26)/varchar(26) عادي بلا أي قيد — ومن هنا تأتي المشكلة: char(26) عرض قد تستخدمه لأي شيء آخر (كود قسيمة، رقم فاتورة خارجية، بادئة hash). العرض وحده ليس دليلاً، ولو عاملت المنصة كل char(26) كمرجع منصّة لرفضت كتاباتك المشروعة.

ولهذا الحارس لا يخمّن: عليك أن توسم العمود صراحةً في الميغريشن.

الوسم — صيغتان

الصيغة (أ) — تعليق على العمود في كتالوج Postgres (المفضّلة)، لأنها تبقى في قاعدة البيانات الحيّة فتقرأها okta-web وأدوات الفحص لاحقاً:

CREATE TABLE "students" (
    "id"           BIGSERIAL PRIMARY KEY,
    "owner_ulid"   CHAR(26) NOT NULL,
    "teacher_ulid" CHAR(26)
);

COMMENT ON COLUMN "students"."owner_ulid"   IS 'core_reference:tenants';
COMMENT ON COLUMN "students"."teacher_ulid" IS 'core_reference:users';

في ميغريشن Laravel هذه هي ->comment():

$table->string('owner_ulid', 26)->index()->comment('core_reference:tenants');

الصيغة (ب) — تعليق SQL على سطر العمود نفسه، داخل CREATE TABLE أو على ALTER TABLE … ADD COLUMN من سطر واحد:

CREATE TABLE "students" (
    "id"         BIGSERIAL PRIMARY KEY,
    "owner_ulid" CHAR(26) NOT NULL, -- core_reference: tenants
);

ALTER TABLE "students" ADD COLUMN "teacher_ulid" CHAR(26); -- core_reference: users

الفاصل بين الكلمة والهدف مرن: core_reference: tenants و core_reference=tenants و core_reference(tenants) كلها مقبولة. و core_reference بلا هدف تُقبل أيضاً كوسم (قاعدة صيغة الـULID تنطبق مهما كان الجدول الهدف) — لكن سمِّ الهدف دائماً، فهو ما يظهر في الـ manifest.

ماذا يحدث بلا وسم

لا شيء يُرفَض — وهذه هي النقطة الخطرة. العمود ببساطة لا يراه الحارس، فلا يحميه:

• App\Services\Partners\Sandbox\ValidateCoreReferenceWrites لا يعرف أن العمود مرجع منصّة، فيمرّر أي قيمة تكتبها فيه بلا فحص صيغة ULID ولا فحص أن الجدول الهدف مسموح.
• كتلة core_references في الـ manifest تخرج فارغة لأعمدتك غير الموسومة.

الأعمدة بعرض 26 بلا وسم تُصنَّف «مرشّحة» (candidates) وتُعرَض لك في اللوحة — تنبيهاً لا رفضاً. فالفرق بين «هذا الجدول لا يحوي مراجع منصّة» و«قد يحويها ولا نراها» فرق يجب أن تحسمه أنت بالوسم.

ميغريشنات بمسار ملف داخل مستودعك (.php) لا يمكن قراءة SQL منها في وقت الفحص، فتُحسب ضمن unreadable وتُعرَض على أنها غير مفحوصة — لا تفترض تغطية كاملة معها.

ممنوع (بوسم أو بدونه):

• (int) $row->student_id_ulid — كسته إلى integer.
• where('student_id_ulid', 12345) — مقارنته بـliteral رقمي.

كلاهما يُكشَف من boilerplate scanner ويفشل CI. خزّنه ومرّره دائماً كـstring.

تحديث الكتالوج محلياً (okta-partners)

الكتالوج يُحدَّث تلقائياً من okta-web عبر:

1. Cron كل ساعة (افتراضي).
2. Webhook فوري على partner_scopes.catalog.changed.
3. يدوي: php artisan partners:sync-scope-catalog --force.

تحديث محلي عبر hash drift detection — لو الـhash لم يتغيّر يتجاوز المزامنة بالكامل.

حسابات المنصّة: مَن يفتح تطبيقك

النطاقات تجيب «أي بيانات يقرأ تطبيقك». وهذا القسم يجيب سؤالاً آخر تماماً: مَن الجالس أمام الشاشة. المنصّة تعرف أربعة حسابات، وهي لا تعمل بآلية واحدة — وهذا الفرق هو ما يكسر افتراضات أكثر من أي شيء آخر في التكامل.

١. الموظّف — دور داخل الجهة

المعلّم والإداري يعيشان داخل الجهة: صفّ في tenant_employees يحمل type (وظيفته)، وعضوية في الجهة، ودور. الثلاثة لازمة: العضوية تُظهِر الجهة في منتقي السياق، والدور هو ما يُدخِله فعلاً.

والموظّف نوع واحد: تسجّله المدرسة معلّماً أو إدارياً — لا الاثنين، ولا «موظّفاً» بجانب أحدهما، فكلاهما موظّف أصلاً — فيُمنَح دور teacher أو administrator: دور بلا أي صلاحية، مفتاح باب لا أكثر. ما يحقّ له فعله يُقرَّر بعدها بإلحاق صلاحيات بالدور أو بوضعه في مجموعة إدارية.

داخل تطبيقك هذا هو الحساب «العاديّ»: Tenant::current() مضبوطة، والنطاق tenant، وكل ما تعرفه عن سياق الجهة صحيح.

المطابقة أوسع مما تظنّ. "roles": ["teacher"] تُطابَق على ثلاثة أشياء معاً: الدور النشط، وكل الأدوار المختارة في الجلسة، وtenant_employees.type نفسه. كلّها تُطبَّع قبل المقارنة (حروف صغيرة، والمسافات و_ تصير -)، فـ"Teacher" و"teacher" سواء.

٢ و٣. الطالب ووليّ الأمر — بوّابتان لا دوران

هنا يتغيّر كل شيء. الطالب ووليّ الأمر ليس لهما صفّ دور إطلاقاً: اسم البوّابة هو الجمهور نفسه. والنطاق general، وtenant_id في السياق فارغ، والجهة تعيش في مفتاح آخر: portal_tenant_id.

وهذا ليس تفصيلاً في التسمية. حساب البوّابة لا يملك سياق جهة بالمعنى المعتاد. المنصّة تُقلِع جهته لهذا الطلب وحده، وعلى صفحات التطبيق التي أعلنها بيانك فقط؛ خارجها يبقى بلا جهة، وصفحات المنصّة المرتبطة بجهة تظلّ ترفضه. فأيّ كود يفترض أن Tenant::current() موجودة دائماً سيسقط على صفحة بوّابة.

ووليّ الأمر عابر للجهات: قد يكون له أبناء في مدرستين، فيختار الجهة عند الدخول — وتلك الجهة هي التي تحملها القائمة الجانبية وتُفتَح بها التطبيقات.

٤. المفوَّض من وليّ أمر — بوّابة مستقلّة، لا نكهة من وليّ الأمر

وليُّ الأمر يستطيع أن يفوّض شخصاً على شؤون أبنائه: قريباً يستلم طفلاً من البوّابة، أو سائقاً. والتفويض ليس حساباً موازياً لوليّ الأمر، بل شريحةٌ من صلاحياته هو:

• على أبناء بأعيانهم — يسمّيهم وليُّ الأمر واحداً واحداً، لا «كل أبنائي».
• بجزء من صلاحياته — يختار ما يُسلِّمه (النداء، متابعة الحضور…).
• وغالباً إلى تاريخ — تفويضٌ لأسبوع الاختبارات ينتهي بانتهائه.

والمفوَّض لا صفّ عضوية له إطلاقاً: لا tenant_guardians ولا tenant_students. كلُّ وجوده في المدرسة صفُّ تفويض، فيختفي وحده حين ينتهي التفويض أو يُسحَب أو يفقد وليُّ الأمر نفسه ارتباطه بالطالب.

ولماذا بوّابة مستقلّة ولم يُلحَق بوليّ الأمر: تطبيقٌ يخدم الآباء لا يخدم بذلك كلَّ من سلّمه أبٌ مفتاحاً — عليه أن يقول إنه يخدمه. فلو دخل المفوَّض بمفتاح guardian لطابق كلَّ جمهور وليّ أمر منشور اليوم بلا أن يعلن أحدٌ شيئاً. والثمن صريح: تطبيقك لا يبلغ المفوَّضين حتى تُعلن هذا الجمهور وتنشر.

"account_types": [
  { "key": "guardian", "kind": "dependent", "portal": "guardian",
    "web_route": "call.family", "mobile_entry": "okta_app/webview/family.html" },
  { "key": "guardian-delegate", "kind": "dependent", "portal": "guardian-delegate",
    "web_route": "call.delegate", "mobile_entry": "okta_app/webview/delegate.html" }
]

والمنصّة تفرض الحدود، وأنت ترسمها. لا يقع عليك أن ترفض: نداءات قراءة الطلاب في سياق مفوَّض مقيَّدة خادمياً بأبناء تفويضه — ListStudents تعيد هؤلاء وحدهم، وGetStudent لطالب خارجهم تجيب بالـ404 نفسه الذي يجيب به معرّفٌ مجهول (كي لا يتعلّم المفوَّض من الرفض من غيرُهم مسجَّل)، وقائمة أبناء وليّ الأمر الذي فوّضه تعود بأبناء التفويض لا بعائلته كلّها. وتفويضٌ انتهى لا يصل شيئاً: يُقيَّد إلى لا أحد، لا يُفكّ قيده.

وما ترسمه أنت هو الزرّ: $viewer في سياق مفوَّض يحمل

@if ($viewer->isDelegate())
    @foreach ($viewer->delegatedChildren() as $child)
        {{-- ارسم البطاقة، وأظهر زرّ النداء لمن يملكه وحده --}}
        @if ($viewer->mayForChild($child['id'], 'okta_hdor.pickup.call'))
            <x-button wire:click="call('{{ $child['id'] }}')">{{ __('نداء') }}</x-button>
        @endif
    @endforeach
@endif

• delegatedChildren() لا تكون فارغة أبداً في سياق مفوَّض: مفوَّضٌ لم يبقَ له شيء ساري يُجاب بـ$viewer === null كما يُجاب وليُّ أمرٍ فُكّ ارتباطه — فهي قائمةٌ تُرسَم، لا قائمةٌ تُفحَص هل هي فارغة.
• expiresAt تاريخ انتهاء التفويض (أو null لتفويض بلا نهاية) — اعرِضه: «ينتهي الخميس» يشرح للمستخدم اختفاءَ الزرّ بعد غد.
• mayForChild للرسم، وليست هي ما يمنع: المنصّة ترفض الفعل خارج التفويض بنفسها، فشاشةٌ نسيت الفحص لا تستطيع أن تُنفّذ. ولمن ليس مفوَّضاً تجيب false دائماً — فاحرس شاشة وليّ الأمر بكونه وليَّ أمر لا بها.

القدرات كلُّها من عندك — المنصّة لا تُعلن واحدة

كل قدرة يستطيع وليُّ الأمر أن يسلّمها لمفوَّض يعلنها تطبيقٌ مثبَّت. لا توجد قائمة منصّة، ولن تجد ما تختار منه.

وكانت توجد: تسع قدرات ثابتة (pickup_student، view_marks، pay_fees وأخواتها) تُعرَض على كل وليّ أمر في كل مدرسة. ولا يقرؤها شيء — لا شاشة ولا نقطة نهاية ولا وسيط في المنصّة سأل يوماً هل يحمل المفوَّض واحدةً منها. القارئ الوحيد كان، ولا يزال، mayForChild() في تطبيقٍ مثبَّت. وأوّل تطبيقٍ احتاج قدرةً أعلن قدرته بنفسه بدل أن يستعمل pickup_student — فصار مربّعان لفعل واحد، ولا يعرف الوالد أيَّهما تحترمه المدرسة. فالمفردات صارت لمن يفرضها.

ما يعنيه لك عملياً: جهةٌ لا يُعلن أيُّ تطبيق مثبَّت فيها قدرةً لا تعرض على وليّ الأمر أيّ مربّع، والتفويض يبقى معناه «هذا الشخص يصل هؤلاء الأبناء». فإن أردت أن يستطيع وليُّ الأمر تسليم شيءٍ من تطبيقك، أعلِنه — وإلا فلا شيء يُسلَّم.

فأعلِنها في manifest.json، توأماً عائلياً لـrbac_permissions:

"guardian_capabilities": [
  { "key": "okta_hdor.pickup.call",
    "label": { "ar": "إجراء النداء", "en": "Place the pickup call" } },

  { "key": "okta_hdor.attendance.read",
    "label": { "ar": "عرض حضور الابن", "en": "View attendance" },
    "gates": ["okta_hdor.attendance.read"] }
]

• المفتاح <feature>.<resource>.<action> وfeature هو slug تطبيقك بصيغة snake (okta-hdor → okta_hdor) — نفس قاعدة rbac_permissions وبنفس الحدّة. والسبب ليس ترتيباً: المفتاح يُخزَّن على تفويض الأسرة ويُقرأ بحسب التطبيق، فإعلانه في مجال تطبيق آخر يضع خانةً في شاشة وليّ الأمر نيابةً عن شريك آخر، تحت عنوانٍ يقرؤه الوالد على أنه من المنصّة. المفتاح خارج مجالك يُرفض بالاسم.
• label.ar إلزامي — هو كلُّ ما يقرأه وليُّ الأمر بجانب الخانة، وخانةٌ بلا عنوان لا يستطيع أحد أن يضغطها بصدق. وlabel.en يسقط إلى العربية.
• المدرسة لا تمنحها ولا تمنعها ولا تُستأذَن فيها. وليُّ الأمر يحملها كلَّها بصفته وليَّ أمر في تلك الجهة، والقرار الوحيد قراره هو: أيّها يسلّم. والحدّ الذي بقي هو ارتباط وليّ الأمر بالابن نفسه — ابنٌ لم يعد وليُّ أمره يصله يسقط من التفويض كلّه.
• والمدرسة تقرأ ما جرى ولا تتدخّل فيه: صفحة «المفوَّضون» في لوحة الجهة تسرد من فوّض ومن فُوِّض وعلى أيّ أبناء وبأيّ قدرات وإلى متى — قراءةٌ فقط.
• وتظهر لوليّ الأمر مجموعةً باسم تطبيقك في شاشة التفويض، عند كل جهة ثبّتته. والحدّ يبقى: التفويض نفسه، وتاريخ انتهائه، والأبناء المسمَّون فيه.

واقرأها وقت التشغيل بالدالة نفسها:

if ($viewer->mayForChild($childId, 'okta_hdor.pickup.call')) {
    // ارسم زرّ النداء لهذا الابن
}

• والمفوَّض لا يُفوَّض على نفسه: مفتاحٌ يسمّي ابناً حسابُه هو حسابُ المفوَّض يُرفض عند الإنشاء وعند التعديل، ولا يُعرَض في منتقي الأبناء أصلاً.

وgates اختيارية، وتركها فارغةً هو الحال العادي: تقرأ القدرة بنفسك وترسم عليها، ولا يتغيّر شيء لأي تطبيق منشور. وحين تسمّي فيها نطاقاتك أنت، تنتقل بوّابة الرفض إلى المنصّة: نداءٌ يستعمل ذلك النطاق في سياق مفوَّض لم يُمنح القدرة يُرفض قبل أن يصل كودك. اختيارٌ لكل قدرة على حدة، فلا شيء سبق نشره يتبدّل سلوكه.

والكتلة تصل الإصدار من مستودعك بزرّ «مزامنة من manifest» أو بأداة sync_from_manifest، وتُقرأ وتُكتب أيضاً بـget_guardian_capabilities و set_guardian_capabilities. وغائبةً لا تُمَسّ: مستودعٌ توقّف عن ذكر المفتاح لا يسحب بصمت قدراتٍ عُرضت على الأسر فعلاً.

كيف تُعلن جمهورك

تبويب «أنواع الحسابات» في محرّر الإصدار — أو set_account_types عبر MCP — وهو ما يصير menu.audiences[] في okta-web وmobile.audiences[] في تطبيق أوكتا. لكل نوع:

"account_types": [
  { "key": "teacher",  "kind": "primary",   "roles": ["teacher"], "web_route": "school-app.staff" },
  { "key": "guardian", "kind": "dependent", "portal": "guardian", "web_route": "school-app.family" }
]

• kind — primary (الجمهور الأساسي) أو dependent (تابع).
• هدف واحد فقط: roles (أدوار داخل الجهة) أو portal (بوّابة).
• سطح واحد على الأقل: web_route و/أو mobile_entry.

وweb_route اسم مسار Laravel لا رابطاً ولا /path — وحدّ فضاء أسماء: school-app.admin يغطّي school-app.admin.reports ولا يغطّي school-app.admins. شكل المقاطع يحمل معنى، فلا تكتبه اعتباطاً.

الهدف الثالث: permissions[] — من منحته المدرسة، لا من خمّنتَ دوره

أسماء الأدوار في roles[] تخمينك لما تسمّيه المدارس، والمدرسة تنشئ أدوارها المخصّصة وتربط بها موظّفيها: «محاسبة»، «شؤون الموظفين»، «مشرف الحضور». فموظّفةٌ نوع حسابها administrator وأُعطيت صلاحياتِ الإدارة عن طريق دور مخصّص كانت تُوجَّه إلى شاشة الإداريين نفسها، لأن المشغّل كان يختار المسار بالدور وحده.

فصار للجمهور هدفٌ ثالث: الصلاحية.

"account_types": [
  { "key": "management", "kind": "primary",   "permissions": ["okta_hr.management.view"], "web_route": "okta-hr.admin" },
  { "key": "administrator", "kind": "dependent", "roles": ["administrator"], "web_route": "okta-hr.staff" }
]

• يطابق من يحمل أيّاً من الأسماء المذكورة داخل الجهة — تقرؤها المنصّة من الجداول وقت الطلب، سواء جاءت من دوره الأساسي أو من دور مخصّص أنشأته المدرسة وربطته به. لا يعنيك اسم الدور ولا اختلافه بين مدرسة وأخرى.
• الأسماء صلاحياتك أنت بصيغتها الكاملة <feature>.<resource>.<action>، وأعلِنها في rbac_permissions كذلك — وإلا لم تستطع المدرسة منح أحد إياها.
• الترتيب هو القرار: المشغّل يربط البطاقة بـأول جمهور مطابق (الأساسي قبل التبعي، ثم ترتيب الإعلان). فضَع جمهور الصلاحية قبل جماهير الأدوار ليغلب عند من يطابق الاثنين.
• هدف مستقلّ: لا يجتمع مع roles[] ولا مع portal (مستخدم البوّابة لا يحمل صلاحية في الجهة أصلاً)، ويحتاج web_route.
• أوكتا ويب وحدها: تطبيق أوكتا يطابق بطاقاته بالدور والبوّابة، وحاملُ الصلاحية يصله سطحُ الموظّفين العامّ هناك — فلا mobile_entry على هذا النوع.

وهذا لا يُغني عن can() داخل الشاشة: الجمهور يقرّر أين يدخل، والصلاحية تقرّر ما يراه ويفعله بعد الدخول.

نوع الجهة: entity_types — شاشة مدير المجمّع غير شاشة مدير المدرسة

مدير الجهة في مجمّع يدير مدارس، ومدير الجهة في مدرسة يدير طلاباً: نوع الحساب واحد (tenant-admin) والشاشة ليست واحدة. وكان الطريق الوحيد حزمةً واحدة تسأل عند الفتح عن نوع الجهة التي هي فيها ثم تتفرّع — فتُنزَّل شاشة المجمّع وتُترجَم على هاتف كل مدرسة. الآن تُعلن صفّين للنوع نفسه، والمنصّة تختار بنوع الجهة التي يقف فيها صاحبه:

"account_types": [
  { "key": "tenant-admin", "roles": ["tenant-admin"],
    "web_route": "okta-hr.dashboard",
    "mobile_entry": "okta_app/native/main/lib/main.dart" },
  { "key": "tenant-admin", "roles": ["tenant-admin"],
    "entity_types": ["complex", "education_company"],
    "web_route": "okta-hr.group",
    "mobile_entry": "okta_app/native/group/lib/main.dart" }
]

وفي manifest.json هو entityTypes على الجمهور، في menu.audiences[] وmobile.audiences[] كليهما:

{ "key": "tenant-admin@complex+education_company", "kind": "primary",
  "roles": ["tenant-admin"], "entityTypes": ["complex", "education_company"],
  "entry": "okta_app/native/group/lib/main.dart" }

• الأضيق يغلب لا الأسبق. حيث ينطبق الصفّ المقيَّد يغلب صفَّ النوع نفسه بلا أنواع أيّاً كان ترتيب الإعلان، والصفّ بلا أنواع يخدم كل جهة أخرى. فالشكل المعتاد صفّان: عامّ لكل الجهات، ومقيَّد حيث تحتاج شاشةً خاصّة.
• بلا entity_types = كل أنواع الجهات، وهو حال كل تطبيق نُشر قبل الحقل: لا يتغيّر بيانه بايتاً، ولا يتغيّر ما يراه أحد.
• المفردات مغلقة: individual_teacher، school، complex، college، university، institute، academy، education_company، daycare_center. والاسم المجهول يُرفَض بالاسم ولا يُسقَط: إسقاطه يضيّق الصفّ بصمت، وإسقاط آخر اسمٍ فيه يوسّعه إلى كل الجهات — عكس ما كُتب تماماً.
• للموظّفين وحدهم: على roles وpermissions. ويُرفَض على البوّابة: الطالب ووليّ الأمر والمفوَّض عابرون للجهات (أبناءٌ في مدرستين)، ولا يُختار جمهورهم بالمكان الذي يقفون فيه.
• نوع حساب واحد في نوع جهة واحد = شاشة واحدة: صفّان للنوع نفسه يسمّيان النوع نفسه من الجهات يُرفضان على السطح نفسه، لأن الثاني شاشة لا يصلها أحد هناك. والسطحان مستقلّان: يجوز أن تضيّق أوكتا ويب ولا تضيّق تطبيق أوكتا.
• المفتاح <الدور>@<الأنواع> (tenant-admin@complex+education_company): يشتقّه المحرّر وset_account_types لأن النوع الواحد صار صفّين. ومع set_account_types مرّر الدور وحده أو المفتاح المشتقّ.
• نوع الجهة يُقرأ من سجلّها لا من الطلب: لا ترويسة ولا معامل يغيّر أيّ شاشة تُفتح. وجهةٌ نوعها مجهول للمنصّة (سجلّ أقدم من المفردات) لا يبلغها إلا الصفّ العامّ.
• بلا رفع عقد ولا تحديث لتطبيق أوكتا: الخادم يختار، والهاتف يستلم مدخلاً واحداً كما يستلمه اليوم. ولكل صفّ مقيَّد مدخله وأرضيته (min_contract) وصفوف versions[] الخاصة به.
• وحامل الصلاحية (من يدخل بصلاحية من تطبيقك لا بدوره) يُحسَب في الجهة التي يقف فيها: صفٌّ للمجمّعات لا يسلب المدارس شاشتها الوحيدة.

والمحاكي يعمل على بيئة تجربة من نوع «مدرسة»، فيركّب مدخل المدرسة ويسرد الصفوف المقيَّدة بأسمائها. جرّب شاشة المجمّع على بيئة تجربة من نوع «مجمع تعليمي» (يُختار النوع عند تجهيز البيئة) وادخل إليها من الهاتف.

الفخّ: يُنشَر بنجاح ثم لا يعمل أبداً

مفتاح بوّابة داخل roles[]. "roles": ["student"] يبدو سليماً تماماً — student مفتاح معروف في الكتالوج — لكن المنصّة تطابق مستخدم البوّابة على حقل portal وحده ولا تطابقه أبداً على أسماء الأدوار. فالإعلان لا يطابق أحداً: يُنشَر الإصدار، ويبدو البيان صحيحاً، ثم تُرفض كل صفحات ذلك الجمهور لكل مستخدم. و"custom": true لا تُنقذه — البوّابة ليست دوراً تعرّفه الجهة، والمنصّة ترفض custom على جمهور portal أصلاً.

ومفتاح دور مخترَع أو مكتوب خطأً ("staff" مثلاً) يفشل بنفس الطريقة الصامتة. الجهات تعرّف أدوارها الخاصة، فالمفتاح خارج الكتالوج مقبول — لكن بإعلان صريح: "custom": true. أما بدونها فمرفوض عمداً، لأن البديل أن تكتشف الخطأ من شكوى مدرسة لا من رسالة نشر.

الفرض حقيقي لا إخفاء

EnsureAppAudience مُطبَّقة على مجموعة web كاملةً — بلا تعاون منك — و كذلك على نداءات Livewire عبر persistent middleware تُعيد الفحص على مسار الصفحة الأصلية. فحراسة الصفحة وحدها كانت ستترك النوافذ مفتوحة: كل فعل بعد الرسم نداء POST إلى مسار آخر.

والبوّابة ترفض بالافتراض. قبلها كان المُشغِّل يخفي الرابط في قائمة التطبيقات فقط، ومَن يعرف المسار ويكتبه في شريط العنوان كان يُخدَم.

مَن يفتح تطبيقك الآن؟ — ULID المستخدم

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

use App\Services\PartnerApi\Identity\GetCurrentViewer;

$viewer = app(GetCurrentViewer::class)();

if ($viewer === null) {
    return; // لا مستخدم من الأنواع الثلاثة يشاهد الآن.
}

$viewer->type;        // employee | student | guardian
$viewer->id;          // ULID — وهو ما تخزّنه وتربط به
$viewer->displayName;
$viewer->roles;       // مفاتيح الأدوار الخام — للموظّف وحده
$viewer->entityId;    // ULID الجهة
$viewer->accountType; // tenant_admin | administrator | teacher | employee | student | guardian
$viewer->groups;      // [{key, title}] المجموعات الإدارية التي صنعتها المدرسة — للعرض
$viewer->hasStaffRecord(); // هل للشخص صفّ في دليل موظفي الجهة؟

موظّفٌ بلا صفّ في دليل الموظفين — hasStaffRecord()

في كل جهة موظّفون لم تُدخلهم المدرسة في دليلها: الحساب الذي سجّل المدرسة (لا أحد يضيف المالك إلى الدليل)، ومن أُلحق بالجهة مباشرةً، وحسابا بيئة التجربة اللذان تعمل عليهما أنت. هؤلاء يصلك عنهم viewer كامل — نوع الحساب، والمجموعات، والصلاحيات، والجهة — لكن id يعود فارغاً و hasStaffRecord() تجيب false، لأن لا صفّ في الدليل يُربَط به.

فاقرأها قبل الربط على id وحده؛ أما can() وaccountType فتُسألان بلا تفكير. (قبل هذا كان الجواب null عن هؤلاء جميعاً، فكانت الواجهة ميّتة في بيئة التجربة نفسها.)

لا تستعمل auth()->id() لهذا

الفاحص لا يمنعها، لكنها مفتاح رقمي داخلي للمنصّة، وقاعدة العقد أن المعرّفات الرقمية لا تعبر حدّ الشريك أبداً. والأهمّ أنها لا تفيدك: هي الرقم نفسه سواء دخل الشخص معلّماً أو وليَّ أمر، فلا تُطابِق شيئاً مما تملكه.

id يُطابِق ما تُرجِعه خدمات القراءة — وهذا كلّ الفائدة

فالربط مباشر بلا تحويل:

$mine = MyAppRecord::query()->where('student_ulid', $viewer->id)->get();

ولاحظ أن هذه المعرّفات تأتي من جداول مختلفة عمداً: الطالب يُعرَّف بصفّ تسجيله، ووليّ الأمر بسجلّ مستخدمه. فلا تحاول اشتقاق المعرّف بنفسك من أي شيء آخر — اقرأه من هنا.

type هي الهويّة التي دخل بها، لا كل ما هو عليه

إنسان واحد قد يكون معلّماً في المدرسة ووليَّ أمر لطالب فيها. يدخل بإحداهما، وهذه تُخبرك بأيّهما دخل — وهي نفس الهويّة التي بنت عليها بوّابة الجماهير قرارها بخدمة الصفحة. فتطبيق يقرّر بـ«هل هذا الشخص وليّ أمر في مكان ما؟» سيعرض للمعلّم شاشة وليّ الأمر.

null ليست خطأ

تعني: لا أحد مسجَّل دخوله، أو أن المُشاهِد ليس من الأنواع الثلاثة — مشرف المنصّة يفتح صفحتك مثال على ذلك. اعرض حالة فارغة مفهومة، لا خطأً.

لا شيء منها يُقرَأ من الطلب

الهويّة تُحلّ في الخادم من سياق الجلسة. لا تقبل معرّف مستخدم من الواجهة ولا من query string: مُشاهِد يستطيع المُنادي تسميته هو مُشاهِد يستطيع تزويره.

نوع الحساب شيء، وما منحته المدرسة شيء آخر

هذا أكثر ما يُخلَط في التكامل، فيُقال صراحةً. أمام شاشتك شخصان قد يبدوان واحداً: إداريّ وشخص مُنح صلاحيات تحت مسمّى «مدير الموارد البشرية». الأول نوع حساب — كلمة المنصّة، ومعناها واحد في كل مدرسة. والثاني مجموعة صلاحيات صنعتها هذه المدرسة في محرّر أدوارها، وسمّتها كما شاءت، ووضعت فيها ما شاءت من الصلاحيات — والمدرسة التالية تسمّي الوظيفة نفسها اسماً آخر، أو لا تملكها أصلاً.

المجموعة ليست حساباً ولا نوع حساب

المستخدم يدخل بحساب واحد. مجموعة الصلاحيات لا تُنشئ حساباً ولا نوع حساب؛ هي تضيف صلاحيات فوق ما يحمله. فالمحاسِبة تدخل بحسابها، ونوع حسابها administrator كأي إداري، والمجموعة أضافت لها ما أضافت. فلا تسأل «بأي حساب دخل؟» — اسأل «لماذا يحمل هذه الصلاحية؟»، وللسؤال جواب جاهز في الجدول أدناه.

ولذلك تحمل الـDTO حقلين لا واحداً، ولكلٍّ سؤاله:

وبأشخاص حقيقيين:

• tenant_admin تعلو على غيرها: من يدير الجهة يبقى كذلك مهما حمل.
• employee ليس نوعاً ثالثاً للموظّف: صفٌّ قديم لم تُسجَّل له صفة. عامله موظّفاً عامّاً وأظهر له ما تسمح به صلاحياته، لا صنفاً خاصّاً.
• والدور الذي دخل به شيء ثالث: صفحة اختيار السياق تعرض بطاقةً لكل دور يحمله الشخص في الجهة — ومجموعة الصلاحيات صفُّ دور، فهي بطاقة مثل غيرها — ويضغط واحدة، فتكتبها المنصّة تحت اسمه طوال الجلسة. تقرأه في $viewer->activeRole؛ راجع «الباب الذي دخل منه» أدناه، ولا تخلطه بنوع الحساب: الأول يتغيّر بين جلستين للشخص نفسه، والثاني لا يتغيّر.

الصلاحية لا اسم الدور — الدوال التي تفرّق لك

المشكلة التي جاءت هذه الدوال تحلّها: تطبيقٌ يفرّع على «إداري» يعرض شاشات الإدارة لكل من نوع حسابه administrator — ومنهم المحاسِب الذي وضعته المدرسة في مجموعة سمّتها «محاسبة» وأعطته صلاحية واحدة. ولا يستطيع التطبيق أن يفرّع على «محاسبة» لأن المدرسة التالية تسمّيها «المالية» أو لا تملكها. الجواب الوحيد الثابت عبر المدارس هو الصلاحية، ولذلك يحمل ViewerDto الآن صلاحيات تطبيقك التي يحملها هذا الشخص في هذه الجهة — مقروءةً من الجداول لا من الجلسة، فتجيب على الويب وفي الجوال وفي مهمّة طابور سواء — ومعها مصدر كل صلاحية:

مفاتيح المجموعات: مجموعة الصلاحيات مفتاحها group.<slug>. وكانت تُسمّى administrator.<slug> فتصادمت الكلمة مع نوع الحساب administrator، فيعود الشخص إدارياً ومجموعتُه إدارية ولا يعرف قارئ الأدوار أيّهما يقصد. المجموعات القديمة أُعيدت تسميتها، وisGroupRole() تقبل الصيغتين — فلا تقارن البادئة بنفسك، اسأل الدالة.

كيف تُصمَّم شاشتك على ذلك — مثال «الإداري يرى ملفه، والمحاسبة ترى الإدارة»:

1. أعلن صلاحياتك في rbac_permissions وامنح الدور الأساسي أقلّ ما يلزمه؛ ما تريده بيد المدرسة لا تمنحه لدور أساسي:

   "rbac_permissions": {
     "administrator": ["okta_hr.profile.view"],
     "tenant-admin":  ["okta_hr.profile.view", "okta_hr.management.view"]
   }
   

   المدرسة تفتح محرّر أدوارها وتضع okta_hr.management.view في مجموعة «محاسبة» — أو «المالية» — بالعنوان الذي كتبته في rbac_labels.
2. افحص الصلاحية لا الدور:

   $viewer = app(GetCurrentViewer::class)();
   
   if ($viewer->isPortal()) {
       return view('okta-hr::family');                       // الشاشة: نوع الحساب
   }
   
   $showProfile    = $viewer->can('okta_hr.profile.view');    // الإداري (منحة أساسية)
   $showManagement = $viewer->can('okta_hr.management.view'); // «محاسبة» أو «المالية» أو مدير الجهة
   
   if ($viewer->accessLevel() === 'none') {
       return view('okta-hr::no-access');
   }
   

   المحاسِب — وهو administrator أيضاً — يرى ملفه والإدارة: الأول لأنه إداري والثاني لأن مدرسته قالت ذلك. إن أردت شاشةً تعرض ما أضافته المدرسة وحده فـgroupOnlyPermissions() تعطيك إياه؛ لكن لا تخفِ ما يحمله الشخص بحقّ لأن مصدره الدور الأساسي.
3. لا تقارن أبداً $viewer->groups[*]['key'] ولا ['title'] ولا $viewer->roles بنصّ. الفاحص لن يمسكها كلها؛ المدرسة الثانية ستمسكها.

وauth()->user()->can() تعتمد على الحارس: تجيب false على أي طلب لا مستخدمَ مربوطاً عليه — وهو حال أي مسار جوال بلا app.installation. ومع الوسيط تجيب، لكن $viewer->can() تبقى ما تسأله: جوابها واحد على الويب والجوال والطابور، ولا يتوقّف على حارسٍ لا تملكه.

إن رجعت permissions وpermissionSources فارغتين لشخص يحملها فعلاً — وخاصّةً إن كانت auth()->user()->can() تقول نعم بينما $viewer->can() تقول لا — فاسأل $viewer->hasAppContext() قبل أن تلمس المنح.

القائمة مُرشَّحة إلى تطبيقك، فإن لم يحمل الطلبُ سياقَ التطبيق فلا «تطبيقك» هناك، والقائمة فارغة بالبناء مهما ملك الشخص — وهي تبدو تماماً كمن لا يملك شيئاً، وهذا بالضبط ما كان يرسل الجميع يفتّشون في منحٍ سليمة. وaccessLevel() === 'none' عندئذٍ ليست حكماً على الشخص: لم يُسأل عنه شيء.

hasAppContext() تعود false ⇐ المسار بلا وسيط يبني السياق، والوسيطُ يختلف بين السطحين — راجع الجدول أدناه. وتعود true والقائمة فارغة ⇐ المنح فعلاً، فاطلب من فريق المنصّة php artisan partners:viewer-permissions <slug> --user=<معرّفه> --tenant=<id>.

أيّ وسيط يبني السياق — الويب شيء والتوكن شيء آخر

module.context:<slug> وسيط ويب حصراً. يقرأ الجهة من Tenant::current() (أو جهة البوّابة من الجلسة)، ونداء التوكن بلا جلسة فلا جهة — فيردّ 403 no_tenant_context قبل أن يصل مسارك. وضعُه على مجموعة مسارات الجوال يوقف كل نداءات التطبيق المصغّر. (كانت هذه الفقرة تقول «ضعه على مسار الصفحة وعلى كل ما تخدمه Livewire منها» بلا أن تقول إنه للويب وحده — وهو ما أوقع فريقاً في ذلك بالضبط.)

// مجموعة مسارات الجوال — لا module.context هنا
Route::middleware(['api', 'app.installation'])
    ->prefix('api/__MODULE_SLUG__')
    ->group(function () {
        Route::get('/me', [MeController::class, 'show']);
    });

ولا ترويسة تكتبها أنت: المضيف يرسل مع كل نداء من التطبيق المصغّر X-Module-Slug وX-Okta-Tenant-Id وX-Okta-Role-Id بجانب توكن المستخدم، وapp.installation يحلّ التثبيت من (الجهة، الـslug) من طرف الخادم، ويعيد فحص بوّابة البطاقة للدور النشط، ثم يضبط ModuleContext. فتعمل بعدها GetCurrentViewer كاملةً على الجوال: accountType وpermissions وcan() وhasAppContext() وactiveRole.

التوكن الذي يصلك توكن مستخدم لا توكن تثبيت. توكن التثبيت اعتماد خادمي على مستوى الجهة ولا يُشحن إلى هاتف أبداً. لذلك الهويّة من المستخدم والصلاحية من التثبيت — تطبيقك المصغّر لا ينال أكثر ممّا مُنح تطبيقُك.

فالقاعدة العملية:

• لا تفرّع أبداً على مفتاح مجموعة أو عنوانها. group.hr و«مدير الموارد البشرية» مفردات مدرسة واحدة. تطبيقٌ يكتب if ($viewer->groups[0]['title'] === 'مدير الموارد البشرية') يعمل في مدرسة ويصمت في التي بعدها. المجموعة تصلك كي تعرضها بجانب الاسم، لا أكثر.
• ما تشتريه المجموعةُ يجيب عنه can() وحده. المدرسة وضعت في «مدير الموارد البشرية» صلاحية __MODULE_LOWER__.reports.view؟ فاسأل عن الصلاحية لا عن المجموعة — وستعمل الإجابة في المدرسة التي أعطت الصلاحية نفسها لمجموعة اسمها «الوكيل».
• نوع الحساب واحد وثابت، فابنِ عليه الشاشة وحدها. الموظّف معلّم أو إداري — لا الاثنين — ومدير الجهة يعلوهما إن حمل الصفة؛ وemployee يصل فقط لصفّ قديم لم يقرّر أحد نوعه، فعامله كموظّف بلا نوع لا كنوع ثالث.

$viewer = app(GetCurrentViewer::class)();

// الشاشة: نوع الحساب
if ($viewer->accountType === 'guardian') {
    return view('__MODULE_SLUG__::family');
}

// الفعل: الصلاحية — لا المجموعة ولا الدور
$canApprove = $viewer->can('__MODULE_LOWER__.leave_requests.decide');

// لماذا يحملها — حين يهمّ: منحة أساسية أم شيء أضافته المدرسة
$viewer->grantedByGroupOnly('__MODULE_LOWER__.leave_requests.decide');

// العرض فقط: ما تسمّيه المدرسة
$badge = $viewer->groups[0]['title'] ?? null; // «مدير الموارد البشرية»

الباب الذي دخل منه — activeRole

الحقول الثلاثة أعلاه عن الشخص: roles مجموع ما يحمله في الجهة، وpermissions مجموع ما تحمله تلك الأدوار. وهذا الحقل عن الجلسة: الدور الواحد الذي ضغطه على صفحة اختيار السياق، وهو ما تكتبه المنصّة تحت اسمه — «إداري» مرّة و«محاسبة» أخرى، لأن مجموعة الصلاحيات صفُّ دور فهي بابٌ مثل غيره.

$viewer = app(GetCurrentViewer::class)();

// الشاشة تتبع الباب: الإدارية العضو في «محاسبة» ترى شاشة الموظّف حين تدخل
// إدارية، وشاشة المالية حين تدخل محاسِبة.
if ($viewer->activeCan('okta_hr.management.view')) {
    return view('okta-hr::management');
}

return view('okta-hr::staff');

وثلاث قواعد تحكمه، وكلٌّ منها كُتبت لأن نقيضها يكسر شيئاً:

• يقسّم ولا يأذن. الدخول بدور أساسي لا يسحب ما منحته المدرسة: بوّابة المنصّة نفسها لا تضيق بالباب، فـcan() تبقى تجيب على كل ما يحمله الشخص هنا. فاستعمل activeCan() لتقرّر ما يُعرض، وأبقِ can() لتقرّر ما يُفعل — تطبيقٌ يرفض فعلاً لأن الباب لا يحمله يخالف المنصّة في الشخص نفسه واللحظة نفسها، ويرفض على الويب ما يقبله على الهاتف.
• null تعني «بلا باب» لا «بلا دور». حين لا يُسجَّل باب على الطلب يعود الحقلان null، وactiveCan() تسقط تلقائياً إلى can() — فشاشةٌ مبنيّة عليها لا تفرغ. لا تكتب ?? false حولها؛ ولا تقرأ null رفضاً.
• ولا تقبله من العميل أبداً. لا ترسل «الدور المختار» في جسم نداء ولا في ترويسة ولا تخزّنه في المتصفّح: المنصّة تقرؤه من سياق الخادم وحده، ودورٌ يسمّيه المُنادي دورٌ يزوّره.

وعلى الجوال يصلك الباب أيضاً. الهاتف يختار دوراً عند الدخول ويرسله مع كل نداء (X-Okta-Role-Id)، وapp.installation يتحقّق أنه دورٌ يحمله المُنادي في هذه الجهة — بوّابة البطاقة تقوم عليه أصلاً — ثم يُسلّمه للـviewer. فهو ليس ادّعاءً من العميل: دورٌ يسمّيه ولا يحمله لا يمرّ، ودورٌ يحمله لا يفعل إلا أن يُضيّق ما تعرضه. وcan() لا تتغيّر في الحالتين.

كان هذا القسم يقول إن activeRole تعود null على الجوال وإن «الجوال يبقى على مجموع الصلاحيات». كان الدور يُفحص ثم يُهمَل، فصار يصل — والسطح الوحيد الذي لا can() فيه لم يعد السطح الوحيد بلا باب.

والانتحال («تصفّح نيابةً عن»): activeRole للـمنتحَل عنه — المنصّة تُعيد بناء السياق كاملاً للشخص المُنتحَل، فالجلسة جلسته والباب بابه. لكن انتبه: في الانتحال — وفي الدخول إلى بيئة التجربة — لم يضغط أحدٌ بطاقة، فالمنصّة تختار أول أدواره. فهو دورٌ صحيح يحمله الشخص فعلاً، لكنه ليس «ما اختاره»؛ ولذلك لا تجعل activeCan() بوّابةَ فعلٍ: الفرق بين البابين يجب أن يبقى فرق عرض.

أمر جاهز لمساعدك (Claude / Cursor)

انسخه كما هو إلى مساعد الذكاء الاصطناعي داخل مستودع تطبيقك، ليراجع الكود على هذه القاعدة ويصحّح ما يخالفها:

راجع تطبيقنا على قاعدة «نوع الحساب شيء، وما منحته المدرسة شيء آخر» في منصّة
أوكتا، وصحّح ما يخالفها:

أمام الشاشة شخصان قد يبدوان واحداً: إداريّ، وشخصٌ مُنح صلاحيات تحت مسمّى
«مدير الموارد البشرية». الأول نوع حساب — كلمة المنصّة ومعناها واحد في كل
مدرسة. الثاني مجموعة إدارية صنعتها هذه المدرسة وسمّتها كما شاءت، والمدرسة
التالية تسمّي الوظيفة نفسها اسماً آخر أو لا تملكها.

نقرأ الاثنين من GetCurrentViewer:
- $viewer->accountType — مفردات المنصّة الثابتة، واحدة للشخص:
  tenant_admin (مدير الجهة، يعلو ما سواه) | administrator | teacher |
  student | guardian — و employee يصل فقط لصفّ قديم لم يقرّر أحد نوعه.
  الموظّف إمّا معلّم وإمّا إداري، لا الاثنان.
- $viewer->groups — [{key, title}] المجموعات الإدارية التي صنعتها المدرسة،
  بعناوينها. للعرض بجانب الاسم فقط.

المطلوب:
1. الشاشة تُبنى على accountType وحده: أي تفريع «بوّابة الأسرة أم سطح
   الموظّفين»، وأي إعلان في audiences[]، يقرؤه من هنا. لا من $viewer->roles
   الخام ولا من اسم دور.
2. الفعل يُبنى على الصلاحية وحدها: هل يرى هذا الزرّ، هل يستطيع هذا الحفظ →
   $viewer->can('__MODULE_LOWER__.<resource>.<action>') (تجيب على الويب والجوال
   سواء؛ auth()->user()->can() تجيب false بلا جلسة). لا «هل هو إداري» ولا
   «هل هو في مجموعة X». والمساعدات: canAny/canAll، accessLevel()
   (full|granted|none)، isTenantAdmin()/isStaff()/isPortal()،
   وgrantedByGroupOnly()/grantedByBaseRole()/permissionSources حين يهمّك
   لماذا يحملها — منحة الدور الأساسي من rbac_permissions أم شيء أضافته هذه
   المدرسة لمجموعة. أعلن للدور الأساسي أقلّ ما يلزمه، واترك ما تريده بيد
   المدرسة لمجموعاتها.
3. لا تفريع أبداً على مفتاح مجموعة أو عنوانها. ابحث في الكود عن أي مقارنة
   بنصّ مثل 'مدير الموارد البشرية' أو 'group.hr' أو
   $viewer->groups[...]['key'|'title'] داخل if/match، واستبدلها بـ can()
   على الصلاحية التي تعنيها فعلاً — وأعلن تلك الصلاحية في manifest.json →
   rbac_permissions ببادئة feature = __MODULE_LOWER__، وعنوانها في
   rbac_labels.
4. لا تعامل employee كنوع ثالث: هو موظّف بلا نوع مسجَّل. اعرض له السطح
   العامّ وما تسمح به صلاحياته.
5. لا تفترض أن حامل الصلاحية إداري، ولا أن الإداري يحمل صلاحية: اعرض ما
   تسمح به الصلاحيات، وأخفِ ما عداه بدل 403.
6. إن أردت أن يتبع سطحُ الشاشة الدورَ الذي دخل به الشخص (مرّة «إداري» ومرّة
   «محاسبة») فاستعمل $viewer->activeCan()/enteredAs()/enteredAsGroup()
   للعرض وحده، وأبقِ can() لكل رفض فعل. activeRole تعود null على نداءات
   التوكن وactiveCan() تسقط عندها إلى can() — فلا تكتب ?? false حولها ولا
   تقرأ null رفضاً.

مثال الشكل الصحيح:
    $viewer = app(GetCurrentViewer::class)();
    if ($viewer->accountType === 'guardian') return view('__MODULE_SLUG__::family'); // شاشة
    $canApprove = auth()->user()->can('__MODULE_LOWER__.leave_requests.decide');   // فعل
    $badge = $viewer->groups[0]['title'] ?? null;                                  // عرض فقط

المرجع: دليل المطوّر، فصل «حسابات المنصّة» → قسم «نوع الحساب شيء، وما منحته
المدرسة شيء آخر» — اقرأه بـ read_guide/search_guide قبل التعديل، ثم شغّل
scan_code و validate_manifest على ما غيّرته.

أثر الإعلان على ظهور تطبيقك

الإعلان لا يحكم المسارات وحدها، بل ظهور تطبيقك في مشغّل التطبيقات:

• لم تُعلن جماهير أصلاً؟ بطاقتك تظهر لكل من في الجهة، كما كانت دائماً.
• أعلنت جماهير وطابَق المستخدمُ واحداً؟ تظهر البطاقة، ورابطها هو مسار ذلك الجمهور.
• أعلنت جماهير ولم يطابق أياً منها؟ لا بطاقة إطلاقاً.

الحالة الثالثة مقصودة: بطاقة تفتح صفحة سترفضها البوّابة أسوأ من غياب البطاقة، لأن المستخدم يقرؤها عطلاً في صلاحياته لدى المنصّة لا تطبيقاً لم يكن له. فإن اختفى تطبيقك عن نوع حساب تتوقّع أن يراه، فالعطب في إعلانك لا في تثبيت الجهة.

المحور الثاني: من يملك صلاحيةً من تطبيقك يدخله

نوع الحساب ليس المحور الوحيد، ولا يجوز أن تبني عليه وحده. أسماء الأدوار التي تكتبها في roles[] هي تخمينك لما تسمّيه المدارس؛ والجهة تخترع أدوارها («مشرف الحضور»، «وكيل الشؤون») ولا تسألك. فتطبيقٌ يعلن roles: ["tenant-admin", "teacher"] يختفي عن موظّفٍ أعطته المدرسة كل صلاحياته الاثنتي عشرة — لأن المحورين لم يلتقيا قطّ.

لذلك: من يحمل أي صلاحية من rbac_permissions الخاصة بتطبيقك يصل سطحك العامّ — بطاقة في المشغّل، والبوّابة تسمح، وبطاقة في كتالوج الجوال. منح الجهةِ الصلاحيةَ هو قولها إن هذا الموظّف يستعمل تطبيقك.

والمحوران يبقيان منفصلين، وهذا هو الشرط:

فالصلاحية تفتح menu.route (سطحك العامّ) ولا تفتح شاشة جمهور آخر أبداً: من لم تُعلنه لـschool-app.admin لا يدخلها ولو حمل كل صلاحياتك. وحالتان وحدهما لا يُفتح فيهما شيء:

• أن يملك menu.route جمهور بوّابة (طالب أو وليّ أمر): صلاحية موظّف ليست طريقاً إلى شاشة الأسرة مهما منحته المدرسة.
• أن تكون شاشات موظّفيك مجزَّأة فعلاً — مساران مختلفان أو أكثر — وmenu.route أحدها: فالدخول حينها دخولٌ على شاشة بُنيت لغيره.

وأن تشير جماهير الموظّفين كلّها إلى المسار نفسه ليس تجزئة. تطبيقٌ يعلن جمهوراً واحداً (tenant-admin → app.dashboard) وmenu.route هو ذلك المسار عينه له شاشة موظّفين واحدة؛ الجمهور هنا يقول من يلقاها افتراضاً لا أنها ملكه وحده، فيصلها حاملُ الصلاحية. هذه حال أكثر التطبيقات، وهي الحال التي تعمل فيها القاعدة بلا أن تغيّر شيئاً في بيانك.

ما يعنيه هذا لك عملياً:

• احرس شاشاتك بـcan() لا بافتراض الدور. auth()->user()->can('__MODULE_LOWER__.orders.view') هو السؤال الصحيح؛ «هل هذا المستخدم tenant-admin؟» سؤالٌ يجيب خطأً في أول مدرسة تسمّي أدوارها بغير ما توقّعت.
• أعلن rbac_permissions لكل فعل حقيقي في تطبيقك (راجع صلاحيات الأدوار داخل تطبيقك) — فهي الآن بابُ الدخول لا وصفَ الأفعال وحده.
• أبقِ لموظّفيك سطحاً واحداً يستقبل من دخل بالصلاحية، ثم فرّع منه بـcan() — إمّا menu.route لا يملكه جمهور، وإمّا شاشة موظّفين واحدة يشير إليها جمهورك كلّه. تطبيقٌ يشقّ موظّفيه على مسارات مختلفة يغلق بابه على كل دور لم تتوقّعه.

الوضع الحالي: البوّابة تسجّل ولا ترفض بعد

PARTNER_AUDIENCE_GUARD_MODE قيمته الافتراضية log اليوم: البوّابة تسجّل المخالفة وتخدم الصفحة. وهذا يعني أن إعلاناً خاطئاً — مفتاح بوّابة داخل roles[]، أو دور مخترَع بلا custom — يبدو عاملاً الآن، ثم يتوقّف تماماً في اللحظة التي تُقلَب فيها القيمة إلى enforce.

فلا تختبر إعلانك على سلوك اليوم. اختبره تحت الفرض:

config(['partners.audience_guard.mode' => 'enforce']);

والقاعدة عندها الرفض بالافتراض داخل التطبيق المقسَّم: ما إن تُعلن audiences حتى يصير كل مسار لا يغطّيه أي جمهور مرفوضاً. فصفحة نسيت إعلانها لا تبقى مفتوحة — تُغلق. أحصِ مساراتك قبل أن تُعلن أول جمهور.

ملاحظة: إخفاء البطاقة في المشغّل يعمل الآن بلا انتظار قلب الوضع، لأنه ترشيح عرض لا حراسة. فقد ترى تطبيقك مخفياً عن مستخدم وما يزال يستطيع فتح مساره بكتابته — هذا هو الفارق بين log وenforce بعينه.

الشركات والمجمّعات: شجرة الجهة وبيانات مدارسها

النطاقات تجيب «أيّ بيانات»، والفصل السابق يجيب «مَن الجالس». يبقى سؤال ثالث لا تصله أيّ منهما: في أيّ مكان يعمل تطبيقك، وما فوقه وما تحته.

الجهة على المنصّة ليست مدرسة دائماً. الشركة التعليمية تملك مجمّعات، والمجمّع يضمّ مدارس — والتطبيق نفسه قد يُثبَّت على أيّ مستوى من الثلاثة. وعلى المدرسة يعرض تطبيقك طلابها؛ وفي مقرّ الشركة لا طلاب له أصلاً، وعمله أن يتحرّك عبر المدارس التي تحتها. قبل هذه النقاط كان /whoami يعطي التطبيق رقماً داخلياً للجهة ولا شيء غيره: تطبيق المقرّ لا يستطيع تسمية مدارسه، وتطبيق المدرسة لا يعرف أنها تابعة لمجمّع أصلاً.

باختصار — هل يقرأ تطبيق المجمّع بيانات مدارسه؟ نعم، ومن التطبيق المصغّر مباشرةً. سمِّ المدارس في أيّ مسار قراءة: ?entities=<ulid>,<ulid> (غلافٌ بمفتاح كل مدرسة) أو ?entity=<ulid> (ردّ مدرسة واحدة كما هو). ويلزم ثلاثة: تطبيقك يحمل entity.hierarchy.read، ونطاق البيانات ممنوحٌ على المجمّع أو على المدرسة — أحدهما يكفي — والشخص الذي يستعمل التطبيق يحمل tenants.children.view_members في المجمّع. التفاصيل في «قراءة بيانات المدارس من المجمّع» أدناه، والمثال الكامل من Dart في فصل الوضع native.

الشجرة ليست بعمق ثابت

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

شركة ─┬─ مجمّع ─┬─ مدرسة أ
      │         └─ مدرسة ب
      └─ مدرسة ج            ← مباشرة، بلا مجمّع

مجمّع مستقل ─── مدرسة د      ← لا شركة فوقه

مدرسة هـ                     ← لا أحد فوقها

فلا تكتب «السلف الثاني هو الشركة». اقرأ السلسلة كما تأتيك، وافحص type.

أين أنا؟ — GetCurrentEntity (بلا نطاق)

use App\Services\PartnerApi\Entity\Hierarchy\GetCurrentEntity;

$here = app(GetCurrentEntity::class)();

$here->id;           // ULID الجهة — نفس `entityId` في ViewerDto
$here->type;         // school | complex | education_company | university | …
$here->isContainer;  // هل هذا النوع يضمّ جهات؟
$here->parentId;     // ULID الجهة الأمّ مباشرةً، أو null
$here->students;     // من تحمله هذه الجهة نفسها — لا مجموع الشجرة

بلا نطاق عمداً، إلى جوار /whoami والساعة وللسبب نفسه: اسم الجهة ونوعها هما الإطار الذي تُقرأ فيه بيانات تطبيقك، لا بيانات تحميها منحة. أمّا اسم الأمّ وبقيّة الشجرة فجهات أخرى، وهي خلف النطاق التالي.

ابدأ به. type هو ما يقرّر أيّ واجهة يرسمها تطبيقك: isContainer صادقة ⇐ شاشة المقرّ (قائمة الجهات)، كاذبة ⇐ شاشة المدرسة (الطلاب).

النطاق الواحد: entity.hierarchy.read

يفتح قراءات الشجرة التالية، للأعلى وللأسفل، ومعناه واحد: «يحقّ لهذا التطبيق أن يرى شكل الشجرة التي هو فيها» — مَن تحته، وملفّ كل جهة منها، ومَن فوقه. مدرسةٌ هي عميلة عند شركة لم توافق على أن يعدّها كلّ تطبيق تثبّته الشركة على نفسها — فمسؤول الجهة يمنح هذا صراحةً. لا .write: الشجرة ترسمها المنصّة ومسؤولو الشركة، وتطبيق يستطيع نقل مدرسة تحت أمّ أخرى هو تطبيق يستطيع نقل طلاب بين عملاء.

وهو شرطٌ أيضاً لقراءة بيانات الجهات التابعة (أدناه): تطبيقٌ لم يُسمح له برؤية الشجرة لا يقرأ مدارسها ولو حمل معرّفاتها.

للأسفل: مَن تحتي؟ — ListChildEntities

use App\Services\PartnerApi\Entity\Hierarchy\ListChildEntities;

$direct = app(ListChildEntities::class)();                    // المستوى التالي فقط
$all    = app(ListChildEntities::class)(descendants: true);   // كل المستويات

foreach ($all as $entity) {
    $entity->name;       // «مدرسة النخبة»
    $entity->type;       // school
    $entity->parentId;   // ULID أمّها — لتعيد بناء الشجرة من قائمة مسطّحة
    $entity->students;   // طلابها هي
    $entity->children;   // كم جهة تضمّ (للمجمّع)
    $entity->installed;  // هل لتطبيقك تثبيتٌ هو عليها
    $entity->access;     // ['installed' => …, 'scopes' => [...]] ← ما يُقرأ فيها
}

installed وaccess هما ما يجعلان القائمة قابلةً للعمل.

• installed — هل لتطبيقك تثبيتٌ هو على تلك الجهة. هذا ما زال الطريق الوحيد إلى الكتابة فيها، بالنطاقات التي منحها مسؤولوها.
• access.scopes — نطاقات القراءة التي يقرأ بها تطبيقك تلك الجهة: ما منحته هي لتثبيتك إن وُجد، ومنحة القراءة التي أعطتها جهتك نازلةً إليها. إحداهما تكفي — فمدرسةٌ لم تثبّت تطبيقك تُقرأ بمنحة المجمّع.

والقائمة تقول أيضاً هل الشخص الذي يستعمل التطبيق الآن يستطيع قراءة الجهات التابعة: can_read_children في ردّ /entity/children، و app(CanReadChildEntities::class)() في الكود المدمج. اقرأه قبل أن ترسم زرّ «تنزيل بيانات المدارس»، فإن كان false لا ترسمه.

(التثبيت على الجهات التابعة دفعةً واحدة يفعله مسؤول الشركة من okta-web: الجهات التابعة ← تثبيت تطبيق — كل جهة تحصل على تثبيتها ومنحتها.)

للأعلى: تابعة لمَن؟ — GetEntityAncestors

use App\Services\PartnerApi\Entity\Hierarchy\GetEntityAncestors;

$chain = app(GetEntityAncestors::class)();   // الأقرب أوّلاً؛ فارغة عند الجذر

// مدرسة تحت مجمّع تحت شركة:
$chain[0]->type;  // complex           ← المجمّع
$chain[1]->type;  // education_company ← الشركة

// مدرسة مباشرة تحت شركة:
$chain[0]->type;  // education_company — ولا يوجد [1]

// مدرسة وحدها:
$chain === [];

هذا ما يقرّر أشياءً حقيقية في التطبيق: ترويسة مَن على التقرير، هل الرسوم تُضبط هنا أم تُورَث من فوق، هل التعميم جاء من المدرسة أم من المقرّ. ابحث في السلسلة عن النوع الذي تريده بدل الاعتماد على موضعه:

$company = collect($chain)->firstWhere('type', 'education_company');  // أو null
$complex = collect($chain)->firstWhere('type', 'complex');            // أو null

ملفّ مدرسة واحدة — GET /entity/children/{id}

القائمة خريطة؛ هذا ما ترسمه على بطاقة المدرسة:

{
  "id": "01HN…A", "name": "مدرسة النخبة", "type": "school", "parent_id": "01HN…X",
  "status": "active", "students": 412, "employees": 38, "children": 0,
  "grades": 6, "sections": 18,
  "logo": "/api/apps/entity/children/01HN…A/logo",
  "phone": "0112345678", "email": "info@…", "website": null, "address": "حي الملقا، الرياض",
  "country": { "code": "SA", "name": "Saudi Arabia" },
  "timezone": "Asia/Riyadh",
  "stage": { "id": 3, "country_id": 1, "name_ar": "الابتدائية", "name_en": "Primary", "order": 1, "is_active": true },
  "installed": false,
  "access": { "installed": false, "scopes": ["education.students.read", "entity.hierarchy.read"] },
  "can_read_children": true
}

• الشعار مسارٌ لا رابط، كصورة الطالب: التطبيق المصغّر لا يجلب رابطاً بنفسه، فاعرضه بـOkta.remoteImage(school['logo'], 48). وnull حين لا شعار.
• country.code هو الرمز الذي يعيده /countries، و**stage** هو الكائن نفسه الذي يسرده /countries/education-levels — طابِق بالمعرّف لا بالاسم.
• الأعداد للمدرسة نفسها كبقيّة هذا السطح، لا مجموع شجرة.
• مدرسةٌ ليست تحت جهتك، وULID لا يسمّي شيئاً: 404 واحد — entity_not_found.

قراءة بيانات المدارس من المجمّع — ?entities= و?entity=

تطبيقك مفتوحٌ في مجمّع، والطلاب في مدارسه. مسارات البيانات نفسها تجيب عن المدارس التابعة حين تسمّيها — بلا سطر كود خادم، ومن التطبيق المصغّر مباشرةً:

final r = await Okta.getQuery('/api/apps/education/students', {
  'entities': '$schoolA,$schoolB',   // حتى ٢٠ مدرسة في النداء
  'per_page': '100',
});

والردّ مغلَّفٌ بمفتاح كل مدرسة، وقيمة كل مفتاح هي نفس الردّ الذي يعطيه المسار لتلك المدرسة — تقرؤه بالكود نفسه الذي تقرأ به ردّ جهتك:

{
  "entities": {
    "01HN…A": { "data": [ … ], "total": 412, "per_page": 100, "current_page": 1, "last_page": 5 },
    "01HN…B": { "data": [ … ], "total": 88, "per_page": 100, "current_page": 1, "last_page": 1 },
    "01HN…C": { "error": "missing_scope", "status": 403, "scope": "education.guardians.read", "message": "…" }
  }
}

بأيّ منحة تُقرأ المدرسة؟ بإحدى اثنتين، وأيّهما تكفي: ما منحته المدرسة لتثبيت تطبيقك عندها، أو منحة القراءة التي أعطتها جهتك (المجمّع أو الشركة) نازلةً إليها. فمدرسةٌ لم تثبّت تطبيقك، أو أزالته، أو لم تمنحه النطاق، تُقرأ ما دام المجمّع منح. وحدّان:

• ينزل ما ينتهي بـ.read وحده. الكتابة في مدرسة تبقى بمنحتها هي: ActInChildEntity لشخصٍ يشغّل نسخة المجمّع المُدارة (أدناه)، أو RunAsChildEntity في مهمّة، أو توكن تلك المدرسة لخادمك.
• ينزل لشخص. يجب أن يحمل مستعمل التطبيق صلاحية «السجلّ الموحّد» (tenants.children.view_members) في المجمّع — وإلا 403 children_not_readable. وخادمك بتوكن التثبيت لا يقرأ هكذا أبداً (403 entities_need_a_person): يقرأ كل مدرسة بتوكنها هي كما كان.

قواعد الردّ:

• الترقيم لكل مدرسة على حدة: page وper_page يُطبَّقان على كل مفتاح. مدرسةٌ بقيت لها صفحات اطلبها وحدها: ?entities=01HN…A&page=2.
• المدرسة المرفوضة مفتاحٌ لا الردّ كلّه: تحت مفتاحها error وstatus (وscope حين ينقص نطاق)، والباقي يصل، والردّ 200.
• entity_not_found لمدرسة ليست تحت جهتك ولـULID لا يسمّي شيئاً — الجوابان واحد عمداً، كي لا يصير الغلاف وسيلةً لمعرفة ما هو موجود.
• جهتك نفسها يجوز أن تُسمّى في القائمة، فتأتي بياناتها تحت مفتاحها.
• المرشِّح الخاص بمدرسة واحدة (section_id مثلاً) يُرسَل كما هو لكل المدارس، فتعيد الأخرى صفحةً فارغة لا خطأ.

?entity=<ulid> لمدرسة واحدة: الردّ هو ردّ تلك المدرسة كما هو — بلا غلاف، وبالحالة والترويسات نفسها. وصورة الطالب لا تُقرأ إلا هكذا، لأن الملف لا يدخل داخل غلاف:

Okta.remoteImage('/api/apps/education/students/$id/photo?entity=$school', 64);

يُرفض بالاسم، ولا يُتجاهَل (لأن تجاهله يعيد بيانات المجمّع نفسه بمظهر النجاح):

يعمل على كل مسار قراءة لبيانات الجهة: education/* (الطلاب، الصور، قوالب الوجه، أولياء الأمور، المواد، المناهج، الصفوف، الشعب، الأعوام، الفصول)، وemployees/directory، وtool-keys/*، وreports/*. ولا يحتاج رفع minContract: المعامل جزء من الرابط، وOkta.get/Okta.getQuery يحملانه على كل مضيف.

العمل داخل جهة تابعة — RunAsChildEntity (المدمج فقط)

المقابل المدمج لـ?entities=: يدخل جهةً تابعة ويشغّل كودك داخلها، فكل خدمة PartnerApi هناك تعمل كأن تطبيقك مثبَّت على تلك المدرسة. القاعدة نفسها: داخل المدرسة يحمل تطبيقك ما منحته هي لتثبيته عندها، ومنحة القراءة من جهتك نازلةً حين يكون من يسأل شخصاً يحمل tenants.children.view_members. والكتابة بمنحة المدرسة وحدها.

use App\Services\PartnerApi\Entity\Hierarchy\ListChildEntities;
use App\Services\PartnerApi\Entity\Hierarchy\RunAsChildEntity;
use App\Services\PartnerApi\Education\Students\ListStudents;

$children = app(ListChildEntities::class)(descendants: true);

foreach ($children as $school) {
    if ($school->type !== 'school' || ! in_array('education.students.read', $school->access['scopes'], true)) {
        continue;   // ليست مدرسة، أو لا منحة تقرأ بها طلابها
    }

    $students = app(RunAsChildEntity::class)($school->id, function () {
        // هنا أنت «تطبيقٌ على هذه المدرسة» تماماً: Tenant::current() هي
        // المدرسة، والنطاقات منحتها هي ومنحة القراءة من جهتك.
        return app(ListStudents::class)(perPage: 100)->data;
    });
}

ما يُفحص، بالترتيب: (١) تحمل entity.hierarchy.read؛ (٢) الهدف تابع لجهتك بأيّ عمق — الشقيقة والأمّ والغريبة تُرفض كـ«غير موجودة» لا «ممنوعة»، حتى لا يصير الخطأ وسيلةً لاستكشاف أيّ جهات موجودة؛ (٣) النداء ليس من داخل فعلٍ للمجمّع — وإلا ChildActRefusedException (already_acting)؛ (٤) السياق الذي يسأل لم يُضيَّق عمداً — شاشةٌ مثبَّتة على فصول أو صفوف، أو مفوَّضٌ من وليّ أمر، أو توكن تثبيت ومعه شخصٌ مسجَّل دخوله في الطلب نفسه — وإلا ChildActRefusedException (narrowed)؛ (٥) منحةٌ يُعمل بها هناك: تثبيت تطبيقك نفسه نشطاً على الهدف، أو — لشخصٍ يحمل الصلاحية — منحة القراءة من جهتك، وإلا MissingScopeException بمفتاح entity.child_installation. وتُستعاد الجهة الحالية والسياق دائماً بعد الإغلاق حتى لو رمى استثناءً — فلا يبقى طلبك يعمل باسم المدرسة في السطر التالي.

بلا شخص لا تنزل منحة جهتك. مهمّةٌ مجدولة أو طابور أو خادم: لا أحد يسأل، فداخل المدرسة يحمل تطبيقك ما منحته المدرسة فقط، والمدرسة التي لم تثبّته تُرفض كما كانت. ومع شخصٍ يحمل الصلاحية تنزل قراءات جهتك وحدها، لا كتاباتها.

لا على مسار طلب. لا يسأل عن الشخص شيئاً حيث يهمّ السؤال: المدرسة التي ثبّتت تطبيقك تُدخَل بمنحتها هي — والكتابة منها — أيّاً كان السائل، ولو كان شخصاً لم يأذن له المجمّع بدخول مدارسه. وفحص الشخص أعلاه لا يقرّر إلا هل تُضاف قراءات جهتك فوق تلك المنحة. فأبقِه للمهامّ المجدولة والطوابير والخوادم. وعلى مسار الطلب يقرأ الشخص المدارس بـ?entities= (أو بقراءات الشجرة) ويكتب فيها بـActInChildEntity — «التطبيق يعمل داخل مدارس المجمّع» أدناه.

التطبيق الخارجي: توكن لكل جهة

خادمُ التطبيق الخارجي يحمل توكن تثبيت لكل جهة أصلاً: يقرأ الشجرة من الجهة التي هو فيها، ثم يصل إلى جهة تابعة بتوكن تلك الجهة على الـ API نفسها، وinstalled يقول له إن كان ذلك التوكن يمكن أن يوجد. أمّا ?entities= فليس له: التوكن لا شخص خلفه، فيُجاب 403 entities_need_a_person. وواجهات تطبيقك التي يفتحها مستخدم (تطبيق مصغّر، صفحة ويب) تستعمل ?entities= كغيرها.

كيف تعلن تطبيقك «يدعم الشركات والمجمّعات»

عمل التطبيق على الشكل الحاوي لا يحتاج إعلاناً في الـ manifest. ما يجعله يعمل هناك ثلاثة أفعال في الكود: (١) افحص type/isContainer عند الفتح وارسم الشاشة المناسبة؛ (٢) اطلب entity.hierarchy.read في نطاقاتك متى كنت تحتاج الشجرة؛ (٣) لا تفترض عمقاً. وتطبيقٌ يفعل (١) وحدها يعمل على المدرسة كما كان، ويعرض في المقرّ شاشةً تقول ما هو، بدل أن يعرض «لا طلاب» ويبدو معطوباً.

والإعلانان في هذا الباب يجيبان عن سؤالين آخرين: لا «هل يعمل تطبيقك في المجمّع؟» بل «هل يجوز للمجمّع أن يضعه في مدارسه فلا تزيله؟» — وهو القسم التالي — و«حين يثبّته المجمّع، هل يُثبَّت في مدارسه معه؟» — وهو الذي يليه.

وحين تكون شاشة المقرّ تطبيقاً آخر لا فرعاً في الشاشة نفسها، فلا تشحنها إلى كل مدرسة: أعلن لنوع الحساب صفّاً مقيَّداً بـentity_types (فصل «حسابات المنصّة»، قسم «نوع الجهة»)، فتختار المنصّة الحزمة بنوع الجهة ولا تصل حزمة المجمّع هاتف مدرسة أبداً.

المجمّع يثبّت تطبيقك في مدارسه — hierarchy.managed_install

المجمّع (أو الشركة التعليمية، أو الجامعة) يستطيع أصلاً أن يثبّت أي تطبيق من المتجر في مدارسه من صفحة «تطبيقات الجهات التابعة» — نسخةً لكل مدرسة تملكها وتزيلها متى شاءت. ولبعض التطبيقات هذا هو الشكل الخطأ: حضور المجمّع، وموارده البشرية، ونقله، قراراتٌ يتّخذها المجمّع لمدارسه كلّها، ومدرسةٌ تزيل واحداً منها بهدوء تترك ثقباً في صورة المجمّع لا يلاحظه أحد حتى يعود تقريرٌ ناقصاً.

إعلانٌ واحد في الـ manifest يُدخل تطبيقك في الشكل الآخر:

{ "hierarchy": { "managed_install": true } }

وحين يكون مفعَّلاً:

ثلاثة أمور قبل أن تفعّله:

• المجمّع يعتمد عن كل مدرسة كل النطاقات التي يطلبها تطبيقك — كما يفعل التثبيت الجماعي العادي أصلاً؛ وأخذُ إدارة نسخةٍ ثبّتتها المدرسة بنفسها لا يوسّع شيئاً. وكما في كل تثبيت، كل نشرٍ لك يضبط نطاقات كل نسخة على ما يعلنه بيانك — المراجعة هي نقطة الموافقة في المنصّة. فاطلب ما يحتاجه التطبيق ولا شيء غيره: في التثبيت المُدار لا أحد في المدرسة يؤشّر على القائمة.
• جهةٌ حاوية واحدة في كل مرّة. نسخة المدرسة تُديرها جهة واحدة؛ والشركة التي تُديرها هناك لا يتجاوزها مجمّعٌ تحتها — وصفحة المجمّع تقول من يُديرها.
• الإعلان يحكم ما يُثبَّت من الآن. إطفاؤه في إصدار لاحق يوقف التثبيت المُدار الجديد، والتلقائيَّ في المدارس الجديدة؛ والنسخ المُدارة القائمة تبقى مُدارة حتى يزيلها المجمّع. نشرُك لا يفكّ قفل مدرسة أبداً.

ويُحفَظ مع الإصدار: من تبويب «التكامل» في محرّر الإصدار، أو بأداة MCP set_managed_install، أو بـsync_from_manifest من مستودعك — أبقِ المستودع والإصدار متّفقين، وإلا أعادت المزامنة التالية كتابة قيمة المستودع. و validate_manifest يرفض "1" و1: okta-web لا يقبل إلا true حرفياً.

ولا يتغيّر شيء في كودك: النسخة المُدارة تثبيتٌ عادي بتوكنه وإعداداته والنطاقات المعتمدة له.

تثبيت المجمّع يشمل مدارسه — hierarchy.reach

التثبيت المُدار أعلاه يترك للمجمّع أن يختار المدارس. ولتطبيقٍ تعمل به كل مدارس المجمّع بلا استثناء — الحضور، النقل، الانصراف — هذا الاختيار خطوةٌ زائدة ينساها أحد: يثبّت المجمّع التطبيق لنفسه، ويظنّ أنه صار في مدارسه، ولا يكون. فأنت كمطوّر تجيب مرّةً عن سؤال واحد: حين يثبّت المجمّع تطبيقك، ماذا يشمل التثبيت؟

{ "hierarchy": { "reach": "container_and_children" } }

• يحمل التثبيت المُدار معه: "container_and_children" يضع نسخاً مُدارة، فهو يعني managed_install: true وإن لم تكتبه — والمجمّع يستطيع بعدها إزالته من مدرسة بعينها من صفحة «تطبيقات الجهات التابعة» كما في القسم السابق. و "managed_install": false بجانبه تناقضٌ يرفضه validate_manifest وokta-web بالاسم.
• مَن يضغط «تثبيت» يُسأل عن المدارس أيضاً: نافذة المتجر تقول للمجمّع قبل الزرّ إن التطبيق سيُثبَّت في جهاته التابعة وكم عددها، ولا تقبل التثبيت ممّن لا يملك صلاحية «تثبيت التطبيقات في الجهات التابعة» (أو باقةً لا تتيحها) — لا تثبيتاً في المجمّع وحده بصمت. وواجهة المتجر البرمجية ترفضه بـ403، error: reach_not_allowed.
• المدرسة التي ثبّتته قبل المجمّع يبقى عندها كما هو، ويصير المجمّع من يُديره؛ والنسخة التي تُديرها جهةٌ أعلى (شركة فوق المجمّع) لا تُمَسّ. والشركة التي تثبّته تصل مجمّعاتها ومدارسها معاً، والمجمّع الذي وُضع فيه لا يسبقها إلى مدارسه.
• المجمّع يعتمد عن كل مدرسة كل النطاقات التي يطلبها تطبيقك — ولا أحد في المدرسة يؤشّر على القائمة. فاطلب ما يحتاجه التطبيق فعلاً.
• الخيار يحكم ما يُثبَّت من الآن. مجمّعٌ ثبّت إصداراً أقدم لا يُعمَّم عند نشرك: نشرُك لا يثبّت شيئاً في مدرسة لم يُقرّره مجمّعها. ويستطيع ذلك المجمّع وضعه في مدارسه كلّها من صفحة «تطبيقات الجهات التابعة». والعكس كذلك: العودة إلى "container" تمنع التثبيت الجديد، والنسخ القائمة تبقى حتى يزيلها المجمّع.
• وتطبيقك يعرف أين يعمل: النسخة في المدرسة تثبيتٌ عادي بتوكن المدرسة، ونسخة المجمّع تقرأ مدارسه بـ?entities= كما في أول هذا الفصل، وتكتب فيها عبر ActInChildEntity (القسم التالي).

ويُحفَظ مع الإصدار: من تبويب «التكامل» في محرّر الإصدار (خيار «حين يثبّت المجمّع تطبيقك، ماذا يشمل التثبيت؟»)، أو بأداة MCP set_install_reach، أو بـsync_from_manifest من مستودعك — أبقِ المستودع والإصدار متّفقين.

التطبيق يعمل داخل مدارس المجمّع — ActInChildEntity

المجمّع الذي يشغّل بوّابةً واحدة لكل مدارسه — الحضور عند بابه، أو الانصراف، أو الحافلة — يكتب سجلّاتٍ عن طلابٍ مسجَّلين في مدارسه لا في المجمّع نفسه. و ?entities= يقرأ تلك المدارس ولا يكتب فيها، وRunAsChildEntity يدخل المدرسة دون أن يسأل عن الشخص شيئاً. أمّا ActInChildEntity فهو طريق الشخص الذي يشغّل نسخة المجمّع من تطبيقك: تسأل المنصّة عن سلطته في المجمّع، ثم تشغّل كودك داخل مدرسة الطالب تحت نسخة المدرسة نفسها من تطبيقك — فيقع السجلّ، ومعه إشعار وليّ الأمر، في المدرسة وبإعداداتها.

باختصار: للتطبيق المدمج وحده، داخل العملية — ولا مسار HTTP له. يحمل الشخص في المجمّع مفتاحين: tenants.children.operate_apps وصلاحيةً من صلاحيات تطبيقك. ولا تُفتح إلا المدارس التي تُدير نسخةَ تطبيقك فيها نسخةُ المجمّع نفسها (hierarchy.managed_install / hierarchy.reach). والمدرسة التي يقع فيها السجلّ تُستنتج من الطالب على الخادم، ولا تُؤخذ من الطلب أبداً.

لمن هذا

• التطبيق المدمج، داخل العملية: خدماتٌ تحت App\Services\PartnerApi\…. ولا مسار HTTP للشركاء يعمل داخل المدارس — لا شيء تحت /api/apps/*، ولا شيء في مرجع الـ API.
• التطبيق المصغّر يكتب عبر نقاطك أنت (خلف app.installation — فصل «حسابات المنصّة»، قسم «أيّ وسيط يبني السياق»)، ونقاطك هي التي تنادي هذه الخدمات. ويقرأ المدارس بـ?entities= كما كان، أو عبر نقاطك التي تنادي قراءات الشجرة أدناه.
• خادم التطبيق الخارجي يبقى على توكن لكل جهة: يكتب في المدرسة بتوكنها هي.

مفتاحان، وكلاهما في المجمّع

• tenants.children.operate_apps — «تشغيل التطبيقات داخل الجهات التابعة». صلاحيةٌ من المنصّة يحملها دور tenant-admin العامّ، ويمنحها المجمّع لأيّ مجموعة أخرى تشغّل تطبيقك عبر مدارسه.
• صلاحيةٌ من تطبيقك للفعل نفسه — مثل my_app.arrivals.record — معلنةٌ في rbac_permissions أو تحت بادئتك. وصلاحية التشغيل لا تُقبل على أنها «من تطبيقك»: المفتاحان يبقيان اثنين.

وأحدهما وحده مرفوض: صلاحيتك وحدها يحملها عادةً كل إداري في المجمّع، وصلاحية التشغيل وحدها لا تسمّي فعلاً. ويُقرأ الاثنان في فريق المجمّع نفسه ومن جداول الصلاحيات — لا عبر can() («نعم» الشاملة لمشغّل المنصّة لا تُحتسب)، ولا في المدرسة (مدير الجهة الذي صُنع داخل المدرسة بزرّ «دخول» لا يحمل هنا شيئاً). ويضيّقهما الدور الذي دخل منه الشخص — البطاقة التي اختارها على الويب، وX-Okta-Role-Id الذي تحقّق منه app.installation على الجوال؛ أمّا الصلاحية الممنوحة للشخص مباشرةً لا عبر دور فلا تضيق. وإن كانت مسارات الجوال عندك تمرّ ببوّابةٍ من صنعك بدل app.installation، فمرّر قيمة تلك الترويسة إلى VerifyEnteredRole قبل أول فعل (App\Services\PartnerApi\Identity\VerifyEnteredRole، __invoke(int $tenantId, ?int $claimedRoleId): void): مع دورٍ لا يحمله الشخص هناك يُرمى AccessDeniedHttpException (403، ورسالته entered_role_not_assigned)، وبلا هذا النداء لا يضيق شيء، فيعمل الشخص بكل الأدوار التي يحملها في المجمّع.

ويلزم تطبيقَك نفسه entity.hierarchy.read على نسخة المجمّع.

أيّ المدارس تُفتح

المدرسة التي تُدير نسختَها النشطة من تطبيقك نسخةُ المجمّع نفسها، ولا غيرها — وضعها فيها المجمّع أو تبنّاها عبر hierarchy.managed_install أو hierarchy.reach (القسمان السابقان). أمّا نسخةٌ ثبّتتها المدرسة بنفسها ولم يتبنّها أحد، أو نسخةٌ تُديرها شركةٌ فوق المجمّع، أو مدرسةٌ بلا نسخة، أو مدرسةٌ معلَّقة، فجوابها child_not_managed. ويُسأل هذا مع كل نداء، فمجمّعٌ أزال نسخته، أو مدرسةٌ نُقلت من تحته، تُغلق من الطلب التالي.

وداخل المدرسة يحمل تطبيقك منحة نسخة المدرسة ولا شيء غيرها: لا يُضاف نطاقٌ من نطاقات المجمّع، ولا رجوع إلى منحته أبداً. سمِّ النطاقات التي يحتاجها كودك في $requiredChildScopes، والمدرسة التي تنقص نسختَها واحدةٌ منها تُرفض school_grant_missing:<scope> قبل أن يعمل كودك.

مدرسة واحدة — ActInChildEntity

__invoke(string $childEntityUlid, string $appPermission, Closure $callback, array $requiredChildScopes = []): mixed — ويعيد ما تعيده دالّتك.

داخل دالّتك Tenant::current() هي المدرسة، وسياق الوحدة سياق نسخة المدرسة (تثبيتها، والنطاقات التي اعتمدتها المدرسة لها)، وGetActiveEntityId() وGetCurrentEntity() يجيبان بالمدرسة، وDispatchNotification يرسل تحت نسخة المدرسة. ويُستعاد ذلك كلّه في finally ولو رمت دالّتك استثناءً.

والأسئلة بالترتيب — كل كلمة هي reason في App\Exceptions\ChildActRefusedException ما لم يقل السطر غير ذلك:

1. تطبيقك يحمل entity.hierarchy.read — وإلا MissingScopeException.
2. السياق هو تثبيت تطبيقك النشط نفسه في الجهة التي يعمل فيها — وإلا not_the_app_root (سياقٌ نزل إلى مدرسة ليس جذراً).
3. لستَ داخل فعلٍ آخر — وإلا already_acting: المدرسة لا تعمل على ما تحتها بسلطة المجمّع.
4. الصلاحية من صلاحيات تطبيقك — وإلا InvalidArgumentException('app_permission_not_declared')؛ وعنصرٌ فارغ أو ليس نصّاً في $requiredChildScopes يُرمى InvalidArgumentException('required_scope_invalid'). هذه أخطاءٌ في كودك، لا أجوبةٌ عن الشخص.
5. تلك الجهة حاوية — وإلا not_container — والـ ULID يسمّي جهةً قائمة تحتها — وإلا child_entity_not_found، والجواب واحد للشقيقة والأمّ والغريبة والـ ULID الذي لا يسمّي شيئاً.
6. الفاعل، في المجمّع: no_actor (لا أحد — مهمّةٌ في الطابور، أو توكن تثبيت)، وnarrowed (بابٌ ضُيّق عمداً — شاشةٌ مثبَّتة على فصول، أو مفوَّضٌ من وليّ أمر)، وmissing_permission (ليس عضواً قائماً في المجمّع، أو ينقصه أحد المفتاحين عبر الدور الذي دخل منه)، وdevice_elsewhere (لوحةٌ مقترنة بجهة أخرى).
7. نسخة المدرسة تُديرها نسخة المجمّع — وإلا child_not_managed.
8. منحة المدرسة نفسها تحمل كل نطاق في $requiredChildScopes — وإلا school_grant_missing:<scope>.

الخطوات ١–٤ تخصّ نداءك أنت، فتُرمى قبل النظر في أيّ مدرسة. ومن الخطوة ٥ فصاعداً تكتب المنصّة سطر تدقيق واحداً (app-children-act) لكل نداء — لكل مدرسة لا لكل سجلّ — في الفعل وفي كل رفض: مَن، وعبر أيّ دور، وبأيّ صلاحية، وفي أيّ مدرسة، وما النتيجة. ولا شيء يُحفظ بين طلبٍ وآخر: سحب صلاحية التشغيل، أو إزالة نسخة المجمّع، يسري من الطلب التالي.

وإن تركت الاستثناء يمرّ فالجواب أحد اثنين: 404 {"error": "child_entity_not_found"}، أو 403 {"error": "child_act_refused", "reason": "…"}. ولتتفرّع عليه، التقط ChildActRefusedException (فاحص السياسة يسمح بـApp\Exceptions\*) واقرأ reason وchildEntityUlid وisNotFound().

دفعة طلاب — ActForStudentsInTree

__invoke(array $studentUlids, string $appPermission, Closure $perSchool, array $requiredChildScopes = []): ChildActBatch — وتستلم دالّتك (string $entityUlid, array $studentUlids).

• تضع كل طالب في الجهة المسجَّل فيها — على الخادم، من تسجيله القائم — وتشغّل دالّتك مرّة لكل مدرسة عبر ActInChildEntity: مئتا سجلّ في خمس مدارس خمسة أفعال.
• طلاب المجمّع نفسه تعمل دالّتك لهم في مكانها، تحت نسخة المجمّع، بلا تبديل — وبلا سؤال عن المفتاحين وبلا سطر تدقيق: هم من جهة تطبيقك نفسها، ويحرسهم ما يحرس مسارك. وفي مدرسة (ليست حاوية) يعمل النداء أيضاً: طلابها في مكانهم، ومن سواهم unplaced.
• رفضُ مدرسةٍ لا يوقف الأخريات، ولا يُكتب لطلابها شيء في أيّ مكان — المدرسة المرفوضة لا تنقلب كتابةً تحت المجمّع أبداً.
• ChildActBatch: results (ULID الجهة ← ما أعادته دالّتك)، وrefused (ULID الجهة ← سبب الرفض)، وunplaced (ULIDs طلابٍ خارج المجمّع، أو أُخلي سبيلهم، أو لا تسمّي أحداً — في سلّة واحدة عمداً)، وpupils (ULID الجهة ← الطلاب الذين جُمعوا فيها)، وentityOf($studentUlid).
• يُرمى ولا يُسجَّل على مدرسة: MissingScopeException، وnot_the_app_root، وalready_acting، واستثناءات InvalidArgumentException — لأنها تخصّ نداءك. والاستثناء الذي ترميه دالّتك أنت لك: ليس رفضاً، ويمرّ كما هو.

use App\Services\PartnerApi\Entity\Hierarchy\ActForStudentsInTree;
use App\Services\PartnerApi\Notifications\DispatchNotification;
use Modules\MyApp\Models\Arrival;

// البوّابة ترسل ULIDs الطلاب — ولا شيء عن مدارسهم.
$pupils = $request->input('students', []);

$batch = app(ActForStudentsInTree::class)(
    $pupils,
    'my_app.arrivals.record',        // صلاحيتك، يحملها الشخص في المجمّع بجانب operate_apps
    function (string $schoolUlid, array $schoolPupils): int {
        // مرّة لكل مدرسة، وداخلها: الجهة وسياق تطبيقك وإعدادات الإشعار كلّها
        // لتلك المدرسة.
        foreach ($schoolPupils as $pupilUlid) {
            Arrival::create([
                'school_ulid' => $schoolUlid,   // حيث الطالب مسجَّل — قرّرته المنصّة
                'student_ulid' => $pupilUlid,
                'arrived_at' => now(),
            ]);

            app(DispatchNotification::class)('my-app.arrival.recorded', [
                'recipient' => ['type' => 'parent_of_student', 'id' => $pupilUlid],
            ]);
        }

        return count($schoolPupils);
    },
    ['education.students.read'],     // يجب أن تحملها نسخة كل مدرسة هي
);

$batch->results;    // ['01HN…A' => 12, '01HN…B' => 3]
$batch->refused;    // ['01HN…C' => 'child_not_managed'] — لم يُكتب لطلابها شيء
$batch->unplaced;   // خارج المجمّع، أو أُخلي سبيله، أو مجهول

القراءة عبر الشجرة — بلا دخول مدرسة

قراءات الشجرة تعمل في المجمّع ولا تبدّل الجهة. كلٌّ منها يسأل المفتاحين نفسيهما (وصلاحيتك هنا صلاحية القراءة — مثل my_app.arrivals.view)، ويقرأ كل مدرسة بمنحة نسختها هي. وهذا ما يفرّقها عن ?entities=، الذي يسأل tenants.children.view_members ويقرأ أيّ مدرسة تحتك بإحدى المنحتين: الشجرة هنا هي المجمّع والمدارس التي يُديرها، لا غير.

والنطاق في العمود الأخير يُسأل مرّتين: عن نسخة المجمّع (وإلا MissingScopeException)، وعن نسخة كل مدرسة. والمدرسة المُدارة التي تنقص نسختَها تُسمّى في skipped_entities ({id, name, missing_scope}) — لا تظهر مدرسةً فارغة — ولطالبٍ واحد يُجاب عنه بأنه غير موجود.

• الاستطلاع يجيب بقيمة. ListOperableChildEntities لا يرمي رفضاً أبداً: refusal هي missing_scope أو not_the_app_root أو إحدى كلمات الفعل، مع قائمة فارغة — فاسأله قبل أن ترسم شاشة المجمّع. والمجمّع الذي لا تُدير نسختُه أيّ مدرسة يجيب [المجمّع] بلا رفض. ولا يُرمى إلا صلاحيةٌ ليست من تطبيقك. و ActInChildEntity::refusal($appPermission) يجيب السؤال نفسه عن الشخص دون أن يسرد شيئاً.
• الأربعة الأخرى ترمي. إن نقص نسخةَ المجمّع نطاقٌ — entity.hierarchy.read أو نطاق القراءة نفسها — رُمي MissingScopeException. وكل رفضٍ غيره App\Exceptions\ChildEntitiesNotOperableException بـreason — not_the_app_root، وalready_acting، وnot_container، وكلمات الفاعل (no_actor، وnarrowed، وmissing_permission، وdevice_elsewhere)، وtree_too_large على الكشفين — ويُجاب به نداء JSON أو API هكذا: 403 {"error": "children_not_operable", "reason": "…"}.
• السقف يرفض ولا يقصّ. ListOperableStudents وكشف البطاقات يرفضان شجرةً فيها أكثر من ١٠٬٠٠٠ طالب قائم أو ٥٠ مدرسة بـtree_too_large، في كل نداء أيّاً كان مرشِّحه: القائمة المقصوصة تجعل الطلاب بعد القصّ غرباء عند الباب.
• 404 واحد لكل ما هو خارج. GetOperableStudent وGetOperableStudentPhoto يرميان ModelNotFoundException نفسه لطالب عميلٍ آخر، ولطالبٍ أُخلي سبيله، ولطالب مدرسةٍ لا يشغّلها المجمّع، ولـ ULID لا يسمّي أحداً.
• بصماتٌ لا رموز بطاقات. لا مفتاح codes في الكشف، وكل بصمة تحت سرّ المجمّع — السرّ الذي يبصم به تطبيق أوكتا المسحَ وهو مفتوح في المجمّع. فتطابق مسحات البوّابة هذه الصفوف، لا كشف المدرسة نفسها.
• رقم الهوية والصورة لا يظهران في الصفّ إلا حين تحمل النطاق نسخةُ المجمّع ونسخةُ مدرسة ذلك الطالب معاً؛ وشطر الهوية في البحث لا يعمل إلا حين منحته كل المدارس المبحوث فيها.
• ListOperableStudents يسرد من أُخلي سبيلهم كما تسردهم قائمة المدرسة نفسها، وكشف البطاقات يتركهم.
• key (في OperableEntityDto، وفي ManagingEntityDto أدناه) رقم المنصّة للجهة — القيمة التي يجيب بها GetActiveEntityId() داخل تلك المدرسة — يُسلَّم لكودك من أجل جداولك أنت. وtoArray() لا يحمله؛ فلا ترسله إلى أيّ مكان.

مَن يُدير هذه النسخة — GetManagingEntity

__invoke(): ?ManagingEntityDto (النطاق entity.hierarchy.read): الجهة الحاوية التي تُدير نسختُها النسخةَ التي تقف فيها — id (ULID)، وkey، وname، و clock، وهو TenantClockDto يقول حقلُه source أيّ حلقة من السلسلة أجابت (platform أو tenant أو country أو default). وnull لنسخةٍ لا يُديرها أحد، وهو الجواب اليومي. ويُقرأ من القفل الحيّ، فالمجمّع الذي أزال نسخته، أو المدرسة التي نُقلت من تحته، يُجاب عنهما بـnull فوراً. وداخل الفعل النسخةُ القائمة هناك نسخة المدرسة، فيجيب بالمجمّع الذي يكتب — وهو ما ترجع إليه إعدادات المدرسة.

الـ viewer داخل الفعل

GetCurrentViewer داخل دالّتك يعيد viewer المجمّع — entityId المجمّع، وأدواره ومجموعاته، وصلاحيات تطبيقك التي يحملها هناك، لأن هناك سُئلت سلطته — ومعه actingInEntityId بـ ULID المدرسة وisActingBeneath() صادقة. اختم السجلّ بالمدرسة لا بـentityId: entityId داخل الفعل هو المجمّع. وخارج الفعل لا يتغيّر شيء (actingInEntityId فارغة)، والجهاز لا يكون viewer أبداً (null).

المدرسة تُستنتج من الطالب، على الخادم

لا ترويسة، ولا حقل في الجسم، ولا معامل في الرابط، يقول في أيّ مدرسة يقع السجلّ. وschool_id يرسله العميل ادّعاءٌ ولو بدا صحيحاً. لدفعة طلاب يضعهم ActForStudentsInTree، ولطالب واحد يجيب GetOperableStudent($appPermission, $studentUlid)->entityId. والمرشِّح مثل entityUlid في ListOperableStudents يضيّق داخل الشجرة التي قرّرتها السلطة أصلاً — ULID خارجها صفحةٌ فارغة، لا مدرسةٌ تُفتح.

الإشعار يقع في المدرسة

• داخل الفعل يرسل DispatchNotification تحت نسخة المدرسة: أولياء الأمور هم أولياء الطالب في تلك المدرسة، وصفّ التسليم للمدرسة.
• النسخة المُدارة في المدرسة تتبع إعداد المجمّع للإشعار ما دام أحدٌ في المدرسة لم يضبط ذلك الصفّ: مفتاح التشغيل، والقنوات، وساعات الصمت، والنصّ. أمّا المستلمون فيبقون مستلمي المدرسة دائماً، ومعرّف قالب المزوّد لا يعبر إلا حين ترسل الجهتان تلك القناة عبر تطبيق المزوّد نفسه. وما إن يعدّل أحدٌ في المدرسة الصفّ — والصفّ الذي كان مفعَّلاً أو معدَّل النصّ أو غُيّر قبل ذلك يُحسب معدَّلاً — حتى يحكم صفّها هي، ولو كان إطفاءً متعمَّداً، إلى أن يضغط «اتّبع إعداد <المجمّع>». ولا يتغيّر شيء في كودك.
• إشعارٌ يُرسَل من سياق المجمّع نفسه إلى أولياء طالبٍ في مدرسةٍ تحته (parent_of_student) لا يصل أحداً: صفّ تسليم واحد، قناته all وحالته failed وخطؤه recipient_in_child_entity:<ULID المدرسة> — …، ولا يُرسَل شيء. ولا يُعاد إرساله — فالإعادة تجري في المكان نفسه. أرسله من داخل المدرسة، عبر ActInChildEntity أو ActForStudentsInTree.

ما ليس هنا

• اللوحات المقترنة. قاعدة الجهاز موجودة في المنصّة — اللوحة المقترنة بالمجمّع تعمل بمنح دورها، بالمفتاحين أنفسهما؛ ومقترنةً بجهة أخرى جوابها device_elsewhere؛ والشاشة المثبَّتة على أماكن narrowed — لكن لا سطح في المنصّة يفتح تطبيقك للوحة تشغيل بعد. فالذي يعمل اليوم شخص.
• RunAsChildEntity ليس هذا. لا يسأل عن الشخص شيئاً: المدرسة التي ثبّتت تطبيقك تُدخَل بمنحتها هي — والكتابة منها — أيّاً كان السائل. وسوى فحص الشجرة والمنحة لا يرفض إلا أمرين: الباب المضيَّق (narrowed)، والنداء من داخل فعل (already_acting) — «العمل داخل جهة تابعة» أعلاه. وُجد للمهامّ المجدولة والطوابير والخوادم التي لا يسأل فيها أحد. وعلى مسار الطلب اقرأ بـ?entities= أو بقراءات الشجرة أعلاه، واكتب بـActInChildEntity.
• علامة الإطلاق ليست لك لتقرأها. إطلاق الوضع native في المجمّع يحمل "operates": {"scope": "tree"} حين يجوز للشخص، عبر الدور الذي فتح به، أن يشغّل مدارس المجمّع بتطبيقك ونسختُه تُدير مدرسةً واحدة على الأقل؛ وإطلاق المدرسة — وكل إطلاق لا يستوفي ذلك — بلا مفتاح operates أصلاً. لا يقرؤه إلا تطبيق أوكتا: ليس في Okta.context()، ولا يصل خادمك أبداً. وما تراه منه أن package:okta_face يحمّل شجرة المجمّع المُشغَّلة بدل مدرسة واحدة (فصل الوضع native، قسم «مَن رأته كاميرا التعرّف»).
• لا شيء تعلنه. لا مفتاح جديد في البيان، ولا نطاق جديد، ولا minContract. وما يُشغّل هذا كلّه موجودٌ في هذا الفصل أصلاً: hierarchy.managed_install أو hierarchy.reach (حتى توجد نسخٌ مُدارة)، وentity.hierarchy.read، وصلاحيتك في rbac_permissions.

أقسام المجمّع — GET /entity/departments

المجمّع قد يقسّم مدارسه إلى أقسام (اختيارية): لكل قسم مدير وموظّفون ومدارس محدّدة، والمدرسة في قسم واحد على الأكثر. وموظّف القسم يرى مدارس قسمه وحدها، في المنصّة وفي تطبيقك معاً.

باختصار: لا شيء تعلنه ولا نطاق جديد. المنصّة تحصر قراءات الشجرة وأفعالها في قسم الشخص من تلقاء نفسها، وGET /api/apps/entity/departments (خلف entity.hierarchy.read) يخبرك بالأقسام وبمكان الشخص منها، كي يرسم تطبيقك المدارس تحت أقسامها ويشرح غياب مدرسة بدل أن يبدو معطّلاً.

ما تحصره المنصّة عنك

لشخصٍ في قسمٍ من أقسام الجهة التي ثُبِّت عليها تطبيقك، المدارس خارج قسمه غير موجودة في كل طرق الشجرة:

ومن يرى الشجرة كلّها: مَن ليس في أيّ قسم، ومن يحمل tenants.children.manage_departments (من يوزّع المدارس على الأقسام). إلا أنّ مدير المجمّع الذي يدير قسماً أيضاً يختار عند الدخول بين بطاقة «المجمّع» وبطاقة «مدير قسم X»؛ والثانية تحصره في ذلك القسم. وخادمك بتوكن التثبيت لا يُحصَر أبداً: لا شخص يُسأل عن قسمه.

فلا تخزّن قائمة المدارس من شخص لتعرضها على آخر: القائمة تختلف بين موظّفَين في الجهة نفسها.

الردّ

{
  "data": [
    {
      "id": "01JB…",
      "name": "قسم البنين",
      "description": null,
      "manager": { "name": "خالد" },
      "staff": 4,
      "schools": ["01JA…", "01JC…"]
    }
  ],
  "viewer": {
    "manages": ["01JB…"],
    "member_of": [],
    "acting_department": "01JB…",
    "reach": ["01JA…", "01JC…"]
  }
}

• schools ULIDs المدارس كما في /entity/children، فاربطهما بالمعرّف.
• viewer هو null حين لا شخص خلف الطلب (خادم).
• viewer.reach هو null حين يرى الشخص الشجرة كلّها، وإلا فقائمة ما يبلغه — وقد تكون فارغة: قسمٌ بلا مدارس يُبقي موظّفيه على لا شيء، لا على الكل.
• viewer.acting_department القسم الذي دخل به مدير المجمّع، أو null.
• جهةٌ بلا أقسام تعيد data: []، وكل شيء يعمل كما كان.

use App\Services\PartnerApi\Entity\Hierarchy\ListDepartments;

$answer = app(ListDepartments::class)();   // التطبيق المدمج: الشكل نفسه

والتطبيق المصغّر يقرؤه بـOkta.get('/api/apps/entity/departments').

لتفعيل الأقسام في تطبيقك

1. اقرأ المدارس من المنصّة في كل جلسة، لا من نسخة مخزّنة: /entity/children يعطيك ما يبلغه هذا الشخص بالضبط.
2. جمّع المدارس تحت أقسامها في شاشة المقرّ: اقرأ /entity/departments، واعرض «بلا قسم» للمدارس التي لا يحملها قسم.
3. قل لماذا القائمة قصيرة: viewer.reach غير null ⇐ «تعرض مدارس قسمك»؛ وفارغة ⇐ «لا مدارس في قسمك بعد، راجع مدير المجمّع» — لا شاشة فارغة صامتة.
4. لا تبنِ سياجك الخاص: لا تقرأ جدول الأقسام ولا تقارن المدارس بنفسك قبل القراءة أو الكتابة. المنصّة ترفض ما خارج القسم، وتطبيقٌ يحصر وحده يفترق عنها يوم يتغيّر القسم.
5. تقاريرك ومجاميعك عبر الشجرة تأخذ المدارس من /entity/children نفسها، كي لا يجمع موظّف القسم أرقام مدارس لا يراها.

دورة حياة التطبيق

Draft  →  Submitted  →  In Review  →  Approved  →  Published
                              ↓
                          Rejected

• Draft: تكتب وتعدّل بحريّة.
• Submitted: أرسلتَ للمراجعة. لا يمكن التعديل.
• In Review: فريق أوكتا يفحص.
• Approved: تمت الموافقة. ستُنشر تلقائياً عند تشغيل النشر.
• Published: ظاهر في المتجر، يمكن تثبيته من المستأجرين.
• Rejected: تُعاد لـ Draft مع تعليقات لإصلاحها.

التطبيق المدمج (Embedded)

الـ boilerplate

عند إنشاء تطبيق Embedded، يُجهَّز لك مستودع GitHub جديد فيه:

.github/workflows/partner-module-policy.yml   ← CI policy scan
scripts/partner-policy/                       ← regex Scanner + AST PHPStan rule
app/                                          ← كود تطبيقك
config/<my-module>.php                        ← كل مفاتيحك تحت هذه الـ namespace
database/migrations/                          ← migrations لجداولك الخاصة
manifest.json
module.json
phpstan.neon                                  ← مع PHPStan rule جاهزة

قواعد العزل

التطبيق المدمج يعيش داخل أوكتا، لكنه ممنوع من:

• ✗ استيراد App\Models\* (نماذج المنصة)
• ✗ استيراد App\Services\* ما عدا App\Services\PartnerApi\*
• ✗ قراءة env keys للمنصة (DB_, REDIS_, الخ)
• ✗ قراءة config المنصة (database.*, services.*، الخ)
• ✗ قراءة .env مباشرة

الطريقة الصحيحة للوصول للبيانات

استخدم خدمات PartnerApi فقط:

use App\Services\PartnerApi\Education\Students\ListStudents;

class MyController
{
    public function __invoke(ListStudents $list)
    {
        $page = $list(page: 1, perPage: 20);

        return view('my-module::dashboard', [
            'students' => $page->data,  // → list<StudentDto>
            'total'    => $page->total,
        ]);
    }
}

كل خدمة تتحقق من النطاق المطلوب آلياً قبل تنفيذ أي عملية. إذا كان المستأجر لم يُعطِ تطبيقك الـ scope المطلوب، تحصل على MissingScopeException (يتحوّل إلى 403).

الجداول الخاصة بك

أنت تملك schema منفصل تماماً عن أوكتا. اسم الـ schema يُولَّد من slug تطبيقك (m_<my_module>). لا يلامس وصولك جداول المنصة على الإطلاق (PostgreSQL يفرض ذلك على مستوى الـ role).

كيف تصل جداولك إلى ذلك الـ schema — وكيف تصحّح ما أخطأت فيه — في قاعدة بيانات التطبيق (Migrations).

قاعدة بيانات التطبيق (Migrations)

ملفات الترحيل في مستودعك هي مصدر الحقيقة. لا يوجد مصمّم مخططات في البوّابة يرسم لك جدولاً — كان موجوداً وحُذف، لأنه لم يكن يكتب شيئاً في مستودعك، فصار الجدول المرسوم حقيقة ثالثة لا تطابق المستودع ولا القاعدة الحيّة. تكتب ملف Laravel migration عادياً، وتدفعه، وتستورده.

السلسلة كاملة

database/migrations/ في مستودعك
        │  «استيراد من المستودع» (أو import_migrations_from_repo)
        ▼
متجر الترحيلات في البوّابة  ──→ manifest.database.migrations[]
        │
        ▼  provision_database (sandbox) / زر البوّابة (production)
schema خاص بتطبيقك في PostgreSQL

كل حلقة لازمة. بلا الاستيراد يُصدِر البيان requiresDatabase:false وmigrations:[]، فترفض okta-web إنشاء القاعدة بحجّة «لا شيء لتجهيزه» — والاستيراد نفسه هو ما يقلب requires_database ويملأ database_schema على إصداراتك.

شكل الملف

database/migrations/2026_07_20_101500_create_exam_papers.php
                    └─────┬────────┘ └────────┬───────────┘
                       version                اسم الترحيل

الصيغة إلزامية: YYYY_MM_DD_HHMMSS_<name>.php. ما لا يطابقها يُتجاوَز بصمت.

version هو مفتاح كل شيء بعد ذلك: ترتيب التنفيذ، ومطابقة الاستيراد المتكرّر، وسجلّ ما نُفِّذ. تغيير الطابع الزمني لملف قائم = ترحيل جديد في نظر المنصّة، لا تعديل للقديم.

ملف الأساس 000000_create_<app>_database.php

يشحنه القالب باسم يبدأ بـ000000 عمداً: هذا الاسم لا يطابق الصيغة أعلاه، فلا يُستورَد أبداً. إنشاء القاعدة نفسها خطوة تقوم بها okta-web، وملف يفعلها مجدداً يصطدم بها.

لكن التجاوز بالاسم لا بالنيّة: إن أعدت تسميته إلى طابع زمني حقيقي (2026_07_26_100000_create_<app>_database.php) فهو ترحيل عادي في نظر المنصّة، ويُستورَد ويُشحَن — وغالباً بطابع زمني أقدم من ترحيلاتك الحقيقية، وهو ما يقود مباشرةً إلى الخطأ التالي.

«Out-of-order migration» — ولماذا يوقف كل شيء

Out-of-order migration "2026_07_26_100000" precedes already-applied
"2026_07_27_100001" on binding #21. Migrations are immutable once applied
— add a new corrective migration instead.

المُطبِّق يمرّ على الترحيلات بترتيب version، ويرفض تنفيذ ترحيل أقدم من أحدث ما نُفِّذ فعلاً على تلك القاعدة. السبب أن العكس كذبة: تشغيل ترحيل قديم بعد أحدث منه يعطيك مخططاً لم يمرّ به أي تثبيت آخر، ويجعل ترتيب التنفيذ مختلفاً بين قاعدتين تدّعيان النسخة نفسها.

والرفض يُسقِط التشغيل كلّه، لا ذلك الصفّ وحده. فترحيل واحد بطابع زمني خاطئ يجمّد كل ما بعده: تقرأ «مطبَّقة ٧، معلَّقة ١» ولا تتحرّك مهما ضغطت «مزامنة الآن».

كيف تخرج منه:

1. إن كان الصفّ لا يجب أن يُشحَن أصلاً — ملف الأساس أعلاه هو الحالة النموذجية — احذفه من الجدول. لم يُنفَّذ على شيء، فالحذف نظيف تماماً، ويزول الحاجز فوراً.
2. إن كان ترحيلاً حقيقياً وصل متأخراً بطابع زمني قديم: أعطه طابعاً زمنياً بعد آخر ما نُفِّذ (أي ملفاً جديداً في مستودعك)، ثم احذف الصفّ القديم وأعد الاستيراد.
3. إن كان قد نُفِّذ فعلاً على قاعدة ما، فلا تحذفه ولا تعدّله: أضف ترحيلاً تصحيحياً جديداً. هذا هو معنى «immutable once applied» في نصّ الخطأ.

حالتان: draft و published

الاستيراد يكتب published مباشرةً — هذه ملفات إصدار فعلية لا مسودّات تُجرَّب. لهذا لا تعني «منشور» هنا أن أحداً قرّر الإصدار: ملف كان ناقصاً يوم دفعتَه يصل مجمَّداً.

تصحيح ترحيل بعد وصوله

الطريق الأول — ترحيل جديد. هذا هو الطبيعي: ALTER يصحّح ما فعله سابقه. SQL المنشور مجمَّد لسبب: قاعدة مدرسة نفّذته بالفعل، وإعادة كتابته تحت قدمها تجعل ما في القاعدة مختلفاً عمّا يقوله البيان.

الطريق الثاني — الحذف. متاح لكل صفّ، منشوراً كان أو مسودّة، من جدول قاعدة البيانات في البوّابة. لكن اعرف ما يفعله وما لا يفعله:

• ✓ يزيله من كل بيان قادم → التثبيتات الجديدة لن تحصل عليه.
• ✗ لا يتراجع عن شيء نُفِّذ. جدولٌ أُنشئ الأسبوع الماضي يبقى منشأً.
• ✗ لا يمسّ البيانات المُرسَلة سابقاً إلى okta-web؛ الفرق يبدأ من النشرة التالية.
• ✗ لا يمسّ سجلّ التنفيذ. ذلك السجلّ يقول ما نفّذته قاعدة حقيقية، وتعديله ليطابق قراراً اتُّخذ بعده يفقد المنصّة قدرتها على معرفة ما في تلك القاعدة.

فإن كان الترحيل قد نُفِّذ على قواعد قائمة، الحذف يُنشئ اختلافاً دائماً بينها وبين أي تثبيت جديد. البوّابة تعرض على الصفّ شارة «منفَّذ على N قاعدة» وتغيّر نصّ التأكيد بحسبها — اقرأه، فهو الفرق بين تنظيف قائمة وبين مخططين لن يتطابقا مجدداً.

متى الحذف هو الجواب الصحيح؟ ترحيل ناقص أو معطوب لم يُنفَّذ بعد على أي قاعدة، أو صفٌّ لم يعد له ملف في مستودعك أصلاً.

الصفوف التي لم يعد لها ملف

الاستيراد يضيف ويحدّث ولا يحذف. فلو حذفت ملفاً من مستودعك ودفعت وأعدت الاستيراد، يعود إليك «تم الاستيراد بنجاح» بينما الملف المحذوف ما يزال يُشحَن في كل بيان.

لذلك يُبلِغك الاستيراد بعددها ويضع على صفوفها شارة «غير موجود في المستودع». لا تُحذف تلقائياً: الاستيراد يجري على مرجع (ref) واحد، وغياب الملف عنه قد يعني غيابه عن ذلك الفرع فقط، وقد يكون نُفِّذ فعلاً على قاعدة حيّة. القرار قرارك على الصفّ.

SQL مباشر داخل البوّابة

للتصحيحات الصغيرة التي لا تستحقّ دورة كاملة عبر المستودع. تُحفَظ draft وتُنشَر مع الإصدار التالي. تُرفَض عبارات لا شأن لترحيل تطبيق بها — DROP DATABASE/SCHEMA/ROLE/USER، وGRANT/REVOKE، وALTER ROLE/USER، وCOPY … FROM PROGRAM، ودوالّ قراءة ملفات الخادم. الشبكة الحقيقية ليست هذه القائمة بل الـ schema المعزول: دور الاتصال لا يستطيع لمس بيانات تطبيق آخر أصلاً.

أدوات MCP

diff_schema يذكر تغطيته دائماً: ترحيل مخزَّن كمسار ملف لا يحمل SQL هنا، فلا يستطيع الفاحص ادّعاء «غير مُعلَن» على ما لم يقرأه.

توسيع ملف الطالب (Student Profile)

يقدر تطبيقك المُضمَّن يضيف محتوى لصفحة ملف الطالب في okta-web من الكود مباشرة — بدون أي إعداد في البوّابة. تكتب مكوّن Livewire داخل مجلد ثابت، تضيف عليه Attribute واحد، والمنصة تكتشفه وتسجّله تلقائياً.

لتطبيقات Embedded فقط. التطبيقات الخارجية تعرض بياناتها عبر HTTP/webhooks لا عبر هذا السجلّ.

هيكلة المجلد (تُشحن جاهزة في الـ boilerplate)

Modules/<App>/app/StudentProfile/
├── Panels/    ← بطاقات كاملة (Panel)
├── Stats/     ← أرقام في الشريط العلوي (Stat)
└── Actions/   ← أزرار في الترويسة (Action)

أي مكوّن داخل هذه المجلدات يحمل الـ Attribute المناسب يُكتشف ويُسجَّل آلياً عند الإقلاع — لا كود تسجيل تكتبه بنفسك.

التعريف: Attribute على الكلاس

namespace Modules\MyApp\app\StudentProfile\Panels;

use App\Support\StudentProfile\Attributes\StudentPanel;
use App\Support\StudentProfile\StudentProfileZone;
use Livewire\Component;

#[StudentPanel(
    title: 'ملخّص الحضور',
    permission: 'my_app.records.view',
    order: 50,
    zone: StudentProfileZone::Main,
)]
class AttendanceSummary extends Component
{
    public string $studentHashid;   // الوحيد المُمرَّر — لا id رقمي

    public function render()
    {
        return view('my-app::student-profile.attendance-summary');
    }
}

• key و component يُشتقّان تلقائياً من الكلاس (لا تكتبهما).
• يكفي title/label + permission؛ الباقي اختياري.

قواعد إلزامية

• استخدم studentHashid فقط — لا تمرّر id رقمياً أبداً.
• كل مساهمة لها permission بصيغة <feature>.<resource>.<action>.
• الآلية Embedded فقط.

الأنواع الأربعة (معاملات الـ Attribute)

1) #[StudentPanel] — بطاقة كاملة

2) #[StudentStat] — رقم في الشريط العلوي

المكوّن نفسه هو الـ widget الحيّ الذي يعرض القيمة.

3) #[StudentAction] — زر في الترويسة

url له الأولوية على event. الحدث يُبَثّ بـ Alpine $dispatch ويلتقطه Livewire عبر #[On] أو wire-elements (openModal).

4) الزون (Zone)

• Main — العمود العريض في وسط الصفحة.
• Sidebar — العمود الجانبي.

الكروم الموحّد للبلوكات (<x-profile-block> / <x-profile-stat>)

صفحة ملف الطالب لوحة بلوكات موحّدة: كل بطاقة تُعرض داخل كروم تملكه المنصة يُظهر مصدرها (تطبيقك) ولونه المميّز وحالة المزامنة وآخر تحديث ورابط «فتح في التطبيق». لتندمج بطاقتك بصرياً مع بقية اللوحة، لفّ محتوى الـ Panel بـ <x-profile-block> (بدل <x-card>):

{{-- my-app::student-profile.attendance-summary --}}
<x-profile-block
    :title="__('my-app::profile.attendance')"
    :source="\App\Support\StudentProfile\BlockSource::resolve('my-app')"
    status="live"                    {{-- live | syncing | offline | error --}}
    :last-synced-at="$syncedAt"
    :open-in-app-href="route('store.show', 'my-app')"
    :open-in-app-label="__('my-app::profile.open')">

    {{-- محتواك: مخطط/جدول/قائمة — بيانات الـ tenant من App\Services\PartnerApi\* فقط --}}

    <x-slot:actions>…</x-slot:actions>   {{-- اختياري: قائمة ⋮ --}}
</x-profile-block>

• BlockSource::resolve('<module-slug>') يعطيك هوية المصدر (اسم/لون/أيقونة) بشكل ثابت — لا تخترع لوناً لكل بطاقة. (أو مرّر source-label/accent/icon مباشرة.)
• الحالة ديناميكية: مرّر status وlast-synced-at وقت العرض حسب حالة مزامنتك الفعلية. status="offline" يعرض حالة «غير متصل» — استعمل <x-slot:offline> لمحتوى بديل (دعوة ربط).
• بطاقات الإحصاء (#[StudentStat]) تستخدم <x-profile-stat> (:label + :value + :source) لتظهر في شريط الإحصاءات منسوبةً لمصدرها.
• المنصة تملك الكروم؛ أنت تقدّم المحتوى + الحالة فقط. الشريط العلوي «مصادر البيانات» وفلتر المصدر يُشتقّان آلياً من بلوكاتك المسجَّلة (لا إعداد إضافي).

كيف يظهر في البوّابة

بوّابة الشركاء لا تشغّل كود تطبيقك؛ لذا تبويب ملف الطالب فيها للعرض فقط: يعرض المساهمات التي اكتشفها okta-web بعد تثبيت الـ sandbox، ويُشتقّ منها بلوك studentProfile في الـ manifest المنشور. أنت تكتب الكود فقط — والباقي تلقائي.

المكوّن يستقبل studentHashid فقط: <livewire:my-app::student-profile-summary :studentHashid="$studentHashid" />.

ويدجتس صفحة الهبوط (Landing Widgets)

يقدر تطبيقك المُضمَّن يضيف بلوكات إلى محرر صفحة الهبوط العامة للجهة: الويدجت يظهر في تصنيف «تطبيقاتك» داخل المحرر (للجهات التي ثبّتت تطبيقك فقط)، والجهة تسحبه إلى موقعها العام فيُعرض لزوّارها كأي بلوك من بلوكات المنصة — دون أن تكتب الجهة سطر كود واحداً. أنت تصرّح بالويدجت في الـ manifest وتشحن مكوّن Livewire واحداً؛ المنصة تتكفّل بالباقي:

• بطاقة المحرر باسم تطبيقك وأيقونته.
• فورم إعدادات البلوك يتولّد آلياً من تصريح settings_schema — لا تكتب أي Blade للمحرر.
• سلوك البلوك (نقل/نسخ/أعمدة/إظهار وإخفاء) يأتي من المحرر نفسه؛ الويدجت يُخزَّن داخل مستند الصفحة كبلوك جسر واحد من نوع partner-widget — تثبيت تطبيق جديد لا يضيف block class للمنصة.
• الأمن مجاناً وإجبارياً: سياق التشغيل على الصفحة العامة تبنيه المنصة، لا أنت.

لتطبيقات Embedded فقط. الويدجت يُرسم in-process داخل okta-web كمكوّن Livewire؛ تطبيق مستضاف خارجياً لا يملك ما يُرسم هناك. تصريح landing_widgets مع أي integrationType آخر يُرسِب نشر الإصدار.

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

التصريح في الـ manifest

{
  "integrationType": "embedded",
  // ... بقية الـ manifest ...
  "landing_widgets": [
    {
      "key": "admission_register",
      "label": "التسجيل في القبول",
      "label_en": "Admission Registration",
      "description": "نموذج تقديم طلب قبول من موقع الجهة العام.",
      "description_en": "Admission application form on the tenant public site.",
      "icon": "clipboard",
      "category": "conversion",
      "livewire_component": "my-app-landing-register",
      "interaction": "static",
      "scopes": ["education.grades.read"],
      "cache_ttl": 300,
      "settings_schema": {
        "fields": [
          { "key": "title", "type": "text", "label": "العنوان", "label_en": "Title",
            "localized": true, "default": "سجّل الآن", "min": 1, "max": 80 },
          { "key": "show_deadline", "type": "toggle", "label": "إظهار آخر موعد", "default": true }
        ]
      },
      "preview": { "thumbnail_url": "https://cdn.example.com/widgets/register.png" }
    }
  ]
}

الحقول

landing_widgets مصفوفة بحد أقصى 10 ويدجت لكل تطبيق.

فورم الإعدادات: settings_schema

{ "fields": [ { /* حقل */ }, ... ] }   // بحد أقصى 20 حقلاً

الأنواع مفردات مغلقة — ثمانية لا غير: text, textarea, number, toggle, select, color, image, link.

لا يوجد ولن يوجد نوع html (والتصريح به يرفض النشر برسالة صريحة). هذا قرار أمني لا نقص: كل قيمة إعداد تمرّ عبر escaping الـ Blade عند الرسم، فلا يمكن لأدمن جهة (أو لمخترق حسابه) حقن سكربت في الصفحة العامة عبر إعدادات ويدجتك. إن احتجت تنسيقاً غنياً، ابنه في مكوّنك من حقول مهيكلة.

خصائص الحقل:

مثال يغطي الأنواع الثمانية:

{ "fields": [
  { "key": "title",    "type": "text",     "label": "العنوان", "localized": true,
    "default": "سجّل الآن", "min": 1, "max": 80 },
  { "key": "intro",    "type": "textarea", "label": "المقدمة", "localized": true, "max": 400 },
  { "key": "max_rows", "type": "number",   "label": "عدد الصفوف", "default": 5, "min": 1, "max": 20 },
  { "key": "show_fees","type": "toggle",   "label": "إظهار الرسوم", "default": false },
  { "key": "layout",   "type": "select",   "label": "التخطيط",
    "options": [
      { "value": "grid", "label": "شبكة", "label_en": "Grid" },
      { "value": "list", "label": "قائمة", "label_en": "List" }
    ],
    "default": "grid" },
  { "key": "accent",   "type": "color",    "label": "لون التمييز", "default": "#0ea5e9" },
  { "key": "banner",   "type": "image",    "label": "صورة الترويسة" },
  { "key": "policy",   "type": "link",     "label": "رابط سياسة القبول", "localized": true }
]}

نقطتان تحكمان فهمك للتخزين:

• البلوك يُخزَّن لكل لغة داخل مستند الصفحة، والحقول غير المترجَمة تُكرَّر عبر اللغتين بنفس القيمة — لا مخزن «مشترك».
• بلوك أُدرج قبل أن تضيف حقلاً جديداً في إصدار لاحق لن يحمل مفتاحه. لذلك: كل قراءة من settings في مكوّنك خلف ?? $default، دائماً.

كتابة المكوّن

الويدجت مكوّن Livewire عادي داخل تطبيقك، يخضع لنفس عقد الكود Embedded كله — لا استثناء لكونه على صفحة عامة:

1. البيانات حصراً عبر App\Services\PartnerApi\* — الـ policy scanner يرسب البناء على غيرها، وكل خدمة تستدعي فحص النطاق داخلياً فما ليس في السياق يُرفض تلقائياً.
2. لا تفترض مستخدماً. على الصفحة العامة auth()->user() هو null دائماً. كود يفترض جلسة سينكسر هناك حتى لو عمل في معاينة المحرر.
3. إعدادات المطوّر متاحة: GetAppSetting / GetAppSettings تعمل داخل الويدجت كأي سياق تشغيل — تقرأ مخزن تطبيقك أنت فقط، فتغيّر سلوك الويدجت دون نشر إصدار جديد.
4. الواجهة بمعايير المنصة: مكوّنات <x-…> والـ tokens الدلالية — الويدجت يُرسم داخل صفحة الجهة بثيمها وبراندها، والألوان الصلبة تكسر ذلك.
5. افترض الفشل: استثناء من مكوّنك على الصفحة العامة لا يُظهر صفحة خطأ — يُنتج فراغاً صامتاً مكان الويدجت (انظر أدناه).

الويدجت الساكن (static) يُرسم مرة ويُخزَّن ناتجه cache_ttl ثانية: أي wire:click أو wire:model في blade ساكن يتجمّد سمات ميتة في HTML مخزَّن. مناسب للعرض: قوائم، إحصاءات، بطاقات، روابط. ومكوّنه يستقبل عند الرسم بالضبط settings + locale ولا شيء غيرهما — ما يحتاجه عن الجهة يقرأه من الـ ModuleContext النشط كأي خدمة PartnerApi.

نموذج الأمن — سطحان غير متماثلان

سطحا الرسم غير متماثلين، والفرق بينهما هو جوهر التصميم كله:

• معاينة المحرر: أدمن الجهة مسجّل دخوله، فالسياق يُحلّ كالمعتاد (نفس مسار بقية صفحات تطبيقك). المعاينة ترى ما يراه التطبيق عادةً.
• الصفحة العامة: الزائر مجهول تماماً — لا مستخدم، لا جلسة. المنصة تعيد بناء سياق التشغيل لكل طلب من الجهة وحدها (تُحلّ من الدومين)، ونطاقات هذا السياق هي اتحاد مجموعتين، كلٌّ منهما تقاطع ثلاثي مستقل:

READ  = (الممنوح للتثبيت) ∩ (الموسوم public_surface في الكتالوج)  ∩ (scopes الويدجت)
WRITE = (الممنوح للتثبيت) ∩ (الموسوم public_writable في الكتالوج) ∩ (public_writes الويدجت)

السياق = READ ∪ WRITE

ليستا مساراً واحداً بعلمٍ مدموج عمداً: القراءة والكتابة تجيبان سؤالين مختلفين («هل يجوز لغريب أن يرى هذا؟» مقابل «هل يجوز لغريب أن يسبّب هذا؟»)، ومسار واحد كان سيسمح لتعديل مستقبلي على أحدهما أن يحرّك الآخر بصمت. ومرشَّح الفعل يعمل مرتين على كل ضلع: .write داخل scopes[] ليس تصريح قراءة مهما قال الـ manifest، وصف كتالوج وُسم خطأً لا يركب منحةً إلى السياق.

ضلع الكتابة يحمل شرطين إضافيين: علم تفاعلية عام تفحصه المنصة داخل الـ resolver نفسه، وتذكرة كتابة عامة لا تُسكّ إلا بعد اجتياز الحواجز (انظر الويدجت التفاعلي). بلا تذكرة = مجموعة كتابة فارغة — وهذا ما يحصل عليه كل مسار قراءة، افتراضياً وإلى الأبد.

المبدأ الحاكم: ما لا يدخل السياق لا يحتاج حارساً. لا فحص أذونات جديد ولا middleware إضافي ولا قائمة منع تُصان يدوياً — سياق فقير عمداً، والحارس القائم نفسه الذي يحرس كل خدمات PartnerApi يرفض كل نطاق غير موجود فيه.

النتيجة العملية التي يجب أن تعرفها قبل أن تبني: نطاقات الطلاب وأولياء الأمور والموظفين والماليات لا تُوسم public_surface ولا public_writable أبداً. استثناؤها بنيوي لا سياسة: ليست قاعدة في middleware يمكن أن يخطئها أحد — هي ببساطة لا تدخل السياق، فكل استدعاء لها يُرفض كأنها لم تُمنح قط. ويدجت يستدعي ListStudents على صفحة عامة سيفشل دائماً، مهما أعلنت في scopes. إن كان تصوّر ويدجتك يحتاج بيانات أشخاص على صفحة عامة، فالتصوّر نفسه يحتاج إعادة نظر.

قائمة public_surface اليوم (قد تتوسع بقرار منصّة، بتحفّظ شديد):

• countries.directory.read — بيانات مرجعية عامة (قائمة الدول).
• countries.education_levels.read — سُلّم المراحل التعليمية المرجعي.
• education.grades.read — صفوف الجهة نفسها (بنية مؤسسية تنشرها المدرسة على موقعها أصلاً — لا شخص ولا سجل فيها).

الحقلان scopes وpublic_writes في تصريحك هما الضلع الثالث من تقاطعَيهما، وهما في صالحك: صرّح بأقل ما يلزم، فتضمن أن ثغرة في كود ويدجتك لا تصل إلا لما أعلنته — حتى لو كان تثبيتك ممنوحاً أكثر.

الفشل فراغ صامت — ومخزَّن

فشل الويدجت على الصفحة العامة — استثناء، نطاق مرفوض، alias لا يُحلّ، تطبيق أُزيل تثبيته — يُنتج فراغاً صامتاً مكان البلوك، ولا يُسقط موقع الجهة أبداً. وفشل الساكن يُخزَّن 30 ثانية لمنع الطَرق المتكرر: ويدجت ينهار لن يُعاد تنفيذه مع كل زائر. اعكسها على نفسك أثناء التطوير: إصلاحك قد لا يظهر فوراً بسبب كاش الفشل، وستظن أن «الويدجت لا يعمل بلا سبب» بينما السبب استثناء مبلوع — افحص سجلات okta-web ولا تعتمد على تحديث الصفحة المتكرر كاختبار.

على السطح الآخر — round-trip لويدجت تفاعلي — الفشل ليس صامتاً: طلب لا يمكن نسبته إلى ويدجت تملكه الجهة فعلاً يُرفض 403. الصمت للصفحة، والصراحة للـ round-trip.

الويدجت التفاعلي (interaction=interactive)

ويدجت يقبل إدخالاً من زائر مجهول (فورم تقديم مثلاً). عقد أثقل بكثير من مجرد قلب الحقل، وكل جملة فيه مفروضة بكود لا بمراجعة.

الوراثة إلزامية — و CI يفرضها

مكوّنك يجب أن يرث App\Support\LandingWidgets\PublicWidgetComponent — صنف تملكه المنصة. قاعدة landing-widget-base-class في policy scanner تُرسِب البناء لأي class تحت app/LandingWidgets/ في تطبيقك لا يرثه: Livewire\Component عادي هناك ليس «ويدجت بلا إضافات» — هو مسار كتابة عام بلا اشتقاق سياق وبلا حواجز، يفشل مفتوحاً لا مغلقاً. (صنف وسيط خاص بك يرث PublicWidgetComponent شكل مشروع — أعفِه على سطر التصريح بـ // partner-policy:allow=landing-widget-base-class.)

لماذا: /livewire/update لا يذكر شيئاً

الرسم الأول تصنعه المنصة وهي ممسكة بالجهة والتثبيت والسياق. لكن كل wire:click بعده يذهب إلى /livewire/update — route لا يعرف صفحات هبوط ولا جهات؛ كل ما معه snapshot أرسله المتصفح. لذلك الصنف الأساسي يعيد اشتقاق السياق كاملاً على كل hydrate من بيانات حيّة: جهة حقيقية → الباقة ما زالت تشمل الويدجتس → التفاعلية مفعّلة → الويدجت ما زال في كتالوج الجهة → مصرَّح interactive → سياق منحول بالتقاطعات. #[Locked] على خصائص الهوية يعمل عملاً حقيقياً لكنه ليس الحارس: tenantUlid مزوَّر يُحلّ على بيانات حيّة ويُرفض لأن تلك الجهة لم تثبّت تطبيقك. حتى settings المحمولة على الـ snapshot يُعاد ضبطها على schema الويدجت الحالية قبل أي استخدام.

mount() وboot() وdehydrate() وexception() كلها final عمداً. نقطتك أنت: mounted() تعمل مرة بعد قيام السياق. ولا تخزّن الـ context على خاصية — قيم per-request تُعاد صناعتها كل hydrate.

مكوّنك يستقبل عند الرسم — إضافةً إلى settings — ثلاثية الهوية moduleSlug / widgetKey / tenantUlid + widgetLocale، لأنه سيعيد بناء السياق بها على كل round-trip. (الاختيار بفحص الصنف المحلول، لا بحقل interaction المصرَّح.)

الكتابة: withPublicWrite() والحواجز الثلاثة

كل كتابة نيابةً عن الزائر تمرّ حصراً من:

public function submit(): void
{
    $this->validate([...]);

    $this->withPublicWrite('submit', function (): void {
        app(\App\Services\PartnerApi\...\CreateSomething::class)(...);
    });
}

بالترتيب، وكلها في الصنف الأساسي فلا تستطيع إسقاط أحدها:

1. honeypot — حقل مخفٍ تملكه المنصة (انظر الـ partial أدناه). تعبئته = بوت.
2. throttle — لكل (IP × جهة × module × ويدجت × action)؛ الافتراضي 5/دقيقة، أو maxPerMinute لكل نداء. دالة throttle() متاحة لك مستقلةً أيضاً لحماية قراءة مكلفة.
3. captcha — يعمل فقط حين تربط المنصة provider وتفعّله الجهة (أو تفرضه المنصة عاماً). المنصة لا تشحن provider افتراضياً، فالحاجز غائب بدل أن يحجب جهةً بفحص لا يستطيع العمل.

الرفض ليس استثناء تعالجه: الـ callback ببساطة لا يعمل، withPublicWrite يرجع null، و$widgetBarrierMessage يحمل جملة مترجمة يعرضها الـ partial للزائر.

بعد اجتياز الثلاثة — وهناك فقط — تُسكّ تذكرة الكتابة العامة، والسياق يُعاد اشتقاقه معها فيدخل ضلع الكتابة، يعمل الـ callback، ثم finally يعيد الاشتقاق بلا تذكرة — تصريح الكتابة يدوم بالضبط بقدر الكتابة، والـ render التالي بسياق قراءة فقط. لا مكان آخر في المنصة يسكّ التذكرة، فلا مسار لكتابة عامة تخطّى حاجزاً.

الـ form-guard partial — include إلزامي لا يُتجاوز

@include('landing-builder::blocks.partner-widget.partials.form-guard')

مرة واحدة داخل عنصر جذر مكوّنك. يرسم الـ honeypot + علامة الحارس + رسالة الرفض. الفرض من الـ HTML الناتج فعلاً: الصنف الأساسي يفحص مخرَج الرسم ويشتق منه حالة الحارس — فورم بلا الـ partial يصل للكتابة التالية بحاجز honeypot فاشل دائماً، ولا يتجاوز. العرَض المضلِّل حين تنساه: الفورم يظهر ويعمل ظاهرياً، والكتابة ترجع null مع رسالة حاجز.

فخّ النشر: SESSION_DOMAIN — اعرفه قبل أن تنشر

الويدجت التفاعلي = POST بجلسة و CSRF، والكوكي يعود للخادم فقط إذا غطّى نطاقَ المضيف المخدوم:

• SESSION_DOMAIN غير مضبوط: كل نطاق جهة (مخصص أو subdomain) يحصل على جلسته. هذا الترتيب الذي يعمل.
• SESSION_DOMAIN مثبَّت على نطاق المنصة: جهة تخدم صفحتها من example.com لا تحصل على كوكي جلسة إطلاقاً — الصفحة تُرسم، الفورم يظهر، وأول نقرة 419 أمام زائر لا يستطيع الإبلاغ.

المنصة تكشف الحالة الثانية ولا «تصلحها» (نطاق كوكي منصّي يُضبط عادة عمداً): تقمع الويدجت التفاعلي على ذلك المضيف وتعرض كرتاً مهذّباً بدل فورم ينتهي بـ 419، مع سطر warning في سجلات okta-web. ليس خطأك ولا خطأ كودك — شرط نشر. اختبر على نطاق مخصص إن كانت جهاتك تستعملها.

النطاق الوحيد الموسوم public_writable اليوم

education.admission_applications.write — طلب قبول يقدّمه زائر من موقع الجهة العام. صندوق بريد: يدخل ولا يخرج — لا يوجد له .read مقابل إطلاقاً (قراءة عامة كانت ستكشف طلبات المتقدمين الآخرين لأي زائر)، وهو موسوم is_dangerous فيُعرض بألوان الخطر على شاشة منح التثبيت عمداً.

توسيع القائمة قرار منصّة لا يُطلب عبر الـ manifest، ومحكوم بثلاث قواعد غير قابلة للتفاوض: intake فقط (إنشاء سجل وارد جديد يخصّ الزائر نفسه — لا update ولا لمس سجل قائم)، لا أشخاص ولا أموال، لا delete أبداً. عندك حالة استخدام؟ قدّمها لفريق المنصة.

دورة الحياة

1. النشر: تضيف landing_widgets إلى manifest إصدارك وتنشره. الفحص عند القبول (الصيغ، الحدود، integrationType=embedded، وسوم public_writes ضد الكتالوج الحي) — الكتلة المخالفة ترفض الإصدار.
2. التثبيت: الجهة تثبّت تطبيقك من المتجر وتمنح النطاقات كالمعتاد.
3. الظهور في المحرر: كتالوج ويدجتس الجهة يُشتق لكل طلب من تثبيتاتها — ويدجتس التطبيقات المثبَّتة فقط.
4. الإدراج: أدمن الجهة يسحب الويدجت، والفاحص يعرض فورم الإعدادات المولَّد من settings_schema. المعاينة تُرسم بسياق الأدمن.
5. نشر الصفحة: على الموقع العام يُرسم الويدجت بالسياق المجهول (اتحاد التقاطعين). الساكن يُخزَّن ناتجه cache_ttl ثانية (مفتاح الكاش يحمل بصمة الإعدادات — تعديل الإعدادات ونشره يظهر فوراً)؛ التفاعلي يُرسم حيّاً على كل طلب.
6. إزالة التثبيت: الويدجت يختفي من كتالوج المحرر فوراً. البلوكات المدرَجة سابقاً على صفحات منشورة تفقد مرجعها فتسقط في مسار الفشل نفسه: فراغ صامت، لا خطأ على موقع الجهة. (الجهة تحذف البلوك اليتيم من محررها متى شاءت.)
7. تحديث الإصدار: الكتالوج يعكس manifest الإصدار المثبَّت. حقل settings جديد لا يظهر في بلوكات قديمة إلا بقيمته الافتراضية من كودك (?? $default)؛ حذف ويدجت أو تغيير key يترك البلوكات القديمة يتيمة كما في الإزالة.

تسجيل الـ alias والمكوّن

// في ServiceProvider::boot() لتطبيقك — الصيغة المسطَّحة إلزامية.
use Livewire\Livewire;

Livewire::component(
    'my-app-landing-register',
    \Modules\MyApp\Livewire\Landing\RegisterWidget::class,
);

<?php

namespace Modules\MyApp\Livewire\Landing;

use Livewire\Component;

class RegisterWidget extends Component
{
    /** قيم settings_schema للّغة المعروضة، كما خزّنها المحرر. */
    public array $settings = [];

    public function render()
    {
        // القراءة حصراً عبر App\Services\PartnerApi\* — الخدمة تفحص
        // النطاق داخلياً وترفض ما ليس في السياق.
        $grades = app(\App\Services\PartnerApi\Education\Grades\ListGrades::class)(
            onlyActive: true,
        );

        return view('my-app::livewire.landing.register-widget', [
            'grades' => $grades->data,
            'title' => $this->settings['title'] ?? 'سجّل الآن',
        ]);
    }
}

هذا كل شيء للويدجت الساكن. التفاعلي يرث PublicWidgetComponent بدل Component، يعيش تحت app/LandingWidgets/، ويكتب عبر withPublicWrite() كما في قسمه أعلاه.

الأخطاء الشائعة وحلولها

قائمة تحقق قبل النشر

• integrationType=embedded والكتلة landing_widgets ≤ 10 ويدجت.
• كل key يطابق ^[a-z][a-z0-9_]{1,39}$ وفريد داخل التطبيق — واسمه نهائي.
• livewire_component بالصيغة المسطَّحة (لا ::)، ومسجَّل بـ Livewire::component() في boot().
• scopes هي الحد الأدنى الذي يحتاجه الرسم فعلاً — لا نسخ لقائمة نطاقات التثبيت.
• لا استدعاء لأي نطاق أشخاص/ماليات من مسار الرسم العام — لن يُوسم public_surface أبداً.
• settings_schema ≤ 20 حقلاً، الأنواع من الثمانية، وكل قراءة settings خلف ?? $default.
• الويدجت الساكن بلا أي wire:* في الـ blade.
• التفاعلي: يرث PublicWidgetComponent، تحت app/LandingWidgets/، وكل كتابة داخل withPublicWrite().
• التفاعلي: @include('landing-builder::blocks.partner-widget.partials.form-guard') مرة واحدة داخل عنصر الجذر.
• public_writes كلها موسومة public_writable في الكتالوج وinteraction=interactive.
• التفاعلي مجرَّب على نطاق جهة مخصص إن كانت جهاتك تستعملها.
• الرسم مجرَّب بسياق فقير (بلا مستخدم، بنطاقات scopes فقط) وبِلغتي الصفحة وبحالة بيانات فارغة.
• preview.thumbnail_url رابط https يعمل، والبطاقة مراجَعة في المحرر.

التطبيق الخارجي (External)

الإعداد

عند إنشاء تطبيق External تُدخل:

• webhook_url: عنوان HTTPS يستقبل أحداث المستأجر.
• webhook_events: قائمة أحداث الاشتراك (مثل education.students.created).
• redirect_urls: عناوين OAuth callbacks لتدفّق التثبيت.

Installation Token

عندما يُثبِّت مستأجر تطبيقك، يُصدَر installation token فريد لتلك الـ (مستأجر، تطبيق). هذا الـ token هو ما تستخدمه في كل طلب API.

Authorization: Bearer <installation_token>

التوكن:

• يدوم بشكل دائم حتى يُلغى أو يُدوَّر.
• المستأجر يستطيع تدويره/إلغاءه من لوحة "تطبيقاتي" في أي وقت.
• يحمل النطاقات التي وافق عليها المستأجر — نطاق غير مُمنح = 403.

تدوير الـ Token

عند تدوير المستأجر للـ token، تستلم webhook event partner.installation.token_rotated. الـ token الجديد فيه؛ احفظه فوراً. الـ token القديم يبقى صالحاً لمدة 15 دقيقة (grace period) لتسهيل الانتقال بدون انقطاع.

تطبيقات الإشعار (Notification)

تطبيق الإشعار يُسجَّل كقناة قابلة للتوصيل تستهلكها المنصة عبر واجهة موحَّدة. أنت تبني المزوِّد مرة، والمنصة تستدعيه بـ send(recipient, message) بصرف النظر عن القناة الفعلية (واتساب، SMS، Push، Slack، ...).

الـ manifest block

{
  "integrationType": "notification",
  "notification": {
    "channels": ["whatsapp", "sms"],
    "delivery": "api",
    "api": {
      "send_endpoint": "https://your-app.example/notifications/send",
      "auth": "hmac"
    },
    "embedded": {
      "provider_class": "Modules\\AcmeSms\\Providers\\AcmeSmsProvider"
    },
    "capabilities": {
      "supports_templates": true,
      "supports_media": false,
      "supports_bulk": true,
      "max_bulk_recipients": 1000
    },
    "settings_ui": {
      "has_settings_page": true,
      "livewire_component": "partner-apps.acme-sms.settings"
    }
  }
}

قواعد التحقق التي تفرضها المنصة على manifest الإشعار:

• notification.channels مصفوفة غير فارغة من قيم معروفة: whatsapp, sms, push, slack, email, telegram, voice.
• notification.delivery لازم تكون api أو embedded أو hybrid.
• إذا delivery=api أو hybrid ⇐ notification.api.send_endpoint لازم يكون HTTPS.
• إذا delivery=embedded أو hybrid ⇐ notification.embedded.provider_class لازم يكون FQCN صالح (مثل Modules\Foo\Providers\Bar).
• لا يُسمح بـ notification block إلا حين integrationType=notification.

الـ scopes (تُمنح تلقائياً)

عند اختيار integrationType=notification من نموذج الإنشاء، المنصة تُلحق تلقائياً بمنحات تطبيقك:

• notifications.providers.send (إجباري — يسمح بالإرسال)
• notifications.logs.read (اختياري — قراءة سجل الإرسال)

لا تحتاج اختيار شيء من picker الصلاحيات لو تطبيقك بحت إشعار.

مسار 1: delivery=api (موصى به للبدء السريع)

العقد بين المنصة وتطبيقك

تستقبل من okta-web:

POST https://your-app.example/notifications/send
Content-Type: application/json
X-Okta-Timestamp: 1736435261
X-Okta-Signature: <hmac-sha256-hex>
X-Okta-Delivery-Id: <uuid>

{
  "channel": "whatsapp",
  "recipient_identifier": "+966500000000",
  "message": {
    "body": "غاب سارة يوم 2026-09-15",
    "title": "غياب طالب",
    "template_id": "student_absent_v2",
    "variables": { "student_name": "سارة", "date": "2026-09-15" },
    "media": []
  },
  "metadata": {
    "notification_key": "okta-attendance.student_absent",
    "app_slug": "okta-attendance",
    "delivery_id": 48213
  }
}

metadata هي هوية الإشعار — راجع القسم التالي؛ وmessage.variables هي متغيّرات الكتالوج كما أرسلها التطبيق لا الجسم المُصيَّر وحده، و message.template_id ما اختارته الجهة إن اختارت (أو null).

هوية الإشعار — ما يصل مزوّدك عن كل رسالة

لماذا هذا الفصل موجود: رقم واتساب رسمي (Cloud API) لا يسلّم رسالةً تبدأها الجهة إلا قالباً معتمداً لدى Meta. مزوّدٌ يلفّ كل إشعار في قالب افتراضي واحد يبقى هناك ما لم يعرف أيَّ إشعار يحمل — ولم يكن في الحمولة ما يقوله. صار كل نداء send() — من كل قناة، ومن زرّ «إرسال تجريبي» عند الجهة — يحمل في metadata ثلاثة مفاتيح ثابتة:

ومعها:

• variables — متغيّرات الكتالوج كما أرسلها التطبيق (student_name، date، …) لا الجسم المُصيَّر وحده. اجعلها هي ما يملأ خانات القالب؛ وbody هو النصّ الجاهز لمن لا يعمل بالقوالب أو لقالب عام بخانة واحدة.
• templateId — ما اختارته الجهة لهذا الإشعار من قوالبك (القسم التالي)، أو null فتقرّر أنت: قالبٌ تربطه بـnotification_key، أو قالبك الافتراضي.
• test: true يظهر فقط حين يأتي النداء من زرّ التجربة عند الجهة؛ الهوية الثلاثية تصل معه كاملةً، فاختر للتجربة ما ستختاره للإرسال الحقيقي — تجربةٌ تنجح بقالب افتراضي وإرسالٌ يفشل بقالب لم يُعتمد هما ما جاء هذا الفصل ليمنعه.

فخّ يستحقّ سطره: على عامل الطابور يعمل مزوّدك داخل سياق تثبيته هو. فلو سألت AppContextManager «أي تطبيق أنا؟» سمعت اسمك أنت لا اسم المُرسِل. اسم المُرسِل يصلك في metadata.app_slug وحدها.

مسار POST /api/apps/notifications/send الخام (تطبيق يرسل عبرك مباشرةً بلا كتالوج) يحمل app_slug وrecipient_type فقط — لا مفتاح ولا صفّ تسليم هناك.

قوالب معتمدة تختارها الجهة — supports_templates

إن كان مزوّدك يعلن notification.capabilities.supports_templates: true، تعرض الجهة في «تخصيص الرسالة» على /settings/notifications حقلاً إضافياً لكل إشعار: قالب المزوّد المعتمد. ما تختاره يصلك في كل إرسال NotificationPayload::$templateId (وmessage.template_id على الـ api).

• مزوّد مدمج يستطيع أن يدرج قوالبه فتظهر قائمةً، بتطبيق عقد ثانٍ اختياري بجانب PartnerNotificationProvider:

  use App\Contracts\ListsNotificationTemplates;
  
  final class WaCloudProvider implements PartnerNotificationProvider, ListsNotificationTemplates
  {
      /** @return list<array{id: string, name: string, description?: ?string}> */
      public function templates(string $channel): array
      {
          // قوالب الرقم المعتمدة لدى Meta — تُنادى داخل سياق تثبيتك،
          // فرقم الجهة هو رقمها. لا ترمِ؛ أعِد [] عند التعذّر.
          return $this->meta->approvedTemplates($channel);
      }
  }
  

  والقائمة مغلقة: معرّف خارجها يُرفض عند الحفظ، فلا يصل Meta قالبٌ غير موجود.

• مزوّد api لا صنف له هنا، فالجهة تكتب معرّف القالب كما هو عندك.

• لا supports_templates ⇐ لا حقل، وtemplateId دائماً null.

المنطق عندك لا يتغيّر بوجود الاختيار: templateId أولاً إن وصل، وإلا ما تربطه بـnotification_key، وإلا الافتراضي.

كتالوج إشعارات التطبيقات المثبَّتة — مصدرك لبناء القوالب

القالب المعتمد يُبنى قبل أول إرسال، ولا تستطيع بناءه لمفتاح لا تعرفه. ولذلك للمزوّد نقطة تقرأ كتالوج إشعارات كل التطبيقات المثبَّتة على الجهة التي ثُبِّت فيها — بنطاقه هو notifications.providers.send، بلا نطاق إضافي:

GET /api/apps/notifications/catalog?channel=whatsapp
Authorization: Bearer <installation token>

{
  "tenant_id": 4821,
  "apps": [
    {
      "app_slug": "okta-attendance",
      "display_name": "اوكتا حضور",
      "installation_id": 918,
      "notifications": [
        {
          "key": "okta-attendance.student_absent",
          "display_name_ar": "غياب طالب",
          "display_name_en": "Student absent",
          "audience": ["guardian"],
          "variables": { "student_name": "string", "date": "date" },
          "default_template": "غاب {{ student_name }} يوم {{ date }}",
          "default_channels": ["whatsapp", "in_app"],
          "tenant": { "enabled": true, "channels": ["whatsapp"], "template_id": "student_absent_v2", "has_custom_template": false }
        }
      ]
    }
  ]
}

• key هو ما سيصلك في metadata.notification_key، و**variables** (اسم ← نوع) هي بالضبط أسماء ما يصل في variables مع كل إرسال — خانات قالبك تُبنى عليها.

• tenant حالة الجهة للمفتاح إن ضبطته (null إن لم تضبطه بعد): هل هو مفعَّل، وعلى أي قنوات، وأيّ قالب من قوالبك اختارت. default_channels سقف المطوّر، وtenant.channels ما ضيّقته الجهة منه.

• ?channel=whatsapp يقتصر على المفاتيح التي ستخرج فعلاً على هذه القناة هنا (اختيار الجهة إن وُجد، وإلا سقف المطوّر) — وهي القائمة التي تحتاج قالباً لكل بند فيها.

• تطبيقات هذه الجهة وحدها، والمُعلَن النشط فقط؛ ولا مستلمين ولا حمولات ولا سجلّ تسليم لتطبيق غيرك.

• installed_apps تسرد كل تثبيت نشط على الجهة بعدد إشعاراته (حتى مزوّدك نفسه بصفر) — فإن جاءت apps فارغة اقرأها: قائمة تثبيتات بلا إشعارات تعني أن التطبيقات لا تُعلن شيئاً؛ وقائمة فارغة تعني أن توكنك على جهة أخرى (لكل شريك سندبوكس لكل نوع جهة — مدرسة، حضانة… — وكلٌّ بتثبيتاته)، وtenant_id في الردّ هو ما تقارنه بالجهة التي تفتحها في المتصفّح.

• التوكن على السندبوكس: التثبيت هناك لا يُصدر توكناً تلقائياً. من حساب مدير السندبوكس POST /api/store/modules/{slug}/installation-token/rotate يُصدر أول توكن للتثبيت (بنطاقاته المعتمدة) ويعيده مرة واحدة — أو استعمل النداء المدمج أدناه بلا توكن.

• المزوّد المدمج يقرؤه بلا HTTP — الصنف نفسه من داخل كودك، وهو تحت App\Services\PartnerApi\* فالفاحص يسمح باستيراده:

  use App\Services\PartnerApi\Notifications\Catalog\GetInstalledAppsNotificationCatalog;
  
  // على صفحات إعداداتك (الوسيط بنى سياق تثبيتك) أو داخل send() على العامل
  // (تصل ملفوفاً بسياقك) — الجهة والتثبيت من السياق، لا من وسيط.
  $catalog = app(GetInstalledAppsNotificationCatalog::class)('whatsapp');
  
  foreach ($catalog['apps'] as $app) {
      foreach ($app['notifications'] as $n) {
          // $n['key'] هو ما سيصلك في metadata.notification_key،
          // و$n['variables'] أسماء خانات قالبك.
          $this->ensureTemplateFor($n['key'], array_keys($n['variables']));
      }
  }
  

  خارج أي سياق تثبيت (من tinker مثلاً) يُرفض بـno_app_context — لا يجيب عن جهة مجهولة.

الكتالوج يتغيّر حين تنشر التطبيقات إصدارات جديدة، فأعد قراءته دورياً أو عند أول مفتاح مجهول يصلك — لا تخبّئه إلى الأبد.

التحقق من التوقيع

$timestamp = $request->header('X-Okta-Timestamp');
$signature = $request->header('X-Okta-Signature');
$body      = $request->getContent();

$expected = hash_hmac('sha256', $timestamp . '.' . $body, $signingSecret);

if (! hash_equals($expected, $signature)) {
    abort(401, 'invalid_signature');
}

// رفض إن كان الطابع الزمني أقدم من 5 دقائق
if (abs(time() - (int) $timestamp) > 300) {
    abort(401, 'timestamp_skew');
}

الرد المتوقَّع

HTTP/1.1 200 OK
Content-Type: application/json

{ "provider_id": "wamid.HBgL..." }

• 2xx = نجاح. أعِد provider_id لتربط الرسالة بمعرف المزوِّد.
• 4xx = فشل دائم (رقم خاطئ، رسالة مرفوضة، ...). لا retry.
• 5xx = فشل مؤقّت. okta-web تعيد المحاولة مرة واحدة.

الحصول على signingSecret

السر يصدر تلقائياً عند install على المنصة. للحصول عليه برمجياً:

// من جانب okta-partners
$creds = app(\App\Services\OktaWebService::class)
    ->getInstallationCredentials($installationId);

$signingSecret = $creds['signing_secret'] ?? null;

أو يدوياً عبر زر تدوير Token في صفحة install على okta-web — يعرض signing_secret مرة واحدة. كل تدوير يُنتج سراً جديداً.

مسار 2: delivery=embedded

تشحن class داخل okta-web يُطبِّق العقد:

namespace Modules\AcmeSms\Providers;

use App\Contracts\PartnerNotificationProvider;
use App\Services\PartnerApi\Notifications\NotificationPayload;
use App\Services\PartnerApi\Notifications\NotificationResult;

final class AcmeSmsProvider implements PartnerNotificationProvider
{
    public function send(NotificationPayload $payload): NotificationResult
    {
        try {
            // أيُّ إشعار هذا، ومن أرسله، وأيّ صفّ تسليم — راجع «هوية الإشعار».
            $key = $payload->metadata['notification_key'] ?? null;   // okta-attendance.student_absent
            $template = $payload->templateId                          // اختيار الجهة إن وُجد
                ?? $this->templateFor($key);                          // وإلا ما تربطه أنت بالمفتاح

            $response = SmsClient::send([
                'to'        => $payload->recipientIdentifier,
                'text'      => $payload->body,
                'template'  => $template,
                'params'    => $payload->variables,                   // متغيّرات الكتالوج تملأ الخانات
                'reference' => $payload->metadata['delivery_id'] ?? null,
            ]);

            return NotificationResult::success(providerId: $response['id'] ?? null);
        } catch (\Throwable $e) {
            return NotificationResult::failure($e->getMessage());
        }
    }

    public function supports(string $channel): bool
    {
        return $channel === 'sms';
    }

    public function isConfigured(): bool
    {
        return ! empty(config('acme-sms.api_key'));
    }
}

ملاحظات:

• المسار لازم يبدأ بأحد الـ namespaces المسموح بها: Modules\ (الافتراضي) أو ما يضيفه فريق المنصة في partners.embedded_notification_namespaces.
• لا تَرمِ exceptions من send() — التف بـ try/catch وأعِد NotificationResult::failure().

مسار 3: delivery=hybrid

يبني المنصة HybridNotificationProvider يجرّب المسار embedded أولاً، ويتراجع لـ api عند:

• embedded.isConfigured() يُرجِع false.
• embedded.send() يُرجِع NotificationResult::failure().

مفيد للـ canary releases: تشحن class جديد لإصدار، تترك الـ API كاحتياط لو الـ class تعطّل.

واجهة الإعدادات (settings_ui) — اختيارية

لو تطبيقك يحتاج صفحة إعدادات داخل لوحة tenant على okta-web، صرّح في manifest:

"settings_ui": {
  "has_settings_page": true,
  "livewire_component": "partner-apps.acme-sms.settings"
}

المنصة تعرض رابط "فتح الإعدادات" في صفحة /partner-apps/notification/providers ويفتح shell موحَّد يحمّل مكوِّن Livewire الخاص بك. المسار لازم يطابق livewire-component مُسجَّل (تشحنه ضمن نفس module).

الـ overrides لكل إصدار

كل الحقول السابقة (channels, delivery, api.send_endpoint, embedded.provider_class, capabilities, settings_ui) قابلة للتخصيص لكل إصدار من تبويب التكامل في صفحة الإصدار. الحقل الذي يُترك فارغاً يرث من الـ module تلقائياً عند build، فلا حاجة لتكرار الإعدادات في كل release.

تطبيقات الدفع (Payment)

تطبيق الدفع يُسجَّل كبوابة/وسيلة دفع قابلة للتوصيل تثبّتها الجهة مرة واحدة، ثم تدفع بقية التطبيقات المبالغ من خلاله عبر عقد دفع موحَّد في okta-web. أنت تبني المزوِّد مرة، والمنصة تستدعيه بـ charge(...) بصرف النظر عن البوابة الفعلية (Tabby، Tamara، Noon Payments، ...).

الـ manifest block

{
  "integrationType": "payment",
  "payment": {
    "payment_methods": ["card", "mada", "applepay", "stcpay", "tabby", "tamara", "bank_transfer", "wallet", "cash"],
    "delivery": "api",
    "api": {
      "charge_endpoint": "https://your-gateway.example/okta/charge",
      "auth": "hmac"
    },
    "embedded": {
      "provider_class": "Modules\\AcmePay\\Payments\\AcmePayProvider"
    },
    "capabilities": {
      "supports_refunds": true,
      "supports_partial_refunds": false,
      "supports_installments": true,
      "min_amount": null,
      "max_amount": null,
      "currencies": ["SAR"]
    },
    "settings_ui": {
      "has_settings_page": true,
      "livewire_component": "vendor-x-payment-settings"
    }
  }
}

قواعد التحقق التي تفرضها المنصة على manifest الدفع:

• payment.payment_methods مصفوفة غير فارغة من قيم معروفة: card, mada, applepay, stcpay, tabby, tamara, bank_transfer, wallet, cash.
• payment.delivery لازم تكون api أو embedded أو hybrid.
• إذا delivery=api أو hybrid ⇐ payment.api.charge_endpoint لازم يكون HTTPS.
• إذا delivery=embedded أو hybrid ⇐ payment.embedded.provider_class لازم يكون FQCN صالح (مثل Modules\AcmePay\Payments\AcmePayProvider).
• لا يُسمح بـ payment block إلا حين integrationType=payment.

وسائل دفع مخصصة

بالإضافة إلى الوسائل التسع القياسية، يمكن لمزوّد الدفع تعريف وسائل مخصصة عبر بلوك custom_methods بجانب payment_methods:

"payment": {
  "payment_methods": ["card", "mada", "my_regional_wallet"],
  "custom_methods": [
    { "key": "my_regional_wallet", "label": "محفظتي الإقليمية", "label_en": "My Regional Wallet", "kind": "wallet" }
  ],
  "delivery": "api"
}

القواعد:

• key: يطابق ^[a-z][a-z0-9_]{1,31}$، ولا يساوي أي وسيلة قياسية، وفريد ضمن القائمة.
• label (عربي) وlabel_en (إنجليزي): مطلوبان، طول كل منهما 2–60 حرفاً.
• kind: مطلوب، أحد: card | wallet | bnpl | transfer | cash | other.
• كل مفتاح في custom_methods لازم يظهر في payment_methods (والعكس: أي إدخال غير قياسي في payment_methods لازم يقابله إدخال في custom_methods). في نموذج الإنشاء تُضاف مفاتيح الوسائل المخصصة تلقائياً إلى payment_methods، فلا حاجة لتأشيرها يدوياً.
• يُحذف custom_methods من الـ manifest تماماً حين لا توجد وسائل مخصصة.

التطبيقات المستهلِكة ترى الوسائل المخصصة (مع مسمياتها) عبر GET /api/apps/payments/methods تماماً كالوسائل القياسية، وتستخدم key عند تنفيذ الدفعة.

الـ scopes (تُمنح تلقائياً)

عند اختيار integrationType=payment من نموذج الإنشاء، المنصة تُلحق تلقائياً بمنحات تطبيقك:

• payments.charges.update (إجباري — يسمح بتحديث حالة الدفعة)
• payments.charges.read (اختياري — قراءة حالة الدفعة)

لا تحتاج اختيار شيء من picker الصلاحيات لو تطبيقك بحت مزوّد دفع.

مسار 1: delivery=api

العقد بين المنصة وتطبيقك

تستقبل من okta-web طلب دفعة موقَّعاً:

POST https://your-gateway.example/okta/charge
Content-Type: application/json
X-Okta-Timestamp: 1736435261
X-Okta-Signature: <hmac-sha256-hex>
X-Okta-Charge-Id: <uuid>
X-Okta-Idempotency-Key: <key>

{
  "method": "tabby",
  "amount": 150.00,
  "currency": "SAR",
  "description": "اشتراك سنوي",
  "customer": { "name": "أحمد", "phone": "+966500000000", "email": "a@example.com" },
  "metadata": {},
  "charge_ref": "chg_01H..."
}

• التوقيع: X-Okta-Signature = hmac_sha256("<timestamp>.<body>", signingSecret) — نفس آلية الإشعار.
• لا إعادة محاولة تلقائية من okta-web؛ يُعتمد على X-Okta-Idempotency-Key لضمان عدم الخصم المزدوج إن أعدت الطلب.

الرد المتوقَّع

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "pending",
  "provider_ref": "tabby_pay_123",
  "redirect_url": "https://checkout.tabby.ai/..."
}

• status واحدة من: pending | paid | failed.
• provider_ref معرّف العملية لدى المزوّد.
• redirect_url اختياري — لو الدفع يحتاج توجيه العميل (Tabby/Tamara).
• أي رد 2xx يُعتبر مقبولاً؛ حدِّث الحالة لاحقاً عبر callback الحالة.

تحديث الحالة لاحقاً

عند تغيّر حالة العملية (تم الدفع / فشل)، يرسل تطبيقك تحديثاً لـ okta-web بـ installation token الخاص به (scope payments.charges.update):

POST https://<okta-web>/api/apps/payments/charges/{charge_ref}/status
Authorization: Bearer <installation-token>
Content-Type: application/json

{ "status": "paid", "provider_ref": "tabby_pay_123" }

مسار 2: delivery=embedded

تشحن class داخل okta-web يُطبِّق App\Contracts\PartnerPaymentProvider (charge / refund / supports / isConfigured). لا تَرمِ exceptions من charge() — التف بـ try/catch وأعِد نتيجة فشل.

مسار 3: delivery=hybrid

يبني المنصة مزوّداً هجيناً يجرّب المسار embedded أولاً، ويتراجع لـ api عند عدم تهيئة الـ class (isConfigured()=false) أو فشل غير دائم.

استهلاك المدفوعات من تطبيقك (Embedded فقط)

قاعدة صارمة: استهلاك الدفع (إنشاء دفعة / قراءتها / سردها / استرجاعها) متاح حصراً لتطبيقات Embedded. أي محاولة استهلاك من تطبيق External تُرفض بخطأ payment_consumption_embedded_only. السبب: ردّة الفعل على نتيجة الدفعة تصل عبر حدث داخل العملية (in-process) لا webhook — تطبيق مستضاف خارجياً لا يملك مساراً للاستماع لحدث Laravel داخلي، فسيبقى "أعمى" عن النتيجة النهائية لو سُمح له بالدفع. مزوّدو الدفع أنفسهم (integrationType=payment) لا يستهلكون أيضاً — دورهم استقبال نداء الدفع وتحديث حالته فقط (payments.charges.update)، وليس بدء عمليات دفع لصالح تطبيقات أخرى.

كيف تعمل الآلية من طرف إلى طرف

1. الجهة تُثبّت مزوّد دفع واحد أو أكثر (integrationType=payment) من /partner-apps/payment/providers — خطوة إدارية تقوم بها الجهة نفسها، لا علاقة لتطبيقك بها.
2. تطبيقك المدمج (Embedded) يطلب تنفيذ دفعة بمبلغ عبر عقد CreateCharge الموحَّد دون أن يعرف أي بوابة فعلية مثبَّتة لدى الجهة.
3. المنصة (ResolveTenantPaymentProvider) تحلّ المزوّد النشط الذي يدعم الوسيلة المطلوبة، وتُنفّذ الدفعة عبره (نفس مسارات api/embedded/hybrid الموصوفة أعلاه من جهة المزوّد).
4. تطبيقك يتابع النتيجة بطريقتين متكاملتين:
   • فورياً من قيمة الرد نفسه (status: paid|pending|failed).
   • لاحقاً عبر الحدث ChargeUpdated الذي تبثّه المنصة عند كل تحوّل حالة — ضروري لحالات pending التي تتحوّل لاحقاً إلى paid عبر بوابات BNPL بعد أن يُكمل العميل الدفع على صفحة البوابة.

النطاقات المطلوبة

اطلبها من picker النطاقات عند بناء تطبيقك (resource payments):

payments.charges.update ليس ضمن picker المستهلكين — هذا النطاق حصري لمزوّدي الدفع أنفسهم (يُمنح تلقائياً عند integrationType=payment فقط، لتحديث حالة الدفعات التي ينفّذونها). استدعاؤه من سياق استهلاك يُرفض بخطأ payment_status_update_provider_only.

الخدمات (in-process — الطريق الأساسي)

نفس نمط بقية App\Services\PartnerApi\* — بدون HTTP، بدون exceptions للتحكم بالتدفق العادي، مسموحة للسكانر. كل خدمة تُعيد array (لا Eloquent، لا تسريب schema):

ListCharges تُعيد فقط الدفعات التي أنشأها تطبيقك أنت (تُصفّى بمعرّف تثبيتك الخاص) — فلاتر مدعومة: status, method, from, to، مع page/per_page (حتى 100)، وترتيب الأحدث أولاً.

مثال 1 — بيع ميزة/خدمة داخل تطبيقك

// Modules/SchoolPortal/app/Services/Reports/SellPremiumReport.php

namespace Modules\SchoolPortal\Services\Reports;

use App\Services\PartnerApi\Payments\CreateCharge;

final class SellPremiumReport
{
    public function __construct(
        private readonly CreateCharge $createCharge,
    ) {}

    /**
     * @return array<string, mixed>
     */
    public function __invoke(string $orderId, float $amount): array
    {
        return ($this->createCharge)([
            'method' => 'tabby',
            'amount' => $amount,
            'currency' => 'SAR',
            'description' => 'تقرير تحليلي مميّز',
            'metadata' => [
                'feature' => 'premium_reports',
                'order_id' => $orderId,
            ],
            'idempotency_key' => "premium-report-{$orderId}",
        ]);
    }
}

من الـ Livewire component المستدعي:

$result = app(SellPremiumReport::class)($orderId, 49.00);

if ($result['status'] === 'paid') {
    // فعّل الميزة فوراً — الرد جاء paid مباشرة (بطاقة/مدى).
    $this->dispatch('feature-unlocked');
    return;
}

if ($result['status'] === 'pending' && $result['redirect_url']) {
    // بوابات BNPL (Tabby/Tamara) — وجّه العميل لإكمال الدفع هناك.
    $this->redirect($result['redirect_url']);
    return;
}

if ($result['status'] === 'failed') {
    $this->addError('payment', __('فشلت عملية الدفع. حاول بوسيلة أخرى.'));
    return;
}

// pending بدون redirect_url — انتظر حدث ChargeUpdated (مثال 2).

لا تعيد استدعاء CreateCharge عند إعادة تحميل الصفحة أو فشل الشبكة — مرّر نفس idempotency_key دائماً؛ المنصة تُعيد الدفعة المخزَّنة نفسها بدل تكرار الدفع (لا إعادة محاولة تلقائية على الدفع).

مثال 2 — فتح الميزة عند اكتمال الدفع (ChargeUpdated)

دفعة بدأت pending (بوابة BNPL) تتحوّل لاحقاً إلى paid/failed من خارج طلب CreateCharge الأصلي — لا webhook يصلك بهذا (الاستهلاك in-process حصراً)؛ استمع للحدث داخل نفس العملية من boot() الخاص بـ ServiceProvider تطبيقك:

// Modules/SchoolPortal/app/Providers/SchoolPortalServiceProvider.php

namespace Modules\SchoolPortal\Providers;

use App\Events\PartnerPayments\ChargeUpdated;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\ServiceProvider;
use Modules\SchoolPortal\Services\Reports\GrantOrRevokePremiumReport;

class SchoolPortalServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Event::listen(function (ChargeUpdated $event): void {
            // فلترة إلزامية — المنصة تبثّ نفس الحدث لكل التطبيقات
            // المستمعة، وليس فقط تطبيقك.
            if ($event->consumerModuleSlug !== 'school-portal') {
                return;
            }

            if (($event->metadata['feature'] ?? null) !== 'premium_reports') {
                return;
            }

            $orderId = $event->metadata['order_id'] ?? null;

            match ($event->status) {
                'paid' => app(GrantOrRevokePremiumReport::class)->grant($orderId),
                'refunded', 'partially_refunded' => app(GrantOrRevokePremiumReport::class)->revoke($orderId),
                default => null, // failed — لا فعل إضافي، pending لا يصل هنا أبداً
            };
        });
    }
}

نقاط مهمة حول الحدث:

• يصلك فقط عند تغيّر الحالة فعلياً — لن يصلك على الإنشاء الأولي بحالة pending (هذه ليست "تحوّلاً")، بل على pending→paid|failed أو paid→refunded|partially_refunded لاحقاً. استرجاع فاشل لا يُطلق الحدث.
• اجعل المعالج idempotent — تحقّق من الحالة الحالية لديك قبل التفعيل/الإلغاء، تحسّباً لإعادة تشغيل أو تكرار نادر.
• عالج refunded/partially_refunded دائماً — الحدث قد يصلك لاحقاً لعملية سبق أن فتحت ميزة؛ أوقفها.
• الحقول المتاحة: chargeRef, tenantId, consumerModuleSlug, previousStatus, status, method, amount, currency, refundedAmount, metadata, occurredAt.

مثال 3 — التسوية والمطابقة (Reconciliation)

use App\Services\PartnerApi\Payments\ListCharges;

$page = app(ListCharges::class)([
    'status' => 'paid',
    'from' => '2026-07-01',
    'to' => '2026-07-31',
    'per_page' => 100,
]);

foreach ($page['data'] as $charge) {
    // $charge['charge_ref'] هو المعرّف العام الوحيد — لا id رقمي يُكشف أبداً
    // طابق $charge['metadata']['order_id'] بسجلك المحلي
}

$page['pagination']; // total / per_page / current_page / last_page

الاسترجاع (Refund)

use App\Services\PartnerApi\Payments\RefundCharge;

$result = app(RefundCharge::class)($chargeRef, ['amount' => null]); // null = استرجاع كامل

ضوابط RefundCharge:

• الدفعة يجب أن تكون ملك تطبيقك (أُنشئت بواسطته — غير ذلك تُعامَل كأنها غير موجودة).
• حالتها الحالية paid (لا استرجاع على pending/failed).
• amount ≤ المتبقي القابل للاسترجاع (amount − refunded_amount) — يحترم استرجاعات جزئية سابقة تلقائياً.
• لا إعادة محاولة تلقائية هنا أيضاً؛ استرجاع فاشل لا يُطلق ChargeUpdated.

واجهة الإعدادات (settings_ui) — اختيارية

مثل الإشعار: صرّح has_settings_page + livewire_component لعرض صفحة إعدادات المزوّد داخل لوحة tenant.

الـ overrides لكل إصدار

كل حقول الدفع (payment_methods, delivery, api.charge_endpoint, embedded.provider_class, capabilities, settings_ui) قابلة للتخصيص لكل إصدار من تبويب التكامل في صفحة الإصدار؛ الحقل الفارغ يرث من الـ module.

لوحة تحكم التطبيق (App Control Panel)

المطوّر يبني لوحة تحكم تطبيقه بنفسه داخل كود التطبيق؛ المنصة تملك ضوابط التصميم والوصول، وتفتحها من بوابة الشركاء عبر رابط موقَّع. لكل تطبيق لوحتان — واحدة لكل بيئة (الإنتاج والتجربة) — حسب الإصدار المنشور/المثبَّت فيها. بالإضافة لما تبنيه بنفسك، تضيف المنصة تلقائياً قسم «بيانات التطبيق» إلى chrome كل لوحة — مخزن key/value معزول لتطبيقك تديره بلا أي كود (راجع بيانات التطبيق (App Data) أدناه).

كيف تعمل

1. تُصرّح باللوحة في الـ manifest عبر كتلة developer_ui.
2. تظهر في بوابة الشركاء داخل تبويب التكامل بطاقتان: الإنتاج والتجربة. كل بطاقة تُفعَّل فقط عندما يكون هناك إصدار حيّ في تلك البيئة و اللوحة مُصرَّحة في الـ manifest.
3. زر «فتح اللوحة» يستدعي endpoint خفيف في okta-partners (GET /partner/modules/{slug}/dev-panel/{env}) يُصدر JWT قصير العمر (5 دقائق) ويعيد توجيهك إلى صفحة اللوحة على بيئة okta-web المستهدفة: <web base>/partner-dev/{slug}/panel?token=<jwt>.
4. الـ JWT موقَّع بـ HS256 بنفس السر المشترك للجسر الذي تستخدمه نداءات الجسر الصادرة لكل بيئة (production ⇒ outboundToken، sandbox ⇒ sandboxOutboundToken)، فلا يوجد سرّ جديد. الـ claims: { iss:"okta-partners", aud:"okta-web-devpanel", sub:<partner user id>, module:<slug>, env:"production"|"sandbox", iat, exp:iat+300, jti }.

كتلة الـ manifest

لأي نوع تكامل (embedded / payment / notification / external):

"developer_ui": {
  "has_developer_page": true,
  "livewire_component": "my-app-developer-panel"
}

• embedded / payment / notification ⇒ تعرّف livewire_component (اسم مكوّن Livewire يُعرَض داخل okta-web؛ الصيغة ^[a-z0-9][a-z0-9-]*(::|-)[a-z0-9-.]+$ — استخدم صيغة الشرطة مثل my-app-developer-panel؛ الصيغة بـ :: لا يحلّها Livewire 4).
• external ⇒ تعرّف url بدلاً منه (رابط HTTPS تستضيفه على بيئتك الخاصة — بيئاتك ملكك، فتظهر بطاقة واحدة تفتح الرابط مباشرةً في تبويب جديد):

"developer_ui": {
  "has_developer_page": true,
  "url": "https://partner.example/console"
}

الحقلان متنافيان (XOR): يُصدِّر الـ manifest الحقل المطابق لنوع التكامل فقط. الكتلة قابلة للتخصيص لكل إصدار من تبويب التكامل في صفحة الإصدار؛ القيمة الفارغة ترث من الـ module.

أقسام اللوحة (sections)

مَن يملك ماذا — هذا هو الأساس الذي يُبنى عليه كل ما تحته:

المنصة تثبّت الأقسام الأساسية في كل لوحة؛ وsections هي نصيبك: أقسام تخصّ تطبيقك تُعلَّق على تنقّل المنصة، كل قسم يعرض أحد مكوّنات Livewire لديك داخل الهيكل. المفتاح اختياري — غيابه يعني لوحة بقسم واحد، وهو السلوك نفسه الذي كان قبل وجوده.

"developer_ui": {
  "has_developer_page": true,
  "livewire_component": "my-app-developer-panel",
  "sections": [
    { "key": "trips", "label": "الرحلات", "label_en": "Trips",
      "icon": "map", "livewire_component": "my-app-trips" },
    { "key": "drivers", "label": "السائقون", "label_en": "Drivers",
      "icon": "users", "livewire_component": "my-app-drivers" }
  ]
}

• الحد الأقصى 10 أقسام، وترتيب المصفوفة هو ترتيب التنقّل.
• صيغة key هنا أضيق عمداً من التي يقبلها okta-web (^[a-z][a-z0-9_-]{0,39}$): okta-partners يُنتج الـ manifest وokta-web يستهلكه، فالمنتِج هو الطرف الأصرم. مفتاح نُجيزه هنا ويرفضه okta-web يعني نشراً يفشل بسبب بيانات أجزناها نحن.
• التطبيقات External لا تملك sections: هي تستضيف لوحتها كاملةً بنفسها، فلا يوجد هيكل من المنصة تُعلَّق عليه أقسام — والمفتاح يُسقَط كما يُسقَط livewire_component.
• لا تُشحن كتلة نصف صالحة: قسم ينقصه key أو label أو livewire_component (أو يخالف صيغتها) يُسقَط كاملاً — مدخل تنقّل لا يؤدي إلى شيء أسوأ من مدخل غائب. key مكرَّر يُبقي أول ظهور فقط، وأيقونة خارج القائمة تُسقَط بصمت (القسم يبقى بلا أيقونة — الزخرفة لا تُفشِل إعلاناً)، والقائمة تُقصّ عند 10.

سياسة تصميم اللوحة

اللوحة تعيش داخل هيكل تملكه المنصة، ومن هنا تأتي القواعد — كلها قابلة للتنفيذ حرفياً:

1. لا تبنِ ترويسة أو شريط تنقّل داخل القسم. الهيكل يوفّرهما أصلاً؛ أي ترويسة/تنقّل تضيفه يظهر مكرَّراً فوق ترويسة المنصة.
2. مكوّنات <x-…> فقط. لا <button> / <input> / <select> / <textarea> / <table> خام — الهوية البصرية تعيش داخل المكوّنات.
3. لا ألوان ثابتة من نوع gray / zinc / slate / indigo؛ استخدم tokens المنصة (neutral, primary, success, warning, danger).
4. لا max-w-*. الهيكل يفرض حدود العرض؛ إضافتها تكسر الشبكة وتقطع المحتوى الطويل.
5. اسم القسم من label/label_en لا من داخل الـ blade — المنصة هي التي ترسم العنوان في التنقّل.
6. أيقونتك من القائمة المسموحة فقط؛ لا تشحن SVG خاصاً بك في التنقّل.

القواعد 2–4 يفرضها فاحص التصميم UiScanner وبوّابة الـ CI على كل *.blade.php في مستودعك، فما يخالفها لا يصل الإنتاج أصلاً.

الضوابط

• التصميم: blade اللوحة يمرّ على نفس فاحص التصميم (UiScanner) وبوابة الـ CI مثل بقية صفحاتك — مكوّنات <x-…> وtokens المنصة فقط، لا HTML خام، لا ألوان gray/zinc/slate/indigo، لا max-w-*.
• الوصول: رابط موقَّع من المنصة فقط. سياق المطوّر بلا مستأجر — أنت تنظر إلى صحّة تطبيقك التجميعية عبر كل التثبيتات، لا إلى بيانات جهة بعينها. الواجهة المتاحة من مكوّن اللوحة الخاص بك هي namespace واحد فقط: App\Services\PartnerApi\DeveloperPanel\* — التجميعات للقراءة فقط (GetInstallsCount, ...) بالإضافة إلى CRUD بيانات التطبيق تحت DeveloperPanel\Settings\* (راجع القسم التالي).

مثال كامل

مكوّن Livewire (يُشحن جاهزاً في الـ boilerplate تحت app/DeveloperPanel/Panel.php.example):

namespace Modules\MyApp\app\DeveloperPanel;

use App\Services\PartnerApi\DeveloperPanel\GetInstallsCount;
use Livewire\Component;

class Panel extends Component
{
    // المُدخلان الوحيدان اللذان تمرّرهما المنصة — لا مُعرّف جهة أبداً.
    public string $moduleSlug = '';
    public string $environment = 'production';

    public function render(): \Illuminate\View\View
    {
        $installs = app(GetInstallsCount::class)($this->moduleSlug);

        return view('my-app::developer-panel.panel', [
            'installs' => $installs,
        ]);
    }
}

الـ blade يستخدم مكوّنات المنصة فقط:

<div class="space-y-6">
    <x-badge :color="$environment === 'production' ? 'success' : 'warning'" variant="soft">
        {{ $environment }}
    </x-badge>

    <x-card>
        <div class="p-4">
            <p class="text-3xl font-bold text-[var(--color-neutral-900)]">{{ $installs }}</p>
        </div>
    </x-card>
</div>

الإحصاءات المتاحة

سطح القراءة App\Services\PartnerApi\DeveloperPanel\* على okta-web يوفّر تجميعات عبر كل تثبيتات تطبيقك (لا بيانات جهة مفردة) — مثل عدد التثبيتات (GetInstallsCount)، التثبيتات النشطة، وعدّادات الأخطاء. أي عملية دفع تظهر في هذه التجميعات تُسمّى «دفعة».

بيانات التطبيق (App Data)

جدول key/value (JSON) مرتبط حصراً بتطبيقك — طريقة منخفضة الاحتكاك لتخزين إعدادات/أعلام تشغيلية تريد تعديلها بين الإصدارات دون نشر جديد.

• واجهة إدارة جاهزة بلا كود: قسم «بيانات التطبيق» يظهر تلقائياً داخل chrome اللوحة — كل تطبيق يحصل على CRUD كامل لمفاتيحه (إضافة/تعديل/حذف) من دون أي كود من جهتك.
• سطحان من الخدمات:
  1. من داخل مكوّن اللوحة الخاص بك (namespace مسموح ضمن سياق اللوحة فقط): App\Services\PartnerApi\DeveloperPanel\Settings\{ListSettings, PutSetting, DeleteSetting} — كل واحدة تأخذ moduleSlug تطبيقك.
  2. من كود تطبيقك المُشحَّن وقت التشغيل الفعلي عند الجهات (قراءة فقط، لا كتابة): App\Services\PartnerApi\AppSettings\{GetAppSetting, GetAppSettings} — نتيجة مكاشة ~60 ثانية.
• الحدود: 100 مفتاح كحد أقصى لكل تطبيق، قيمة كل مفتاح ≤ 64KB، صيغة المفتاح ^[a-z][a-z0-9_.-]{0,119}$.
• العزل: مضمون من الخادم بالكامل — سياق جلسة اللوحة يُشتق فقط من الـ JWT الموقَّع (iss=okta-partners, aud=okta-web-devpanel)؛ جلسة تطبيقك لا يمكن أبداً أن تلمس بيانات تطبيق آخر.
• النمط الموصى به: اضبط سلوك تطبيقك (أعلام الميزات، الحدود، معاملات المزوّد، نصوص العرض) من اللوحة بين الإصدارات — بدون إعادة نشر.

قراءة وقت التشغيل من كود تطبيقك (مثلاً داخل service تحت App\Services\PartnerApi\*):

use App\Services\PartnerApi\AppSettings\GetAppSetting;

$maxItems = app(GetAppSetting::class)('max_items_per_page', 20);

كتابة من عمل (action) داخل مكوّن اللوحة نفسه:

use App\Services\PartnerApi\DeveloperPanel\Settings\PutSetting;

public function saveMaxItems(): void
{
    app(PutSetting::class)($this->moduleSlug, 'max_items_per_page', (string) $this->maxItems);

    $this->dispatch('saved');
}

أدوات المتصفح (Browser Tools)

أداة المتصفح شيفرة تعمل داخل نظام تستخدمه المدرسة أصلاً — نظام نور مثلاً — لا داخل أوكتا. أنت تكتبها، وتُشحن داخل إصدار تطبيقك، وأوكتا تخدمها لإضافة «أدوات أوكتا» في متصفح المستخدم. صالحة لأي نوع تكامل: الأداة قدرةٌ يشحنها تطبيقك لا نوعاً من التطبيقات، فلا يشترطها integrationType ولا مفتاح آخر.

القاعدة الحاكمة: الإضافة وحدها تشغّل، وأوكتا تخدم

تغيّرت القاعدة عمّا كانت. كان الشريك يستضيف ملف .user.js وأوكتا تُدرج رابطه ليثبّته المستخدم في Tampermonkey أو أخواته. لم يعد ذلك مساراً مدعوماً:

• المستخدم لا ينزّل شيئاً ولا يحتاج مدير userscripts.
• إضافة «أدوات أوكتا» (متجر كروم) هي الطريق الوحيد لتشغيل أي أداة.
• أنت تكتب جسم الأداة في حقل script داخل الإصدار، وأوكتا تخدمه من نطاقها للإضافة وحدها.

ما تكسبه من ذلك ثلاثة أشياء لم تكن ممكنة قبله:

1. ما يعمل عند الجهة هو ما نُشر ورُوجع. لا يتبدّل تحت أقدامها بين مراجعتين.
2. تحديث الشيفرة يصل بلا إعادة تثبيت أي شيء. انشر إصداراً، فتلتقطه الإضافة.
3. لا حائط مصادقة يوقف التحديث صامتاً، ولا رابط شريك يتعطّل بعد سنة فتبقى الأداة ميتة بلا أن يلاحظ أحد. تلك كانت أشيع ثلاثة أعطال في المسار القديم، وكلها اختفت مع الاستضافة.

الشكل القديم ما زال مقبولاً: إصدارٌ منشور يحمل url ينتهي بـ.user.js بلا script لا يُرفض ولا يختفي — إسقاطه كان سيخفي أداةً تعمل اليوم عند جهات مثبِّتة. لكنه لا يُستعمل لعمل جديد، ولا يستفيد من أيٍّ من الثلاثة أعلاه.

delivery: webstore لم يتغيّر: إضافةٌ توزّعها من متجر كروم، والرابط هو المنتج كلّه.

الإعلان

من صفحة تطبيقك في البوّابة: تبويب التكامل ← قسم أدوات المتصفح ← «إضافة أداة». الحقول:

💡 بديل عن النموذج: أداة MCP set_browser_tools تكتب القائمة مباشرةً على إصدار قابل للتعديل (أو على التطبيق)، وget_browser_tools تقرؤها مع تجاوزات كل إصدار. القائمة المُمرَّرة تستبدل المخزَّن كاملاً، و[] تمسح التصريح — وعلى إصدار تعني إلغاء التجاوز فيعود يرث قائمة التطبيق.

والفرق الذي يهمّك: النموذج يُسقط الصفّ المعطوب بصمت (وهو الصواب لبنّاء يحمي الـmanifest)، أما الأداة فترفض بالاسم — مفتاح مكرَّر، match غائبة عن userscript، world مجهول، رابط .user.js مُعلَن webstore — لأن الصفّ الساقط لا يظهر إلا كأداة غائبة من كتالوج الجهة بعد النشر.

بحدّ أقصى 10 أدوات لكل تطبيق. والترتيب في القائمة هو ترتيب العرض عند الجهة — وهو التحكّم الوحيد لديك في أيّها تراه أولاً.

world: أخطر حقل في هذا القسم

عالَم التنفيذ اختيار وظيفي لا تفضيل، وأثره لا يظهر إلا وقت التشغيل عند المستخدم:

القاعدة العملية: إن كانت أداتك تنادي أي شيء تعرّفه الصفحة — $find في تطبيقات ASP.NET، أو jQuery، أو كائن التطبيق العميل — فهي تحتاج main. في isolated تجد تلك الدوالّ غير معرّفة، فتفشل بـis not a function بينما كل شيء آخر يبدو سليماً: الأداة مثبَّتة، والأزرار مرسومة، والصفحة تعمل. هذا بالضبط ما حدث مع أداة تصدير نور، وهو صنف الأعطال التي لا يشتكي منها المستخدم لأنه لا يعرف ما الذي كان يُفترض أن يحدث.

ابدأ بـisolated — إن كانت أداتك تقرأ الـDOM وتكتب فيه فقط فهي تكفيها وهي الأضيق صلاحيةً. ولا ترفع إلى main إلا لهذا السبب بعينه.

قيمة غير معروفة (page مثلاً) تُسقط الأداة كاملةً ولا تُخفَّض إلى isolated: التخفيض الصامت يشحن العطل نفسه الموصوف أعلاه.

التقاطعات التي تُسقط الصفّ

بوّابة الشركاء تفحصها وتمنعك من الحفظ، لكن اعرفها لأنها سبب أكثر الأخطاء شيوعاً:

1. delivery: userscript بلا script. الجسم يسافر داخل الإصدار، فأداةٌ بلا جسم ليست أداة. (الاستثناء الوحيد: الشكل القديم برابط .user.js.)
2. script وurl معاً على صفّ واحد. مصدرٌ واحد للحقيقة لكل أداة — وإلا لم يعد ممكناً معرفة أي جسم تشغّله الجهة.
3. delivery: webstore بجسم script. لا شيء يشغّله: إضافة المتجر هي المنتج، فالجسم هنا شيفرةٌ ميتة تُقرأ كأنها تعمل.
4. delivery: userscript بلا نمط match. هي الإفصاح الوحيد للجهة عن المواقع التي تلمسها أداتك، وهي ما تطلب الإضافةُ الإذنَ عليه.
5. delivery: webstore برابط ينتهي بـ.user.js. نوع تسليم مكتوب خطأً.

لماذا نمنعك بدل أن نقبل ونصحّح: BuildBrowserToolsBlock يُسقط أي صفّ لا يستطيع شحنه كاملاً. لو مرّرناه لحُفظ النموذج بنجاح، وخرج الـmanifest بأداةٍ أقل، ولاكتشفت ذلك من بلاغ جهة لم تظهر لها الأداة. فالرفض عند النموذج هو الفرق بين «البوّابة قالت إن أداتي ناقصة» و«أداتي اختفت بصمت».

أنماط match

بصيغة أنماط كروم: <scheme>://<host><path>.

https://noor.moe.gov.sa/*
https://*.moe.gov.sa/reports/*

ثلاث نقاط تُخطئ غالباً:

• * في المخطّط تعني http|https فقط — لا «أي مخطّط».
• *.example.com يشمل example.com نفسه لا نطاقاته الفرعية وحدها.
• المسار إلزامي: https://noor.moe.gov.sa بلا / نمطٌ غير صالح.

اجعلها أضيق ما يكفي. النمط الواسع يعني نافذة إذنٍ أوسع أمام المستخدم، وسببٌ إضافي لرفضه تشغيل أداتك.

الشكل في الـmanifest

{
  "browser_tools": [
    {
      "key": "noor-helper",
      "name": "مساعد نور",
      "name_en": "Noor Helper",
      "description": "يختصر إدخال الدرجات في نور.",
      "delivery": "userscript",
      "script": "(function () { 'use strict'; /* ... */ })();",
      "world": "main",
      "icon": "https://partner.example/tools/icon.png",
      "version": "1.2",
      "match": ["https://noor.moe.gov.sa/*"]
    }
  ]
}

ترويسة ==UserScript== غير مطلوبة — الإضافة لا تقرأها؛ الـmatch والـworld في الإعلان هما ما يحكم الحقن. اكتبها إن شئت للتوثيق فحسب.

التجاوز على مستوى الإصدار

القائمة مملوكة على مستوى التطبيق، ويرثها كل إصدار. ولإصدارٍ أن يحمل قائمته الخاصة من محرّر الإصدار (بطاقة «أدوات المتصفح» ← «تخصيص القائمة لهذا الإصدار»).

اعرف ما يترتّب على ذلك قبل أن تفعله:

• القائمة الخاصة تهزم قائمة التطبيق عند بناء الـmanifest. فأي أداة تضيفها لاحقاً على مستوى التطبيق لن تصل إلى ذلك الإصدار.
• القائمة الخاصة الفارغة ليست وراثة، بل إعلانٌ صريح بأن هذا الإصدار يشحن بلا أي أداة. استعملها حين تسحب أداةً في إصدار وتُبقيها في غيره.
• العودة: «العودة إلى قائمة التطبيق» في البطاقة نفسها تمحو التجاوز وتعيد الوراثة الديناميكية.

ولأن الجسم صار جزءاً من الإصدار، فالتجاوز هنا يعني أيضاً تجميد شيفرة الأداة على ذلك الإصدار.

تحديث أداة منشورة

عدّل script، وارفع version، وانشر. الإضافة تقارن الإصدار وتعيد جلب الجسم عند اختلافه، وتتخطّى ذلك تماماً حين لا يتغيّر شيء. لا يُطلَب من المستخدم إعادة تثبيت الإضافة ولا الأداة.

وتجميد الرقم يعني تجميد الأداة على نسختها القديمة عند كل من فعّلها، بلا عَرَض ظاهر لأحد — فارفعه مع كل تعديل مهما صغر.

ما لا تفعله الأداة

الأداة لا تصل إلى أوكتا في أي عالَم كانت: لا تحمل توكن التثبيت، ولا تقرأ نطاقاتك (scopes)، ولا تستدعي /api/apps/* بهوية تطبيقك. world: main يوسّع ما تراه من الصفحة المستهدفة لا ما تملكه من أوكتا. إن احتجت بيانات من أوكتا فذلك عمل تطبيقك نفسه لا أداته.

الـ Manifest

كل تطبيق يصدر manifest.json يصف قدراته:

{
  "moduleId": "warehouse",
  "displayName": "إدارة المستودعات",
  "version": "1.0.0",
  "category": "logistics",
  "integrationType": "embedded",
  "description": "...",
  "scopes": [
    { "key": "education.students.read",  "required": true,  "reason": "لعرض قوائم الطلاب" },
    { "key": "education.students.write", "required": false, "reason": "لتسجيل النتائج" }
  ]
}

لـ External يُضاف:

{
  "external": {
    "webhookUrl":    "https://your-app.example/okta/webhook",
    "webhookEvents": ["education.students.created"],
    "redirectUrls":  ["https://your-app.example/oauth/callback"]
  }
}

للتطبيقات المدمجة التي توسّع صفحة ملف الطالب يُضاف بلوك studentProfile (راجع توسيع ملف الطالب).

ولأي نوع تكامل يُضاف بلوك browser_tools حين يشحن التطبيق أدوات متصفح (راجع أدوات المتصفح).

وللتطبيق الذي يجوز للمجمّع تثبيته مُداراً في مدارسه، أو الذي يُثبَّت في مدارس المجمّع مع تثبيته، يُضاف بلوك hierarchy (راجع المجمّع يثبّت تطبيقك في مدارسه وتثبيت المجمّع يشمل مدارسه).

الـ manifest يُولَّد آلياً من بيانات النموذج في بوّابة الشركاء؛ لا تحتاج لكتابته يدوياً إلا في حالات متقدمة.

صلاحيات الأدوار داخل تطبيقك (rbac_permissions)

النطاقات تقول ما تسمح المنصّة لتطبيقك بقراءته. وهذه الكتلة تقول ما يسمح تطبيقك لموظّفي المدرسة بفعله داخله: مَن يرى صفحة الحضور، ومَن يعتمد الطلب، ومَن يصدّر التقرير. صلاحياتٌ تُنشأ في الجهة وتُمنح لأدوارها، ويحرسها كودك بـ can() — كأي صلاحية في المنصّة.

الشكل

{
  "moduleId": "okta-hdor",
  "rbac_permissions": {
    "tenant-admin": [
      "okta_hdor.attendance.view",
      "okta_hdor.attendance.update",
      "okta_hdor.reports.export"
    ],
    "teacher": [
      "okta_hdor.attendance.view",
      "okta_hdor.attendance.update"
    ]
  },
  "rbac_labels": {
    "feature": { "ar": "الحضور", "en": "Attendance" },
    "permissions": {
      "okta_hdor.attendance.view":   { "ar": "عرض الحضور",   "en": "View attendance" },
      "okta_hdor.attendance.update": { "ar": "تسجيل الحضور", "en": "Record attendance" },
      "okta_hdor.reports.export":    { "ar": "تصدير التقارير", "en": "Export reports" }
    }
  }
}

• المفتاح اسم دور عامّ في المنصّة (tenant-admin, teacher, …) — دورٌ لا تعرفه المنصّة يُتجاوَز بصمت عند التثبيت، فلا تخترع أدواراً.
• كل اسم <feature>.<resource>.<action>، والـ feature هو معرّف تطبيقك بصيغة snake_case: okta-hdor → okta_hdor. المنصّة تجمّع محرّر صلاحيات الجهة بالمقطع الأول وتُنشئ الاسم كما هو، فاسمٌ خارج مجموعتك (education.students.delete مثلاً) يقع داخل مجموعة المنصّة نفسها ويُظلّل مفرداتها — ولذلك يُرفَض بالاسم عند المزامنة ولا يصل النشر. أفعالٌ محدّدة (view, create, update, delete, export, approve) لا manage.
• rbac_labels هي ما تراه المدرسة. المنصّة تركّب أسماء الصلاحيات من ملفات لغتها هي، وتعرض المفتاح الخام لما لا تعرفه — ومواردك بحكم التعريف مجهولة لديها. بلا هذه الكتلة يرى مدير المدرسة مجموعة اسمها okta_hdor وداخلها okta_hdor.attendance.view. عنوان للمجموعة وعنوان لكل صلاحية، بالعربية والإنجليزية (٨٠ حرفاً كحدّ)، وعنوانٌ لاسم غير مُعلَن يُسقَط.
• حدّ الكتلة ١٠٠ صلاحية.

كيف تصل الإصدار

الكتلة تُقرأ من manifest.json على الفرع بزرّ «مزامنة من manifest» في محرّر الإصدار (أو أداة MCP sync_from_manifest)، وتظهر في بطاقة «صلاحيات الأدوار» قراءةً — مع كل بند رُفض وسببه. تستطيع أيضاً ضبطها مباشرةً بأداة set_rbac_permissions وقراءتها بـ get_rbac_permissions، لكن اجعل المستودع مصدر الحقيقة: الكود الذي ينادي can('okta_hdor.attendance.view') يعيش هناك، والاسمان يجب أن يتطابقا حرفاً بحرف.

ثم يمرّ الفاحص: validate_manifest يرفض الاسم خارج مجموعتك ويحذّرك من صلاحية بلا عنوان قبل أن تنشر.

متى تُنشأ في الجهة

عند التثبيت الأول وعند كل نشر — لا عند التثبيت وحده. حين تنشر إصداراً يعلن صلاحية جديدة، تُنشأ في كل جهة مثبِّتة وتُمنح لأدوارها المسمّاة عند وصول التحديث إليها؛ لا تنتظر المدرسة إعادة تثبيت.

ما تُعلنه لدور هو كل ما يحمله ذلك الدور منك

عند كل نشر تُسوّي المنصّة أدوارها العامّة مع بيانك: كل دور تُسمّيه في rbac_permissions يصير يحمل من صلاحياتك ما أعلنته له، ولا شيء غيره — فما أعلنه إصدار قديم لذلك الدور وتوقّفت عن إعلانه يُسحَب منه.

• الدور الذي لا تذكره لا يُمَسّ. الصمت ليس «اسحب كل شيء»: تطبيقٌ لم يذكر tenant-admin قطّ لم يدّعِ عنه شيئاً، ولو فُهم الصمت سحباً لأخذ الشاشات من مَن يدير المدرسة.
• ولإفراغ دور، سمِّه بقائمة فارغة: "administrator": []. هذه هي الجملة الوحيدة التي تقول «هذا الدور لا يحمل شيئاً من صلاحياتي»، وهي طريقك الوحيد لاسترجاع منحةٍ أعطاها إصدارٌ قديم.
• مجموعات المدرسة لا تُمَسّ أبداً («محاسبة»، «شؤون الموظفين»)، ولا الصلاحية المُعطاة لشخص بعينه. تلك قرار المدرسة لا قرارك.
• ولا شيء خارج مجموعتك: التسوية لا ترى إلا الأسماء التي تبدأ بـ <feature>. الخاص بك.

ولماذا هذا لازم: صفوف منح الأدوار العامّة بلا عمود جهة — الصفّ الواحد هو كل المدارس معاً. فتطبيقٌ أعلن ست عشرة صلاحية لـadministrator في إصدار قديم ثم توقّف عن إعلانها كان يترك كل إداري في كل مدرسة يحمل عرض كشوف الرواتب وتعديل ملفات الموظفين، بلا طريق للمطوّر يستردّها، وبلا شيء في المدرسة يقول من أين جاءت.

أما ما أنشأته المنصّة في الجهة فيبقى: الصلاحية تبقى موجودة في قائمة الجهة (فتستطيع المدرسة وضعها في مجموعة من مجموعاتها)، والذي يُسحَب هو منحها للدور العامّ. وسمِّ الصلاحية مرّةً واحدةً صحيحةً — إعادة التسمية تعني اسمين حيّين في كل مدرسة.

في الكود

// صفحة Livewire — الحارس في mount()، والقائمة تخفي الرابط بنفس الاسم:
protected ?string $permission = 'okta_hdor.attendance.view';

public function mount(): void
{
    abort_unless(auth()->user()?->can($this->permission), 403);
}

php artisan okta-hdor:make-page Attendance --permission=okta_hdor.attendance.view يولّد الحارس ومدخل القائمة معاً. إخفاء الرابط ليس تحكّماً في الوصول؛ الصفحة هي التي تُحرَس.

ما ليس هنا: لا نطاق يُطلب من الجهة ولا موافقة — هذه صلاحيات داخل تطبيقك على بيانات تطبيقك، والمدرسة تملك توزيعها على أدوارها من إعدادات الأدوار كما تفعل مع أي ميزة في المنصّة.

الـ API

يتوفّر مرجع API تفاعلي عام بكامل نقاط النهاية والنطاقات وأمثلة cURL على صفحة مرجع الـ API — مناسب للمشاركة المباشرة.

URL الأساسي

https://getokta.io/api/apps

المصادقة

كل طلب يحمل Authorization: Bearer <installation_token>.

نقاط النهاية الجاهزة

كل نقطة قراءة لبيانات الجهة (education/*، employees/directory، tool-keys/*، reports/*) تقبل ?entities=<ulid>,<ulid> أو ?entity=<ulid> لتقرأ الجهات التابعة من المجمّع — لشخص يحمل tenants.children.view_members، لا لتوكن التثبيت. التفاصيل في فصل «الشركات والمجمّعات: شجرة الجهة وبيانات مدارسها».

القائمة الكاملة دائماً في https://partners.getokta.io/docs/openapi.json (مواصفة OpenAPI 3.1 محدّثة آلياً). ويُمكنك استيراد Postman collection جاهزة.

Pagination

كل قائمة ترجع:

{
  "data": [ ... ],
  "total": 1242,
  "per_page": 20,
  "current_page": 1,
  "last_page": 63
}

استخدم ?page=2&per_page=50 (الحد الأقصى 100 لكل صفحة).

Idempotency

عمليات الكتابة تقبل header اختياري:

Idempotency-Key: <uuid>

نفس المفتاح خلال 24 ساعة يعيد نفس الإجابة المخزّنة، حتى لو تم استدعاؤه عشرات المرات. هذا يضمن أنه لو حصل timeout على جانبك، إعادة المحاولة لن تُنشئ سجلاً مكرراً.

الـ Webhooks

الصيغة

كل webhook هو HTTP POST بجسم JSON:

{
  "id":         "550e8400-e29b-41d4-a716-446655440000",
  "event":      "education.students.created",
  "tenant_id":  42,
  "created_at": "2026-04-26T10:30:15+03:00",
  "data": {
    "student": { "id": 123, "full_name": "...", ... }
  }
}

Headers

التحقق من التوقيع

$expected = hash_hmac(
    'sha256',
    $request->header('X-Okta-Timestamp') . '.' . $request->getContent(),
    $YOUR_WEBHOOK_SECRET,
);

if (! hash_equals($expected, $request->header('X-Okta-Signature'))) {
    return response('invalid signature', 401);
}

حماية من Replay

افحص أن X-Okta-Timestamp ضمن آخر 5 دقائق، وخزّن X-Okta-Delivery-Id لمدة 15 دقيقة على الأقل لرفض إعادة الإرسال.

إعادة المحاولة

أوكتا يعيد المحاولة مع backoff: 30s → 2m → 10m → 1h → 6h. بعد 6 محاولات بدون 2xx، يُعتبر التسليم فاشلاً نهائياً ويُسجَّل في صفحة "تسليمات Webhook" في لوحة الشريك.

مهم: ردّك يجب أن يكون 2xx خلال 10 ثوانٍ. لو احتجت معالجة طويلة، اقبل الـ webhook بـ 202 Accepted فوراً وعالج خلفياً.

كتالوج الإشعارات

يصرّح كل تطبيق شريك بـكتالوج الإشعارات الخاص به — قائمة الأحداث التي يستطيع التطبيق إرسالها للمستخدمين، وكل حدث له مفتاح ثابت ودلالات ومتغيّرات وقنوات تسليم افتراضية. الكتالوج يُعرَّف من بوّابة الشركاء ثم يُنتقَل إلى okta-web عند النشر، فيظهر للمستأجرين على صفحة /settings/notifications ليُفعّلوا ما يريدون لكل تثبيت ويختاروا قنوات التسليم.

التمييز عن نوع التكامل: قسم تطبيقات الإشعار (Notification) أعلاه يخص نوع التكامل الذي يكون فيه التطبيق مزوِّد قناة تسليم (واتساب/SMS/Push). الكتالوج هنا مختلف: متاح لـأي نوع تطبيق (Embedded/External/Notification) ليُصرّح بقائمة الأحداث التي يُرسلها هو، بصرف النظر عن القنوات.

الفلسفة: Declare-first

لا يستطيع تطبيقك إرسال إشعار من الكود قبل تصريحه في الكتالوج. هذه ليست توصية — هي قاعدة مفروضة عبر:

1. NotificationScanner في الـCI: يفحص الكود ويُسقط أي DispatchNotification('<key>', ...) حيث <key> غير مُصرَّح في manifest.json["notifications"]. الـPR يفشل.
2. بوّابة وقت التشغيل في okta-web: مفتاحٌ لم يُصرَّح في الكتالوج المُستورَد يُرفَض بالاسم — استثناء تحقّق من DispatchNotification داخل المودول، و422 بجسم {errors: {key: [...]}} على POST /api/apps/notifications/dispatch. ومفتاحٌ مُصرَّح لكن الجهة لم تضبطه بعد (تثبيتٌ سبق الإصدار الذي أضافه) يُبذَر لها مُعطَّلاً وتُسجَّل المحاولة skipped_disabled في سجلّ التسليم. لا شيء يُسقَط بصمت.

السبب وراء الصرامة: المستأجر يحتاج يعرف مقدّماً كل إشعار ممكن يصله من تطبيقك ليُقرّر:

• هل يفعّله أصلاً؟
• على أي قناة (email/SMS/WhatsApp/push/in-app/webhook)؟
• لمن (admin فقط؟ كل المستخدمين؟ مجموعة محددة؟)

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

دورة الحياة

Draft version  →  Edit catalog freely  →  Submit  →  Approved  →  Published
       │                                                              │
       │                                                              ▼
       │                                                       Catalog frozen
       │                                                       Shipped to okta-web
       │                                                       Tenants can install
       │
       └──── Create new version ──→ Catalog cloned forward ──→ Edit freely ──→ ...

النقاط المهمة:

• الكتالوج مربوط بإصدار، ليس بالـmodule. الإصدار v1.0.0 له كتالوج، و v1.1.0 له كتالوجه الخاص.
• النسخ التلقائي عند إنشاء إصدار جديد: عند إنشاء v1.1.0 من v1.0.0 المنشور، كل الإشعارات تُنسخ تلقائياً إلى الإصدار الجديد كنقطة بداية، وتقدر تعدّلها/تحذفها/تضيف عليها بحرية. (التنفيذ: App\Services\PartnerModules\Notifications\CloneNotificationsToNewVersion)
• التجميد عند النشر: ما إن يُنشَر الإصدار، كتالوجه يُصبح read-only. لتغيير أي شيء، أنشئ إصداراً جديداً.
• المزامنة المستمرة مع GitHub: كل تعديل من تبويب الإشعارات يُحدِّث manifest.json["notifications"] على فرع الإصدار في الـrepo تلقائياً. هذا يخلي الـmanifest على disk دائماً مطابق لـDB.

تشريح إدخال إشعار

كل سجل إشعار يحتوي:

كيف يعيش قالبك عند الجهات

• صندوق «تخصيص الرسالة» في إعدادات الجهة يفتح على نصك الافتراضي جاهزاً للتعديل — لا على فراغ.
• جهة أبقت نصك دون تعديل تبقى وارثة له: حسّنت الصياغة في إصدار لاحق؟ تصل تلقائياً لكل جهة لم تخصّص. أما من عدّلت فنصها ثابت حتى تعيد ضبطه (إفراغ الصندوق والحفظ يعيد الوراثة).
• زر «إرسال تجريبي» عند الجهة يصيّر قالبك بقيم وهمية بحسب نوع كل متغيّر: الأرقام أرقاماً حقيقية، التواريخ تاريخ اليوم، والنصوص بشكل «اسم_المتغير» — فاجعل قالبك يُقرأ جيداً حتى بهذه العيّنات، فهي أول انطباع للجهة عن رسالتك.
• إن كان مزوّد القناة عند الجهة مقيَّداً بقوالب معتمدة (رقم واتساب رسمي)، فقد تختار الجهة في الصندوق نفسه قالباً من قوالب المزوّد لهذا الإشعار. لا شيء عليك فعله: المزوّد يستلم مفتاح إشعارك ومتغيّراتك (metadata.notification_key + variables) ويملأ القالب منها — فاجعل متغيّراتك المُعلَنة هي ما يحتاجه نصّ الرسالة فعلاً، لا ما يسهل حسابه.

كيف تُصرّح

من بوّابة الشركاء: التطبيقات ← اختر تطبيقك ← تبويب "الإشعارات".

الـURL المباشر: /dashboard/modules/<your-slug>?tab=notifications.

• اختر الإصدار (يُختار آخر draft تلقائياً).
• إضافة إشعار ← اكتب المفتاح (البادئة <slug>. مضافة تلقائياً)، املأ display name (ar/en)، اختياري description، أضف المتغيّرات، اكتب نص الرسالة الافتراضي بمتغيّراته، حدّد موجَّهة إلى، حدّد القنوات، اختر severity، اضغط حفظ.
• لتعديل: انقر "تعديل" بجانب الصف.
• لحذف: انقر "حذف". لو الإصدار منشور والمفتاح مستخدَم في تثبيتات نشطة، الحذف يُرفَض (استخدم toggle is_active بدلاً).

الإرسال من الكود

نداءٌ واحد بوسيطين — المفتاح والحمولة — ولا شيء غيرهما: لا وسيط ثالث، ولا قناة داخل الحمولة، ولا helper.

use App\Services\PartnerApi\Notifications\DispatchNotification;

app(DispatchNotification::class)('hr-pro.leave_request.approved', [
    'recipient' => ['type' => 'host_user', 'id' => $employee->user_ulid],
    'variables' => [
        'employee_name' => $employee->name,
        'leave_days'    => 5,
        'start_date'    => '2026-04-26',
    ],
    'url' => route('hr-pro.leaves.show', $leave),   // اختياري
]);

النداء نفسه لتطبيق External عبر HTTP: POST /api/apps/notifications/dispatch بجسم {key, payload} خلف نطاق notifications.dispatch.send، والجواب 202 مع delivery_ids (صفّ تسليم لكل قناة). التفاصيل في مرجع الـAPI.

شكل الحمولة — هذه المفاتيح محجوزة، وكل مفتاح آخر على المستوى الأعلى يُنقَل تلقائياً تحت variables:

القاعدة التي كلّفت أكثر من غيرها: مفتاحٌ مثل student_id أو user_id بجانب المتغيّرات متغيّرُ قالب لا عنوان. حمولةٌ تعتمد عليه تصل بلا مستلم، فتسقط إلى مستلمي الجهة المضبوطين على صفّ الإشعار (إداريو المدرسة افتراضاً) — فيصل إلى المكتب ما كان لوليّ الأمر، أو يُكتب في سجلّ التسليم failed: No … recipients حين لا مستلم مضبوطاً. لذلك كل مفتاح audience فيه guardian أو student يحمل recipient دائماً؛ وحده الإشعار الإداري (audience: admin — إقفال يوم، تقرير أسبوعي) يجوز أن يُرسَل بلا عنوان ليصل من ضبطتهم الجهة. والفاحص ينبّه — بلا رسوب — حين يرى حمولةً حرفية بلا recipient لمفتاحٍ كهذا (notification-recipient-missing).

النصّ الذي يقرؤه الإنسان تختاره المنصة بهذا الترتيب: نصّ الجهة المخصَّص ← default_template الذي كتبتَه ← body في الحمولة ← نصّ بديل من اسم الإشعار. فاعتنِ بـdefault_template، لا بـbody.

ومتى يصل push فعلاً: حين تكون push مُفعَّلة على صفّ الجهة، وللمنصة حساب FCM مضبوط، وللمستلم جهاز مسجَّل من okta-app. غياب أيٍّ منها لا يرمي — يُكتب skipped_no_transport أو failed بنصّ السبب على صفّ التسليم (راجع «تجربة محلياً» أدناه).

ولا يوجد partner_notify() على المنصة. نسخةٌ أقدم من هذا الدليل ذكرته؛ النداء يفشل وقت التشغيل ما لم يعرّفه مودولك بنفسه، والفاحص ينبّه عليه (notification-helper-undefined).

الإشعار الذي يُفعَل عليه: recipient وurl

الـpayload ليس متغيّرات القالب وحدها. مفتاحان محجوزان فيه يقرؤهما okta-web قبل أن يصل شيء إلى القالب، وهما الفرق بين إشعار يُقرأ وإشعار يُتصرَّف بناءً عليه:

recipient — العنوان الفعلي

partner_notify('leaves.request.submitted', [
    'student_name' => $student->name,
    'recipient' => ['type' => 'parent_of_student', 'id' => $student->ulid],
]);

الأنواع التي تُحَل:

• parent_of_student + id = ULID الطالب → أولياء أمره الساريون في هذه الجهة (رابط غير مسحوب، وليّ أمر غير مُفرَج عنه). هذا هو العنوان الذي تحتاجه أغلب إشعارات المدرسة، ولاحظ أنه ULID الطالب لا وليّ الأمر: تطبيقك يعرف الطالب، والمنصّة تعرف من يخصّه.
• host_user + id = ULID المستخدم → ذلك المستخدم وحده.
• school_admin (بلا id) → إداريو الجهة.

بغير recipient — أو بنوع لا تعرفه المنصّة — يعود التوجيه إلى ما ضبطته الجهة في /settings/notifications (أدوار + مستخدمون بأعيانهم). هذا سلوك سليم للبثّ («تم نشر جدول الاختبارات»)، وخطأ صامت للحدث الشخصي: «ابنك طلب الخروج مبكراً» تصل حينها لقائمة الجهة كلها ولا تصل الأب.

audience في الكتالوج ليست توجيهاً. هي إعلان تقرؤه الجهة قبل أن تفعّل الإشعار («موجَّهة إلى وليّ الأمر»). التوجيه يحصل هنا، في كل نداء على حدة.

url — ما يفتحه القارئ

بطاقة الإشعار — في مركز الإشعارات وفي بطاقة الصفحة الأولى ببوّابة وليّ الأمر — تصير رابطاً حين يحمل الـpayload مفتاح url، وتبقى بطاقة صمّاء بدونه:

partner_notify('leaves.request.submitted', [
    'student_name' => $student->name,
    'recipient' => ['type' => 'parent_of_student', 'id' => $student->ulid],
    'subject'   => 'طلب استئذان بانتظار موافقتك',
    'body'      => "{$student->name} طلب الخروج الساعة ١١:٣٠",
    'url'       => route('leaves.requests.show', $request),   // ← الفعل
]);

اجعله رابط الشاشة التي تُنجَز عليها العملية لا صفحة تطبيقك الرئيسية: وليّ الأمر الذي يصله «طلب بانتظار موافقتك» ثم يُلقى على لوحة التطبيق عليه أن يبحث عن ابنه ثم عن الطلب — وهي الرحلة نفسها التي جاء الإشعار ليُلغيها. الرابط النسبي (/apps/leaves/requests/42) كافٍ ومُفضَّل.

نصّ البطاقة

العنوان يأتي من الكتالوج (display_name_ar/display_name_en بحسب لغة القارئ) لا من الـpayload — ولهذا الاسم العربي إجباري. أما الجسد فيُقرأ من payload.body ثم payload.subject، ويسقط إلى وصف الكتالوج حين لا يرسل التطبيق شيئاً. أرسِل body مكتوباً للقارئ: وصف الكتالوج عام بطبيعته («يُرسَل عند تقديم طلب استئذان») ولا يذكر أيّ ابن ولا أيّ ساعة.

شرطان قبل أن تظهر البطاقة أصلاً

1. in_app مُعلَنة في default_channels لهذا المفتاح — الجهة تستطيع تضييق قنواتك لا توسيعها.
2. الجهة لم تُطفئ القناة أو الإشعار من /settings/notifications.

فحص ما حدث فعلاً: mcp__okta__delivery_stats وwebhook_deliveries تقرآن صفوف التسليم، وصفّ skipped_disabled يعني أن الجهة أطفأته — لا أن نداءك فشل.

السكانر — ما يفعله

scripts/partner-policy/NotificationScanner.php في الـboilerplate يفحص كل ملف PHP تحت Modules/<Namespace>/ و:

1. يجمع كل المفاتيح الـ"مُستخدَمة" من نداءات الإرسال:
   • app(DispatchNotification::class)('key', ...)
   • app(\App\Services\PartnerApi\Notifications\DispatchNotification::class)('key', ...)
   • partner_notify('key', ...) — يُلتقط كي يُحسَب مفتاحه، مع تنبيه أن الدالة ليست على المنصة (notification-helper-undefined).
2. يجمع كل المفاتيح الـ"مُصرَّح بها" وaudience كلٍّ منها من manifest.json["notifications"].
3. يقارن:
   • مفتاح مستخدَم لكن غير مُصرَّح → violation (يكسر CI، رفض الـPR).
   • مفتاح مُصرَّح لكن غير مستخدَم → warning (غير قاطع، لكن يظهر في الـlog ليُذكِّرك بالتنظيف).
   • مفتاح جمهوره guardian/student يُرسَل بحمولة حرفية بلا recipient → warning (notification-recipient-missing) — لا يُرسِب، لكنه يسمّي الحمولة التي ستصل بلا مستلم قبل أن تكتشفها مدرسة.

تشغيل محلياً:

php scripts/partner-policy/check.php Modules/

الـoutput format يدعم --format=github للـannotations في PR.

عقد الـManifest

عند build الإصدار، يُولَّد block جديد في manifest.json:

{
  "notifications": [
    {
      "key": "hr-pro.leave_request.approved",
      "display_name": {
        "ar": "تمت الموافقة على طلب الإجازة",
        "en": "Leave request approved"
      },
      "description": {
        "ar": "يُرسَل تلقائياً للموظف عند موافقة مديره.",
        "en": "Sent automatically when the manager approves a leave request."
      },
      "variables": {
        "employee_name": "string",
        "leave_days": "int",
        "start_date": "string"
      },
      "default_channels": ["email", "in_app"],
      "severity": "info",
      "is_active": true
    }
  ]
}

okta-web's SyncCatalogFromManifest يقرأ هذا الـblock عند النشر ويُدخل/يحدّث الصفوف في جدول الإشعارات على جانبه. التطبيق يصير ظاهراً للمستأجرين فوراً.

لا تحرر هذا الـblock يدوياً في الكود. التبويب على البوّابة يكتبه تلقائياً. أي تعديل يدوي يُكتسَح في المزامنة التالية.

من يتحكم بأي قناة

┌─────────────────┬──────────────────────────────────────┐
│ الشريك يصرّح    │ القنوات الممكنة (مثل: email, in_app)  │
│ (default_channels) │ ⇣                                  │
├─────────────────┼──────────────────────────────────────┤
│ المستأجر يفعّل  │ subset من القنوات الممكنة            │
│ (per install)   │ + يختار المستلمين                    │
│                 │ + يكتب قالب الرسالة (اختياري)        │
└─────────────────┴──────────────────────────────────────┘

النتيجة: تطبيقك يقول dispatch(key, payload) بدون قلق حول قناة التسليم. okta-web يتولّى الـfan-out كاملاً:

• يقرأ إعدادات المستأجر لهذا التثبيت لهذا المفتاح
• يحوّل الـpayload إلى قالب الرسالة المعدّ
• يرسل عبر كل قناة مفعّلة (email عبر Mailable، SMS عبر provider، WhatsApp عبر template API، push عبر Web Push/FCM، in_app يكتب في جدول notifications، webhook_out يرسل HMAC-signed POST لمستقبِل خارجي)

تطبيقك لا يكتب أي transport class مخصّص. هذا جوهر النموذج.

مثال كامل: تطبيق HR

1. صرّح الإشعارات في البوّابة

2. ادفع الفرع — الفاحص يمرّ بتنبيهات فقط: المفاتيح مُصرَّحة ولم تُستعمل بعد (notification-key-unused).

3. أضف الـdispatch في الكود

// Modules/HrPro/app/Services/LeaveRequests/ApproveLeaveRequest.php

namespace Modules\HrPro\Services\LeaveRequests;

use App\Services\PartnerApi\Notifications\DispatchNotification;
use Modules\HrPro\Models\LeaveRequest;

final class ApproveLeaveRequest
{
    public function __construct(
        private readonly DispatchNotification $notify,
    ) {}

    public function __invoke(LeaveRequest $request, int $approverId): LeaveRequest
    {
        $request->update([
            'status' => 'approved',
            'approved_by' => $approverId,
            'approved_at' => now(),
        ]);

        ($this->notify)('hr-pro.leave_request.approved', [
            'recipient' => ['type' => 'host_user', 'id' => $request->employee_user_ulid],
            'variables' => [
                'employee_name' => $request->employee_name,
                'leave_days' => $request->days_count,
                'start_date' => $request->starts_at->toDateString(),
            ],
        ]);

        return $request->fresh();
    }
}

4. ادفع — السكانر يمر:

Partner policy scan: clean. No violations found.

5. قدّم الإصدار، اقبله، انشره. المستأجر الآن يرى الإشعارات

في /settings/notifications ويستطيع تفعيلها.

نصائح وممارسات

• سَمِّ المفاتيح حسب الـdomain، ليس التقنية. hr-pro.leave_request.approved × hr-pro.email.sent.
• لا تجعل مفاتيحك عامة جداً. school-portal.exam.grade_published × school-portal.notification.new.
• default_channels سقفٌ لا افتراض: الجهة تُضيّقه ولا توسّعه، فقناةٌ لم تُعلنها لا تستطيع أي مدرسة تفعيلها أبداً. أعلن كل قناة يصلح لها الإشعار (in_app وpush لما يخصّ وليّ الأمر في التطبيق، وwhatsapp/sms لما يستحقّ رسالة مدفوعة) — الصفّ يُبذَر للجهة معطَّلاً على كل حال، والقناة المدفوعة قرارها ومزوّدها هي.
• استخدم severity بحرص. critical يكسر سياسات الـquiet hours على بعض القنوات (push يبقى يطرق حتى في الليل). احفظها للأحداث المهمة فعلاً.
• خزّن متغيّرات قليلة وذات معنى. لا تُرسِل كل الـmodel كـpayload — فقط ما يحتاجه قالب الرسالة. الحمولة المنتفخة تكلّف في الـbatch notifications.
• استخدم is_active=false بدل الحذف على إصدار منشور. الحذف يُرفَض لو هناك تثبيتات نشطة؛ التطفيش حلّ آمن.

الأخطاء الشائعة وحلولها

تجربة محلياً

الإرسال يحتاج سياق تثبيت لا جلسة tinker: DispatchNotification يقرأ الجهة والتثبيت من ModuleContext الذي يبنيه وسيط module.context على مسارات مودولك، ويرفض خارجه بـ«outside a partner-app context». فجرّب من داخل التطبيق على السندبوكس بأحد طريقين:

• من شاشة مودولك (مسار خلف module.context)، أو من مهمّة طابور/نقطة جوال تبني السياق بنفسها عبر BootModuleContext — بلفّ العمل داخله لا بندائه ثم العمل بعده.
• أو بطلب HTTP بتوكن التثبيت (External، أو أي تطبيق من الطرفية):

curl -X POST "<sandbox base url>/api/apps/notifications/dispatch" \
  -H "Authorization: Bearer <installation token>" \
  -H "Content-Type: application/json" \
  -d '{"key":"hr-pro.leave_request.approved","payload":{"recipient":{"type":"host_user","id":"<user ulid>"},"variables":{"employee_name":"سارة","leave_days":3}}}'

ثم اقرأ ما جرى — ثلاثة أماكن تعرض صفّ التسليم نفسه بحالته ونصّ خطئه:

• صفحة الجهة /settings/notifications ← بطاقة «سجلّ التسليم» أسفل الجدول (آخر الأيام: كل محاولة بقناتها وحالتها والخطأ الذي تركته مهمّة القناة). وفي الصفحة نفسها زرّ «إرسال تجريبي» لكل مفتاح يصيّر قالبك بقيم وهمية ويُرسله فعلاً إلى مستلمٍ يختاره المشغّل — أسرع طريقة لتعرف أن FCM مضبوط وأن الجهاز مسجَّل.
• من تطبيقك: GET /api/apps/notifications/logs (نطاق notifications.logs.read) بمرشّحات channel / status / key / from / to.
• من مساعدك: أداة MCP notification_deliveries {slug} — إجماليات بحسب الحالة والقناة والمفتاح عبر كل المدارس التي ثبّتت تطبيقك، ثم آخر الإخفاقات بنصّها.

الحالات التي ستراها: sent / queued وصل أو في الطابور؛ failed بنصّ السبب — وNo … recipients تحديداً يعني حمولة بلا recipient؛ skipped_disabled المدرسة لم تفعّل المفتاح بعد؛ skipped_quiet ساعات الهدوء؛ skipped_no_transport قناة بلا ناقل على المنصة (push بلا FCM)؛ skipped_plan_feature باقة الجهة لا تشمل إشعارات التطبيقات.

الوصول بين التطبيقات (تطبيقك يحتاج بيانات تطبيق آخر)

تطبيق الجدول يحتاج يعرف مين غاب اليوم. بيانات الحضور تعيش في قاعدة بيانات تطبيق الحضور — مخطّط منفصل لا يصل إليه غيره. فالسؤال ليس «كيف أقرأ الجدول الفلاني»، بل «كيف أطلب من مطوّر تطبيق الحضور أن يفتح لي جزءاً محدَّداً من بياناته».

الجواب موافقتان لا واحدة:

الثانية موجودة في okta-web أصلاً. الأولى هي ما نتحدّث عنه هنا، ولا يمكن تخطّيها: إعلان وصول بلا موافقة مطوّر لا يُنشَر.

1. إن كنت صاحب البيانات: أعلِن ما تشاركه

لا أحد يستطيع أن يطلب منك شيئاً لم تعلنه. في محرّر التطبيق (أو الإصدار) → «الوصول بين التطبيقات» → «ما يشاركه هذا التطبيق»:

"provides": [
  {
    "resource": "records",
    "access": "read",
    "label": "سجلّات الحضور اليومية",
    "label_en": "Daily attendance records",
    "description": "حضور الطالب وغيابه وتأخّره، بالتاريخ والحصّة.",
    "reader": "Modules\\Attendance\\Services\\PartnerApi\\RecordsReader"
  }
]

• resource — حروف صغيرة و_ فقط، حتى ٤٠ حرفاً. هذا هو المفتاح الذي تُخزَّن به موافقة الجهة في okta-web، فتغييره لاحقاً يفصل كل موافقة قائمة عن معناها.
• access — read أو write. ليستا درجتين على سلّم: عرض read لا يعني أنك عرضت write، والعكس. إن أردت الاثنين فأعلن صفّين.
• label وdescription — تكتبهما للمدرسة لا للمبرمج. هذا النص نفسه هو ما يظهر على شاشة الموافقة في المتجر. «سجلّات الحضور اليومية» تُقرَأ ويُقرَّر بناءً عليها؛ att_rec_v2 لا.
• reader — الحقل الذي يجعل العرض يُثمِر شيئاً. بقيّة الحقول أوراق موافقة: تُثبِت أن الرابط يجوز. هذا الصنف هو ما تشغّله المنصّة فعلاً لتُنتِج الصفوف. بدونه تستطيع المدرسة أن توافق على السطر، ثم لا يُرجِع شيئاً. مطلوب أن يكون تحت Modules\ في كودك أنت، وأن ينفّذ الواجهة — انظر القسم التالي.
• writer — نظير reader على عرض access: write: الصنف الذي يقبل ما يرسله التطبيق الآخر ويتحقّق منه ويخزّنه بقواعدك. عرض كتابة بلا كاتب موافقةٌ تُمنَح ولا تُخزِّن شيئاً. انظر «الكتابة في بيانات تطبيق آخر» أدناه.

اكتب القارئ

namespace Modules\Attendance\Services\PartnerApi;

use App\Services\PartnerApi\Contracts\CrossAppReader;
use Modules\Attendance\Models\AttendanceRecord;

final class RecordsReader implements CrossAppReader
{
    public function read(string $resource, array $filters, string $consumerSlug): array
    {
        return AttendanceRecord::query()
            ->when($filters['from'] ?? null, fn ($q, $d) => $q->whereDate('date', '>=', $d))
            ->limit(200)
            ->get()
            ->map(fn ($r) => [
                'student_ulid' => $r->student->ulid,
                'date' => $r->date->toDateString(),
                'status' => $r->status,
            ])
            ->all();
    }
}

ثلاث قواعد لا تتفاوض:

• لا تفحص الصلاحية هنا. المنصّة لا تستدعي صنفك إلا بعد أن تكون قد أثبتت الثلاثة: أن مطوّر التطبيق الطالب مُنِح هذا الزوج، وأن هذه الجهة بالذات وافقت عليه، وأن المُنادي هو $consumerSlug (مأخوذاً من سياق التشغيل لا من شيء أرسله المُنادي). فحصك الثاني يضيف تعقيداً لا أماناً.
• $filters مدخلات غير موثوقة. تأتي من تطبيق آخر. تحقّق منها كما تتحقّق من $request، وضَع سقفاً للعدد.
• أرجِع قيماً صِرفة، وULIDs لا معرّفات رقمية. المُنادي قاعدة كود أخرى قد تكون منشورة بإصدار مختلف؛ تمرير نموذج Eloquent يربط مخطّطَي المنتجين معاً فيصير أيّ تغيير اسم عمود لاحقاً كسراً لتطبيق شريك آخر.

يعمل الصنف داخل سياقك أنت: مخطّطك، وصلاحياتك المعتمَدة، والجهة الحاليّة. فاحصر استعلامك بالجهة الحاليّة كما تفعل في صفحاتك تماماً.

المدمجة فقط. القارئ صنف PHP يعيش في كود تشحنه داخل okta-web. التطبيقات الخارجية تُعلِن provides وتظهر على شاشة الموافقة، لكن لا قناة قراءة لها بعد.

لا يظهر إلا المنشور. التطبيقات الأخرى ترى provides من آخر إصدار منشور لك فقط. ما دام في مسوّدة فهو غير موجود بالنسبة لهم — ومقصود: الرابط التزام بين منتجين يعملان، وبناؤه على مسوّدة يعني أن ما تعتمد عليه قد يتغيّر أو يختفي قبل أن يراه أحد خارج فريقك.

وثّق ما تشاركه

label وdescription جملتان للمدرسة. المطوّر الذي يبني على عرضك يحتاج ما لا يتّسع له البيان: شكل الصفوف التي يُرجعها القارئ، والمرشِّحات التي يفهمها، والحمولة التي يقبلها الكاتب وما يُرجعه، ومثال نداء. لهذا وثائق البيانات المشتركة: صفحة Markdown لكل تطبيق، تكتبها من محرّر التطبيق («وثّق ما تشاركه» في بطاقة «ما يشاركه هذا التطبيق») أو من مساعد MCP:

set_shared_docs {
  "slug": "attendance",
  "body": "## records (read)\n\nكل صفّ: `student_ulid`, `date` (YYYY-MM-DD), `status` (present|absent|late).\n\nالمرشِّحات: `from` تاريخ البداية. الحدّ ٢٠٠ صفّ.\n\n```php\napp(ReadFromApp::class)('attendance', 'records', ['from' => '2026-09-01']);\n```\n\n## records (write)\n\nالحمولة: `student_ulid`, `date`, `status`. يُرجع `{id, status}`."
}

من يقرؤها: فريقك، ومطوّرو التطبيقات التي وافقتَ على طلب ربطها بتطبيقك — بعد الموافقة لا قبلها. طلب معلّق لا يقرأ شيئاً، وطلب مسحوب لم يعد يقرأ. ليست للمدارس ولا عامّة، فاكتب فيها تفاصيل الحقول التي لا تليق ببطاقة موافقة. وهي خارج البيان: تعديلها يصل القارئ فوراً بلا إصدار جديد.

2. إن كنت المحتاج: أرسل الطلب

/dashboard/app-links → «طلب وصول جديد». تختار تطبيقك، ثم التطبيق صاحب البيانات، ثم من قائمته المنشورة ما تحتاجه، ثم تكتب السبب.

السبب ليس إجراءً شكلياً: هو كلّ ما يقرأه المطوّر الآخر قبل أن يقرّر. اكتب فيه ما ستعرضه للمستخدم تحديداً («نعرض حصص الغياب داخل جدول الطالب، بلا تخزين») لا وصفاً عامّاً («للتكامل»).

3. الردّ: قبول كلّي أو جزئي أو رفض

مطوّر التطبيق صاحب البيانات يرى الطلب في «طلبات واردة»، ويستطيع:

• الموافقة على الكل — الحالة الشائعة، بضغطة واحدة.
• الموافقة على البعض — «اقرأ الملخّص الشهري، لا السجلّ التفصيلي». هذا ردّ طبيعي على طلب حقيقي، وليس حالة استثنائية.
• الرفض — مع ذكر السبب إلزاماً. «لا» بلا سبب تترك المطوّر الآخر بلا شيء يغيّره ولا طريقة يعرف بها إن كان إعادة الطلب مجدية أصلاً.

الموافقة لا تحتاج تعليلاً، والرفض يحتاجه. وبعد الموافقة يبقى للمطوّر أن يسحبها (بسبب أيضاً) — وحينها لا يعود تطبيقك يستطيع إعلان ذلك الوصول في إصداراته القادمة.

بعد الموافقة تُفتح لك وثائق التطبيق المزوّد: زرّ «الوثائق» على الرابط في صفحة الروابط، أو get_shared_docs {"slug": "attendance"} من المساعد. اقرأها قبل أن تكتب سطراً من ReadFromApp أو WriteToApp؛ البيان لا يحمل إلا اسماً وجملة لكل عرض.

4. أعلِن الاعتماد في إصدارك

بعد الموافقة يظهر السطر في محرّر التطبيق تحت «بيانات يحتاجها هذا التطبيق». لا تكتبه يدوياً — القائمة مبنيّة من الموافقات السارية، فما لا يظهر فيها لا يمكن إعلانه أصلاً. تختار لكل سطر أمرين:

"cross_module_access": [
  {
    "module": "attendance",
    "resource": "records",
    "access": "read",
    "required": true,
    "reason": "لعرض حصص الغياب داخل جدول الطالب."
  }
]

• required — هذا هو الحقل الذي تشعر به المدرسة:

  • true → المتجر يطلب منها تثبيت التطبيقين معاً، وتطبيقك لا يعمل بدونه.
  • false → بقيّة التطبيق تعمل، وتتعطّل هذه الميزة وحدها.

  اقلبه بالخطأ وستجد مدرسة عاجزة عن استخدام ما دفعت ثمنه. اجعله true فقط إذا كان التطبيق بلا هذه البيانات بلا معنى.

• reason — يظهر حرفياً في صفحة المتجر بجانب زر الموافقة. اكتبه للمدرسة.

ما يحدث عند التثبيت — وعند كل تحديث

okta-web يقرأ cross_module_access من بيانك، ويُنشئ لكل سطر صفّاً في module_cross_access_grants غير ممنوح (is_granted = false). ثم تعرض صفحة التطبيق البطاقة على الجهة، وهي التي تمنح أو ترفض كل سطر على حدة. لا بيانات تتحرّك قبل ذلك.

والصفوف تُنشأ عند كل تحديث أيضاً، لا عند أول تثبيت فقط. إن أضفت الاعتماد في إصدار لاحق (مثلاً 2.3.17)، فكل جهة كانت قد ثبّتت تطبيقك قبله تحصل على الصفوف الناقصة لحظة نشر الإصدار، وتظهر البطاقة لديها بمفاتيحها — بلا إعادة تثبيت. الصفوف القائمة لا تُمَسّ: ما منحته الجهة يبقى ممنوحاً، وما رفضته يبقى مرفوضاً.

موافقة المطوّر ليست موافقة الجهة. موافقته تعني «يحقّ لهذا التطبيق أن يطلب» فقط. كل مدرسة تُسأل بعدها على حدة، ولها أن ترفض.

ومن في المدرسة يجيب؟ من تحمل أدواره صلاحية «اعتماد مشاركة البيانات بين التطبيقات» (app_store.cross_access.approve) — تُمنح لدور مدير الجهة افتراضاً، وللمدرسة أن تمنحها من تشاء. فمن يفتح صفحة تطبيقك بلا هذه الصلاحية يرى الحالة ولا يستطيع تغييرها. إن أبلغتك مدرسة أن الميزة لا تعمل وأن «لا أحد يستطيع الموافقة»، فهذا هو السؤال الأول: من عندهم يحملها.

ما تفحصه بوّابة الإصدار — وما لا تفحصه

المنصّة تفحص إعلان cross_module_access في ثلاث لحظات، ولا تفحص الشيء نفسه في كلٍّ منها:

القصّة التي فرضت القاعدة: تطبيقٌ يعلن قراءة attendance_status من «حضور»، نُشر ووافقت عليه المدارس والقراءة تعمل. ثم نشر «حضور» إصداراً سقطت منه provides سهواً — فصارت إعادة نشر التطبيق الأول تُرفض بـ«"حضور" لا ينشر okta_hdor.attendance_status.read في آخر إصدار منشور له»، بينما الإصدار المثبَّت عند المدارس ينشره فعلاً. التطبيق عوقب على تغيّر لم يُحدثه، والعقوبة تعطّل خطّ نشره كلّه — إصلاحٌ لا علاقة له بالمشاركة لا يستطيع الخروج.

فلماذا القاعدة آمنة: المدرسة لا تحتاج البوّابة لتحميها من سطر شُحن قبلُ. وقت التشغيل يرفض القراءة أصلاً إن لم يعد المزوّد ينشر المورد أو لم توافق المدرسة (ReadFromApp)، ويُسقط العرضَ المعطوب من الكتالوج. البوّابة عند النشر تحمي من سطر جديد يُشحن بلا موافقة مطوّر أو بلا عرض منشور — وهذا ما ما زالت تفعله بالضبط.

ما يعنيه لك:

• إن رأيت «لا ينشر … في آخر إصدار منشور له» عند الحفظ على سطر كان يعمل، فالمزوّد غيّر كتالوجه. راسل مطوّره؛ إصدارك المنشور لا يتأثّر، ونشرك التالي لا يُعطَّل بهذا السطر.
• الرسالة نفسها عند النشر تعني سطراً جديداً في هذا الإصدار: المزوّد لا ينشر ما تطلبه، أو لم يوافق بعد. هذا رفضٌ صحيح، ولا يُلتفّ عليه.
• write بجانب read حيّ سطرٌ جديد — صفّا موافقة لا درجتان على سلّم.

الكتابة في بيانات تطبيق آخر

القناة كانت قناة قراءة بشكلها، والدليل كان يقول إن write يُعلَن ويُعرَض للمدرسة ولا يُفرَض. لم يعد الأمر كذلك: للكتابة بابها الخاص، والكلمة على بطاقة الموافقة هي التي تقرّر أيّ باب يُفتح.

عند صاحب البيانات — عرض access: write يسمّي writer:

{
  "resource": "records",
  "access": "write",
  "label": "تسجيل حضور من تطبيق آخر",
  "description": "يسمح لتطبيق آخر بتسجيل حضور طالب أو غيابه لهذا اليوم.",
  "writer": "Modules\\Attendance\\Services\\PartnerApi\\RecordsWriter"
}

namespace Modules\Attendance\Services\PartnerApi;

use App\Services\PartnerApi\Contracts\CrossAppWriter;
use Illuminate\Support\Facades\Validator;
use Modules\Attendance\Models\AttendanceRecord;

final class RecordsWriter implements CrossAppWriter
{
    public function write(string $resource, array $payload, string $consumerSlug): array
    {
        $data = Validator::validate($payload, [
            'student_ulid' => ['required', 'string'],
            'date' => ['required', 'date'],
            'status' => ['required', 'in:present,absent,late'],
        ]);

        $record = AttendanceRecord::query()->updateOrCreate(
            ['student_ulid' => $data['student_ulid'], 'date' => $data['date']],
            ['status' => $data['status'], 'source' => $consumerSlug],
        );

        return ['id' => $record->ulid, 'status' => $record->status];
    }
}

القواعد الثلاث نفسها التي للقارئ، وواحدة فوقها: $payload مدخلات من تطبيق آخر — تحقّق منها كما تتحقّق من $request، وارفض المعطوب برمي استثناء لا بالصمت؛ كاتبٌ يعود بلا خطأ عن شيء لم يُخزَّن يجعل التطبيق الآخر يظنّ أنه كتب.

عند المحتاج — نداء واحد، بنفس شكل القراءة:

use App\Services\PartnerApi\CrossApp\WriteToApp;

$written = app(WriteToApp::class)('attendance', 'records', [
    'student_ulid' => '01J…',
    'date' => '2026-09-13',
    'status' => 'absent',
]);
// ['id' => '01K…', 'status' => 'absent']

ما يفحصه النداء هو ما تفحصه القراءة، بفارق واحد يجب أن تعرفه: موافقة المدرسة على الكتابة موافقة أخرى. read وwrite صفّان منفصلان في module_cross_access_grants وسطران منفصلان على البطاقة، وokta-web يقارن عمود access الآن: موافقة read لا تفتح WriteToApp، وموافقة write لا تفتح ReadFromApp. تطبيقٌ يحتاج الاثنين يُعلن سطرين في cross_module_access ويُسأل عنهما المدرسة كلاً على حدة.

على بيئة التجربة: تطبيقاتك تقرأ بعضها بلا موافقة

على جهة بيئة التجربة، تطبيقان لك أنت يقرآن بعضهما مباشرةً: لا اعتماد من مطوّر آخر (لا يوجد)، ولا موافقة من الجهة (هي جهتك)، ولا نشر على الإنتاج. ما يُحكَم به هو ما ثبّته على التجربة: ثبّت التطبيق المزوّد هناك بإصدار يعلن المورد في provides ويسمّي له قارئاً، ثم نادِ ReadFromApp من التطبيق الآخر فتصلك البيانات. بطاقة الموافقة في متجر التجربة تعرض السطر بشارة «مُنحت تلقائياً» بدل مفتاح.

وفي محرّر الإصدار، تظهر موارد تطبيقاتك الأخرى المثبَّتة على التجربة قابلةً للإعلان حتى لو لم تُنشر بعد، بشارة «على بيئة التجربة فقط». هذا يكفي للحفظ وللتجربة، ولا يكفي للمراجعة: إرسال الإصدار للمراجعة يعود إلى القاعدة الأصلية — التطبيق الآخر يجب أن يكون قد نشر ما تعتمد عليه، لأن مدرسة على الإنتاج لا تُسأل الموافقة على مورد لم يُشحن إليها.

القاعدة لا تمرّ على جهة إنتاج أبداً، ولو كان التطبيقان لك: بيانات المدرسة بيانات المدرسة، والصفّ الممنوح هو الإذن الوحيد هناك.

مثال كامل: كتابة بين تطبيقين لك على التجربة، بلا نشر

الحالة: تطبيق «الحضور» يملك سجلّات الحضور، وتطبيق «البوّابة» يريد أن يسجّل غياب طالب عندما تمرّ بطاقته. كلاهما لك، ولم يُنشر أيّ منهما بعد. الخطوات من مساعد MCP (أو من المحرّر — الشاشتان تكتبان الأعمدة نفسها):

1. المزوّد يعلن عرض كتابة بكاتب — على إصدار الحضور القابل للتعديل:

set_shared_data {
  "slug": "attendance",
  "shares": [
    {
      "resource": "records",
      "access": "write",
      "label": "تسجيل حضور من تطبيق آخر",
      "description": "يسمح لتطبيق آخر بتسجيل حضور طالب أو غيابه لهذا اليوم.",
      "writer": "Modules\\Attendance\\Services\\PartnerApi\\RecordsWriter"
    }
  ]
}

ثم يكتب الصنف RecordsWriter كما في قسم «الكتابة في بيانات تطبيق آخر» أعلاه، ويدفعه إلى المستودع.

2. المزوّد يُثبَّت على التجربة — install_on_sandbox {"slug": "attendance"} (أو زرّ التثبيت في تبويب التجربة). هذا هو ما يُحكَم به: الإصدار المثبَّت على التجربة، لا آخر إصدار منشور.

3. المستهلك يعلن الاعتماد — يظهر العرض الآن في get_app_dependencies {"slug": "gate"} تحت «المتاح للإعلان» بعلامة «(على التجربة فقط)»:

set_app_dependencies {
  "slug": "gate",
  "dependencies": [
    {
      "module": "attendance",
      "resource": "records",
      "access": "write",
      "required": false,
      "reason": "لتسجيل غياب الطالب تلقائياً عند مرور بطاقته من البوّابة."
    }
  ]
}

يُقبل الحفظ لأن الاثنين لك والمزوّد مثبَّت على التجربة. (لو كان «الحضور» لمطوّر آخر لرُفض السطر حتى يوافق ذلك المطوّر وينشر العرض.)

4. المستهلك يُثبَّت على التجربة ويكتب — install_on_sandbox {"slug": "gate"}، ثم من كود البوّابة:

use App\Services\PartnerApi\CrossApp\WriteToApp;

$written = app(WriteToApp::class)('attendance', 'records', [
    'student_ulid' => $student->ulid,
    'date' => today()->toDateString(),
    'status' => 'absent',
]);

لا صفّ موافقة يُنتظر: على جهة التجربة، والتطبيقان لمطوّر واحد، يمرّ النداء مباشرةً إلى RecordsWriter في سياق الحضور. بطاقة الموافقة في متجر التجربة تعرض سطر الكتابة بشارة «مُنحت تلقائياً».

5. قبل المراجعة — انشر «الحضور» أولاً (فيصير عرض الكتابة منشوراً)، ثم أرسل «البوّابة» للمراجعة. بالترتيب المعكوس تُرفض البوّابة بـ«لا ينشر»، وهو الرفض الصحيح: مدرسةٌ على الإنتاج ستُسأل عن سطر كتابة، ولا بدّ أن يكون خلفه عرضٌ منشور.

ما يتغيّر على الإنتاج بعد ذلك شيء واحد: موافقة المدرسة على سطر الكتابة تصير الإذن، وتُسأل عنه على حدة عن أيّ سطر قراءة.

قراءة البيانات فعلياً

استدعاء واحد، من داخل تطبيقك:

use App\Services\PartnerApi\CrossApp\ReadFromApp;

$records = app(ReadFromApp::class)('attendance', 'records', ['from' => '2026-08-01']);
// [['student_ulid' => '01J…', 'date' => '2026-08-16', 'status' => 'absent'], …]

ثلاثة وسائط: التطبيق صاحب البيانات، والمورد كما أعلنه هو في provides، ومرشِّحات اختيارية تمرّ كما هي إلى قارئه. تُرجِع ما أرجعه القارئ — مصفوفات وقيماً صِرفة.

لا تُمرِّر هويّتك. لا $tenantId ولا معرّف (slug) تطبيقك: كلاهما مقروء من سياق التشغيل الذي أنت فيه أصلاً. لو كان معرّف المُنادي وسيطاً لأمكن لأي تطبيق أن يدّعي أنه غيره ويستعير روابطه.

ما يفحصه النداء قبل أن يُرجِع شيئاً

1. المُنادي هو سياق التشغيل الحالي، لا شيء أرسلته.
2. الجهة وافقت على هذا السطر بعينه — (الطالب، المزوّد، المورد) — وهي البطاقة التي رأتها في المتجر. موافقة المطوّر وحدها لا تكفي.
3. المزوّد ما يزال يعلن المورد وسمّى له قارئاً في بيان الإصدار المُثبَّت، لا في السطر الذي حصلت عليه يوم الموافقة. مَن سحب المورد يتوقّف عن الإجابة عليه.

ثم تدخل المنصّة سياق المزوّد وتستدعي قارئه هناك، فيقرأ بياناته باعتماداته هو، وتستعيد سياقك بعد الرجوع. أنت لا تلمس مخطّطه ولا تعرف عنه شيئاً — وهذا مقصود: لكل تثبيت مخطّط Postgres خاص خلف دور مُقيَّد، فالقراءة المباشرة ليست ممنوعة فحسب، بل مستحيلة تقنياً.

الفشل استثناء لا مصفوفة فارغة

سطر لم تمنحه الجهة يرمي RuntimeException برسالة تقول أيّ الأبواب أُغلق، ولا يعيد [] — لأن «لا يوجد ما تقرأه» و«لست مسموحاً لك» حالتان مختلفتان تماماً، وخلطهما يجعلك تشحن لوحة فارغة بدل خطأ قابل للإصلاح.

وهذا يعني أنك تتوقّع الاستثناء وتتعامل معه كحالة طبيعية على سطر required=false:

try {
    $records = app(ReadFromApp::class)('attendance', 'records');
} catch (\RuntimeException) {
    $records = null; // اعرض الجدول بلا عمود الغياب.
}

على سطر required=true هو ما يحدث بين التثبيت والموافقة فقط، وبعدها لا يتكرّر.

لماذا لا CrossModuleAccessService::hasAccess()؟ كان هذا الدليل يوجّهك إليه، وكان خطأً من وجهين: فاحص السياسة يرفض استيراده (internal-service-import — العقد هو App\Services\PartnerApi\* وحده)، وهو يعيد true/false على أي حال، فيُخبرك أنك مسموح لك بالقراءة ولا يعطيك بها سبيلاً. ReadFromApp يفحص الشيء نفسه ثم يُرجِع البيانات.

حدود يجب أن تعرفها

• write مفروض. okta-web يقارن عمود access: موافقة read تفتح القراءة وحدها، وموافقة write تفتح الكتابة وحدها. تطبيقٌ كان يعتمد على أن صفّ قراءة يمرّ في فحص كتابة (وهو ما كان يقوله هذا الدليل) يحتاج الآن عرض write بكاتب عند المزوّد وسطر write في إعلانه وموافقة المدرسة عليه.
• السحب لا يرجع بالزمن. إن سحب المطوّر موافقته، تتوقّف إصداراتك القادمة عن إعلان الوصول، لكن الجهات التي منحته أصلاً تبقى موافقتها سارية حتى تُحدَّث المنصة.
• تطبيقاك أنت لا يحتاجان طلباً. تطبيقان لجهة واحدة لا شيء بينهما للتفاوض — تُعلِن الاعتماد مباشرةً. على بيئة التجربة يكفي أن يكون التطبيق الآخر مثبَّتاً هناك بالمورد؛ وعند المراجعة يبقى ملزَماً بأن يكون قد نشر ما تُسمّيه في provides.

الطباعة على ترويسة المدرسة (قوالب التقارير)

ما هو القالب

القالب ترويسة، لا مستند. المدرسة تملك الإطار — شعارها، ترويستها، تذييلها، علامتها المائية، هوامشها، مقاس الورق واتجاهه — وتُرتّبه مرة واحدة في «منشئ التقارير» داخل أوكتا. الجسم يؤلّفه تطبيقك: القالب لا يحمل محتوى خاصاً به.

هذا هو التقسيم كاملاً:

لماذا لا تطبع بنفسك

كل تطبيق يطبع شيئاً يصطدم بالجدار نفسه: تشكيل العربية، الاتجاه من اليمين، خطٌّ يرسمها، هوامش الصفحة، وترويسةٌ تعرف المدرسة أنها ترويستها. ومحلولاً في كل تطبيق على حدة يُحَل في كل تطبيق بشكل مختلف، فتنتهي المدرسة وفي يدها ستة مستندات بستة تخطيطات — ولا واحد منها ترويستها، والشيء الوحيد الذي أرادته، أن هذه المستندات من مدرستها، هو الشيء الذي لا يحمله أيٌّ منها.

والمحرّك يعرف ذلك كلّه أصلاً، لأن المدرسة أعدّته مرة واحدة.

متى لا يناسبك هذا: إن كان مستندك تصميماً خاصاً بك لا علاقة له بهوية المدرسة (فاتورة تحمل هويّتك أنت مثلاً)، اطبعه بنفسك. القوالب لمستندات تخرج باسم المدرسة.

النطاق المطلوب

reports.builder.read — وهو نفسه نطاق كتالوج التقارير. المدرسة تُسأل سؤالاً واحداً: هل يقرأ هذا التطبيق سطح التقارير؟ والطباعة على ترويسة قراءة لها.

وهذا كل ما يحتاجه أغلب التطبيقات. بقيّة هذا القسم عن الطباعة على ما رتّبته المدرسة أصلاً، ولا تحتاج معها write إطلاقاً.

والتأليف نطاق ثانٍ منفصل: reports.builder.write يسمح لتطبيقك أن يقترح قالباً من عنده حين لا يجد في المدرسة ما يناسب مستنده — ولا يسمح له بأن يطبع عليه: المقترَح يصل مسودةً حتى تعتمده المدرسة. تفصيله في أن يقترح تطبيقك ترويسة.

الخطوة ١ — اسرد القوالب

GET /api/apps/reports/templates

{
  "data": [
    {
      "id": "9wXqB4",
      "name_ar": "خطاب صادر",
      "name_en": "Outgoing letter",
      "type": "general",
      "orientation": "portrait",
      "paper_size": "a4",
      "header_enabled": true,
      "footer_enabled": true,
      "variables": [
        {
          "key": "letter_no",
          "label_ar": "رقم الخطاب",
          "label_en": "Letter number",
          "type": "text",
          "required": true,
          "default": ""
        }
      ]
    }
  ]
}

id نصٌّ مبهم — استعمله كما وصلك ولا تبنِه بنفسك ولا تشتقّه من شيء. وهو ليس ULID بخلاف بقية معرّفات هذا السطح.

اقرأ variables — هذه ليست حقلاً تتخطّاه. هي الحقول التي يطلبها هذا القالب بعينه عند الطباعة: ترويسة تقول «رقم الخطاب: {{letter_no}}» ستطبع فراغاً مكانه إن لم تُرسل قيمة، ولا شيء في المستند سيقول لك لماذا. وrequired إشارتك إلى أن تسأل إنساناً بدل أن تخمّن.

تُسرد القوالب المعتمدة فقط. مدرسة في منتصف إعادة تصميم ترويستها لديها مسودة يجب ألّا تصل وليّ أمر، وتطبيقك لا يستطيع أن يميّز تصميماً منتهياً من آخر تحت التعديل بالنظر إليه — فالمنصّة لا تعرضه عليك أصلاً.

الخطوة ٢ — اطبع

POST /api/apps/reports/templates/{id}/render

{
  "blocks": [
    { "type": "heading",  "text": "كشف الدرجات", "level": "h1" },
    { "type": "info-row", "label": "الطالب", "value": "أحمد صالح" },
    { "type": "table",
      "headers": ["المادة", "الدرجة"],
      "rows": [["الرياضيات", "95"], ["العلوم", "88"]] }
  ],
  "variables": { "letter_no": "1447-42" }
}

الجواب هو ملف PDF نفسه (Content-Type: application/pdf) لا رابطاً إليه. الملف المخزَّن يحتاج عمراً وسياسة تنظيف وقاعدة وصول، لمستندٍ قد يحمل درجات طفل باسمه — وتسليم البايتات يترك الثلاثة معك.

curl -X POST \
  -H "Authorization: Bearer $INSTALLATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"blocks":[{"type":"heading","text":"كشف الدرجات","level":"h1"}]}' \
  --output report.pdf \
  https://getokta.io/api/apps/reports/templates/9wXqB4/render

الكتل المتاحة

النوع المجهول يُرفَض ولا يُتخطّى. كتلةٌ ساقطة بصمت تُخرج مستنداً ناقصاً قسماً كاملاً لا يقول عن نفسه شيئاً، وتقريرٌ ينقصه صفٌّ أسوأ من تقرير فشلت طباعته. الجواب 422 ونصّه يسمّي الكتلة ونوعها:

{ "error": "Block 2 has an unknown type «chart». Known types: heading, text, table, info-row, divider, spacer, image." }

المتغيّرات

القالب قد يُعلن حقولاً خاصة به، وتملؤها أنت عند الطباعة بمفاتيحها:

"variables": { "letter_no": "1447-42", "recipient": "إدارة التعليم" }

قواعد ثلاث تستحق أن تُعرف مسبقاً:

• المتغيّر غير المُعلَن يُسقَط ولا يُرفَض الطلب. بخلاف نوع الكتلة المجهول: الكتلة الساقطة تُنقص المستند قسماً، والمفتاح الزائد لا يُنقص الورقة شيئاً — فتستطيع إرسال حمولة واحدة على عدّة قوالب.
• لا يمكنك الكتابة فوق متغيّرات المنصّة ({{tenant.name}}، {{date.today}}، {{page.number}} …). لو أمكن، لطبع تطبيقٌ اسم مدرسة أخرى على ورق هذه المدرسة.
• ما لم تُرسله يعود إلى القيمة الافتراضية التي ضبطتها المدرسة، لا إلى فراغ — إن كانت لها قيمة افتراضية.

الاعتماد

للقالب دورة حياة عند المدرسة: مسودة → بانتظار الاعتماد → معتمد. ولا يُطبع إلا المعتمد، ويُعاد الفحص عند كل طباعة لا عند السرد فقط: المُعرّف يعيش في مخزن تطبيقك بعد أن تكون المدرسة قد أعادت القالب للتصميم.

فإذا خزّنت مُعرّف قالب، تعامل مع 422 عند الطباعة كحالة طبيعية لا كعطل: اسرد القوالب من جديد ودع المستخدم يختار.

من تطبيق مدمج (Embedded)

التطبيق المدمج ينادي الخدمات مباشرةً في نفس العملية — بلا HTTP وبلا توكن:

use App\Services\PartnerApi\Reports\Templates\ListReportTemplates;
use App\Services\PartnerApi\Reports\Templates\RenderReportTemplate;

$templates = app(ListReportTemplates::class)();

$pdf = app(RenderReportTemplate::class)(
    $templates[0]->id,
    [
        ['type' => 'heading',  'text' => 'كشف الدرجات', 'level' => 'h1'],
        ['type' => 'info-row', 'label' => 'الطالب', 'value' => 'أحمد صالح'],
    ],
    ['letter_no' => '1447-42'],
);

// ['filename' => '...', 'mime' => 'application/pdf', 'bytes' => '...']
return response($pdf['bytes'], 200, [
    'Content-Type' => $pdf['mime'],
    'Content-Disposition' => 'attachment; filename="'.$pdf['filename'].'"',
]);

النطاق نفسه مطلوب، ويُفحص من سياق التثبيت النشط.

أن يقترح تطبيقك ترويسة

كل ما سبق يفترض أن المدرسة قد رتّبت ترويسةً تناسب مستندك. وكثيراً لا تكون قد فعلت: تطبيق درجات يحتاج كشفاً فيه الفصل الدراسي في الترويسة وتوقيعا معلّم المادة ومدير المدرسة أسفله، والمدرسة لا تعرف أن هذا ما يحتاجه — حتى تراه.

فالتطبيق يستطيع أن يقترح القالب الذي يعرف شكله، وتبقى المدرسة هي التي تقرّر.

النطاق: reports.builder.write — منفصل عن read عمداً، فتُسأل المدرسة سؤالاً ثانياً عند التثبيت بدل أن يكتسب كلُّ تطبيق يقرأ التقارير القدرةَ على وضع مسوّدات أمامها.

ما لا يشتريه هذا النطاق

هذه الأربع هي العقد كلّه، ولا يُنقض واحدٌ منها بأي حال:

1. المقترَح يصل مسودةً ولا يُطبع. حتى تعتمده المدرسة. القالب الذي ألّفتَه للتوّ لا يظهر في GET /reports/templates ويُجيب POST .../render عليه بـ422. وهذا ليس عطلاً تلتفّ حوله: كل ما يُطبع على ترويسة يخرج باسم المدرسة إلى وليّ أمر أو وزارة، وتطبيقٌ يؤلّف ويطبع في نفس اللحظة تطبيقٌ يُصدر مستندات باسم مدرسةٍ لم يرها فيها أحد.
2. لا تمسّ إلا ما ألّفتَه أنت. ترويسة المدرسة التي رتّبتها بيدها، وقالبٌ ألّفه تطبيق آخر على المدرسة نفسها — كلاهما 422 عند التعديل أو الحذف. (عزل الجهات لا يقول شيئاً هنا: التطبيقان مثبَّتان على المدرسة نفسها بشرعية.)
3. التعديل يُسقط الاعتماد. قالبٌ اعتمدته المدرسة ثم عدّلتَه يعود مسودة ويتوقّف عن الطباعة حتى يُعتمد ثانيةً. هذا ثمنٌ حقيقي وهو المقصود: اعتمادٌ يبقى بعد التعديل يعني أن تطبيقاً يُمرّر قالباً بريئاً للاعتماد ثم يكتب فيه ما شاء.
4. المعتمد لم يعد لك لتحذفه. الاعتماد هو أخذ المدرسة التصميمَ لنفسها — وقد يكون على أوراق فصلٍ كامل. الحذف من هنا يُجيب 422، والمدرسة تحذفه من منشئ التقارير حيث تُرى العاقبة أمام من يقرّرها.

إنشاء قالب

POST /api/apps/reports/templates

{
  "name_ar": "كشف درجات",
  "name_en": "Marks sheet",
  "orientation": "portrait",
  "paper_size": "a4",

  "header_center_content": "كشف درجات — الفصل {{term}}",
  "footer_center_content": "{{page.number}} / {{page.total}}",

  "signatures_enabled": true,
  "signatures_columns": 2,
  "signatures": [
    { "title_ar": "معلم المادة", "title_en": "Subject teacher" },
    { "title_ar": "مدير المدرسة", "title_en": "Principal" }
  ],

  "variables": [
    { "key": "term", "label_ar": "الفصل الدراسي", "type": "text", "required": true }
  ]
}

الجواب 201 وجسمه نفس شكل القالب في السرد — بمعرّفه المبهم وبـ variables كما سُجِّلت، فترى فوراً ما ستُطالَب بإرساله عند الطباعة.

الشعار واسم الجهة يُورَثان ولا تُرسلهما. المنصّة تنسخهما من ترويسةٍ اعتمدتها المدرسة سابقاً — لأن قالباً بترويسة فارغة أول ما تراه المدرسة يبدو تطبيقاً معطوباً لا مسودةً تنتظر شعارها. وتطبيقك لا يملك تعيينهما: ملفٌّ يصل من خارج المدرسة ليكون شعارها ليس ما يقرّره تطبيق.

ما يُقبل من حقول

قائمة سماح: كل ما ليس فيها غير قابل للكتابة من هنا.

وخارجها عمداً — والسبب يستحق أن يُقال:

• header_logo وbackground_image — علامة المدرسة على ورقها. راجع أعلاه.
• حالة الاعتماد ورفيقاتها — لو كانت قابلة للكتابة لاعتمد التطبيق مسوّدته بنفسه، وصار كل ما في هذا القسم زينة.

محتوى الخانات نصّ يقبل المتغيّرات: متغيّرات المنصّة ({{tenant.name}}، {{date.today}}، {{page.number}} …) ومتغيّرات القالب التي أعلنتَها أنت.

ومفتاحٌ يظلّل متغيّراً جاهزاً يُسقَط بصمت — tenant.name مثلاً لا يصير حقلاً تملؤه. القاعدة ليست خاصة بالتطبيقات: هي القاعدة نفسها التي يمرّ منها محرّر المدرسة، فلا تنحرف بين البابين.

التعديل

PATCH /api/apps/reports/templates/{id}

نفس الحقول، وكلها اختيارية. الغياب يعني «اتركه كما هو» ولا يعني «امسحه» — فتطبيقٌ نسي مفتاحاً لا يمسح تذييل المدرسة. الاستثناء الوحيد variables و signatures: مصفوفة فارغة صريحة تعني «احذفها كلّها»، وهي الحالة التي قال فيها المستدعي ما يقصده بوضوح.

وتذكّر البند ٣ أعلاه: بعد التعديل يتوقّف القالب عن الطباعة حتى يُعتمد ثانية.

الحذف

DELETE /api/apps/reports/templates/{id}

لمسودةٍ لم تعتمدها المدرسة. والمعتمد 422.

حدّ العدد

٢٥ قالباً لكل تثبيت. التطبيق يقترح حفنة مستندات يعرف كيف يملؤها؛ حلقةٌ فيها خطأ تقترح آلافاً، فتكتشفها المدرسة صفحةَ منشئ تقارير لم تعد تُقرأ. تجاوز الحدّ 422.

ماذا يحدث عند إزالة التطبيق

لا شيء يُحذف. القوالب التي اقترحها تطبيقك تبقى للمدرسة — راجعتها واعتمدتها وطبعت عليها، وهي مستنداتها الآن أيّاً كان من صاغها. تفقد نسبتها إليك فقط، وتصير قوالب مدرسة عادية.

فلا تعتمد على أن إعادة التثبيت تُعيد إليك ملكيّتها: تثبيتٌ جديد لا يملك ما ألّفه تثبيتٌ سابق، وسيحتاج أن يقترح من جديد.

التأليف من تطبيق مدمج

use App\Services\PartnerApi\Reports\Templates\CreateReportTemplate;
use App\Services\PartnerApi\Reports\Templates\UpdateReportTemplate;
use App\Services\PartnerApi\Reports\Templates\DeleteReportTemplate;

$template = app(CreateReportTemplate::class)([
    'name_ar' => 'كشف درجات',
    'header_center_content' => 'كشف درجات — الفصل {{term}}',
    'variables' => [
        ['key' => 'term', 'label_ar' => 'الفصل الدراسي', 'required' => true],
    ],
]);

// $template->id — المعرّف المبهم نفسه الذي يعيده HTTP

متى تقترح، ومتى لا

اقترح حين يكون لمستندك شكلٌ يعرفه تطبيقك ولا تعرفه المدرسة: كشف درجات، خطاب قبول، شهادة حضور. اقترحه مرة واحدة عند أول تشغيل — لا في كل مرة يفتح فيها المستخدم شاشة، وإلا امتلأت لوحة المدرسة بمسوّدات متطابقة تنتظر اعتماداً لن يأتي.

لا تقترح حين تجد في GET /reports/templates ما يناسبك: الترويسة التي رتّبتها المدرسة بيدها أولى دائماً، والمقترَح لا يُغني عن اختيار المستخدم.

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

قائمة تحقق قبل النشر

• reports.builder.read معلَن في الـ manifest مع سبب واضح.
• تسرد القوالب وتدع المستخدم يختار — لا تُثبّت مُعرّفاً في الكود.
• تقرأ variables وتسأل عن كل required قبل الطباعة.
• 422 عند الطباعة يُعاد به إلى السرد، ولا يُعرض كعطل في التطبيق.
• لا تفترض وجود قالب: مدرسة لم تُنشئ ولا ترويسة تُرجع data: []، وواجهتك تحتاج ما تقوله عندها.

وإن كنت تؤلّف قوالب أيضاً:

• reports.builder.write معلَن ومُبرَّر — ولا تطلبه إن كنت تطبع فقط.
• تقترح مرة واحدة عند أول تشغيل، لا في كل فتح شاشة.
• تسرد أولاً وتقترح فقط حين لا تجد ما يناسبك.
• واجهتك تقول للمستخدم إن المقترَح ينتظر اعتماد المدرسة — لا تعرضه جاهزاً للطباعة، فهو ليس كذلك.
• لا حلقة انتظار للاعتماد، ولا افتراض أنه سيقع.
• تعديل قالب معتمد قرارٌ تتّخذه بعلم أنه يوقف طباعته حتى يُعتمد ثانيةً.

نُهج الأمان

Embedded

• ✓ Policy scanner (regex + PHPStan AST) يفحص كل PR في مستودعك.
• ✓ Postgres role/schema منفصلين تماماً عن المنصة.
• ✓ BlocksPartnerDirectAccess trait يرفض أي وصول خارج App\Services\PartnerApi\*.
• ✓ كل scope مُتحقَّق عند الـ runtime عبر AppPermissionGuard.

External

• ✓ Installation token في DB مشفّر.
• ✓ Webhooks موقَّعة + timestamped + replay-protected.
• ✓ HTTPS فقط للـ webhook_url.
• ✓ rate limiting من جانب أوكتا (60 طلب/دقيقة لكل installation).

مسؤولياتك

• لا تُسرّب الـ installation token في logs أو error reports.
• خزِّن webhook_secret في secret manager، ليس في الكود.
• طبّق rate limiting داخلي إن كان تطبيقك يُمرّر طلبات لخدمات خارجية باستخدام بيانات المستأجر.
• لا تخزِّن بيانات المستأجر أكثر مما تحتاج.

الاختبار محلياً

Sandbox tenant

كل تطبيق Embedded يحصل على sandbox tenant يحاكي مستأجراً حقيقياً ببيانات اختبار. تشغيل ضد sandbox مجاني وغير محدود.

Webhook tunneling

للـ External، استخدم أداة مثل ngrok لإنشاء HTTPS tunnel إلى dev machine الخاصة بك:

ngrok http 8000
# انسخ العنوان (مثل https://abc.ngrok.app) إلى webhook_url في
# إعدادات التطبيق sandbox

أوكتا يُمكِنك من إعادة بثّ webhook events على عنوانك الجديد دون إنشاء أحداث جديدة، عبر صفحة "Webhook Deliveries → Replay".

Postman / Insomnia

استورد:

https://partners.getokta.io/docs/openapi.json
https://partners.getokta.io/docs/postman_collection.json

ملف الـ Postman يأتي بـ installationToken كمتغير — ضع التوكن من sandbox install وستعمل كل الطلبات.

التطوير بمساعدة الذكاء الاصطناعي (MCP)

المنصّة توفّر خادمي MCP (Model Context Protocol) يربطان مساعدك البرمجي (Claude Code، Cursor، أو أي عميل MCP) بمعايير أوكتا وأدواتها — فيلتزم مساعدك بالمعايير من أول سطر بدل اكتشاف المخالفات عند مراجعة الـ PR.

1) الخادم المحلي — داخل مستودعك (بلا حساب)

كل مستودع تطبيق مُنشأ من المنصّة يأتي ومعه خادم MCP محلي جاهز في scripts/mcp/ مع ملف .mcp.json في الجذر:

• Claude Code: يكتشفه تلقائياً بمجرد فتح المستودع — لا إعداد إطلاقاً.
• Cursor: أضِف إلى .cursor/mcp.json:

{ "mcpServers": { "okta-partner": { "command": "php", "args": ["scripts/mcp/server.php"] } } }

يتطلّب php في الـ PATH فقط (بلا Composer وبلا اتصال شبكة). أدواته تلفّ نفس فاحصات CI (scan_code، validate_manifest، lint_permission، component_catalog، feature_service، search_standards، list_scopes) — أي ما يمرّ محلياً يمرّ في بوّابة الدمج. راجع scripts/mcp/README.md داخل مستودعك للتفاصيل.

2) الخادم المستضاف — من حسابك (بموافقة، بلا توكن)

الخادم المستضاف يضيف فوق أدوات المعايير أدوات حيّة مرتبطة بهويّتك: تطبيقاتك وإصداراتها، الكتالوج الحيّ للنطاقات، المتابعة (صحة التطبيق وتسليمات الـ webhooks)، المحاكي، وأدوات التحكّم ولوحة التحكّم.

الربط (مرة واحدة):

# Claude Code
claude mcp add --transport http okta-partner https://partners.getokta.io/mcp

// Cursor — .cursor/mcp.json
{ "mcpServers": { "okta-partner": { "url": "https://partners.getokta.io/mcp" } } }

أول استخدام يفتح المتصفح على شاشة الموافقة في منصّة الشركاء: سجّل دخولك بحسابك المعتاد، راجع ما ستستطيع الأداة فعله، ووافق. لا يوجد أي توكن يُنسخ أو يُلصق — التفويض OAuth (PKCE) بالكامل.

صلاحية الكتابة: افتراضياً الربط قراءة فقط (تطبيقاتك + المعايير + المتابعة). لتمكين أدوات التحكّم (تقديم للمراجعة، إنشاء إصدار، تعديل الـ changelog وقناة الإصدار، ضبط أنواع الحسابات، برمجة لوحة تحكّم التطبيق وإعدادات الـ webhooks) فعّل خيار «سماح بالكتابة (التحكّم في التطبيق)» في شاشة الموافقة نفسها. كل الكتابات تمرّ بنفس ضوابط الواجهة (لا تجاوز لحالة النشر، ولا كتابة على إصدار منشور).

أبرز الأدوات الحيّة:

أنواع الحسابات عبر MCP

تبويب «أنواع الحسابات» في محرّر الإصدار متاح كاملاً من مساعدك:

• list_account_types — الكتالوج الحيّ (نفس قائمة البوابة): لكل نوع key وtarget (role = دور داخل الجهة، portal = بوابة عامّة) وتسمية عربية/إنجليزية. أي مفتاح خارج القائمة يُقبل كـ دور مخصّص؛ البوابتان مجموعة مغلقة (student | guardian).
• get_account_types — ما يُعلنه تطبيقك فعلاً. أنواع الحسابات تُعلَن على الإصدار (لا قيمة على مستوى التطبيق تُورَّث)، فالتقرير سرد لكل إصدار؛ مرّر {version} للتضييق.
• set_account_types — استبدال كامل للقائمة على إصدار قابل للتعديل، تماماً كما يفعل حفظ محرّر الإصدار. اقرأ الحالي أولاً وأعد إرساله كاملاً بعد التعديل؛ account_types: [] تمسح الكل.

كل نوع: key (مطابق لاسم الدور أو البوابة) + kind (primary | dependent) + هدف واحد فقط: roles (دور واحد) أو portal + سطح واحد على الأقل: web_route (اسم مسار Laravel مثل school-app.admin — ليس رابطاً ولا /path) و/أو mobile_entry (بالشكل الذي يفرضه وضع الجوال على الإصدار) — ومع صفّ native له mobile_entry، min_contract اختياري (عدد صحيح ≥ 1: أرضية عقد المضيف لهذا النوع وحده؛ أسقطه ليرث افتراض الكتلة). هذا الإعلان الواحد هو ما يبني menu.audiences[] في okta-web وmobile.audiences[] في تطبيق أوكتا، والأداة ترفض مسبقاً كل ما يرفضه المُحقِّق عند النشر.

الأدوار المخصّصة للجهة. يُسمَح بمفتاح دور خارج كتالوج أنواع الحسابات — فالجهات تعرّف أدوارها الخاصة — لكنه يُعلَن صراحةً: الجمهور الناتج يحمل "custom": true في الـ manifest، وset_account_types تُنبّهك عند تخزين واحد. أما نشر مفتاح خارج الكتالوج بلا هذه العلامة فمرفوض عمداً: المنصّة تطابق مفتاح الدور كنص على الأدوار التي يحملها المستخدمون فعلاً، فالمفتاح المخترَع أو المكتوب خطأً لا يطابق أحداً — يُنشَر الإصدار، ويبدو الـ manifest سليماً، ثم تُرفض كل صفحات ذلك الجمهور لكل مستخدم تحت بوّابة الجماهير التي ترفض بالافتراض. إن كنت تقصد نوعاً معروفاً فاختر مفتاحه بالضبط (list_account_types)، وإن كنت تقصد فعلاً دوراً تعرّفه الجهة فتأكّد أنها تملكه بهذا الاسم حرفياً. ولا تصحّ custom أبداً على جمهور portal.

ملاحظة أمان: التوكن مرتبط بك وبجهتك فقط — لا يرى ولا يلمس تطبيقات أي جهة أخرى، وسرّ الـ webhooks لا يُقرأ ولا يُعرض عبر أي أداة. يمكنك إعادة الربط في أي وقت، والموافقة على الكتابة قرارك في كل ربط.

نظام التصميم وواجهة المستخدم

التطبيق المدمج (Embedded) يظهر داخل لوحة المستأجر جنباً إلى جنب مع شاشات أوكتا الأصلية. لذلك أي ميزة بصرية يبنيها شريك يجب أن تتسق مع هوية أوكتا حتى لا يشعر المستأجر بقفزة بصرية. هذا القسم هو المرجع الوحيد الذي تحتاجه أنت — أو أداة AI مثل Claude Code / Cursor / Codex — لبناء واجهة احترافية متناغمة مع المنصة.

اقتباس سريع: في نهاية القسم برومبت جاهز انسخه إلى أي مساعد AI ليبني لك ملفات Livewire + Blade بنفس هويّة أوكتا، بدون أن تحتاج لشرح النظام كل مرة.

المبادئ الأساسية

1. استخدم المكوّنات الموجودة، لا تخترع مكوّنات جديدة. كل شيء موصوف في "كتالوج المكوّنات" أدناه (<x-card>, <x-button>, <x-badge>, <x-input-field>, <x-textarea>, <x-alert>, <x-spinner>, <x-modal-card>). كل مكوّن آخر هو خروج عن الهوية.
2. Tailwind tokens من الـpalette أدناه للرماديات وألوان الحالة. ولونك الخاص له مكان مدعوم — راجع «مساحة الإبداع» أدناه؛ الممنوع هو hex حرفيّ بلا مقابل داكن.
3. RTL/LTR على مستوى الـlogical properties: start/end, ms-/me-, ps-/pe-, text-start/text-end. الأسهم والـchevron تُدوَّر بـrtl:rotate-180.
4. font-mono و dir="ltr" لكل المعرّفات والـURLs والـslugs.
5. Card-based composition: كل قسم في <x-card> بحدود ناعمة وظِلّ خفيف.
6. States أوّليّة: empty / loading / error دائماً معالَجة بشكل صريح، ليست fallback.
7. Save bar واحد ثابت بدل أزرار حفظ متعدّدة لكل قسم فرعي.
8. الحركة من طبقة motion-* لا من keyframes خاصّة — فمفتاح prefers-reduced-motion مطبَّق عليها مرّة واحدة (راجع «مساحة الإبداع»).

لاختصار التحديث على prod، باقي محتوى قسم التصميم (Brand tokens، كتالوج x-*، wire-elements/modal، Layout rules، البرومبت الجاهز، نسخ مرجعية) كما هو على main commit 40ae5c0 و prod commit 5e29d0f. أي إضافة مستقبلية لقواعد التصميم تذهب هناك أولاً ثم تُنسَخ هنا.

مساحة الإبداع — ما تملك تغييره

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

اسأل مساعدك أولاً: أداة component_catalog في MCP تعرض كل مكوّن بخصائصه وأمثلته، وأصناف الحركة، ولون تطبيقك، وأي قواعد الفاحص تُرسِب وأيّها لا.

١. البطاقة صارت مرنة

<x-card> كان له شكل واحد، فمن أراد غيره ترك المكوّن وبنى div — فخسر التوكنات والوضع الداكن ليكسب شكلاً. الآن الشكل من المكوّن:

<x-card tone="accent" padding="none" overflow="visible" elevation="lifted">

كلّها اختيارية، والافتراضي يُنتج الشكل القديم حرفياً — فلا يتغيّر شيء قائم.

٢. لونك أنت

المسار الوحيد للون خاص كان قيمة حرفية bg-[#0F766E]. ولها قيمة واحدة، فهي صحيحة في وضع وخاطئة في الآخر — والمنصّة لا تستطيع مساعدتك لأن hex داخل صنف غير مقروء لها.

أعلِنه في البيان بقيمتين، فتصير القيمة معلومة:

"brand": {
  "accent":          { "light": "#0F766E", "dark": "#2DD4BF" },
  "accent_contrast": { "light": "#FFFFFF", "dark": "#042F2E" },
  "accent_soft":     { "light": "#CCFBF1", "dark": "#134E4A" }
}

ثم استعمله كمتغيّر — يتبع الوضع الداكن كما تفعل توكنات المنصّة:

<div class="bg-[var(--app-accent)] text-[var(--app-accent-contrast)]">…</div>
<x-card tone="accent">…</x-card>

• hex فقط (٣ أو ٦ أو ٨ خانات). القيمة تُكتَب داخل <style>، فأي صيغة أخرى — rgb(...)، var(...)، color-mix(...) — تُسقَط بلا محاولة تهريب.
• ثلاثة أدوار لا غير. قائمة أطول تصير نظام ثيمات ثانياً، وعندها يفقد نظام المنصّة معناه.
• محصور في صفحاتك عبر [data-app-brand] — لا يبلغ كروم المنصّة ولا تطبيقاً آخر على الشاشة نفسها.
• أعلنت light وحدها؟ الداكن يرث القيمة نفسها، فلا يبقى نصف مطليّ.
• دور معطوب يسقط وحده ولا يُسقِط البقيّة.

٣. الحركة

طبقة جاهزة بدل كتابة @keyframes:

<div class="motion-stagger">
    @foreach ($rows as $row)
        <x-card class="motion-rise">…</x-card>
    @endforeach
</div>

motion-stagger على الحاوية يجعل كل ابن يدخل بعد سابقه بـ40ms — حتى عشرة ثم يثبت، فذيل جدول طويل لا يصل متأخّراً بثانية ونصف.

ولماذا تستعملها بدل keyframes خاصّة بك: prefers-reduced-motion مطبَّق عليها كلّها في مكان واحد. ومَن أوقف الحركة في نظامه لم يفعل ذلك ذوقاً — لصاحب اضطراب دهليزي، حركة لم يطلبها عَرَض لا زينة. كل keyframes تكتبها بنفسك موضع إضافي يجب أن يتذكّره.

وأعِد التوقيت متى شئت: --motion-duration على أي عنصر يعيد توقيت كل ما تحته، و0ms توقفه.

٤. الفاحص قناتان لا واحدة

• يُرسِب البناء — ما ينكسر خارج تصميمك: <input>/<select>/<textarea> الخام، ورماديات gray|zinc|slate|indigo، وmax-w-* بمقاييس الحاويات (3xl فأعلى، full، screen-*).
• يُذكَر ولا يُرسِب — اتساق تملك تجاوزه: <button> خام، ولون حرفي.

وmax-w-prose وmax-w-[42ch] ليستا مخالفتين — تلك طباعة لا حاوية. والجدول الخام لم يعد مخالفة إطلاقاً: <x-table> لا يعبّر عن جدول حصص ولا تقويم، وقاعدة يتخطّاها الجميع تُعلِّم تخطّي القواعد لا احترامها.

٥. النوافذ (Modals)

لا تبنِ نافذة بنفسك بـx-show/x-data وطبقة تعتيم يدوية. المنصّة تستعمل wire-elements/modal، والحزمة مسجَّلة في التخطيط أصلاً — لا تُسجّلها ثانيةً.

١. المكوّن يرث ModalComponent لا Component:

use LivewireUI\Modal\ModalComponent;

class WithdrawalRequestModal extends ModalComponent
{
    public int $moduleId;

    public static function modalMaxWidth(): string
    {
        return 'lg'; // sm | md | lg | xl | 2xl …
    }

    public function mount(int $moduleId): void
    {
        $this->moduleId = $moduleId;
    }

    public function submit(): void
    {
        // …
        $this->closeModal();
    }
}

٢. القالب يستعمل <x-modal-card> دائماً — لا <header> ولا <footer> خاماً:

<x-modal-card class="w-[min(92vw,32rem)]" :title="__('…')" :subtitle="__('…')">
    <form wire:submit="submit" id="my-form" class="space-y-3">
        <x-input-field :label="__('…')" wire:model="amount"
            :errorMessage="$errors->first('amount')" />
    </form>

    <x-slot:footer>
        <x-button variant="primary" type="submit" form="my-form">{{ __('actions.save') }}</x-button>
        <x-button variant="secondary-subtle" type="button"
            wire:click="$dispatch('closeModal')">{{ __('actions.cancel') }}</x-button>
    </x-slot:footer>
</x-modal-card>

<x-modal-card> يعطيك الترويسة وزرّ الإغلاق والحدود والحشوة و<x-slot:footer> بفاصل علوي. ولاحظ w-[min(92vw,32rem)] لا max-w-*: العرض المسؤول للنافذة يُكتب هكذا.

الزرّ خارج <form> ويشير إليه بـform="my-form" — فالفوتر شقيق للنموذج لا ابنه، وزرّ submit خارج نموذجه لا يرسله بلا هذه الإشارة.

٣. الفتح من أي مكان بحدث، مع الوسائط التي يستقبلها mount():

wire:click="$dispatch('openModal', {
    component: 'partner.modules.new-version-modal',
    arguments: { moduleId: {{ $module->id }} }
})"

الاسم هو alias المكوّن بالصيغة المسطَّحة. تجنّب :: فيه — Livewire 4 يمرّر الاسم على normalizeName() قبل البحث، فالـ alias الذي يحوي :: لا يُحَلّ أبداً.

٤. الإغلاق: $this->closeModal() من الخادم، أو wire:click="$dispatch('closeModal')" من القالب.

لماذا لا تبني نافذتك: طبقة التعتيم وحبس التركيز وإغلاق Escape وإعادة التركيز إلى الزرّ الذي فتحها ومنع تمرير الخلفية — كلّها في الحزمة. النافذة المبنيّة يدوياً تبدو صحيحة وتترك مستخدم لوحة المفاتيح داخل الصفحة خلفها.

الرسوم البيانية — <x-chart>

مكوّن واحد لكل رسم بياني، والمكتبة (ApexCharts) مُدمَجة داخل المنصّة — لا تحمّل Chart.js ولا ApexCharts من CDN: تطبيقك يعمل داخل صفحة المنصّة، وسكربت من الخارج يعمل خارج حزمتها وسياسة أمانها ويرسم بألوان لا تعرف الثيم. الفاحص يُرسِب البناء عليه (remote-chart-library).

{{-- من مكوّن Livewire: مرّر البيانات كما تخرج من الاستعلام --}}
<x-chart
    type="bar"
    :series="['حضور' => $present, 'غياب' => $absent]"
    :categories="$days"
    :title="__('my-app::stats.attendance')"
    format="percent"
    height="280"
/>

<x-chart type="donut" :series="['حاضر' => 42, 'غائب' => 3, 'متأخّر' => 5]" />

<x-chart type="line" :series="[['name' => 'الرسوم', 'data' => $fees]]" :categories="$months" format="currency" currency="SAR" />

• type: line (افتراضي) · area · bar · column · scatter · radar · heatmap · treemap · pie · donut · radial.
• series يقبل ما يخرج من استعلامك بلا إعادة تشكيل: قائمة أرقام، قائمة مفتاحية (المفاتيح تصير الفئات أو الشرائح)، خريطة اسم←قائمة (سلسلة لكل مفتاح)، [{name, data}]، ونقاط {x, y} للـ scatter. الدائرية تقبل [{name, value}] أيضاً. null فجوة على الخطّ لا صفر.
• format: number · currency (+ currency="SAR") · percent، مع precision للمنازل. الأرقام تُنسَّق بلغة الصفحة.
• الألوان من tokens المنصّة: لون تطبيقك (من brand في البيان) أولاً ثم لوحة المنصّة، ونصّ المحاور والشبكة من الـ tokens نفسها — فالرسم يتبع الوضع الداكن وRTL تلقائياً ويُعاد رسمه عند تبديل الثيم. :colors تتجاوز اللوحة إن احتجت.
• التحديث الحيّ بلا كود: مرّر :series من خاصية أو دالة في مكوّن Livewire؛ مع كل إعادة تصيير يتحدّث الرسم في مكانه بانتقال متحرّك. لا حدث ولا entangle.
• الفراغ مُعالَج: قيم كلها null (أو مجموع دائري صفر) تُظهر حالة فارغة (emptyText لتغيير النصّ). الصفر على خطّ قيمة لا غياب.
• :options مخرج الطوارئ: أيّ خيار ApexCharts خام يُدمَج آخراً — قبل أن تكتب new ApexCharts( بنفسك (وهو ما يحذّر منه الفاحص: hand-driven-chart).
• فتحتان: <x-slot:actions> بجانب العنوان (فلتر، تبديل مدّة) و<x-slot:footer>.

Toasts

استخدم نظام الـtoasts المشترك بدل alerts مدمجة في الصفحة:

$this->dispatch('toast', message: __('my-module::students.created'));
$this->dispatch('toast', message: __('errors.generic'), type: 'error');

أنواع: success (افتراضي), error, warning, info.

البرومبت الجاهز لمساعد AI

البرومبت الكامل المُوصى به في commit 5e29d0f على prod. ابدأ منه بدون تغيير. القاعدة #12 فيه تذكر بضرورة تصريح كل مفتاح إشعار في الكتالوج أعلاه قبل dispatch من الكود.

دعم الذكاء الاصطناعي

التطبيقات التي تستخدم الذكاء الاصطناعي يجب أن تُعلن ذلك صراحةً في الـ manifest عبر حقلين:

• aiSupport (boolean): هل يستخدم التطبيق الذكاء الاصطناعي؟
• aiMode (enum): إمّا own (أدوات الشريك الذاتية) أو platform (محرّك أوكتا الموحَّد).

واجهة الإعلان داخل المنصة

• عند إنشاء التطبيق: بطاقة "دعم الذكاء الاصطناعي" تظهر بين "البيانات الأساسية" و"التسعير" في صفحة /partner/modules/create.
• عند تحديث الإصدارات: نفس البطاقة تظهر في تبويب "نظرة عامة" داخل محرّر الإصدار، فيمكن إضافة دعم AI لإصدار محدّد دون تعديل التطبيق الأصلي. الإعلان على مستوى الإصدار يتفوّق على إعلان مستوى التطبيق.

الخيارات

• own — التطبيق يدير مزوّداته (OpenAI / Anthropic / Gemini / ...) ومفاتيحه بنفسه. لا يحتاج اعتماداً إضافياً من فريق المنصة.
• platform — التطبيق يستهلك AiManager المركزي في okta-web. التصريح هو الاعتماد، ولا خطوة انتظار بعده.

كيف يُعتمد platform فعلاً

بوّابة التشغيل (EnsureAiPlatformApproved) تسأل عمودَين على جدول modules في okta-web: ai_support وai_mode = platform. لا تقرأ بيانك الخام، ولا تنتظر طابوراً. وهذان العمودان يُملآن من بيانك في مسارَين:

في بيئة التجربة: أعلِن وادفع، ويعمل — بلا أي موافقة من إدارة المنصّة.

بيئة التجربة تُسقِط سؤال الاعتماد كلّه: التطبيق غير مثبَّت في أي جهة حقيقية، والبيانات ليست بيانات أحد، والغاية من البيئة أن تعرف إن كانت الميزة تستحق التقديم أصلاً — فقرارُ اعتمادٍ يمنع التجربة قرارٌ في سؤال لم يُطرَح بعد. حتى السحب لا يصل إلى بيئة التجربة: إن سحبت الإدارة الاعتماد فالإنتاج يتوقّف وتبقى تجربتك تعمل.

والعكس ليس صحيحاً: الدفع إلى بيئة التجربة لا يُلغي سحباً على الإنتاج. في تركيب مشترك تقرأ جهةُ تجربتك والإنتاجُ صفَّ التطبيق نفسه، فلو كان الدفع يمسح العلم لاستعاد أي شريك وصولاً سُحب منه لسبب — بمجرّد الدفع إلى بيئته.

(وهذا كان معطوباً: مسار تثبيت التجربة لم يكن يستخرج العمودَين إطلاقاً، فتطبيق يعلن aiMode: platform يُدفَع إلى التجربة ويحصل على 403 دائماً — والمخرج الوحيد نشرٌ إنتاجي كامل.)

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

قراءة الـ 403 حين يأتي

الرفض يحمل الآن reason يقول أيّ الحالتين هي — وهما تحتاجان علاجَين متعاكسين:

{
  "error": "ai_platform_not_approved",
  "reason": "not_declared",   // أو "revoked"
  "message": "..."
}

• not_declared — بيانك لم يُسجَّل: راجع aiSupport/aiMode فيه، وتأكّد أن التطبيق نُشِر أو دُفِع إلى التجربة. لا تنتظر أحداً.
• revoked — فريق أوكتا سحب الاعتماد: راجعهم.

الترويسات: X-Ai-Approval-Required: 1 وX-Ai-Denied-Reason: <reason>.

مرجع تفصيلي

راجع ai-support.md للحصول على قواعد التحقّق الكاملة، أمثلة manifest، وأسئلة شائعة عن التكلفة والترقية بين own وplatform.

أمثلة كود استخدام AiManager

هذه الأمثلة تنطبق على aiMode=platform فقط. تطبيقات aiMode=own تستخدم مزوّداتها مباشرة (انظر القسم الأخير).

حقن AiManager

use App\AI\AiManager;
use App\AI\AiException;

class StudentReportsController extends Controller
{
    public function __construct(private AiManager $ai) {}

    public function summary(Request $request)
    {
        try {
            $summary = $this->ai->summarize($request->long_text);
            return response()->json(['summary' => $summary]);
        } catch (AiException $e) {
            return response()->json(['error' => $e->getMessage()], 502);
        }
    }
}

Laravel يحلّ AiManager تلقائياً عبر AiServiceProvider (يُسجَّل كـ singleton). يمكن أيضاً استخدام app(AiManager::class) أو app('ai').

chat() — محادثة بسيطة

$reply = app(AiManager::class)->chat(
    prompt: 'لخّص لي تقرير الطالب التالي في 3 نقاط',
    context: [
        ['role' => 'user',      'content' => 'تقرير الطالب: ...'],
        ['role' => 'assistant', 'content' => 'حسناً، سأقرأ التقرير.'],
    ],
    opts: [
        'model'         => 'gpt-4o',     // اختياري — افتراضي يحدّده محرّك أوكتا
        'temperature'   => 0.3,
        'max_tokens'    => 500,
        'system_prompt' => 'أنت مساعد تعليمي محترف. أجب بالعربية.',
    ],
);

stream() — استجابة متدفّقة (للواجهات التفاعلية)

use App\AI\AiManager;

return response()->stream(function () {
    $full = app(AiManager::class)->stream(
        prompt: 'اشرح لي مفهوم التحليل العاملي',
        context: [],
        opts: ['temperature' => 0.5],
        onChunk: function (string $chunk) {
            echo "data: " . json_encode(['text' => $chunk]) . "\n\n";
            ob_flush();
            flush();
        },
    );
}, 200, [
    'Content-Type' => 'text/event-stream',
    'Cache-Control' => 'no-cache',
    'X-Accel-Buffering' => 'no',
]);

في Livewire، استخدم wire:stream أو حدّث خاصية عامة من داخل onChunk callback.

complete() — إكمال نصّ (بدون محادثة)

$completion = app(AiManager::class)->complete(
    text: "كتب الطالب أحمد في مقاله: 'التعليم هو السبيل ل",
    opts: ['max_tokens' => 50],
);
// نتيجة: "...النهضة والتقدّم في المجتمعات الحديثة، ولذلك يجب..."

summarize() — تلخيص نصّ طويل

$summary = app(AiManager::class)->summarize(
    longText: $student->report_full_text,
    opts: [
        'max_tokens' => 300,
        'system_prompt' => 'لخّص في فقرة واحدة، مع التركيز على نقاط القوة والضعف.',
    ],
);

translate() — ترجمة

$en = app(AiManager::class)->translate(
    text: 'الطالب متفوّق في الرياضيات والعلوم',
    toLocale: 'en',
);
// نتيجة: "The student excels in mathematics and sciences"

معالجة الأخطاء

use App\AI\AiException;
use Illuminate\Http\Client\ConnectionException;

try {
    $result = app(AiManager::class)->chat($prompt);
} catch (AiException $e) {
    // فشل المزوّد، تجاوز الحدّ، نموذج غير متاح، ...
    Log::warning('AI request failed', ['error' => $e->getMessage()]);
    return back()->with('error', 'تعذّر معالجة طلبك حالياً. حاول لاحقاً.');
} catch (ConnectionException $e) {
    // عدم وصول للخدمة (نادر)
    return back()->with('error', 'خدمة الذكاء الاصطناعي غير متاحة.');
}

لا تلتقط PlatformAiNotApprovedException (HTTP 403). دعها تنتشر — middleware EnsureAiPlatformApproved سيُرجع للمستخدم رسالة "بانتظار اعتماد المنصة" مع header X-Ai-Approval-Required: true، وهذه رسالة معيارية على المنصة.

أمثلة aiMode=own — أدوات الشريك الذاتية

إذا اخترت aiMode=own، فإن أوكتا لا تشارك في إدارة الطلبات. تستخدم مزوّدك مباشرةً مع SDK الخاص به. مثال OpenAI:

use OpenAI\Laravel\Facades\OpenAI;

$response = OpenAI::chat()->create([
    'model' => 'gpt-4o',
    'messages' => [
        ['role' => 'system', 'content' => 'أنت مساعد تعليمي'],
        ['role' => 'user',   'content' => $userInput],
    ],
]);

$reply = $response->choices[0]->message->content;

أو Anthropic Claude:

$response = Http::withHeaders([
    'x-api-key' => config('services.anthropic.key'),
    'anthropic-version' => '2023-06-01',
])->post('https://api.anthropic.com/v1/messages', [
    'model' => 'claude-opus-4-7',
    'max_tokens' => 1024,
    'messages' => [
        ['role' => 'user', 'content' => $userInput],
    ],
])->json();

$reply = $response['content'][0]['text'];

مسؤوليّاتك في وضع own:

• تخزين مفاتيح API بأمان (متغيرات بيئة، KMS، ...)
• إدارة حدود الاستخدام وفواتير المزوّد
• الإفصاح للمستأجر عن أي بيانات تُرسَل خارج المنصة
• التزام سياسات الخصوصية وحماية البيانات

الوكيل الذكي (AI Agent) مع استخدام الأدوات

التطبيقات التي تريد ذكاءً اصطناعياً يُنفِّذ عمليات (لا يُجيب فقط) تستخدم الوكيل (Agent) مع مفهوم "الأدوات" (Tools). أنت تُعرِّف الأدوات كصفّ PHP، والذكاء الاصطناعي يقرّر متى يستدعيها — مثلاً عند طلب "أضف ٥ لجان بتوزيع ٣٠ طالباً لكل لجنة" يقوم الذكاء بنفسه باستدعاء أداة exams.committees.add وتمرير المعاملات الصحيحة.

هذا الجزء يتطلّب aiMode=platform مُعلَناً في بيانك ومسجَّلاً على المنصّة (بالنشر أو بالدفع إلى بيئة التجربة) — انظر «كيف يُعتمد platform فعلاً» أعلاه.

بنية الأداة

كل أداة في تطبيقك هي صفّ PHP يُنفّذ الواجهة App\AI\Contracts\AiTool ويعيش في المجلد Modules/<اسم-التطبيق>/AiTools/. المنصة تكتشفها تلقائياً عند تحميل التطبيق — لا حاجة لتسجيل يدوي.

مثال كامل: AddCommitteesTool في تطبيق الاختبارات

ملف: Modules/Exams/AiTools/AddCommitteesTool.php

<?php

namespace Modules\Exams\AiTools;

use App\AI\Contracts\AiTool;
use App\AI\Exceptions\AiToolException;
use Modules\Exams\Models\ExamCommittee;
use Modules\Exams\Services\CommitteeDistributor;

class AddCommitteesTool implements AiTool
{
    public function __construct(
        private readonly CommitteeDistributor $distributor,
    ) {}

    public function name(): string
    {
        return 'exams.committees.add';
    }

    public function description(): string
    {
        return 'يُنشئ لجان اختبارات جديدة ويوزّع الطلاب عليها حسب الإعدادات المُعطاة. '
            .'استخدم هذه الأداة عندما يطلب المستخدم إضافة لجان أو توزيع طلاب على لجان.';
    }

    public function parametersSchema(): array
    {
        return [
            'type' => 'object',
            'properties' => [
                'committee_count' => [
                    'type' => 'integer',
                    'minimum' => 1,
                    'maximum' => 100,
                    'description' => 'عدد اللجان المطلوب إنشاؤها',
                ],
                'students_per_committee' => [
                    'type' => 'integer',
                    'minimum' => 1,
                    'maximum' => 60,
                    'description' => 'عدد الطلاب في كل لجنة',
                ],
                'exam_period' => [
                    'type' => 'string',
                    'enum' => ['first', 'second', 'final'],
                    'description' => 'الفترة الامتحانية (first/second/final)',
                ],
                'distribution_strategy' => [
                    'type' => 'string',
                    'enum' => ['alphabetical', 'random', 'by_grade'],
                    'default' => 'alphabetical',
                    'description' => 'استراتيجية التوزيع',
                ],
            ],
            'required' => ['committee_count', 'students_per_committee', 'exam_period'],
        ];
    }

    public function requiredScopes(): array
    {
        return ['exams.committees.write', 'education.students.read'];
    }

    public function handle(array $params): mixed
    {
        $count = (int) $params['committee_count'];
        $perCommittee = (int) $params['students_per_committee'];
        $period = (string) $params['exam_period'];
        $strategy = $params['distribution_strategy'] ?? 'alphabetical';

        $available = $this->distributor->countAvailableStudents($period);
        $needed = $count * $perCommittee;

        if ($available < $needed) {
            throw new AiToolException(
                "عدد الطلاب المتاحين ({$available}) أقل من المطلوب ({$needed}). "
                ."يمكنك تقليل عدد اللجان أو عدد الطلاب لكل لجنة."
            );
        }

        $committees = $this->distributor->createAndDistribute(
            count: $count,
            studentsPerCommittee: $perCommittee,
            period: $period,
            strategy: $strategy,
        );

        return [
            'created' => $committees->count(),
            'total_students_assigned' => $committees->sum('student_count'),
            'period' => $period,
            'committee_ids' => $committees->pluck('id')->all(),
            'message' => "تم إنشاء {$count} لجنة وتوزيع {$needed} طالب بنجاح",
        ];
    }
}

إضافة واجهة الدردشة في صفحة التطبيق

<x-ai-agent
    :title="'مساعد اللجان'"
    :placeholder="'مثال: أضف ٥ لجان للدور الأول بتوزيع ٣٠ طالباً لكل لجنة'"
    :system-prompt="'أنت مساعد ذكي لإدارة لجان الاختبارات في تطبيق okta-exams. ساعد المستخدم في إنشاء وتوزيع وإدارة لجان الاختبارات. تكلّم بالعربية دائماً.'"
    height="600px"
/>

كيف يعمل التدفّق

١. المستخدم يكتب: "أضف ٥ لجان للدور الأول بتوزيع ٣٠ طالباً" ٢. الواجهة ترسل الطلب إلى POST /api/apps/ai/agent/stream ٣. المنصة تستخرج التطبيق الحالي من AppContextManager، تكتشف أدوات Modules/Exams/AiTools/ تلقائياً، تُرشّحها حسب requiredScopes()، وتُرسلها للنموذج ٤. النموذج يردّ بـ {"tool": "exams.committees.add", "args": {...}} ٥. المنصة تنفّذ AddCommitteesTool::handle() وتُرجع النتيجة ٦. الواجهة تعرض كل خطوة لحظياً (running → done)

معالجة الأخطاء

• AiToolException: خطأ متعافٍ — يُرسَل للنموذج فيقرّر. استخدمه للتحقّقات.
• أي خطأ آخر: يُلغى دور الوكيل بأكمله ويُسجَّل في partner_install channel.

الصلاحيات

كل أداة تُعلن requiredScopes(). حلقة الوكيل تُسقط الأدوات التي لا يملك التطبيق صلاحياتها قبل عرضها على النموذج. هذا يعني أن أداة الكتابة تبقى آمنة حتى لو منح المستأجِر صلاحيات قراءة فقط.

حدّ التكرار

كل دور للوكيل محدود بـ ٥ تكرارات. بعد الحدّ، يُطلب من النموذج كتابة ملخّص نهائي.

نصائح للتأليف

١. اسم الأداة: استخدم نمط module.resource.action. ٢. الوصف: اكتبه كتوثيق API. ٣. JSON Schema: كن صارماً (enums, min/max). ٤. القيمة المُرجعة: أعِد بنية بسيطة (array/scalar). ٥. التحقّق المُسبق: ارمِ AiToolException للأخطاء المتوقّعة.

اختبار الأداة محلياً

// tests/Feature/AddCommitteesToolTest.php
$tool = app(\Modules\Exams\AiTools\AddCommitteesTool::class);
$result = $tool->handle([
    'committee_count' => 3,
    'students_per_committee' => 25,
    'exam_period' => 'first',
]);
$this->assertEquals(3, $result['created']);

تطبيق الجوال (Okta Mobile)

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

أين تُفعِّله

لوحة الشريك → التطبيق → الإصدار → تبويب التكامل → بطاقة «خدمات داخل تطبيق أوكتا للجوال» → فعّل الخيار، ثم قدّم الإعدادات.

الأوضاع الثلاثة — اختر واحداً لكل إصدار

native هو الوضع الوحيد الذي يعطيك واجهة أصلية، وهو الوحيد الذي يصل عتاد الجهاز عبر نداءات Okta.*. الوضعان الآخران يمرّان بنموذج صلاحيات المتصفح الذي لا تتوسّطه المنصة.

الإعدادات التي تقدّمها

هيكلة الملفات (وضع webview)

ضع كل ما يُعرض في الجوال داخل مجلد okta_app/webview/ في جذر مستودع تطبيقك:

mobile/
├── README.md
├── manifest.json        ← بيانات وصفية اختيارية للسطح الجوّال
├── screens/             ← ملفات نقطة الدخول التي تُعرض في WebView
│   └── dashboard.blade.php
└── assets/              ← css / js / صور هذه الشاشات

نقطة الدخول مثال: okta_app/webview/screens/dashboard.blade.php.

السياسة (مُلزِمة)

خدمات الجوال محصورة في نطاق okta_app/webview/ المخصّص:

• entry للـ webview يجب أن يكون مساراً نسبياً داخل okta_app/webview/ حصراً — بدون بروتوكول (http(s)://) وبدون خروج بـ ... يُرفض غير ذلك عند الحفظ/المراجعة.
• شاشات الجوال لا يُسمح لها بالربط أو الانتقال أو التضمين لأي صفحة منصّة/مستأجر خارج نطاق okta_app/webview/.
• يُفرض هذا أيضاً وقت التشغيل عبر middleware app.webview على okta-web (السطح الجوّال محصور على نطاق /app).
• في وضع external لا تشحن ملفات هنا — تستضيف الصفحة بنفسك، والعزل يكون عبر allowed origins + صفر ربط بيانات.

لوحة معلومات الجوال (Mobile Dashboard)

الشاشة الأولى في تطبيق أوكتا للجوال لوحة معلومات، لا قائمة تطبيقات. قائمة التطبيقات لها تبويبها الخاص «التطبيقات» في الشريط السفلي؛ واللوحة تعرض ما تقوله التطبيقات المثبَّتة نفسها: أرقام اليوم، طوابير الانتظار، آخر ما حدث.

تطبيقك يستطيع أن يضع بطاقة فيها. وهذا متاح لكل الأوضاع — native وwebview وexternal سواء — لأن البطاقة بيانات لا واجهة.

وللبوّابات الشاشة الرئيسية نفسها

شاشة الطالب وشاشة وليّ الأمر لوحتا معلومات أيضاً، وقائمة تطبيقات البوابة في تبويب «التطبيقات» الخاص بها — الشكل نفسه الذي لمدير الجهة. بطاقتك تصل البوابة تلقائياً متى أعلن تطبيقك جمهوراً لها؛ لا شيء جديداً تعلنه، وaudiences تُضيّق هناك كما تُضيّق للأدوار — اكتب ["guardian"] لتخاطب أولياء الأمور وحدهم.

شيئان يختلفان، وكلاهما مقصود:

• وسيط الجمهور يحمل البوابة. الوسيط الأول لمزوّدك (وحقل role في نداء external) يصل student أو guardian حيث يصل مفتاح الدور في نداء الجهة. الوسيط نفسه والمعنى نفسه — من يقرأ — ومزوّد يتجاهله يخاطب كل الجماهير بالأرقام نفسها، وهذا افتراض سليم.

• البوابة عابرة للجهات، وأنت تقرّر كيف يُقرأ ذلك. وليّ أمر أبناؤه في مدرستين ثبّتتا تطبيقك يرى — افتراضياً — بطاقتين، لأن الأرقام تختلف وجمع مدرستين في رقم واحد يصف لا هذه ولا تلك. لكن تطبيقاً موضوعه الابن لا المدرسة يُقرأ رديئاً هكذا: بطاقتان بعنوان «أبنائي» كلٌّ منهما تحمل نصف الجواب. لهذا portal_scope: "combined" يطوي البطاقتين في بطاقة واحدة فيها قسم لكل مدرسة.

  ومزوّدك لا يتغيّر في الحالتين: يعمل مرة لكل مدرسة داخل سياقها ويجيب عنها وحدها — عزل المخطّط لكل تثبيت يجعل غير ذلك مستحيلاً أصلاً — والدمج يحدث في okta-web بعد أن تتكلّم كل مدرسة. البطاقة تكسب أقساماً، وأنت لا تكسب شيئاً تحترس منه.

  "dashboard": { "enabled": true, "title": "أبنائي", "portal_scope": "combined" }
  

  مدرسة واحدة أجابت؟ تُفكّ البطاقة إلى بطاقة عادية بلا أقسام — قسمٌ واحد عنوانه اسم المدرسة يقول ما تقوله البطاقة نفسها. وكل قسم يحمل حالته: مدرسة متعذّرة لا تُعطّل أرقام أختها، بل تظهر ملاحظتها وحدها.

القاعدة التي تحكم كل ما بعدها: أنت تقول ماذا، والمضيف يقرّر كيف

أنت تُرجع أرقاماً وعناوين وأزراراً؛ تطبيق أوكتا هو الذي يرسمها، بنفس اللغة البصرية لكل التطبيقات. الخط الفاصل ليس بين «بسيط» و«غنيّ» — بل بين ما تريده على البطاقة وكيف يُرسَم. الأول لك بسعة، والثاني ليس لأحد منّا وحده.

فالمفردات واسعة: أرقام، صفوف، أيقونات، أشرطة تقدّم، وأزرار تنفّذ عمليات حقيقية (انظر الأفعال أدناه). والممنوع ثلاثة فقط، ولكلٍّ سبب يبقى صحيحاً مهما اتّسعت المفردات:

• لا markup ولا HTML — بطاقة تأتي بتخطيطها الخاص تجعل لوحةً تحمل خمسة تطبيقات خمسَ شاشات متجاورة، وسؤال القارئ الأول («من يقول لي هذا، وكم عمر هذا الرقم؟») يحصل على خمس إجابات.
• لا ألوان سداسية — tone معنى يحلّه المضيف إلى لوحته في الوضعين الفاتح والداكن؛ لونٌ تختاره أنت لن يطابق أياً منهما.
• لا صور من مضيفك — أصلٌ لم يُراجَع على أول شاشة، لا يتبع الثيم، ويفشل تحميله على الاتصالات نفسها التي وُجدت البطاقة لتخدمها. الأيقونات من مفردات المضيف بدلاً عنها.

وهو أيضاً سبب أن البطاقة لا تكلّف شيئاً: لا ترجمة تطبيق مصغّر، ولا صندوق رملي، ولا نسخة عقد. خمس بطاقات هي خمسة مصفوفات مُعادة، لا خمسة مفسّرات.

الإعلان

داخل mobile في البيان:

"mobile": {
  "supported": true,
  "mode": "native",
  "entry": "main",
  "dashboard": {
    "enabled": true,
    "title": "حضور اليوم",
    "title_en": "Today's attendance",
    "provider": "Modules\\OktaHdor\\App\\Services\\DashboardProvider",
    "audiences": ["tenant-admin", "teacher"],
    "cache_ttl": 300
  }
}

💡 بديل عن تحرير manifest.json يدوياً: أداة MCP set_mobile_dashboard تكتب الكتلة مباشرة على إصدار قابل للتعديل وتشغّل فحوص النشر فوراً، وget_mobile_surface تقرؤها. والمزامنة من مستودعك (sync_from_manifest) تحملها كذلك.

النقل يتبع integrationType ولا يُعلَن. تطبيق embedded يسمّي صنفاً تناديه المنصّة داخل عمليتها، وتطبيق external يسمّي رابطاً تُوقّع إليه المنصّة طلباً واحداً. إعلان الاثنين معاً — أو الخطأ منهما — يُرفض عند النشر، لأن مفتاحاً ثانياً لسؤال يجيب عنه البيان أصلاً يعني أن أول تطبيق يضبطهما متناقضين ينشر بطاقة لا تظهر أبداً.

تطبيق مدمج (Embedded): نفّذ العقد

namespace Modules\OktaHdor\App\Services;

use App\Services\PartnerApi\Contracts\MobileDashboardProvider;

final class DashboardProvider implements MobileDashboardProvider
{
    public function dashboard(string $roleKey, string $locale): array
    {
        $today = Attendance::query()->whereDate('taken_at', today());

        return [
            'stats' => [
                [
                    'label' => $locale === 'en' ? 'Present' : 'حاضر',
                    'value' => number_format($today->clone()->where('status', 'present')->count()),
                    'tone'  => 'success',
                ],
                [
                    'label' => $locale === 'en' ? 'Absent' : 'غائب',
                    'value' => number_format($today->clone()->where('status', 'absent')->count()),
                    'tone'  => 'danger',
                ],
            ],
            'rows' => [
                ['title' => 'الصف الأول', 'subtitle' => 'أ', 'value' => '98%'],
            ],
            'open_label' => $locale === 'en' ? 'Open register' : 'فتح السجل',
        ];
    }
}

يعمل داخل سياق مودولك، فيقرأ مخططك باعتماداتك تماماً كما تفعل صفحاتك. ويجب أن تُقصر كل استعلام على الجهة الحالية.

تطبيق خارجي (External): استقبل POST موقَّعاً

POST <endpoint>
X-Okta-Timestamp: 1755859200
X-Okta-Signature:  HMAC-SHA256( "<timestamp>.<body>", install_signing_secret )

{"tenant_id": 42, "role": "tenant-admin", "locale": "ar"}

تحقّق من التوقيع قبل الإجابة، وأجب بنفس شكل المصفوفة أعلاه. المهلة 6 ثوانٍ — ما بعدها يُعامَل كتعذّر.

لا يُرسَل إليك أي شيء يعرّف الشخص. الرقم على اللوحة يخصّ المدرسة، ولستَ بحاجة لتعرف أيّ موظّف ينظر إلى هاتفه ليعدّ غياب اليوم.

شكل البيانات

[
    'title'      => 'حضور اليوم',   // اختياري — يتقدّم على عنوان البيان
    'stats'      => [ ['label' =>, 'value' =>, 'caption' => ?, 'tone' => ?, 'icon' => ?] ],
    'rows'       => [ ['title' =>, 'subtitle' => ?, 'value' => ?, 'tone' => ?,
                       'icon' => ?, 'progress' => ?, 'action' => ?] ],
    'actions'    => [ ['key' =>, 'label' =>, 'tone' => ?, 'style' => ?,
                       'confirm' => ?, 'icon' => ?] ],   // حتى ٣
    'open_label' => 'فتح السجل',     // اختياري — احذفه فلا يُعرض زر الفتح
    'message'    => null,           // ملاحظة تُعرض مع الأرقام
]

value نصّ صغتَه أنت. النِّسب والعملات والنِّسَب المئوية والأعداد لا تشترك في مُنسِّق واحد، وأنت تعرف أيّها تُنتج، وحقلٌ رقمي كان سيجبر العميل على التخمين — أو على حمل مفردات تنسيق تكبر مع كل شريك.

tone معنى لا لون: neutral | success | warning | danger | info. المضيف يحلّه إلى لوحة تطابق بقية الشاشة في الوضعين الفاتح والداكن؛ لونٌ سداسي تختاره أنت لن يطابق أياً منهما.

الحدود مفروضة: 6 أرقام و8 صفوف بحد أقصى، و120 حرفاً لكل نص. الزائد يُقصّ بصمت — بطاقة تأخذ الشاشة كلها ليست بطاقة.

المفاتيح خارج المفردات تُسقَط، لا تُمرَّر. مفتاح غير معروف يصل العميل يصير جزءاً واقعياً من العقد أول ما يعتمد عليه شريك.

icon من مفردات المضيف لا رابط صورة: bell · calendar · chart · check · clock · alert · users · user · phone · message · money · bus · book · flag · pin · star · download · upload · search · settings · lock · shield · heart · home. اسمٌ خارجها يُسقَط ولا يُستبدَل — صورة خاطئة أسوأ من لا صورة.

progress كسرٌ بين 0 و1 يرسمه المضيف شريطاً. يُحصر ولا يُرفض: نسبة خرجت 1.02 خطأ تقريب، لا سبب لإسقاط الصف الذي تنتمي إليه.

الأفعال: أزرار تعمل، لا تعرض

كانت البطاقة أرقاماً وزرّاً واحداً يفتح تطبيقك. ذلك جعل اللوحة مكاناً للقراءة فقط: تطبيقٌ حركته المفيدة «نادِ كل من ينتظر» كان يعرض الرقم ٣١ ثم يرسل القارئ للبحث داخل التطبيق. الآن تُعلن أزراراً في البيانات التي تُعيدها، ويصلك مفتاح الزرّ المضغوط.

'actions' => [
    ['key' => 'call_waiting', 'label' => 'نادِ الجميع', 'style' => 'primary',
     'icon' => 'phone', 'confirm' => 'سيُنادى ٣١ طالباً الآن. متابعة؟'],
],

ويمكن لصفٍّ أن يكون قابلاً للضغط بإسناد action له بمفتاح فعل — فيصير الصف نفسه زرّاً دون إضافة زرّ ثالث.

التنفيذ — مدمج (Embedded)

نفّذ MobileDashboardActionProvider على نفس الصنف الذي يقدّم البطاقة:

use App\Services\PartnerApi\Contracts\MobileDashboardActionProvider;
use App\Services\PartnerApi\Contracts\MobileDashboardProvider;

final class DashboardProvider implements MobileDashboardProvider, MobileDashboardActionProvider
{
    public function dashboard(string $roleKey, string $locale): array { /* … */ }

    public function dashboardAction(string $actionKey, string $roleKey, string $locale): array
    {
        if ($actionKey !== 'call_waiting') {
            return ['ok' => false, 'message' => 'إجراء غير معروف.'];
        }

        $count = CallWaitingStudents::run();   // ضع البطيء في طابور

        return ['ok' => true, 'message' => "نودي {$count} طالباً.", 'refresh' => true];
    }
}

التنفيذ — خارجي (External)

نفس الـ endpoint، ويميّزه وجود action في الجسم:

POST <endpoint>
X-Okta-Signature: HMAC-SHA256( "<timestamp>.<body>", install_signing_secret )

{"tenant_id": 42, "role": "tenant-admin", "locale": "ar", "action": "call_waiting"}

أجب {"ok": true, "message": "…", "refresh": true}. المهلة ١٠ ثوانٍ هنا (لا ٦) لأن هذا كتابة لا قراءة.

ما تضمنه لك المنصّة، وما يبقى عليك

المنصّة تتحقّق أن التطبيق مثبَّت ونشط، وأن الضاغط يرى تطبيقك أصلاً في كتالوجه تحت (الجهة، الدور) الحالية، وأن audiences تشمل دوره — نفس بوّابة القراءة حرفياً، فلا يُبلَغ فعلٌ بإرسال slug من دورٍ لا يرى التطبيق. وتقفل قفلاً قصيراً لكل (جهة، تطبيق، دور، فعل) يبتلع الضغطة المزدوجة وإعادة المحاولة على شبكة بطيئة. وrefresh: true يُسقط كاش بطاقتك فتُقرأ من جديد.

ويبقى عليك أنت:

• المفتاح المجهول رفضك أنت. المنصّة لا تتحقّق أن المفتاح كان بين ما رسمتَه: البطاقة أمام الشخص قد تكون من الكاش، ومنصّةٌ تحاول ضبط ذلك سترفض ضغطات مشروعة دون أن تجعل المفتاح المجهول آمناً. ارفضه بنفسك.
• الصلاحية والنافذة الزمنية — «هذا الفعل يحتاج صلاحية لا يملكها القارئ»، «انتهت نافذة اليوم» — كلها رفضٌ منك بجملة يفهمها الشخص.
• الفعل مرّة واحدة (idempotency) حيث تستطيع؛ القفل يغطّي الضغطة المزدوجة لا أكثر.

الفشل هنا جواب لا حالة. القراءة تتسامح مع التعذّر (بطاقة «غير محدَّث» والشاشة تُرسَم)، أما الضغط فلا: الشخص ضغط وينتظر جملة تقول هل حدث أم لا.

التضييق بالأدوار: يُضيّق ولا يُوسّع أبداً

audiences مفاتيح أدوار تُقصر البطاقة على بعض من يرون تطبيقك أصلاً. اللوحة تُبنى من الكتالوج الذي يستلمه المستخدم بالفعل، فالتطبيق الذي لا يظهر لدور لا يستطيع مخاطبة ذلك الدور من الباب الخلفي. اترك القائمة فارغة ليراها كل دور يرى التطبيق.

الفشل حالة لا استثناء

اِرمِ استثناءً عند الفشل. المنصّة تلتقطه وتسجّله وتعرض بطاقتك بحالة «غير متصل»، أو بأرقامها السابقة موسومةً «غير محدَّث» إن كانت مخزَّنة.

لا تُرجع مصفوفة فارغة بدل ذلك. الفراغ لا يُفرَّق عن «لا يوجد شيء اليوم فعلاً»، فيُري مشغّلاً صفراً واثقاً في صباحٍ كان الاستعلام فيه معطوباً.

والمنصّة تحتفظ بنسخة احتياطية ليوم كامل تُجيب بها حين لا تُجيب أنت: حضور الأمس موسوماً «غير محدَّث» أنفع لمن يقف عند بوّابة مدرسة من صندوق فارغ.

ارسم البطاقة بنفسك — mode: "native"

كل ما سبق يبقى كما هو — ثم يستطيع التطبيق المدمج (embedded) خطوة أبعد: أن يرسم داخل بطاقته بلغة Dart حقيقية، عبر نفس مسار «المصدر يُترجم على الجهاز» الذي يستعمله تطبيقه المصغّر أصلاً:

"dashboard": {
  "enabled": true,
  "title": "حضور اليوم",
  "title_en": "Today's attendance",
  "provider": "Modules\\OktaHdor\\App\\Services\\DashboardProvider",
  "mode": "native",
  "entry": "okta_app/native/card/lib/main.dart",
  "min_contract": 21
}

الإطار يبقى للمضيف. الزوايا والترويسة باسم تطبيقك وأيقونته وشارة المزامنة وزر «فتح» كلها للمنصّة؛ ودجتك تملك داخل صندوق لا تصل حوافّه — وارتفاعه أيضاً: البطاقة تُقصّ عند 320pt ولا تُمرّر، لأن قائمة تتمرّر داخل شاشة تتمرّر تسرق السحبة من القارئ.

provider يبقى إلزامياً، وهذا هو التصميم لا بقايا منه. الأرقام التي يعيدها هي البطاقة التي يرسمها الهاتف الأقدم — والبطاقة التي يرسمها هذا الهاتف لحظة يفشل أي شيء. كل فشل يهبط إليها، بصمت، وفي الجلسة نفسها: مصدر لا يُترجم، ودجت ترمي أثناء البناء، إطار أول لا يصل خلال 500ms من تسليم المحرّك، جهاز عقده أدنى من min_contract. لا حالة خطأ للشريك على الشاشة الرئيسية — القارئ يرى بطاقة بياناتك، والرئيسية لا تنكسر أبداً بسبب شريك. اختبر بطاقتك بأن تجعلها ترمي عمداً: ما يجب أن تراه هو أرقامك أنت.

• entry حزمة مستقلة. يعيش تحت okta_app/native/<حزمة>/lib/ ككل مدخل native، واجعله حزمة خاصة (okta_app/native/card/) لا ملفاً ثانياً داخل حزمة تطبيقك — التسليم يقتطع حزمة واحدة لكل مدخل، فمدخل بطاقة داخل حزمة التطبيق يعني تنزيل تطبيقك كله وترجمته لرسم بطاقة واحدة.
• min_contract إلزامي والأرضية 21 — فيه شُحن محرّك البطاقات، والأدنى منه يُرفع إليه. الجهاز دونه لا يركّب البطاقة أصلاً ويعرض بطاقة البيانات؛ رفضٌ مقصود وغير مرئي، لا خطأ.
• الصندوق الرملي هو صندوق التطبيق المصغّر نفسه. نفس Okta.*، نفس العزل، نفس الثيم. رمز واحد خاص بالبطاقات: Okta.openMiniApp() يفتح تطبيقك الكامل — نفس فعل زر «فتح» في إطار المضيف. الإبحار العميق مكانه التطبيق؛ البطاقة خلاصة لا شاشة.
• البوّابات تُضاعف البطاقة لا حالتها. وليّ أمر أبناؤه في مدرستين يرى بطاقتين تُترجمان وتُركّبان منفصلتين، لا تتشاركان حالة ولا جهة ولا delegate — نفس عزل المدرسة-بمدرسة الذي للتطبيق الكامل.
• للمدمج فقط. البطاقة native تُترجم من حزمة مصدرك الموقّعة، والتطبيق external لا يشحن كوداً — mode: "native" يُرفض عند النشر؛ ابقَ على mode: "data" مع endpoint.

set_mobile_dashboard تكتب المفاتيح الثلاثة وتشغّل هذه الفحوص وقت التطوير؛ ومخطّط البيان وبوّابة النشر يكرّرانها.

ما يجب أن تعرفه قبل النشر

• بطاقتك تظهر فقط لمن يرى تطبيقك أصلاً في الكتالوج.
• cache_ttl يُحصر بين 30 و3600 في الطرفين — البيان المنشور يُظهر الرقم الذي سيُستعمل فعلاً، لا الذي كتبته.
• provider يجب أن يكون تحت Modules\. المنصّة تُنشئ هذا الصنف بالاسم، فأي اسم خارج فضاء مودولك هو بيانٌ يختار داخليّة منصّة لتُنشَأ — والفحص instanceof متأخّر، لأن المُنشئ يكون قد نُفِّذ.
• البطاقة تحمل أزراراً تعمل (حتى ٣) وصفوفاً قابلة للضغط — لكنها تبقى بيانات: لا HTML، ولا ألوان سداسية، ولا صور من مضيفك. الأيقونات من مفردات المضيف، والألوان من tone.
• الأزرار تحتاج نصفها الثاني: أزرار ترسمها بلا MobileDashboardActionProvider (أو بلا استجابة external لـ action) تظهر ثم تعتذر عند أول ضغطة.

شاشات العرض (Okta Screen)

الهاتف يفتحه شخص؛ الشاشة لا يفتحها أحد. تلفاز معلّق في الفصل، لوحة في ردهة المدرسة، شاشة عند باب المجمّع — جهاز يعمل طول اليوم بلا مستخدم أمامه، ويُدار من تطبيق مستقلّ اسمه Okta Screen (Android TV / Google TV، وWindows). يدخل بالاقتران فقط: لا حساب ولا كلمة سرّ، بل رمز يُنشئه مسؤول الجهة من سجلّ الأجهزة ويكتبه على الشاشة مرّة واحدة.

وما يميّز الشاشة عن الهاتف هو مكانها لا صاحبها: عند الاقتران يختار المسؤول أين تقف — الجهة كاملة (ردهة، ممرّ)، أو صفوف بعينها، أو فصول بعينها. تطبيقك يُعلن لأيّ الأماكن يقدّم سطحاً، والمنصّة تعرضه على الشاشات التي تقف هناك.

والمكان مجموعة لا واحداً. تلفازٌ في رأس ممرّ يخدم «أول ثانوي ١» و«ثاني ثانوي ٣» معاً؛ ولوحةٌ في جناح تخدم صفّين. الشاشة تُعطى مجموعةً من نوع واحد — فصولاً معاً أو صفوفاً معاً، لا خليطاً — وتصلك مفصولةً فترسمها كما تشاء (عمودين، تبويبين، قائمة مدموجة).

الإعلان — mobile.screen

صفّ لكل مكان، ولكل صفّ ملف دخوله:

"mobile": {
  "screen": {
    "enabled": true,
    "title": "نداء الفصل",
    "title_en": "Class roll call",
    "min_contract": 21,
    "auto_launch": true,
    "places": [
      { "scope": "section", "entry": "okta_app/native/screen/lib/main.dart" },
      { "scope": "tenant",  "entry": "okta_app/native/screen_lobby/lib/main.dart",
        "title": "لوحة الإعلانات", "title_en": "Notice board" }
    ]
  }
}

لماذا ملف دخول لكل مكان. الحزمة تُترجَم على الجهاز: الشاشة تنزّل مصدر الحزمة التي أُعلنت لمكانها وتترجمه عندها. فلو تشارك المكانان ملفاً واحداً لصار كل تلفاز فصل ينزّل كود الردهة ويترجمه ليرسم نداءً لا علاقة له به. شاشة الفصل وشاشة الردهة شاشتان مختلفتان، والإعلان يقول ذلك: مكان واحد = صفّ واحد = حزمة واحدة. القالب يشحن الحزمتين جاهزتين — okta_app/native/screen/ (نداء الفصل) وokta_app/native/screen_lobby/ (لوحة الإعلانات).

ويجوز أن يشترك المكانان في ملف واحد إن أردت حزمةً واحدة تتفرّع على Okta.context()['screen']: اكتب المسار نفسه في الصفّين. عندها هي حزمة واحدة باختيارك لا بحكم الصيغة — والمنصّة تعرف أنها ناتج واحد لا اثنان.

والشاشة على صفّ يخدمها إعلان section — ولا تُعلن grade إطلاقاً. المسؤول يستطيع أن يضع الشاشة على صفوف بعينها (شاشة الجناح)، لكن الإعلان لا يعرف كلمة grade ولن يعرفها: لا بيان منشور اليوم يحملها، فاشتراطها كان يشحن المكان ميّتاً — كل تطبيق شاشة قائم يُرفض على أول شاشة جناح. فشاشة الصفّ تأخذ حزمة section نفسها، لأن ما تعرضه هو ما تعرضه شاشة الفصل على نطاق أوسع قليلاً.

وإعلان tenant لا يخدمها: لوحة الردهة تخاطب المدرسة كلّها، وعرضها على شاشة جناح يضع المبنى الخطأ على الحائط. فإن أردت أن تخدم تطبيقك شاشات الأجنحة، أعلِن section.

الصيغة القديمة ما زالت تُقرأ. الشكل الأول كان entry واحداً مع scopes[] مسطّحة؛ إن كان بيانك ما زال عليه فهو يُقرأ صفّاً لكل مكان مذكور، كلّها بذلك الملف — بيانٌ كان يُنشَر بنجاح يبقى يُنشَر. لكنه لا يُكتَب أبداً في الاتجاه الآخر: المخزَّن والمنشور دائماً places[].

الكتلة مستقلّة عن mobile.supported. تطبيق يخدم شاشة الفصل ولا يقدّم شيئاً على الهاتف يُعلن screen وحدها ويترك supported: false — وتصله المزامنة والمحرّر وأداة MCP كلّها بلا أن يُمحى. وهي للتطبيقات المدمجة فقط: الشاشة تُترجم كودك من حزمة مصدرك الموقّعة، والتطبيق external لا يشحن كوداً.

ما تصله الشاشة — Okta.context()

الصندوق الرملي هو صندوق التطبيق المصغّر نفسه: نفس Okta.*، نفس okta_kit، نفس الثيم. الشاشة تضيف ثلاثة مفاتيح إلى Okta.context() ولا رمزاً جديداً — فلا رفع عقد ولا minContract أعلى:

final ctx = Okta.context();
final String scope = '${ctx['screen']}';   // 'section' أو 'grade' أو 'tenant'

// الأماكن كلّها، مفصولةً وبالترتيب الذي رتّبها به المسؤول:
final List ids = (ctx['section_ids'] as List?) ?? const [];
final List names = (ctx['section_names'] as List?) ?? const [];

// وعلى شاشة جناح، الصفوف بدلاً منها:
final List gradeIds = (ctx['grade_ids'] as List?) ?? const [];
final List gradeNames = (ctx['grade_names'] as List?) ?? const [];

// والمفرد باقٍ يحمل **أوّل** مكان — لمن كتب تطبيقه قبل المجموعة:
final dynamic sectionId = ctx['section_id'];
final dynamic sectionName = ctx['section_name'];

اقرأ القوائم لا المفرد. الشاشة قد تقف في فصلين، وsection_id يسمّي أولهما وحده — فتطبيقٌ يقرؤه يعرض نصف ما على الحائط ولا شيء يقول له ذلك. والقوائم تغيب حين لا يكون للشاشة أماكن من ذلك النوع (لوحة الردهة، أو مضيف أقدم من المجموعة)، فاقرأها كما في السطر أعلاه: as List? ثم افتراض فارغ. ولا تشقّ نصّاً على فاصل لاستخراجها — اسم فصل قد يحوي الفاصل نفسه.

والمفرد غائب تماماً على شاشة الجناح، لا null: تلك تقف على صفوف لا فصول، فلا section_id ولا section_name في الخريطة أصلاً (والعكس على شاشة الفصل: لا grade_id). فنداء دالّة على المفقود مباشرةً — ctx['section_id'].toString() وأمثاله — يقتل تطبيقك في المحرّك بـtype 'Null' is not a subtype of type '$Instance' in type cast، وإن وقع في initState تكرّر مع كل إطار. وهذا وقع فعلاً على حائط مدرسة. اقرأ القوائم، أو افحص المفرد قبل استعماله.

ولن تحتاج أن تسمّي الأماكن بنفسك في أغلب الحالات: كل صفّ طالب يصلك من /api/apps/education/students يحمل فصله وصفّه، فتجمّعهم منه مباشرةً. القوائم هنا لترسم العناوين وترتّب الأعمدة، لا لتُرشّح البيانات — الترشيح يقع على الخادم (انظر أدناه).

['screen'] يصلك كما كان — لكنه لم يعد آلية التوجيه: المنصّة تختار لكل شاشة ملف الدخول المُعلَن لمكانها، فحزمة الفصل لا تعمل إلا في فصل. يبقى مفيداً لملفٍ اختَرت أن يخدم المكانين معاً (تتفرّع عليه)، ولحارسٍ يقول «هذه لوحة ردهة عُلِّقت على شاشة فصل» بدل أن يرسم لوحاً فارغاً. وقيمته 'grade' على شاشة الجناح — وهي تصل حزمة section كما قيل أعلاه، فإن رسمت عنواناً باسم الفصل فاقرأ grade_names هناك.

اقرأ المفاتيح بـ ['…'] كما تقرأ locale، وتحقّق من null صراحةً ولا تُدخل القيمة في نصّ قبل ذلك (راجع درس '$value' في قسم native). tenant_id وlocale وis_dark تصل كما هي؛ وrole_id فارغ لأن الشاشة بلا دور.

الشاشة ترى أماكنها فقط — بحكم الخادم

هذه ليست توصية لكودك. شاشة مقترنة بفصول تصل بيانات الطلاب عبر /api/apps/education/students مثبَّتةً على أماكنها في الخادم:

• بلا أي مرشّح → طلاب فصولها هي، لا المدرسة.
• ?section_id= يسمّي فصلاً خارجها → صفحة فارغة.
• /students/{ulid} لطالب خارجها → 404، كما لو لم يوجد.
• /education/sections → فصولها هي وحدها.

وشاشة الجناح مثلها بخطوة أوسع: طلاب فصول صفوفها، ومرشّح يسمّي صفّاً أو فصلاً خارجها يُفرِغ الصفحة.

فتطبيق النداء على شاشة الفصل لا يستطيع سرد المدرسة ولو طلب. والمرشّح الذي يسمّي مكاناً خارج الشاشة يُجيب صفحةً فارغة لا خطأً — وهو نفس ما يُجيبه فصلٌ غير موجود، عمداً: التفريق بينهما كان يجعل مشي المُعرّفات كشفاً لما في المدرسة.

وشاشة الجهة (tenant) ترى ما يراه تطبيقك على الهاتف، بالنطاقات نفسها الممنوحة له عند التثبيت — لا نطاقات خاصة بالشاشات.

ولا نطاق جديد ولا رفع عقد في هذا كلّه: الأماكن تصل في Okta.context() وهي خريطة يُسلسِلها المضيف كما هي، والترشيح يقع على الخادم من صفّ الجهاز. تطبيقك يعمل كما هو ولا يُعلن شيئاً جديداً.

مثال: نداء الفصل (okta_app/native/screen/lib/main.dart)

import 'package:flutter/material.dart';
import 'package:okta_host/okta_host.dart';
import 'package:okta_kit/okta_kit.dart';

Widget main() => const RollCallScreen();

class RollCallScreen extends StatefulWidget {
  const RollCallScreen({super.key});
  @override
  State<RollCallScreen> createState() => _RollCallScreenState();
}

class _RollCallScreenState extends State<RollCallScreen> {
  List<dynamic> students = [];

  @override
  void initState() {
    super.initState();
    load();
  }

  Future<void> load() async {
    // لا مرشّح: الخادم يثبّت الطلب على الفصل الذي تقف فيه الشاشة.
    final res = await Okta.get('/api/apps/education/students?per_page=100');
    if (res.ok) {
      // body يبقى dynamic؛ OktaJson.rows تفكّ غلاف {data: [...]}.
      final dynamic body = res.body;
      final List<dynamic> rows = OktaJson.rows(body);
      setState(() { students = rows; });
    }
  }

  @override
  Widget build(BuildContext context) {
    final dynamic ctx = Okta.context();
    final dynamic section = ctx['section_name'];
    final palette = OktaPalette.of(Okta.isDark());
    final List<Widget> rows = <Widget>[];
    for (final dynamic student in students) {
      rows.add(Padding(
        padding: const EdgeInsets.all(12),
        child: Text(OktaJson.strOr(student, 'full_name', '—'),
            style: TextStyle(fontSize: 36, color: palette.textStrong)),
      ));
    }
    return Scaffold(
      backgroundColor: palette.surface,
      appBar: OktaAppBar.build(section == null ? 'نداء' : 'نداء الفصل $section', palette),
      body: ListView(children: rows),
    );
  }
}

مثال: لوحة إعلانات الردهة (okta_app/native/screen_lobby/lib/main.dart)

حزمة أخرى، وملف آخر — لا فرع داخل الملف الأول. ولاحظ أنها لا تسأل عن طالب: الردهة يمرّ بها الجميع، فالقالب يقرأ من نقطة تطبيقك أنت (/api/<slug>/notices) ولا يحتاج أي نطاق منصّة.

import 'package:flutter/material.dart';
import 'package:okta_host/okta_host.dart';
import 'package:okta_kit/okta_kit.dart';

Widget main() => const LobbyBoardScreen();

class LobbyBoardScreen extends StatefulWidget {
  const LobbyBoardScreen({super.key});
  @override
  State<LobbyBoardScreen> createState() => _LobbyBoardScreenState();
}

class _LobbyBoardScreenState extends State<LobbyBoardScreen> {
  List<dynamic> notices = [];

  @override
  void initState() {
    super.initState();
    load();
  }

  Future<void> load() async {
    final res = await Okta.get('/api/my-app/notices');
    if (res.ok) {
      final dynamic body = res.body;
      final List<dynamic> rows = OktaJson.rows(body);
      setState(() { notices = rows; });
    }
  }

  @override
  Widget build(BuildContext context) {
    final palette = OktaPalette.of(Okta.isDark());
    final List<Widget> rows = <Widget>[];
    for (final dynamic notice in notices) {
      rows.add(Padding(
        padding: const EdgeInsets.all(12),
        child: Text(OktaJson.strOr(notice, 'title', '—'),
            style: TextStyle(fontSize: 36, color: palette.textStrong)),
      ));
    }
    return Scaffold(
      backgroundColor: palette.surface,
      appBar: OktaAppBar.build('لوحة الإعلانات', palette),
      body: ListView(children: rows),
    );
  }
}

النسختان الكاملتان — بحلقة تحديث وإيقافها في dispose — تصلانك جاهزتين في القالب تحت okta_app/native/screen/ وokta_app/native/screen_lobby/.

نصائح للشاشة الكبيرة: خطّ أكبر ممّا تعتاده على الهاتف (يُقرأ من آخر الفصل)، بلا لمس — لا تعتمد على إيماءات أو حقول كتابة — وحدّث بياناتك على جدول لا بسحبٍ للتحديث. الشاشة تُبقي تطبيقك مفتوحاً ساعات؛ وTimer غير مجسور على هذا المحرّك (راجع البند ١٤ في قسم native)، فحلقة التحديث استدعاء ذاتي بعد await Future.delayed(…) — لا دالّة تمرّرها إليها — مع علم إيقاف تضبطه في dispose، وبفاصل طويل — كل دورة رحلة إلى المضيف. وشغّل flutter test tool/validate.dart داخل كل حزمة شاشة تشحنها: الفحص يترجم حزمة واحدة، فحزمة فصل خضراء لا تقول شيئاً عن الردهة.

دعم مفاتيح الاتجاه (D-Pad) ومفتاح القائمة

لا لمس على الشاشة أبداً: التحكّم بريموت تلفاز (مفاتيح اتجاه + OK) أو بلوحة مفاتيح على Windows (أسهم + Enter). وما يلي مَقيس على السندبوكس نفسه لا مستنتَج من Flutter عموماً — والفرق بين الاثنين هنا كبير.

العناصر القياسية تدعم الريموت تلقائياً وبلا سطر إضافي. ElevatedButton وTextButton وListTile: الأسهم/Tab تنقل التركيز إليها، وOK/Enter (وزرّ A على يد التحكّم) يُشغّل onPressed/onTap داخل كودك المُترجَم على الجهاز. استعملها لأي شيء يُفترض أن يصله الريموت ولا تحتاج أكثر.

وبطاقتك أنت تصلها كذلك — منذ العقد 25 (package:okta_focus). هذا هو الجديد، وقبله لم يكن ممكناً بأي حيلة:

import 'package:okta_focus/okta_focus.dart';

OktaFocus.first(               // ← تحمل التركيز عند أول رسم
  myBigCard(student),          // ← أي شيء رسمتَه: Container، Row، صورة…
  () => _call(student),        // ← يُشغَّل على OK/Enter، وعلى اللمس أيضاً
)

• OktaFocus.item(child, onSelect) — العادية، والأولى التي تُستعمل.
• OktaFocus.first(child, onSelect) — نفسها وتحمل التركيز أول رسم. واحدة لكل شاشة: اثنتان تطلبان التركيز الأول سؤالٌ له جوابان، وأيّهما يفوز ليس شيئاً يُبنى عليه.
• OktaFocus.watched(child, onSelect, onFocusChange) وwatchedFirst(...) — تُخبرك بدخول التركيز وخروجه لتكبّر البطاقة أو تلوّنها.
• OktaFocus.reachable(child) — يصله السهم ولا شيء يُضغَط: لصفٍّ في قائمة طويلة ينبغي أن تمرّ الحلقة خلاله بدل أن تقفز فوق كتلة من المحتوى.