---
name: ghayth-experience
description: نمط تصميم تجربة الإدخال التشغيلية في نظام غيث (Ghayth ERP) بمبدأ «الكيان يقود التجربة». استخدم هذه المهارة عند توحيد أو تصميم أو مراجعة صفحات الإنشاء/الإدخال في أي مسار (موارد بشرية، مالية، أسطول، عمرة، عقارات، قانوني، مشاريع، مستودعات، دعم، CRM): واجهة تشغيلية واحدة «تسجيل واقعة» يُدخل فيها المستخدم الكيان وما حدث والبنود والمرفق، والمعالجة (النوع/الحساب/القيد/السلسلة/الالتزام) تُشتقّ خلفيًا. تطبّق التوحيد والبنود المهيكلة والتوزيع والمرفقات بمستويين ودورة الحياة (حفظ≠اعتماد≠ترحيل). ملزمة بالدستور وبوابة المجلس — تُطبّقهما لا تُلغيهما.
---

# غيث — الكيان يقود التجربة (نمط الإدخال التشغيلي الموحّد)

> **مهارة منهجية:** كيف تُصمّم أو توحّد صفحات الإدخال في **أي مسار** على نموذج واحد —
> واجهة تشغيلية + معالجة مشتقّة + بنود مهيكلة + توزيع + مرفقات بمستويين + دورة حياة + التزام زمني + حوكمة.
>
> **المرجع العملي المُنفّذ:** المالية — `docs/finance-audit/25_توحيد_صفحات_الإنشاء_المالية.md` + المهمة **#2994** + الهجرة 418. هذه المهارة **تعمّم** ذلك النموذج على المسارات الباقية.
>
> **لا تُلغي الدستور — تُطبّقه.** كل بناء يمرّ ببواباته: إذن الهجرة، assertion على سطور القيد لأي مساس بالدفتر، عزل المستأجر، RBAC، Audit، ثم بوابة `ghayth-review`. حمّل `ghayth-constitution` و`ghayth-specs` (ملف المسار) قبل التنفيذ.

---

## ٠. النموذج التأسيسي: حدث واحد على شبكة كيانات

لا «صفحات إدخال» منفصلة — بل **شيء واحد**:

> **واقعة = (كيان رئيسي) + (ما حدث) + (بنود) + (كيانات/أطراف مرتبطة) + (مرفق).**

كل التجلّيات (سند · فاتورة · مهمة · تذكرة · مطالبة · عهدة · سلفة · التزام · قيد · تحصيل · سداد) تخرج من **محرّك اشتقاق واحد**: النوع · الحساب/التصنيف · القيد · الأثر التشغيلي · الالتزام الزمني · التفريع الحوكمي · تحديث الكيانات.

**الواجهة للمستخدم = «تسجيل واقعة»** (تشغيلية بحتة) — لا «إنشاء سند/فاتورة/تذكرة».
- **المستخدم يُدخل فقط:** الكيان/الطرف · ما حدث · البنود · المرفق · الربط (عند اللزوم).
- **النظام يقرّر خلفيًا:** النوع والتصنيف والحساب والقيد والسلسلة والالتزام والمطالبة.

**المبادئ السبعة:** ① الحقيقة الواحدة (يُدخل الحد الأدنى غير القابل للاشتقاق) · ② الكيان عقدة (حالة/أرصدة/علاقات/التزامات/قدرات/ملف ٣٦٠) · ③ ثنائية الاتجاه (الواقعة تُنشأ من المستند أو من الكيان نفسه وتظهر في ملفه) · ④ استنتاج النية (النوع من إشارات قليلة) · ⑤ دورة الحياة · ⑥ الأثر المتسلسل **يُطلق عند الترحيل لا عند حفظ المسودة** · ⑦ صدق الأثر (كل سطر/قيد قابل للتتبّع لسببه التشغيلي — لا سجل يتيم).

---

## ١. المبادئ التسعة القابلة للتعميم (طبّقها على أي مسار)

1. **الكيان يقود التجربة.** ابدأ من «مَن/ما المرتبط بالواقعة؟» — اختر الكيان، يفتح النظام عالمه (الحالة/الأرصدة/الفواتير/العقود/الالتزامات/العمليات المسموحة)، ثم يُشتقّ النوع والمعالجة. الكيان **مصدر السياق**، لا حقل ربط في السطر.
2. **الواجهة تشغيلية / المعالجة خلفية مشتقّة.** غير المختص لا يلمس الحسابات ولا الأبعاد التقنية (نموذج الحقيقة التشغيلية — الدستور).
3. **النوع/التصنيف مشتقّ لا مدخل.** أي «تبويب نوع» (قبض/صرف · سلفة/عهدة · صيانة/وقود · بيع/استلام) = **تصنيف وفلترة واختصار، لا سؤال إجباري**. المستخدم يبدأ من (الكيان + الواقعة) والنظام يضع النوع تلقائيًا.
4. **بنود مهيكلة لا نص حر.** جدول بنود موحّد: `صنف/خدمة · وصف · كمية · وحدة · سعر · (ضريبة) · إجمالي`. الصنف **بحث ذكي** (لا نص حر) + `AllowCreateDrawer` لإنشائه؛ **الوحدة تُشتقّ من الصنف**.
5. **مرفقات بمستويين موسومة.** مرفق على مستوى المستند + **مرفق لكل بند** (عبر `lineId`)؛ العرض لوحة جانبية موسومة «المرفق متعلّق بـ…».
6. **توزيع البند على عدة كيانات.** البند الواحد قد يخدم أكثر من كيان (صيانة ٩٬٠٠٠ على ٣ مركبات) → جدول توزيع: `entityType/entityId · allocationType(amount/percent/quantity) · costBearer · reason`. بلا تجزئة يدوية للسطر.
7. **`costBearer` تفريع حوكمي لا تسمية.** «مَن يتحمّل» يحوّل التكلفة → **مطالبة/ذمة حقيقية** على الطرف + سلسلة حوكمة (اعتماد + سبب + متابعة) + التزام متابَع حتى التسوية. يُطبَّق لكل جزء توزيع.
8. **دورة الحياة: الحفظ ≠ الاعتماد ≠ الترحيل.** حفظ مسودة (واقعة غير مرحّلة، لا قيد) ← إرسال للاعتماد ← اعتماد ← **ترحيل** (ينشئ القيد والأثر النهائي) ← تسوية/إغلاق. **السلسلة المالية تُطلق عند الترحيل، لا عند حفظ المسودة.**
9. **طبقة الالتزام الزمني.** أي بند بتاريخ انتهاء (تأمين/رخصة/إقامة/عقد/ترخيص/جلسة) → **التزام مجدول موحّد** → تذكير ← تصعيد ← **تجديد يُغلق الدورة ويفتح جديدة**. محرّك واحد لكل المسارات.

---

## ٢. الكيان القائد لكل مسار (خريطة التعميم)

نفس النموذج، يتغيّر الكيان القائد فقط. (المرجع: `ghayth-specs` — افتح ملف المسار.)

| المسار | الكيان القائد | أمثلة الوقائع (🔁=متجدّد) | المشتقّ خلفيًا |
|---|---|---|---|
| 💰 مالية *(منفّذ)* | الطرف/الكيان المالي | قبض · صرف · فاتورة · تحصيل · سداد · مقدم | الحساب · القيد · الذمة · الالتزام |
| 👤 موارد بشرية | موظف | سلفة · عهدة · مخالفة · إجازة · مكافأة · 🔁إقامة/رخصة/عقد | ذمة/عهدة · خصم راتب · مطالبة · رصيد · **التزام تجديد** |
| 🚗 أسطول | مركبة | رحلة · وقود · صيانة · قطع · حادث · مخالفة · 🔁تأمين/استمارة/فحص | تكلفة المركبة · تذكرة · عداد · `costBearer` · **التزام تجديد** |
| 🕋 عمرة | موسم/مجموعة/معتمر | باقة · سكن · نقل · إعاشة · تحصيل وكيل · 🔁ترخيص | إيراد/تكلفة المجموعة · ذمة وكيل · ربحية الموسم |
| 🏢 عقارات | عقار/وحدة | إيجار · صيانة · ترميم · مطالبة مستأجر · 🔁عقد/تأمين/صك | إيراد مؤجل · تذكرة · (مستأجر→مطالبة) · **تحصيل دوري + تجديد** |
| ⚖️ قانوني | قضية | أتعاب · رسوم · خبير · مصروف قابل للاسترداد · 🔁جلسة/مهلة | تحميل على القضية · (قابل للاسترداد→مطالبة عميل) · **تذكير جلسة/مهلة** |
| 🏗️ مشاريع | مشروع | مادة · مقاول · مستخلص · مهمة · أمر تغيير | تكلفة المشروع · خصم ميزانية · مطالبة عميل · ضمان |
| 📦 مستودعات | صنف/مستودع | استلام · صرف · جرد · تحويل · تلف · حدّ أدنى | حركة مخزنية · تكلفة بضاعة · تنبيه إعادة طلب |
| 🎫 دعم | تذكرة/عميل | بلاغ · رد · تصعيد · إغلاق | SLA · توجيه/Load Balancing · إشعار |
| 📈 CRM | فرصة/عميل | تواصل · مرحلة بيع · عرض سعر · إغلاق | تحديث المرحلة · مهمة متابعة · (فوز→فاتورة) |

> **القاعدة:** المستخدم يختار الكيان، يُدخل ما حدث، يرفق، يراجع ما فهمه النظام، يحفظ. والنظام خلفيًا يقرّر التجلّي والقيد والسلسلة والالتزام.

---

## ٣. منهجية التطبيق على مسار جديد (دفعة دفعة — لا big-bang)

1. **المسح (قراءة فقط):** افتح **بالكود الفعلي** كل صفحات الإنشاء/الإدخال في المسار (لا بالأسماء). استعمل وكيل Explore للمسح إن لزم.
2. **اكتشاف التكرار:** صفحتان تفعلان نفس الشيء بأسماء مختلفة = مرشّحتان للدمج (مثل: سند صرف = مصروف في المالية).
3. **تحديد الكيان القائد + قدراته + وقائعه** (الجدول §٢).
4. **تصميم «تسجيل الواقعة» الموحّد:** الرأس (مشتقّ آليًا) + جدول البنود (بالوحدة) + التوزيع + المرفقات بمستويين + معاينة المشتقّ + دورة الحياة.
5. **اشتقاق المعالجة** من (الكيان × الواقعة): النوع · الحساب/التصنيف · السلسلة التشغيلية · الالتزام الزمني · التفريع الحوكمي.
6. **تخطيط الهجرة (إن لزمت):** اكتب اسم الجدول + الحقول + السبب + الجداول المتأثرة + عزل المستأجر، واطلب **إذن المالك صراحةً** (الدستور قاعدة ٢). لا تنفّذ قبل الإذن.
7. **التنفيذ دفعة دفعة:** PR مستقلّ لكل دفعة، داخل المسار المالك فقط (صفر كتابة عابرة). **assertion على سطور القيد لأي تغيير يمسّ الدفتر** (الدستور قاعدة ٣). الترحيل عند «الترحيل» لا عند حفظ المسودة.
8. **بوابة المجلس:** شغّل `ghayth-review` على diff الدفعة قبل أي «تم». النجاح = حكم «يُعتمد».

---

## ٤. الحوكمة (موروثة من الدستور — لا تُخرَق)

- **نموذج الحقيقة التشغيلية:** غير المختص لا يلمس الحسابات/الأبعاد التقنية أبدًا.
- **لا migration بلا إذن** + بيان ضرورة (قاعدة ٢). **لا حذف صفحة/جدول/عمود تشغيلي** بلا إثبات موت + PR مستقل.
- **assertion على سطور القيد** لأي تغيير يمسّ الدفتر (قاعدة ٣ المطلقة).
- **عزل المستأجر:** كل جدول يحمل `companyId`/`branchId`؛ كل SELECT يُفلتر بهما (قاعدة ٧). كل جدول عملياتي يحمل `assignmentId` حيث ينطبق.
- **Audit إلزامي** عند الإنشاء/التعديل/الحذف/الاعتماد/الإحالة.
- **استقلال المسارات:** لا تنقل قرارًا/سياسة من مسار قائد إلى خادم. المسار الخادم يقدّم خدمة محدّدة عبر عقد واضح فقط.
- **نظام بروحين:** محرّك واحد + **نموذج بيانات واحد**، واجهتان — تشغيلية («تسجيل واقعة») + قائمة كلاسيكية (للمختص)؛ تختلف **واجهة الإدخال فقط**. **ممنوع ازدواج المنطق.**
- **الاستيراد (إن طُلب):** حتمي (Excel/CSV/بنية مهيكلة — `exceljs` متوفّر) **+** OCR مساعِد داخلي بدرجة ثقة وتأكيد بشري — **بلا تكلفة خارجية**، ويمرّ على **نفس محرّك الاشتقاق** + أثر تدقيق.

---

## ٥. مكوّنات مشتركة قابلة لإعادة الاستخدام (لا تبنِ من جديد)

تحقّق منها بالكود قبل بناء أي شيء — أغلبها موجود في الواجهة المشتركة:
- **`LineItemsTable`** — جدول بنود عام (أعمدة + توسعة سطر + صف مجموع).
- **`AllowCreateDrawer`** — إنشاء صنف/طرف في درج جانبي (لا حوار مصغّر، لا منبثقات).
- **`FinancialAttachmentViewer`** / لوحة مرفقات موسومة — مصفوفة مرفقات بوسم ومُحدِّد.
- **`LineAllocationPanel` / allocation-target** — أبعاد/تخصيص لكل سطر.
- **محرّك الالتزامات (`obligationsEngine` + `cronScheduler`)** — لطبقة الالتزام الزمني.
- **معاينة القيد/المشتقّ (dry-run خادمي)** — يعرض الأثر قبل الحفظ.

> القاعدة الدستورية: **لا تنشئ مكوّنًا جديدًا إن وُجد أصل قائم يمكن إصلاحه أو إحياؤه.**

---

## ٦. قالب المخرجات (لكل تطبيق على مسار)

```md
## المسار: <اسم المسار>
## المسح: صفحات الإدخال المرصودة (بالكود + المسار)
## التكرار المكتشف: <صفحات تُدمج ولماذا>
## الكيان القائد + قدراته + وقائعه
## تصميم «تسجيل الواقعة»: الرأس / البنود / التوزيع / المرفقات / دورة الحياة
## المشتقّ: النوع · الحساب/التصنيف · السلسلة · الالتزام · التفريع
## الهجرة المطلوبة (إن لزمت): الجداول + الحقول + السبب + إذن المالك
## الدفعات: م١ … (PR مستقل + assertion على القيد لكل دفعة)
## حكم المجلس (ghayth-review): يُعتمد / يُعتمد بشرط / يُرفض
## قرارات مطلوبة من إبراهيم (دفتر / معماري / migration فقط)
```

---

## ٧. المرجع العملي والمراجع المرتبطة

- **المالية (النموذج المُنفّذ):** `docs/finance-audit/25_توحيد_صفحات_الإنشاء_المالية.md` + المهمة **#2994** + الهجرة 418 (الجداول الثلاثة: `financial_document_lines` · `financial_attachments` · `financial_line_allocations`).
- **الدستور:** `ghayth-constitution` (المرجع الأعلى — يُحمّل دائمًا).
- **المراجعة:** `ghayth-review` (بوابة المجلس — قبل أي «تم»).
- **المواصفات:** `ghayth-specs` (افتح ملف المسار قبل التنفيذ).
- **الحالة:** `ghayth-state` (أين وصل النظام).

> **الأولوية العليا:** سلامة المعمارية مقدّمة على سرعة التسليم. أي حل سريع يكسر حدود المسارات أو ينسخ منطقًا بين المسارات = خطأ معماري حتى لو عمل وظيفيًا.