# HR Module - Task Breakdown Template
# قالب تقسيم المهام لموديول الموارد البشرية

---

## 📋 كيفية الاستخدام

بعد ما تعمل Analysis لأي Feature في الـ HR Module، انسخ القالب ده واملأه، وبعدين اديه للـ Backend والـ Frontend كل واحد الجزء الخاص بيه.

---

## 🔷 قالب التاسك الكامل

### Task Title: [اسم التاسك - مثال: Employee Management]
### Module: HR
### Priority: [High / Medium / Low]
### Estimated Time: [Backend: X hours | Frontend: X hours]

---

## 📌 1. وصف عام (Overview)

```
- ايه الـ Feature دي؟
- مين المستخدم المستهدف (Admin / HR Manager / Employee)؟
- ايه المشكلة اللي بتحلها؟
- ايه الـ Business Rules الأساسية؟
```

---

## 📌 2. مكونات الـ Backend (API Task)

### 2.1 Database Schema

```
Table Name: [اسم الجدول]
├── id (bigint, PK, auto_increment)
├── [field_name] ([type]) - [وصف]
├── [field_name] ([type]) - [وصف]
├── company_id (FK → companies) - للـ Multi-tenant
├── created_by (FK → users)
├── updated_by (FK → users)
├── created_at (timestamp)
├── updated_at (timestamp)
├── deleted_at (timestamp, nullable) - Soft Delete
└── Indexes: [الفهارس المطلوبة]

Relations:
├── belongsTo: [الجداول]
├── hasMany: [الجداول]
└── belongsToMany: [الجداول - pivot tables]
```

### 2.2 API Endpoints

```
لكل Endpoint حدد:

┌─────────────────────────────────────────────────────────┐
│ Endpoint #1                                              │
├─────────────────────────────────────────────────────────┤
│ Method:      [GET / POST / PUT / DELETE]                │
│ URL:         /api/v1/hr/[resource]                      │
│ Auth:        [Required / Optional]                      │
│ Permission:  [permission_name]                          │
│ Description: [وصف الـ endpoint]                         │
│                                                          │
│ Headers:                                                 │
│   Authorization: Bearer {token}                         │
│   Accept: application/json                              │
│   X-Company-ID: {company_id}                            │
│                                                          │
│ Request Params / Body:                                   │
│   {                                                      │
│     "field_1": "string|required|max:255",               │
│     "field_2": "integer|nullable",                      │
│     "field_3": "date|required|after:today"              │
│   }                                                      │
│                                                          │
│ Filters (للـ GET/List):                                  │
│   ?search=keyword                                       │
│   ?status=active                                        │
│   ?department_id=1                                      │
│   ?date_from=2024-01-01&date_to=2024-12-31             │
│   ?page=1&per_page=25                                   │
│   ?sort_by=name&sort_dir=asc                           │
│                                                          │
│ Success Response (200/201):                              │
│   {                                                      │
│     "status": true,                                      │
│     "message": "...",                                    │
│     "data": { ... }                                      │
│   }                                                      │
│                                                          │
│ Error Response (422/400/404):                            │
│   {                                                      │
│     "status": false,                                     │
│     "message": "...",                                    │
│     "errors": { "field": ["error message"] }            │
│   }                                                      │
└─────────────────────────────────────────────────────────┘
```

### 2.3 Validation Rules

```
- field_1: required, string, max:255, unique:table,field,{id}
- field_2: required, exists:related_table,id
- field_3: nullable, date_format:Y-m-d
- file:    nullable, mimes:jpg,png,pdf, max:2048
```

### 2.4 Business Logic / Services

```
- [ ] Logic 1: [وصف - مثال: حساب رصيد الإجازات تلقائياً]
- [ ] Logic 2: [وصف - مثال: إرسال إشعار عند الموافقة]
- [ ] Logic 3: [وصف - مثال: التحقق من عدم تعارض الإجازات]
- [ ] Events/Listeners: [أي events مطلوبة]
- [ ] Jobs/Queues: [أي background jobs]
- [ ] Notifications: [أنواع الإشعارات]
```

### 2.5 Permissions & Roles

```
- hr.employees.view
- hr.employees.create
- hr.employees.update
- hr.employees.delete
- hr.employees.export
```

### 2.6 Seeder / Test Data

```
- [ ] Factory class
- [ ] Seeder مع بيانات تجريبية
- [ ] عدد السجلات المطلوبة للتجربة
```

---

## 📌 3. مكونات الـ Frontend (Flutter Task)

### 3.1 الشاشات المطلوبة (Screens)

```
لكل شاشة حدد:

┌─────────────────────────────────────────────────────────┐
│ Screen #1: [اسم الشاشة]                                │
├─────────────────────────────────────────────────────────┤
│ Route:       /hr/employees                              │
│ Type:        [List / Form / Details / Dashboard]        │
│ Access:      [الصلاحيات المطلوبة]                       │
│                                                          │
│ UI Components:                                           │
│   ├── AppBar: [عنوان + actions (filter, add, export)]  │
│   ├── Search Bar: [search fields]                       │
│   ├── Filter Panel: [filter options]                    │
│   ├── List/Grid: [card/tile design]                     │
│   ├── FAB: [floating action button - إضافة]            │
│   ├── Bottom Sheet: [if needed]                         │
│   └── Empty State: [رسالة + icon لما مفيش بيانات]      │
│                                                          │
│ Data Display:                                            │
│   ├── Field 1: [الاسم] - Text, bold, 16sp              │
│   ├── Field 2: [القسم] - Chip/Tag                      │
│   ├── Field 3: [الحالة] - Status Badge (active/color)  │
│   └── Field 4: [الصورة] - CircleAvatar                 │
│                                                          │
│ Actions:                                                 │
│   ├── Tap: Navigate to details                          │
│   ├── Long Press: [options menu]                        │
│   ├── Swipe: [delete/archive]                           │
│   └── Pull to Refresh: reload data                      │
│                                                          │
│ Pagination:                                              │
│   └── Infinite scroll / Load more button                │
└─────────────────────────────────────────────────────────┘
```

### 3.2 Forms & Inputs

```
┌─────────────────────────────────────────────────────────┐
│ Form: [Add/Edit Employee]                               │
├─────────────────────────────────────────────────────────┤
│ Sections:                                                │
│                                                          │
│ Section 1: البيانات الأساسية                            │
│   ├── الاسم: TextFormField (required, max:255)          │
│   ├── البريد: TextFormField (email, unique)             │
│   ├── الهاتف: TextFormField (phone format)              │
│   ├── القسم: Dropdown (from API /departments)           │
│   ├── المسمى الوظيفي: Dropdown (from API /job_titles)  │
│   ├── تاريخ التعيين: DatePicker (required)             │
│   └── الصورة: ImagePicker (camera/gallery)              │
│                                                          │
│ Section 2: بيانات إضافية                                │
│   ├── العنوان: TextFormField (multiline)                │
│   ├── الراتب: NumberField (decimal)                     │
│   └── ملاحظات: TextFormField (optional, multiline)     │
│                                                          │
│ Validation (Client-side):                                │
│   ├── Required fields: show red border + message        │
│   ├── Email format: regex validation                    │
│   ├── Phone format: regex validation                    │
│   └── File size: max 2MB, jpg/png only                 │
│                                                          │
│ Submit Behavior:                                         │
│   ├── Loading: show progress indicator                  │
│   ├── Success: show snackbar + navigate back            │
│   ├── Error: show field errors from API                 │
│   └── Offline: queue for later sync (if supported)     │
└─────────────────────────────────────────────────────────┘
```

### 3.3 State Management

```
- Provider/Bloc/GetX: [المستخدم في المشروع]
- States:
  ├── Loading: Shimmer/Skeleton
  ├── Success: Show data
  ├── Error: Error widget + retry button
  ├── Empty: Empty state illustration
  └── Offline: Cached data notice
```

### 3.4 API Integration

```
- Base URL: [API_BASE_URL]/api/v1/hr/
- Repository: HrEmployeeRepository
- Model: EmployeeModel (fromJson / toJson)
- Endpoints to consume:
  ├── GET    /employees          → List
  ├── GET    /employees/{id}     → Details
  ├── POST   /employees          → Create
  ├── PUT    /employees/{id}     → Update
  ├── DELETE /employees/{id}     → Delete
  └── GET    /employees/export   → Download
```

### 3.5 RTL / Arabic Support

```
- [ ] كل النصوص تدعم العربية
- [ ] الـ Layout يشتغل RTL صح
- [ ] التاريخ بالهجري والميلادي (لو مطلوب)
- [ ] الأرقام عربية/إنجليزية حسب الإعداد
- [ ] رسائل الخطأ بالعربي
```

### 3.6 الألوان والتصميم

```
- Primary Color: [اللون الأساسي للموديول]
- Status Colors:
  ├── Active:   #4CAF50 (أخضر)
  ├── Inactive: #9E9E9E (رمادي)
  ├── Pending:  #FF9800 (برتقالي)
  └── Rejected: #F44336 (أحمر)
- Card Style: [elevation, border radius, padding]
- Typography: [font family, sizes]
```

---

## 📌 4. Acceptance Criteria (معايير القبول)

```
Backend:
- [ ] كل الـ APIs شغالة وبترجع الـ Response الصحيح
- [ ] الـ Validation شغال لكل الحالات
- [ ] الـ Permissions متطبقة صح
- [ ] الـ Multi-tenant معزول (كل شركة تشوف بياناتها بس)
- [ ] الـ Soft Delete شغال
- [ ] الـ Pagination شغال
- [ ] الـ Search والـ Filters شغالين

Frontend:
- [ ] كل الشاشات شغالة ومتصلة بالـ API
- [ ] الـ Form Validation شغال client-side
- [ ] الـ Error Handling واضح للمستخدم
- [ ] الـ Loading States موجودة
- [ ] شغال RTL بدون مشاكل
- [ ] شغال على Android و iOS
- [ ] الـ Pull to Refresh شغال
- [ ] الـ Pagination شغال
```

---

## 📌 5. Dependencies (الاعتماديات)

```
- [ ] الـ Feature دي تعتمد على: [features تانية لازم تتعمل الأول]
- [ ] APIs خارجية مطلوبة: [لو فيه]
- [ ] Packages مطلوبة: [backend/frontend packages]
```

---

## 📌 6. Notes / ملاحظات

```
- أي ملاحظات إضافية
- Edge cases معروفة
- حاجات مأجلة لمرحلة لاحقة
```

---

# ============================================
# 💡 مثال عملي: تاسك إدارة الموظفين
# ============================================

## Task: Employee Management (إدارة الموظفين)
## Module: HR
## Priority: High

### Overview:
شاشة إدارة بيانات الموظفين الأساسية - إضافة/تعديل/حذف/عرض
المستخدم: HR Manager & Admin

### Backend Endpoints:

| # | Method | URL | Description |
|---|--------|-----|-------------|
| 1 | GET | /api/v1/hr/employees | قائمة الموظفين مع pagination و filters |
| 2 | GET | /api/v1/hr/employees/{id} | بيانات موظف واحد |
| 3 | POST | /api/v1/hr/employees | إضافة موظف جديد |
| 4 | PUT | /api/v1/hr/employees/{id} | تعديل بيانات موظف |
| 5 | DELETE | /api/v1/hr/employees/{id} | حذف موظف (soft delete) |
| 6 | POST | /api/v1/hr/employees/{id}/avatar | رفع صورة الموظف |
| 7 | GET | /api/v1/hr/employees/export | تصدير Excel |
| 8 | POST | /api/v1/hr/employees/import | استيراد من Excel |

### Frontend Screens:

| # | Screen | Type | Notes |
|---|--------|------|-------|
| 1 | قائمة الموظفين | List + Search + Filter | الشاشة الرئيسية |
| 2 | إضافة/تعديل موظف | Multi-step Form | 3 sections |
| 3 | تفاصيل الموظف | Details + Tabs | بيانات + إجازات + رواتب |
| 4 | فلترة متقدمة | Bottom Sheet | قسم، حالة، تاريخ |
