# SenedERP — نظام تشغيل منظمات غير ربحية (NGO ERP)

هذا المستودع يضم **منصة متعددة المستأجرين** (كل منظمة بياناتها وإعداداتها منفصلة) لإدارة العمليات التشغيلية للمنظمات غير الربحية: **المنح والميزانيات** كمركز، مع **الموارد البشرية** (إجازات، حضور، رواتب)، **المشتريات**، **سير الموافقات**، **السفر**، **التوظيف**، وإعدادات مساحة العمل.

التقنية:

- **الواجهة الخلفية (API):** Laravel (PHP)، قاعدة بيانات، مهاجرات، سياسات وصول.
- **واجهة الويب:** Laravel **Blade** + **Tailwind** عبر **Vite** من جذر المستودع (`resources/views/` و`package.json`)، وهي الواجهة الرسمية للوحة والصفحات.

---

## 1. الفكرة العامة: من يفعل ماذا؟

| فاعل | ماذا يفعل في النظام |
|------|----------------------|
| **موظف / مستخدم مساحة العمل** | يقدّم طلبات (إجازة، نماذج ذاتية، سفر، …)، يتابع الحالة، يستلم إشعارًا عند القرار. |
| **معتمد (موافق)** | يرى صندوق المهام «Inbox»، يراجع السياق، يوافق أو يرفض مع **سبب إلزامي** عند الرفض (حيث ينطبق ذلك). |
| **النظام** | يحفظ الحالات، يربط الطلب بسير موافقة، يرسل إشعارات داخل التطبيق، يحدّث السجلات (مثل حالة الإجازة أو أمر الشراء). |
| **مسؤول المنظمة / HR / مالية** | يضبط الموديولات، تعريفات سير الموافقة، أنواع الإجازة، السياسات، والمستخدمين. |

التصميم يميل إلى **وضوح المسار**: من يقدّم → من يراجع → ماذا يحدث بعد القرار، مع صفحة **«طلباتي»** (`/me/requests`) لعرض طلبات المستخدم المرتبطة بسير موافقة.

---

## 2. المستأجر (Tenant) والموديولات

كل **منظمة** (Organisation) لها:

- مستخدمون ضمن نفس المنظمة.
- **موديولات** تُفعّل أو تُعطّل من الإعدادات (مثل: `hr`، `finance`، `procurement`، `approvals`، `travel`، `grants`، `hiring`، `workplace`، `notifications`، …).

إذا كان موديولًا معطّلًا، تختفي واجهاته وغالبًا تُقيّد واجهات البرمجة (API) المرتبطة به. سير الموافقات يرتبط بموديول **Approvals**؛ أنواع المستندات في الموافقة ترتبط أيضًا بموديولات أخرى (مثلاً طلب شراء يحتاج **Finance**، أمر شراء يحتاج **Procurement**).

---

## 3. سير الموافقات (Workflows / Approvals) — القلب التشغيلي

### 3.1 المكوّنات

1. **تعريف سير موافقة (Approval Definition)**  
   يُنشأ من **الإعدادات → الموافقات** (`/settings/approvals`): اسم، نوع المستند (`document_type`)، نشط/غير نشط، و**خطوات** متتابعة (أو متوازية حيث يدعم المحرك).

2. **خطوة (Step)**  
   لكل خطوة نوع مكلّف مثل:

   - مستخدم محدد (`user`)، أو
   - دور داخل المنظمة (`role`)، أو
   - **المدير المباشر** (`line_manager`) لمقدّم الطلب.

3. **مثيل سير موافقة (Approval Instance)**  
   عند بدء الموافقة على مستند حقيقي (مثلاً طلب إجازة)، يُنشأ «مثيل» يربط: المنظمة + التعريف + المستند (`subject_type` / `subject_id`) + حالة (`pending` / `approved` / `rejected`) + من بدأ العملية (`initiated_by`).

4. **خطوات المثيل (Instance Steps)**  
   تسجّل من نُفِّذت له الخطوة، الحالة (`pending` / `approved` / `rejected`)، التوقيع الرقمي عند الموافقة حيث ينطبق، والتعليق عند الرفض.

### 3.2 رحلة مقدّم الطلب

- يُنشئ مستندًا (مثل **مسودة إجازة** من `/me/leave/new`).
- يكمل البيانات ثم **يُرسل للموافقة** (من صفحة تفاصيل الإجازة يختار تعريف سير الموافقة إن لزم).
- يتابع من **«طلباتي»** أو قوائم النطاق (مثل **إجازاتي**).
- عند **الموافقة النهائية أو الرفض** يصل **إشعار داخل التطبيق** للمُنشئ مع ملخص وسبب عند الرفض ورابط للعودة للمستند.

### 3.3 رحلة المعتمد

- **صندوق الموافقات** `/approvals/inbox`: قائمة بالمهام **الأقدم أولًا**، مع تمييز **تأخر SLA** (مثلاً تجاوز 48 ساعة منذ وقت مرجعي) عند الحاجة.
- يمكن **فتح السجل** للمراجعة الكاملة، أو استخدام **إجراءات سريعة** (موافقة / رفض) مع التحقق من **توقيع الموافقة** المحفوظ في الملف الشخصي حيث ينطبق.
- بعد القرار، إن وُجدت مهمة تالية لنفس المعتمد، يمكن توجيهه تلقائيًا لصفحة المراجعة التالية (`next_instance_uuid` من الـ API).

### 3.4 قواعد مهمة

- **الرفض** يتطلب **سببًا** (نصًا كافٍ الطول كما يفرضه الـ API).
- **الموافقة** قد تتطلب **توقيعًا معتمدًا** محفوظًا تحت **Me → Approval signature** حسب إعدادات التوقيع.
- تتزامن حالات بعض الكيانات مع نتيجة المثيل (مثلاً حقل حالة **طلب الإجازة** بعد اكتمال الموافقة أو الرفض).

---

## 4. أنواع المستندات التي يمكن ربطها بسير الموافقة

| نوع المستند (مثال API) | الوحدة التقريبية | ملاحظة |
|------------------------|------------------|---------|
| `leave_request` | HR | إجازات الموظفين. |
| `purchase_request` | Finance | طلب شراء مرتبط بمنح/ميزانية. |
| `purchase_order` | Procurement | أمر شراء. |
| `goods_receipt` | Procurement | استلام بضائع/خدمات مرتبط بأمر شراء. |
| `payroll_period_run` | HR | تشغيل/تقديم كشف رواتب شهري للموافقة. |
| `business_trip` | Travel | سفر/تخليص سفر. |
| `hiring_requisition` | Hiring | طلب توظيف. |
| `hiring_final_decision` | Hiring | قرار توظيف نهائي. |
| `hiring_offer` | Hiring | عرض وظيفي. |
| نماذج البوابة (انظر الجدول التالي) | HR / Workplace | نماذج ذاتية من `/me/forms/...`. |

التعريفات الظاهرة في الإعدادات تعتمد على **الموديولات المفعّلة** للمنظمة.

---

## 5. النماذج (Forms) — بوابة الموظف `/me/forms`

هذه ليست «منشئ نماذج حر» عامًا؛ بل **نماذج جاهزة** لكل نوع، مع مسارات API وواجهات مخصصة تحت:

`/me/forms/[slug]`

الأنواع المعرّفة في الإعدادات (`config/hr_self_forms.php` وواجهة `me-self-service-forms`) تشمل على سبيل المثال:

| المسار التقريبي | الغرض |
|-----------------|--------|
| `wfh` | إعلان يوم عمل عن بُعد. |
| `mileage` | سجل مسافة/رحلة. |
| `bank-change` | طلب تغيير بيانات بنكية. |
| `grievance` | قناة صوت الموظف (حسب سياسة المنظمة). |
| `suggestion` | اقتراح. |
| `overtime` | طلب ساعات إضافية. |
| `certification` | شهادة/اعتماد. |
| `training-pulse` | تغذية راجعة سريعة عن تدريب. |
| `desk` | حجز مكتب. |
| `visitor` | زائر. |
| `equipment` | بلاغ معدات. |
| `union-ack` | إقرار/إقرارات نقابية. |
| `dei-self-id` | تعريف ذاتي متعلق بالتنوع والشمول. |
| `parental-return` | عودة من إجازة والدية. |
| `wellbeing-preferences` | تفضيلات رفاهية. |

**تفعيل/إخفاء** كل نموذج يتحكم به إعداد المنظمة (حقول `hr_self_forms` على مستوى المنظمة) بحيث لا تظهر بلاطات النماذج المعطّلة في لوحة الموظف.

عندما يتطلب النموذج **موافقة**، يُربط بمثيل موافقة من نوع `document_type` المقابل (مثل `wfh_declaration`, `mileage_log`, …) كما في `ApprovalPortalSubjectRegistry` و `ApprovalDefinitionModuleGate`.

---

## 6. الإجازات (Leave) — مثال سير كامل

1. **جديد** من `/me/leave/new`: يختار النوع والتواريخ والملاحظات ويحفظ **مسودة**.
2. من **صفحة الطلب** (`/me/leave/[uuid]`): يراجع الرصيد (حسب السنة والنوع)، يختار **تعريف موافقة** إن وُجدت عدة، ثم **يُرسل للموافقة**.
3. يظهر الطلب لدى المعتمدين في **Inbox** أو من صفحة HR للإجازة حسب الصلاحيات.
4. بعد القرار: تحديث الحالة، إشعار للمُنشئ، ويمكن تصدير PDF حسب الحالة.

---

## 7. المشتريات والمنح (Procurement / Grants)

- **طلبات الشراء** مرتبطة بمنح وخطوط ميزانية (حسب إعداد المنظمة).
- **أوامر الشراء** و**الاستلامات** يمكن أن تمر بموافقات متعددة المراحل.
- واجهات المشتريات تحت `/procurement` مع مسارات لتفاصيل الطلبات وأوامر الشراء والمهام.

---

## 8. الإشعارات و«طلباتي»

- **إشعارات داخل التطبيق** (`/notifications`) عند تفعيل موديول الإشعارات: مثلاً «مطلوب موافقة» مع عنوان وجسم أوضح ورابط مباشر للسجل؛ و«نتيجة الموافقة» للمُنشئ عند الانتهاء.
- **طلباتي** `/me/requests`: تجمع طلبات المستخدم المرتبطة بمثيلات موافقة بدأها (`GET /api/me/approval-submissions`) مع الحالة والرابط المناسب.

---

## 9. الأدوار والوصول (باختصار)

- يوجد تكامل مع **كتالوج صلاحيات** (RBAC) في أجزاء من النظام؛ بعض العمليات تتطلب امتيازًا صريحًا (مثل `WORKFLOW_APPROVE` لصندوق الموافقات وتنفيذ القرار).
- إخفاء عنصر في القائمة لا يغني عن التحقق في الـ API — الحماية نهائية من الخادم.

---

## 10. هيكل المستودع (للمطورين)

| المسار | المحتوى |
|--------|---------|
| `app/` | منطق Laravel، نماذج، خدمات (`ApprovalEngine`, `InAppNotifier`, …)، متحكمات API. |
| `routes/api.php` | مسارات REST للواجهة. |
| `database/migrations/` | مخطط قاعدة البيانات. |
| `config/payroll/rules/` | قواعد رواتب حسب الدولة (YAML). |
| `.cursor/skills/` | مهارات مساعدة للتصميم (مثل operational-ux). |

---

## 11. التشغيل السريع محليًا (مختصر)

**الخلفية:** نسخ `.env`، `composer install`، `php artisan key:generate`، `php artisan migrate`.

**الواجهة:** من جذر المستودع — `npm ci`، ثم `npm run dev` أو `npm run build` (Vite لـ Blade).

تفاصيل إضافية بالإنجليزية في `README.md` في جذر المستودع.

---

## 12. الخلاصة

SenedERP يجمع **البيانات المالية والبرامجية** (منح، ميزانيات، مشتريات) مع **حياة الموظف اليومية** (إجازة، حضور، نماذج، سفر) تحت **سير موافقات موحّد** قابل للضبط لكل منظمة. فهم **الموديولات + تعريفات الموافقة + أنواع المستندات + بوابة `/me/forms`** يكفي غالبًا لرسم أي عملية تشغيلية داخل النظام.

إذا رغبت لاحقًا في نسخة **PDF** أو **مخططات** (Mermaid) لكل وحدة، يمكن توليدها من نفس المحتوى كملحق.
