# 03 — خارطة طريق تطوير HR

**الجمهور:** Product، Engineering، Management  
**المدة الإجمالية المقترحة:** 6–9 أشهر (فريق 2–3 مطورين)  
**المنهجية:** مراحل incrementally shippable — كل مرحلة تُسلّم قيمة تشغيلية

---

## 1. مبادئ الأولوية

1. **Compliance first** — GOSI/WPS/انتهاء الوثائق قبل features "nice to have"
2. **Operations before strategy** — حضور + إجازات + رواتب قبل توظيف + تقييم
3. **Reuse existing patterns** — نفس هيكل accounting/waste
4. **Ship early** — MVP لكل مرحلة قبل الكمال

---

## 2. نظرة عامة على المراحل

```
Phase 0 ✅  Employee Master (مكتمل)
Phase 1     Foundation + Leave + Attendance
Phase 2     Payroll + Accounting + WPS
Phase 3     Lifecycle + Self-Service
Phase 4     Recruitment + Training
Phase 5     Performance + Advanced Analytics
```

| المرحلة | المدة | القيمة للأعمال |
|---------|-------|----------------|
| Phase 0 | ✅ Done | سجل موظفين + مستندات |
| Phase 1 | 6–8 أسابيع | تشغيل يومي: حضور وإجازات |
| Phase 2 | 6–8 أسابيع | رواتب + WPS + محاسبة |
| Phase 3 | 4–6 أسابيع | onboarding/separation + portal |
| Phase 4 | 4–6 أسابيع | توظيف + تدريب |
| Phase 5 | 4+ أسابيع | تقييم + تقارير متقدمة |

---

## 3. Phase 0 — Employee Master ✅ (مكتمل)

**الحالة:** منجز

- [x] employees, departments, job_titles
- [x] Saudi compliance fields
- [x] Document upload/download
- [x] Admin UI (HrPage, forms)
- [x] Stats endpoint
- [x] Permissions hr.read / hr.write

**Quick wins متبقية (لا تنتظر Phase 1):**

- [ ] Dashboard KPIs من `/hr/stats`
- [ ] Org chart UI لـ `reports_to_id`
- [ ] Notifications لانتهاء iqama/passport/contract

---

## 4. Phase 1 — Foundation + Leave + Attendance

**الهدف:** تمكين العمليات اليومية — "من يحضر؟" و"من في إجازة؟"

**المدة:** 6–8 أسابيع

### 4.1 Sprint 1.1 — User ↔ Employee Link (أسبوع 1)

| المهمة | Backend | Frontend |
|--------|---------|----------|
| `employee_id` على users | auth migrate | user form |
| API: GET employees without user | hr route | dropdown |
| API: link/unlink | hr + auth | employee form |
| Permission: self profile | hr.read own | — |

**معيار القبول:** مستخدم مرتبط بموظف يرى بياناته الأساسية.

### 4.2 Sprint 1.2 — Leave Management (أسابيع 2–4)

| المهمة | التفاصيل |
|--------|----------|
| Leave Types | سنوية، مرضية، بدون راتب، طارئة |
| Holiday Lists | عطل Eid + weekly off |
| Leave Policy | policy per company/branch |
| Leave Allocation | تخصيص سنوي + bulk |
| Leave Application | create + approve/reject |
| Leave Ledger | audit trail |
| Notifications | approver + employee |

**ERPNext reference:** Leave Type → Policy → Allocation → Application → Ledger

**معيار القبول:**
- موظف يطلب إجازة من البanel
- مدير يوافق/يرفض
- الرصيد يُحدَّث تلقائياً
- تقرير أرصدة الإجازات

### 4.3 Sprint 1.3 — Attendance (أسابيع 5–7)

| المهمة | التفاصيل |
|--------|----------|
| Shift Types | صباحي/مسائي/ليلي + grace |
| Shift Assignment | per employee |
| Employee Checkin | API import (device_id) |
| Attendance | daily status |
| Auto Attendance | checkins → present/absent |
| Manual override | HR bulk mark |
| Reports | daily, monthly, late |

**ERPNext reference:** Shift Type → Assignment → Checkin → Auto Attendance

**معيار القبول:**
- استيراد checkins من CSV/API
- attendance يومي لكل فرع
- ربط approved leave → On Leave status

### 4.4 Sprint 1.4 — Integration & Polish (أسبوع 8)

- [ ] `/hr/stats` موسّع (leave pending, absent today)
- [ ] Branch filter على attendance/leave
- [ ] i18n كامل للتبويبات الجديدة
- [ ] Tests للـ leave approval flow

---

## 5. Phase 2 — Payroll + Accounting + WPS

**الهدف:** "كم ندفع؟" و"كيف نُحوّل للبنك؟"

**المدة:** 6–8 أسابيع  
**تبعيات:** Phase 1 (attendance + leave → LWP)

### 5.1 Sprint 2.1 — Salary Structure (أسابيع 1–2)

| المهمة | التفاصيل |
|--------|----------|
| Salary Components | Basic, Housing, Transport, GOSI emp, GOSI er |
| Salary Structure | template + formulas |
| Assignment | per employee + effective date |
| Migrate existing | basic_salary fields → assignment |

### 5.2 Sprint 2.2 — Payroll Run (أسابيع 3–5)

| المهمة | التفاصيل |
|--------|----------|
| Payroll Run | select period + employees |
| Salary Slip generation | compute from structure |
| LWP deduction | from leave + attendance |
| Additional Salary | bonus, deduction one-time |
| Payslip PDF | print format |
| Approval workflow | HR → Finance |

### 5.3 Sprint 2.3 — Accounting Integration (أسابيع 5–6)

| المهمة | التفاصيل |
|--------|----------|
| Journal Entry | debit expense, credit payable |
| GOSI payable accounts | employer + employee |
| Payment recording | link to accounting payment |
| Pool to accounting service | like POS pattern |

### 5.4 Sprint 2.4 — Saudi Compliance Export (أسابيع 7–8)

| المهمة | التفاصيل |
|--------|----------|
| WPS file export | SIF format |
| GOSI contribution report | monthly |
| End of Service calculator | Saudi labor law |
| Payslip email | optional |

**معيار القبول:**
- payroll run لشهر كامل
- salary slips صحيحة مع GOSI
- WPS file جاهز للبنك
- journal entry في accounting

---

## 6. Phase 3 — Lifecycle + Self-Service

**الهدف:** إدارة انتقالات الموظف + تمكين الموظف

**المدة:** 4–6 أسابيع

### 6.1 Employee Lifecycle

| العملية | المهام |
|---------|--------|
| Onboarding | checklist + tasks |
| Promotion | record + update employee |
| Transfer | branch/department change |
| Separation | workflow + exit checklist |
| F&F Settlement | calculate dues |

### 6.2 Employee Self-Service Portal

| الميزة | الوصف |
|--------|-------|
| My Profile | view (limited edit) |
| My Payslips | download |
| Leave Request | apply + track |
| My Attendance | view history |
| My Documents | view uploaded |

**تقني:** routes جديدة `/api/hr/me/*` + panel section أو PWA منفصل

---

## 7. Phase 4 — Recruitment + Training

**المدة:** 4–6 أسابيع

### 7.1 Recruitment (MVP)

- Job Opening (internal)
- Job Applicant tracking
- Simple pipeline (Applied → Interview → Offer → Hired)
- Create Employee from Applicant

**لا نبني:** public job portal في هذه المرحلة (optional later)

### 7.2 Training

- Training Program catalog
- Training Event scheduling
- Attendance + basic feedback

---

## 8. Phase 5 — Performance + Analytics

**المدة:** 4+ أسابيع (lower priority)

- Appraisal templates + cycles
- Goals/KRAs
- HR Dashboard analytics
- Headcount reports, turnover, cost per employee
- Saudization report

---

## 9. جدول زمني (Gantt مبسّط)

```
2026 Q2          Q3              Q4              2027 Q1
│────────────────│───────────────│───────────────│──────────│
│ Phase 1        │ Phase 2       │ Phase 3       │ Phase 4-5│
│ Leave+Attend   │ Payroll+WPS   │ Lifecycle+SS  │ Recruit  │
│                │               │               │ Perf     │
```

---

## 10. تعريف MVP لكل مرحلة

| Phase | MVP Statement |
|-------|---------------|
| 1 | "HR يعرف من حضر ومن في إجازة اليوم" |
| 2 | "HR يُصدر رواتب شهرية + WPS" |
| 3 | "الموظف يرى payslip ويطلب إجازة" |
| 4 | "HR يتتبع متقدم حتى التوظيف" |
| 5 | "الإدارة ترى أداء وتحليلات HR" |

---

## 11. المخاطر والتخفيف

| الخطر | التخفيف |
|-------|---------|
| Payroll errors | parallel run مع Excel أول شهرين |
| Biometric integration | CSV import أولاً، API لاحقاً |
| Scope creep | MVP per phase، defer portal/recruitment |
| Accounting mismatch | shared chart of accounts review |
| Saudi law changes | configurable EOS/GOSI rates |

---

## 12. Definition of Done (لكل feature)

- [ ] Migration في `services/hr/src/db/migrate.js`
- [ ] Routes + lib validators/formatters
- [ ] Permissions في auth
- [ ] API methods في `panel/src/api/client.js`
- [ ] UI: config + panel + form page
- [ ] i18n AR/EN
- [ ] Manual test checklist
- [ ] توثيق endpoint في `05-HR_API_SPEC.md`

---

## 13. الخطوة التالية

**ابدأ Phase 1 Sprint 1.1:** ربط User ↔ Employee  
راجع: [04-HR_DATA_MODEL_SPEC.md](./04-HR_DATA_MODEL_SPEC.md) § User Link  
راجع: [05-HR_API_SPEC.md](./05-HR_API_SPEC.md) § Planned Endpoints