# 06 — الامتثال السعودي (Saudi Compliance)

**الجمهور:** HR Operations، Backend، Finance  
**السياق:** مطاعم Shawarma House — multi-branch — موظفون سعوديون وغير سعوديين

---

## 1. نظرة عامة

نظامنا مبني **أصلاً** للامتثال السعودي. Phase 0 يغطي **تخزين البيانات**؛ المراحل القادمة تضيف **العمليات والتقارير** المطلوبة للجهات الرقابية.

```
┌────────────────────────────────────────────────────────────┐
│              Saudi HR Compliance Stack                     │
├──────────────┬──────────────┬──────────────┬───────────────┤
│    GOSI      │    Qiwa      │     WPS      │  Labor Law    │
│  التأمينات   │    قوى       │  حماية الأجور│  نظام العمل   │
├──────────────┴──────────────┴──────────────┴───────────────┤
│  Muqeem/Iqama tracking  │  Saudization  │  EOS Gratuity   │
└────────────────────────────────────────────────────────────┘
```

---

## 2. GOSI — التأمينات الاجتماعية

### 2.1 الوضع الحالي ✅

| الحقل | الجدول | الغرض |
|-------|--------|-------|
| `gosi_number` | employees | رقم الاشتراك |
| `gosi_subscribed` | employees | مشترك/غير مشترك |
| `is_saudi` | employees | تحديد نسبة GOSI |
| `national_id` | employees | للسعوديين |
| `border_number` | employees | لغير السعوديين |

### 2.2 المطلوب — Phase 2

#### نسب GOSI (2026 — قابلة للتحديث)

| الفئة | حصة الموظف | حصة صاحب العمل | على |
|-------|------------|----------------|-----|
| سعودي | 9% | 9% | الأجر الخاضع |
| غير سعودي | 0% | 2% (أخطار مهنية) | الأجر الخاضع |

**الأجر الخاضع:** Basic + Housing (حسب سياسة الشركة — configurable)

#### Salary Components

```
gosi_employee  → deduction 9% (Saudi only)
gosi_employer  → employer cost 9% / 2%
gosi_payable   → liability account
```

#### تقرير GOSI الشهري

| العمود | المصدر |
|--------|--------|
| رقم الهوية/الإقامة | national_id / iqama |
| رقم GOSI | gosi_number |
| الأجر الأساسي | salary slip |
| بدل السكن | salary slip |
| اشتراك الموظف | calculated |
| اشتراك صاحب العمل | calculated |
| الشهر | payroll period |

**Export:** CSV/Excel → upload to GOSI online portal

#### Validation Rules

- Saudi employee → `gosi_subscribed = 1` AND `gosi_number` required
- Non-Saudi → `gosi_subscribed` optional; if subscribed → 2% employer only
- Cannot process payroll for subscribed employee without gosi_number

---

## 3. Qiwa — منصة قوى

### 3.1 الوضع الحالي ✅

| الحقل | الغرض |
|-------|-------|
| `qiwa_contract_number` | رقم عقد العمل الموثق |
| `contract_type` | نوع العقد (unlimited, fixed_term, ...) |
| `contract_start_date` / `contract_end_date` | مدة العقد |

### 3.2 المطلوب — Phase 2–3

| الميزة | الوصف |
|--------|-------|
| Contract expiry alerts | notification 60/30/7 days before |
| Contract renewal workflow | extend contract_end_date + document |
| Qiwa status field | `draft`, `submitted`, `verified` |
| Saudization ratio report | % Saudi vs total per branch |

**ملاحظة:** Qiwa API integration غير متاح publicly — نبدأ بـ **data readiness + alerts** ثم manual sync

---

## 4. WPS — Wage Protection System

### 4.1 الغرض

إلزامي لجميع المنشآت في السعودية — تحويل الرواتب عبر البنك بملف SIF معياري.

### 4.2 المطلوب — Phase 2

#### Pre-requisites

- [ ] IBAN validation (SA + 22 chars) — partial في employee form
- [ ] Bank code mapping (SAMA bank codes)
- [ ] Mol ID (Ministry of Labor establishment ID) — company setting
- [ ] Company bank account for WPS

#### SIF File Format (Standard)

```
# Record types: SCR, EDR, EVR
SCR|Employer Mol ID|Bank Code|Account|Salary Date|Total Records|Total Amount
EDR|Employee ID|Bank Code|IBAN|Name|Basic|Housing|Other|Deductions|Net
```

#### Implementation

```
POST /payroll-runs/:id/wps-export
→ generates SIF file
→ stores at storage/hr/{companyId}/wps/{runNumber}.sif
→ returns download URL
```

#### Validation before export

| Check | Error if fail |
|-------|---------------|
| All employees have valid IBAN | Missing IBAN |
| All employees have national_id/iqama | Missing ID |
| Net pay > 0 | Zero salary |
| Bank code mapped | Unknown bank |
| Payroll status = approved | Not approved |

---

## 5. Iqama & Work Permit Tracking

### 5.1 الوضع الحالي ✅

```
iqama_expiry, work_permit_expiry, passport_expiry, visa_type
```

### 5.2 المطلوب — Phase 1 (Quick Win)

#### Expiry Alerts (notifications service)

| Document | Alert at |
|----------|----------|
| Iqama | 90, 60, 30, 7 days |
| Work permit | 60, 30 days |
| Passport | 90, 30 days |
| Medical insurance | 30 days |
| Contract end | 60, 30 days |

#### Dashboard Widget

```json
{
  "expiringIqama": [
    { "employeeId": 1, "nameAr": "...", "iqamaExpiry": "2026-07-15", "daysLeft": 44 }
  ]
}
```

#### Block Rules (optional Phase 3)

- Cannot process payroll if iqama expired
- Warning on leave application if documents expiring

---

## 6. End of Service (EOS) — مكافأة نهاية الخدمة

### 6.1 نظام العمل السعودي (مبسّط)

| مدة الخدمة | الاستحقاق |
|------------|-----------|
| أقل من 2 سنة | لا مكافأة (إلا باتفاق/ظروف خاصة) |
| 2–5 سنوات | نصف شهر راتب عن كل سنة |
| أكثر من 5 سنوات | شهر راتب عن كل سنة (الأولى 5 نصف شهر) |

**الراتب المحتسب:** Basic + Housing Allowance (configurable)

**Resignation vs Termination:** نسب مختلفة — implement as rules table

### 6.2 API

```
POST /employees/:id/calculate-eos
Body: { "terminationDate": "2026-06-01", "reason": "resignation" }

Response:
{
  "yearsOfService": 3.5,
  "eligibleAmount": 8750.00,
  "breakdown": [
    { "period": "2-5 years", "months": 3.5, "rate": "half month/year", "amount": 8750 }
  ],
  "currency": "SAR"
}
```

### 6.3 Integration with F&F Settlement

EOS amount → `ff_settlements.eos_amount`

---

## 7. Saudization (Nitaqat)

### 7.1 Report

```
GET /reports/saudization?branchId=1

{
  "totalEmployees": 50,
  "saudiEmployees": 12,
  "saudiPercentage": 24.0,
  "targetPercentage": 30.0,
  "gap": 3,
  "byDepartment": [...]
}
```

### 7.2 Fields Used

- `is_saudi`, `nationality`, `employment_status = active`
- Branch/department breakdown

---

## 8. Labor Law — Leave Entitlements (Reference)

| نوع الإجازة | الاستحقاق (نظام العمل) |
|-------------|------------------------|
| سنوية | 21 يوم (< 5 سنوات)، 30 يوم (≥ 5 سنوات) |
| مرضية | 30 يوم full pay + 60 days 75% + 30 days unpaid |
| أمومة | 10 أسابيع |
| حج | مرة واحدة (بعد 2 سنة) |
| وفاة قريب | 5 أيام |
| زواج | 5 أيام |

**Implementation:** seed في `leave_types` + `leave_policy_lines` — configurable per company

---

## 9. Company Settings (Core Service Extension)

```json
{
  "hr": {
    "molEstablishmentId": "1234567",
    "gosiEmployerNumber": "987654",
    "wpsBankCode": "80",
    "wpsBankAccount": "SA...",
    "gosiSaudiEmployeeRate": 0.09,
    "gosiSaudiEmployerRate": 0.09,
    "gosiNonSaudiEmployerRate": 0.02,
    "eosSalaryComponents": ["basic", "housing"],
    "documentExpiryAlertDays": [90, 60, 30, 7],
    "saudizationTarget": 0.30
  }
}
```

Store in `services/core` company settings JSON.

---

## 10. Compliance Checklist (Go-Live Payroll)

| # | Item | Phase |
|---|------|-------|
| 1 | All active employees have IBAN | 2 |
| 2 | GOSI numbers for Saudi employees | 0 ✅ |
| 3 | Iqama expiry > payroll date (non-Saudi) | 1 |
| 4 | Salary structure with GOSI components | 2 |
| 5 | WPS SIF test file with bank | 2 |
| 6 | Accounting accounts mapped | 2 |
| 7 | Qiwa contracts documented | 0 ✅ |
| 8 | Leave policy matches labor law | 1 |
| 9 | EOS calculator validated with HR | 2 |
| 10 | Parallel payroll run vs manual | 2 |

---

## 11. ما لا نبنيه (Out of Scope)

| Item | السبب |
|------|-------|
| Direct GOSI API | لا API عام |
| Direct Qiwa API | يتطلب ترخيص |
| Muqeem integration | external government system |
| ZATCA (tax) for employees | no individual income tax in SA |
| PF/ESI (India-style) | not applicable |

---

## 12. مراجع

- [GOSI Official](https://www.gosi.gov.sa)
- [Qiwa Platform](https://qiwa.sa)
- [MHRSD Labor Law](https://mlsd.gov.sa)
- [SAMA WPS Guidelines](https://www.sama.gov.sa)