# 02 — مرجع ERPNext HR Module

**الغرض:** مرجع وظيفي لتخطيط ميزات HR في نظامنا — **ليس** لنسخ ERPNext حرفياً  
**المصدر:** ERPNext v15 HRMS / Frappe HR  
**الجمهور:** Product، Engineering

---

## 1. نظرة عامة على ERPNext HR

ERPNext HRMS نظام **full-suite** يغطي دورة حياة الموظف من التوظيف حتى التقاعد. يعتمد على **DocTypes** (نماذج بيانات) مترابطة مع **Workflows** للموافقات و**Accounting** للرواتب.

```
┌─────────────────────────────────────────────────────────────────┐
│                    ERPNext HR Module Map                        │
├─────────────┬─────────────┬─────────────┬───────────────────────┤
│  Setup      │  Operations │  Lifecycle  │  Finance              │
│  ─────────  │  ──────────  │  ─────────  │  ───────              │
│  Employee   │  Attendance │  Onboarding │  Salary Component     │
│  Department │  Leave      │  Promotion  │  Salary Structure     │
│  Designation│  Shift      │  Transfer   │  Payroll Entry        │
│  Branch     │  Expense    │  Separation │  Salary Slip          │
│  Grade      │  Training   │  F&F Settle │  Journal Entry        │
│  Holiday    │  Appraisal  │  Exit Int.  │  WPS / Statutory      │
└─────────────┴─────────────┴─────────────┴───────────────────────┘
         │              │              │              │
         └──────────────┴──────────────┴──────────────┘
                    Employee Master (Hub)
```

---

## 2. المكونات الرئيسية (13 مجال)

### 2.1 Employee Master & Organization Setup

**DocTypes:** Employee, Department, Branch, Designation, Employment Type, Employee Grade, Employee Group

| الكيان | الوظيفة | ملاحظات لنظامنا |
|--------|---------|-----------------|
| Employee | السجل المركزي لكل موظف | ✅ موجود — `employees` |
| Department | وحدة تنظيمية | ✅ `departments` |
| Designation | المسمى الوظيفي | ✅ `job_titles` |
| Branch | الفرع | ✅ `branch_id` |
| Employee Grade | الدرجة الوظيفية | 🟡 `job_grade` string |
| Employee Group | تجميع للسياسات | ❌ |
| Employment Type | نوع التوظيف | ✅ `contract_type` |

**Employee Master في ERPNext يتضمن:**
- بيانات شخصية وتواصل
- Department, Designation, Grade, Reports To
- Leave Policy + Holiday List (روابط)
- Salary Structure Assignment (رابط)
- User ID (ربط بحساب النظام)
- Attendance Device ID
- Joining / Exit details
- Emergency Contact, Health Insurance, Bio

---

### 2.2 Recruitment (التوظيف)

**DocTypes:** Staffing Plan → Job Requisition → Job Opening → Job Applicant → Interview → Interview Feedback → Job Offer → Employee

**سير العمل:**

```
Staffing Plan (تخطيط القوى)
    ↓
Job Opening (نشر الوظيفة — portal)
    ↓
Job Applicant (متقدم + CV)
    ↓
Interview + Feedback (جولات + تقييم)
    ↓
Job Offer (عرض عمل)
    ↓
Employee (إنشاء موظف من العرض)
```

**ميزات:**
- Job Portal على الموقع
- تتبع pipeline (Applied → Shortlisted → Interview → Offer → Hired/Rejected)
- موافقات عبر Workflow
- إحصائيات (أيام التوظيف، مصادر المتقدمين)

---

### 2.3 Attendance & Shift Management

**DocTypes:** Employee Checkin, Attendance, Shift Type, Shift Assignment, Auto Attendance

| الكيان | الوظيفة |
|--------|---------|
| Employee Checkin | سجل دخول/خروج (timestamp + IN/OUT) |
| Attendance | حالة يومية (Present/Absent/Half Day/On Leave) |
| Shift Type | تعريف الوردية (بداية، نهاية، grace period) |
| Shift Assignment | ربط موظف بوردية |
| Auto Attendance | تحويل checkins → attendance تلقائياً |

**التكامل:**
- أجهزة البصمة (ZKTeco وغيرها) عبر API → Employee Checkin
- ERPNext v15: endpoint `add_log_based_on_employee_field`
- تقارير: Shift Attendance (تأخير، خروج مبكر، ساعات العمل)

**التأثير على Payroll:** overtime، LWP (Leave Without Pay)

---

### 2.4 Leave Management

**DocTypes:** Leave Type, Holiday List, Leave Policy, Leave Policy Assignment, Leave Allocation, Leave Application, Compensatory Leave, Leave Encashment, Leave Ledger Entry

| الكيان | الوظيفة |
|--------|---------|
| Leave Type | تعريف نوع الإجازة (سنوية، مرضية، بدون راتب...) |
| Holiday List | العطل الرسمية والأسبوعية |
| Leave Policy | حزمة قواعد (أنواع + أرصدة) |
| Leave Allocation | تخصيص رصيد لموظف/فترة |
| Leave Application | طلب إجازة + موافقة |
| Leave Ledger | سجل حركات الرصيد (audit trail) |
| Leave Encashment | صرف رصيد إجازة نقداً |

**سير العمل:**

```
Leave Application (موظف)
    → Approver (مدير/HR)
    → Approved/Rejected
    → Leave Ledger Entry (خصم الرصيد)
    → Attendance (On Leave)
    → Payroll (LWP إن لزم)
```

**Leave Control Panel:** تخصيص جماعي للأرصدة

---

### 2.5 Payroll & Compensation

**DocTypes:** Salary Component, Salary Structure, Salary Structure Assignment, Payroll Period, Payroll Entry, Salary Slip, Additional Salary

| الكيان | الوظيفة |
|--------|---------|
| Salary Component | عنصر راتب (Basic, HRA, GOSI, Tax...) |
| Salary Structure | قالب يجمع المكونات + formulas |
| Salary Structure Assignment | ربط موظف بقالب + effective date |
| Payroll Entry | دفعة رواتب لشهر/فترة |
| Salary Slip | كشف راتب فردي |
| Additional Salary | مكافآت/خصومات لمرة واحدة |

**Salary Component flags:**
- Earning vs Deduction
- Tax Applicable
- Depends on LWP (تناسب مع أيام الغياب)
- Formula / Condition
- Account (للمحاسبة)

**سير Payroll:**

```
Salary Components (setup)
    → Salary Structure (template)
    → Assignment per Employee
    → Payroll Entry (select period + employees)
    → Generate Salary Slips
    → Review → Submit
    → Journal Entry (Accounting)
    → Payment / WPS export
```

---

### 2.6 Expense & Travel

**DocTypes:** Expense Claim, Expense Claim Type, Employee Advance, Travel Request

- مطالبات مصروفات مع موافقة
- سلف موظفين (تُخصم من الراتب)
- ربط بالمحاسبة (Accounts Payable)

---

### 2.7 Performance Management

**DocTypes:** Appraisal Template, Appraisal, Appraisal Cycle, Goal, Employee Performance Feedback

- KRAs مع أوزان
- Self-assessment + Manager review
- Appraisal Overview Report
- ربط بالترقيات والزيادات

---

### 2.8 Training

**DocTypes:** Training Program, Training Event, Training Result, Training Feedback

- جدولة تدريبات
- تسجيل حضور ونتائج
- تقييم فعالية التدريب

---

### 2.9 Employee Lifecycle

**DocTypes:** Employee Onboarding, Employee Promotion, Employee Transfer, Employee Separation, Exit Interview, Full and Final Settlement

| العملية | الوظيفة |
|---------|---------|
| Onboarding | checklist مهام (IT, HR, documents) |
| Promotion | تغيير مسمى/درجة + effective date |
| Transfer | نقل قسم/فرع |
| Separation | استقالة/إنهاء + notice period |
| Exit Interview | مقابلة خروج |
| F&F Settlement | تسوية نهائية (راتب، إجازات، مكافأة) |

---

### 2.10 Loans & Advances

**DocTypes:** Loan Type, Loan Application, Loan

- قروض موظفين
- جدول سداد
- خصم تلقائي من Salary Slip

---

### 2.11 Tax & Benefits

**DocTypes:** Income Tax Slab, Employee Tax Exemption Declaration, Benefit Application, Benefit Claim

- شرائح ضريبية (حسب الدولة)
- مزايا مرنة (fuel, meal vouchers...)
- **للسعودية:** GOSI employer/employee contributions

---

### 2.12 Compliance & Separation

**DocTypes:** Gratuity, Gratuity Rule, Full and Final Settlement

- مكافأة نهاية خدمة (Saudi: حسب نظام العمل)
- تقارير امتثال (WPS, GOSI files)
- تسوية كاملة عند المغادرة

---

### 2.13 Self-Service & Mobile

- Employee Portal: payslips, leave requests, expense claims
- Frappe HR Mobile App (v15): check-in geotag, leave, payslips
- Email notifications على كل workflow

---

## 3. Workflows & Approvals

ERPNext يستخدم **Workflow Engine** لموافقات متعددة المستويات:

```
Draft → Pending Manager → Pending HR → Approved
```

**أمثلة:**
- Leave > 5 days: Manager → HR
- Job Offer above threshold: HR → CEO
- Expense Claim: Employee → Manager → Accounts

**Leave Approver:** role + user permission per department

---

## 4. التكاملات في ERPNext

| النظام | التكامل |
|--------|---------|
| Accounting | Journal Entry من Salary Slip |
| Projects | Timesheets → Payroll |
| Assets | أصول موظف عند الخروج |
| Website | Job Portal |
| Notifications | Email + in-app |

---

## 5. ما نأخذه من ERPNext vs ما نخصصه

### نأخذ (Best Practices)

| المبدأ | السبب |
|--------|-------|
| Employee كـ Hub | كل شيء يرتبط بموظف واحد |
| Leave Ledger | audit trail للأرصدة |
| Salary Component model | مرونة الرواتب |
| Payroll Entry batch | معالجة جماعية |
| Lifecycle docs | Promotion/Transfer/Separation كسجلات |
| Approval workflows | configurable multi-level |

### نخصص (Saudi / Restaurant)

| المجال | التخصيص |
|--------|---------|
| Compliance | GOSI, Qiwa, WPS, Saudization |
| Shifts | ورديات مطاعم (صباحي/مسائي/ليلي) |
| Branch-heavy | multi-branch restaurant ops |
| Simpler recruitment | مطاعم ≠ corporate HR |
| No Income Tax Slab | لا ضريبة دخل على الأفراد في SA |
| End of Service | حسب نظام العمل السعودي |

---

## 6. DocTypes → جداول مقترحة (mapping)

| ERPNext DocType | جدول مقترح في نظامنا |
|-----------------|---------------------|
| Leave Type | `leave_types` |
| Holiday List | `holiday_lists` + `holiday_dates` |
| Leave Policy | `leave_policies` + `leave_policy_lines` |
| Leave Allocation | `leave_allocations` |
| Leave Application | `leave_applications` |
| Leave Ledger Entry | `leave_ledger_entries` |
| Shift Type | `shift_types` |
| Shift Assignment | `shift_assignments` |
| Employee Checkin | `employee_checkins` |
| Attendance | `attendances` |
| Salary Component | `salary_components` |
| Salary Structure | `salary_structures` + `salary_structure_lines` |
| Salary Structure Assignment | `salary_assignments` |
| Payroll Entry | `payroll_runs` |
| Salary Slip | `salary_slips` + `salary_slip_lines` |
| Job Opening | `job_openings` |
| Job Applicant | `job_applicants` |
| Employee Separation | `employee_separations` |

التفاصيل الكاملة في [04-HR_DATA_MODEL_SPEC.md](./04-HR_DATA_MODEL_SPEC.md).

---

## 7. مراجع

- [ERPNext HR Guide](https://frappe.io/erpnext/erp-guide/human-resource-management)
- [ERPNext HRMS](https://frappe.io/erpnext/hrms/employee-management-software)
- [Employee DocType Manual](https://docs.frappe.io/erpnext/v13/user/manual/en/human-resources/employee)
- [ClefinCode v15 Deep Dive](https://clefincode.com/blog/global-digital-vibes/en/erpnext-v15-hr-module-detailed-overview-and-deep-dive)