# 01 — الوضع الحالي وتحليل الفجوات

**الجمهور:** Product، Engineering، HR Operations  
**الخدمة:** `services/hr` | **الواجهة:** `panel/src/pages/Hr*.jsx`

---

## 1. ملخص تنفيذي

موديول HR في Shawarma House ERP **موجود ويعمل** كـ **نظام سجل موظفين (Employee Master Data)** متقدم، مصمم خصيصاً للامتثال السعودي. لا يزال ينقصه **العمليات التشغيلية** التي تميز ERPNext HRMS: الحضور، الإجازات، الرواتب، التوظيف، التقييم، وبوابة الموظف.

هذا التوثيق يحدد **ما تم بناؤه** بدقة، و**ما ينقص** مقارنةً بـ ERPNext، لاستخدامه كأساس لخطة التطوير.

---

## 2. البنية التقنية الحالية

### 2.1 Backend

| العنصر | التفاصيل |
|--------|----------|
| المسار | `services/hr/` |
| المنفذ | 3407 |
| قاعدة البيانات | `DB_HR_*` (MySQL منفصلة) |
| Gateway | `/api/hr/*` |
| الإصدار | 1.0.0 |

**Endpoints الحالية:**

```
GET  /health
GET  /meta/saudi
GET  /employees
GET  /employees/:id
POST /employees
PUT  /employees/:id
PATCH /employees/:id/status
DELETE /employees/:id
GET/POST/DELETE /employees/:id/documents
GET  /employees/:id/documents/:docId/download
GET  /departments
POST /departments
PUT  /departments/:id
DELETE /departments/:id
GET  /job-titles
POST /job-titles
PUT  /job-titles/:id
DELETE /job-titles/:id
GET  /stats
```

### 2.2 Frontend

| الملف | الدور |
|-------|-------|
| `panel/src/pages/HrPage.jsx` | الصفحة الرئيسية (تبويبات + إحصائيات) |
| `panel/src/pages/HrEmployeeFormPage.jsx` | إنشاء/تعديل موظف |
| `panel/src/pages/HrDepartmentFormPage.jsx` | إنشاء/تعديل قسم |
| `panel/src/pages/HrJobTitleFormPage.jsx` | إنشاء/تعديل مسمى |
| `panel/src/config/hr.js` | التبويبات، الأعمدة، النماذج |
| `panel/src/hooks/useHrPage.js` | تحميل البيانات و CRUD |
| `panel/src/components/hr/*` | Panels و Forms |

**المسارات:** `/admin/hr`, `/admin/hr/employees/new`, `/admin/hr/employees/:id/edit`, إلخ.

**الصلاحيات:** `hr.read`, `hr.write` — دور `branch_manager` يملك `hr.read` فقط.

### 2.3 التخزين

- المستندات: `storage/hr/{companyId}/{employeeId}/`
- الحد الأقصى: 10MB
- الأنواع: PDF، صور، Word
- الفئات: photo, national_id, iqama, passport, contract, gosi, qiwa, visa, medical, ...

---

## 3. ما تم إنجازه (مقارنة ERPNext)

### 3.1 Employee Master — ✅ متقدم

| ERPNext | نظامنا | الحالة |
|---------|--------|--------|
| Employee (بيانات شخصية) | `employees` (~70 حقل) | ✅ |
| Department | `departments` | ✅ |
| Designation (Job Title) | `job_titles` | ✅ |
| Branch | `branch_id` على الموظف | ✅ (ربط بخدمة branches) |
| Reports To | `reports_to_id` | 🟡 حقل موجود، لا UI |
| Employment Type | `contract_type` enum | ✅ |
| Joining Details | hire_date, offer_date, confirmation_date, ... | ✅ |
| Leave Policy link | — | ❌ |
| Holiday List link | — | ❌ |
| Contact Details | phone, email, addresses | ✅ |
| Personal Details | family, health, bio | ✅ |
| Exit Details | relieving_date, reason_for_leaving | ✅ |
| Emergency Contact | emergency_contact_* | ✅ |
| Document attachments | `employee_documents` + upload | ✅ |
| User link | — | ❌ |
| Attendance Device ID | `attendance_device_id` | 🟡 حقل فقط |
| Salary (basic fields) | basic_salary, allowances, IBAN | 🟡 بدون payroll |

### 3.2 حقول سعودية — ✅ نقطة قوة

| الحقل | الغرض |
|-------|-------|
| `national_id` / `border_number` | هوية وطنية / رقم حدود |
| `gosi_number`, `gosi_subscribed` | التأمينات الاجتماعية |
| `iqama_expiry`, `work_permit_expiry` | إقامة وتصريح عمل |
| `qiwa_contract_number` | منصة قوى |
| `is_saudi`, `nationality` | تصنيف الموظف |
| `saudi_region`, `city` | الموقع |
| `contract_type` | أنواع العقود السعودية |
| `/meta/saudi` | بيانات مرجعية |

---

## 4. الفجوات الوظيفية (مقارنة ERPNext v15)

### 4.1 مصفوفة الفجوات

| المجال | ERPNext | نظامنا | الأولوية المقترحة |
|--------|---------|--------|-------------------|
| **Organization Setup** | Department, Branch, Designation, Grade, Employee Group | Dept + Job Title + Branch | P2 — إضافة Grade, Group |
| **Recruitment** | Staffing Plan → Job Opening → Applicant → Interview → Offer | — | P3 |
| **Attendance** | Checkin, Shift, Auto Attendance, Upload | حقل device_id فقط | **P1** |
| **Leave** | Types, Policy, Allocation, Application, Ledger | status `on_leave` فقط | **P1** |
| **Payroll** | Components, Structure, Assignment, Entry, Salary Slip | حقول راتب ثابتة | **P1** |
| **Expense & Travel** | Expense Claim, Advance, Travel Request | — | P3 |
| **Performance** | Appraisal, Goals, Feedback | — | P4 |
| **Training** | Program, Event, Result, Feedback | — | P4 |
| **Lifecycle** | Onboarding, Promotion, Transfer, Separation, F&F | حقول exit جزئية | P2 |
| **Loans & Advances** | Loan Type, Application, Repayment | — | P3 |
| **Tax & Benefits** | Tax Slab, Exemptions, Benefit Claim | — | P2 (سعودي: GOSI) |
| **Compliance** | Gratuity, Statutory reports | — | **P1** (WPS, GOSI) |
| **Self-Service** | Employee Portal, Mobile App | — | P2 |
| **Workflows** | Multi-level approvals | — | P2 |
| **Accounting Integration** | Auto Journal from Salary Slip | — | **P1** |
| **Notifications** | Expiry alerts, approval emails | stats فقط | P2 |
| **Dashboard** | Real KPIs | mock data | P2 |

### 4.2 فجوات تقنية

| الفجوة | التأثير | الحل المقترح |
|--------|---------|--------------|
| لا ربط `users.employee_id` | لا self-service ولا approver | migration في auth + HR |
| Marketing `employee_id` بدون FK | بيانات غير موثوقة | validation عبر HR API |
| Dashboard mock | KPIs خاطئة | ربط `/hr/stats` |
| لا tests | regressions | Jest للـ routes الحرجة |
| لا HR README/API docs | onboarding بطيء | هذا المجلد |

---

## 5. نقاط القوة التي يجب الحفاظ عليها

1. **تخصيص سعودي عميق** — ERPNext يحتاج customization لـ GOSI/Qiwa/WPS؛ نظامنا مبني عليها
2. **Microservices نظيف** — HR معزول؛ سهل التوسع بدون كسر accounting/pos
3. **UI patterns موحدة** — CoreTabs, FormPages, i18n AR/EN جاهزة
4. **Document management** — upload/download مع categories جاهز
5. **Multi-company + branch** — البنية التأسيسية موجودة

---

## 6. توصيات فورية (Quick Wins)

| # | المهمة | الجهد | القيمة |
|---|--------|-------|--------|
| 1 | ربط Dashboard بـ `/hr/stats` | 2h | KPIs حقيقية |
| 2 | UI لـ `reports_to_id` (org chart بسيط) | 1d | هيكل تنظيمي |
| 3 | إشعارات انتهاء إقامة/جواز (notifications service) | 2d | compliance |
| 4 | `employee_id` على users | 1d | أساس self-service |
| 5 | validation لـ marketing employee refs | 4h | data integrity |

---

## 7. الخلاصة

النظام **ليس فارغاً** — بل يملك **أساس Employee Master قوي** يتفوق على ERPNext الافتراضي في السياق السعودي. الفجوة الحقيقية في **HR Operations**: حضور → إجازات → رواتب → محاسبة → امتثال.

**المرحلة 1 من خطة التطوير** يجب أن تركز على: User↔Employee، Leave، Attendance، ثم Payroll + WPS (انظر [03-HR_DEVELOPMENT_ROADMAP.md](./03-HR_DEVELOPMENT_ROADMAP.md)).