طبقة التكامل المركزيةIntegration hub

B43التكاملاتمتطلب وارد في الملفات

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

بطاقة الميزة

البند	القيمة
1. اسم الميزة	طبقة التكامل المركزية — Integration hub
2. المعرّف (Feature ID)	`B43`
3. مصدر المتطلب	دليل المطور ص13، 21، خطة ناجز للمطورين: طبقة اتصال واحدة
4. تصنيف المحتوى	متطلب وارد في الملفات كل اتصال خارجي في الخلفية ومسجل، مهلة وإعادة محاولة أسية وحدود، قاطع دائرة، تقنيع البيانات في السجل.
الوحدة	التكاملات
الأدوار المعنية	مدير نظام
درجة الخطورة	عالية
حالة الاعتماد	معتمد في الوثائق
المنصات المرتبطة	ناجز وناجز للمطورين، هيئة الزكاة والضريبة والجمارك — الفوترة الإلكترونية، منصة واتساب للأعمال، مزود الرسائل النصية المحلي، بوابة الدفع المحلية، مزود التوقيع الإلكتروني الموثّق

5الهدف التجاري والمشكلة التي تعالجها

منع أن يتعطل النظام عند تعطل جهة خارجية، وأن تتسرب بيانات في السجلات.

6المجال القانوني المرتبط للمطوّر غير المتخصص

لا ينطبق على هذه الميزة.

7المستخدمون والأدوار والصلاحيات

مدير النظام يراقب.

8شروط البدء والاعتماديات

RQ وطوابير Frappe.

9السيناريو الأساسي خطوة بخطوة

الميزة تطلب عبر Adapter بواجهة موحدة.
الطلب يدخل طابورًا.
التنفيذ بمهلة؛ الفشل القابل لإعادة المحاولة يعاد أسيًا.
السجل بلا جسم الاستجابة وبلا بيانات شخصية.
أخطاء متتالية ← إيقاف وتنبيه.

10السيناريوهات البديلة والاستثناءات

Webhook وارد: تحقق التوقيع، معالجة خلفية، تجاهل المعرف المكرر (دليل المطور ص21).

11المدخلات والحقول

الاسم العربي	الاسم البرمجي	النوع	إلزامي	التحقق	القيمة الافتراضية	مصدر البيانات
الخدمة / العملية	`service / operation`	Data	نعم	—	—	—
الحالة	`status`	Select	تلقائي	قيد الانتظار / نجح / فشل / مرفوض / تجاوز الحد	—	—
المحاولات	`attempts`	Int	تلقائي	—	0	—
معرّف الربط	`correlation_id`	Data	تلقائي	—	—	—

12المخرجات والإشعارات والسجلات والتقارير

لوحة صحة التكاملات P02 مراقبة صحة التكاملات.

13قواعد العمل بصيغة قابلة للتحويل إلى كود

قواعد

RULE B43.1  no external call in request thread
RULE B43.2  backoff = base * 2^attempt (+ jitter), max attempts per adapter
RULE B43.3  N consecutive failures -> pause adapter + alert
RULE B43.4  logs: masked; no response bodies with personal data
RULE B43.5  idempotency key per outbound operation

التفاصيل في نمط موصل التكامل.

14حالات السجل وانتقالاتها وشروطها

الموصل: يعمل / متوقف مؤقتًا / معطل.

15نموذج البيانات والعلاقات والقيود والفهارس

Integration Request (Frappe) مع حقول إضافية اقتراح هندسي.

16DocTypes المطلوبة في Frappe

Integration Request، Adapter Settings اقتراح هندسي.

17الشاشات والعناصر والأزرار ورسائل الخطأ

قائمة الطلبات بتصفية، وزر «إعادة».

18خدمات Backend ومسؤولية كل خدمة

legal_erp.integrations.base.Adapter.

19واجهات API الداخلية

لا توجد واجهة API خاصة بهذه الميزة.

20الأحداث والمهام الخلفية والجدولة وإعادة المحاولة

طوابير short/default/long (الوثيقة المعمارية).

21التكاملات المرتبطة بالميزة وحدودها

كل صفحات فهرس المنصات والتكاملات.

22الأمن والخصوصية والتدقيق والاحتفاظ والحذف

المفاتيح في الخزنة. السجلات مقنعة.

23حالات الاختبار

المعرّف	النوع	السيناريو	النتيجة المتوقعة
`B43-T01`	تكامل	جهة متوقفة	إعادة ثم إيقاف وتنبيه.
`B43-T02`	أمني	السجل	لا بيانات شخصية.
`B43-T03`	حدّي	Webhook مكرر	مرة واحدة.

24معايير القبول

لا اتصال خارجي متزامن.

25تعريف الاكتمال (Definition of Done)

كل قواعد العمل في هذه الصفحة منفذة في الخادم (Controller أو Service)، لا في الواجهة وحدها.
حالات الاختبار المذكورة هنا مكتوبة اختباراتٍ آلية في إطار اختبار Frappe، وتنجح مع كل دفعة كود.
اختبارات الصلاحيات تثبت أن مستخدمًا خارج فريق الملف لا يرى السجل في القائمة ولا برابطه المباشر ولا في البحث العام ولا في العدّادات.
الحقول المخصصة والأدوار ومسارات الاعتماد مُصدَّرة في Fixtures التطبيق، وتظهر بعد تثبيت نظيف على موقع فارغ دون إعداد يدوي.
لا تعديل في ملفات Frappe أو ERPNext.
كل قيمة قانونية (مدة، نسبة، مبلغ، قائمة) محفوظة في إعداد قابل للتعديل، وموسومة بحالة اعتمادها.
نصوص الواجهة ورسائل الخطأ بالعربية، وتخبر المستخدم بما يفعله.
معايير القبول في هذه الصفحة مُتحقق منها ومسجلة في مصفوفة التتبع.

26القرارات المفتوحة والمخاطر والاعتمادات المطلوبة

لا ينطبق على هذه الميزة.