الموكّلون والأطراف والعلاقاتClients, parties and relationships

كل شخص أو جهة يتعامل معها المكتب (موكّل، خصم، وكيل خصم، شاهد، خبير، جهة) يُسجل مرة واحدة في Legal Party، ويُشار إليه من كل ملف. الموكّل يرتبط أيضًا بـ Customer في ERPNext للفوترة.

بطاقة الميزة

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

فحص التعارض مستحيل إذا كُتب اسم الخصم نصًا حرًا داخل الملف (دليل الميزة 1 ص6، 18). السجل المستقل هو «أهم قرار تصميمي في الميزة» (دليل الميزة 1 ص6).

المشكلة: الاسم الواحد يُكتب بصيغ مختلفة في ملفات مختلفة، فيضيع الربط بين الملفات.

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

الموكّل من كلّف المكتب، والخصم من يقف مقابله، والطرف ذو العلاقة من يرتبط بأحدهما. صفة الطرف (مدعٍ، مدعى عليه) تتغير بين المراحل، فتُحفظ في المرحلة لا في الطرف ولا في الملف (دليل المطور ص5). أما «معنا/ضدنا/محايد» فجانب ثابت في الملف.

المعرّفات الوطنية عشر خانات، أولها 1 للمواطن و2 للمقيم و7 للرقم الموحد للمنشأة national-id (دليل الميزة 1 ص3).

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

الشريك والمحامي: قراءة وإنشاء وتعديل، بلا حذف؛ المحمي هو الملف لا اسم الطرف (دليل الميزة 1 ص14). السكرتارية: إنشاء الطرف عند الحجز بالحد الأدنى (اسم، جوال). المحاسب: يرى Customer للفوترة فقط.

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

B01 المستخدمون والأدوار والصلاحيات مفعّلة.

تشفير الحقول الحساسة وإعداد مفتاح HMAC في خزنة الأسرار التشفير وإدارة الأسرار.

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

1. يبحث المستخدم بالاسم أو رقم المعرّف قبل الإنشاء لتفادي التكرار.
2. ينشئ Legal Party بنوعه (فرد، منشأة، جهة حكومية) واسمه الكامل كما في الهوية أو السجل.
3. يدخل نوع المعرّف ورقمه إن توفّر؛ يُطبّع (أرقام لاتينية) ويُشفّر وتُحسب بصمته.
4. عند تحوّل الطرف إلى موكّل: يُنشأ Customer ويُربط بالحقل legal_party.
5. يضيف العلاقات المعروفة في Related Party (مالك، تابعة، قريب، جهة عمل) بتاريخ سريان.

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

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

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

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

• قائمة الأطراف قابلة للبحث بالاسم ورقم المعرّف (والرقم يُبحث ببصمته لا بنصه).
• تنبيه «طرف بمعرّف مطابق موجود».
• سجل تعديلات لكل طرف.

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

RULE B02.1  normalize_digits(id_number, mobile, cr_number)   # ٠-٩ -> 0-9
RULE B02.2  mobile: strip spaces/dashes; "05XXXXXXXX" -> "+9665XXXXXXXX"; reject otherwise
RULE B02.3  IF id_number AND NOT match("^[127][0-9]{9}$") AND id_type in (هوية, إقامة, رقم موحد): WARN (not block)
RULE B02.4  id_hmac = HMAC_SHA256(secret_key, digits(id_number)); unique per (id_type, id_hmac)
RULE B02.5  normalized_name = normalize_arabic(full_name)   # يُحدَّث عند كل حفظ
RULE B02.6  no Delete permission for any role; merge instead
RULE B02.7  Related Party: party != related_party; valid_to IS NULL OR valid_to >= valid_from

المصادر: (دليل الميزة 1 ص13-14) (دليل المطور ص15، 31). قاعدة التفرّد على البصمة اقتراح هندسي.

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

لا يحمل الطرف حالة سير عمل. علاقة الموكّل بالمكتب تُشتق: محتمل (زائر أو حجز)، نشط (له ملف مفتوح)، سابق (كل ملفاته مغلقة) (تقرير التدقيق (Gemini) ص13).

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

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

• Legal Party (تسمية PTY-.#####، حقل العنوان full_name) (دليل الميزة 1 ص8).
• Related Party (party, related_party, relation: مالك/تابعة/عضو مجلس إدارة/قريب/جهة عمل, source, valid_from, valid_to) (دليل المطور ص31).
• Custom Field على Customer: legal_party (Link)، إضافة إلى id_type وid_number في نسخة F1 اقتراح هندسي (دليل الميزة 1 ص10).

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

• نموذج الطرف بأقسام: الهوية، الاتصال، العلاقات، الملفات المرتبطة (للقراءة، بحسب صلاحية الملفات).
• زر «تحويل إلى موكّل» ينشئ Customer.
• رسائل: «يوجد طرف بهذا المعرّف: [الاسم]. افتحه بدل إنشاء سجل جديد.» — «صيغة رقم الهوية غير معتادة. راجعه قبل الحفظ.»

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

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

POST /api/method/legal_erp.api.v1.parties.find_or_create

يبحث بالبصمة أولًا ثم بالاسم الموحد، ويعيد المطابقات قبل الإنشاء.

الصلاحية: شريك، محامٍ، سكرتارية.

{
  "party_kind": "فرد",
  "full_name": "مُحمّد بن عبدالله التجريبي",
  "id_type": "هوية وطنية",
  "id_number": "١٠٠٠٠٠٠٠٠١",
  "mobile": "0500000001"
}

{
  "status": "exists",
  "party": "PTY-00042",
  "match": "id_exact"
}

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

عند تغيّر بيانات طرف (ملاك شركة، معرّف) تُجدول إعادة فحص التعارض للملفات المفتوحة المرتبطة B16 فحص تعارض المصالح (دليل المطور ص31).

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

وزارة التجارة — واثق (بيانات السجل التجاري) لبيانات السجل التجاري عند الاعتماد؛ ناجز وناجز للمطورين قد يعيد بيانات الأطراف بعد ربط القضية، وتظهر الفروق في سجل الفروق لا كتابة صامتة (خطة ناجز ص8).

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

أرقام الهويات مشفّرة وتظهر مقنّعة (10******34) إلا لمستوى صلاحية أعلى (دليل المطور ص15). البصمة لا تُعاد إلى الواجهة. الطرف الذي لم يصبح موكّلًا تُحذف بياناته الزائدة بعد مدة الحفظ ويبقى ما يلزم للتعارض B38 الاحتفاظ والإتلاف والتجميد القانوني يحتاج اعتمادًا قانونيًا.

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

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

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

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

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

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

دمج الأطراف المكررة: يحتاج تحديد من يملك الصلاحية (الشريك افتراض تنفيذي).