# توثيق مشروع "سجل الإنجازات الرقمي" (Achievement Tracking System)

## 📌 نظرة عامة
نظام متكامل لتتبع الأنشطة والإنجازات اليومية للأقسام، مبني باستخدام **Laravel 11**. يوفر واجهات تفاعلية سلسة مع عزل كامل لبيانات الأقسام، ولوحات تحكم مخصصة لكل دور وظيفي.

---

## 🛠️ التقنيات والمكتبات المستخدمة

| المكتبة | الغرض |
| :--- | :--- |
| **Laravel 11** | إطار العمل الأساسي (Backend) |
| **Filament PHP v3** | واجهات المستخدم التفاعلية (Livewire + Tailwind CSS) |
| **Spatie Laravel-Permission** | إدارة الأدوار والصلاحيات |
| **barryvdh/laravel-dompdf / TCPDF** | توليد تقارير PDF بدعم اللغة العربية (RTL) واستخدام خط `aealarabiya` |
| **PhpWord / PhpSpreadsheet** | التصدير إلى تنسيقات Word و Excel بدعم الجداول والنصوص العربية |
| **MySQL** | قاعدة البيانات (اسم القاعدة: `ats_db`) |

---

## 🏗️ هيكل قاعدة البيانات

| الجدول | الوصف |
| :--- | :--- |
| `departments` | الأقسام |
| `divisions` | الشعب التابعة للقسم |
| `employees` | الموظفون التابعون للقسم (يحتوي رقم الحاسبة `computer_number` لمنع التكرار) |
| `users` | المستخدمون (مرتبطون بالأقسام وبموظف مختص عبر `employee_id`) |
| `activities` | الأنشطة اليومية (تحتوي أزرار للفرز الأسبوعي، الشهري، النصف سنوي، والسنوي) |
| `activity_participants` | جدول وسيط (Many-to-Many) بين الأنشطة والموظفين |
| `attachments` | المرفقات (PDF وصور) المرتبطة بكل نشاط |
| `roles` / `permissions` | جداول Spatie لإدارة الأدوار |

---

## 👥 الأدوار والصلاحيات (Roles & Permissions)

### 👑 1. `super_admin` — مدير النظام الأعلى
> يمتلك جميع الصلاحيات المطلقة عبر `Gate::before` في `AppServiceProvider`.

**ما يستطيع فعله:**
- ✅ **إدارة المستخدمين**: إضافة، تعديل، حذف أي حساب في النظام.
- ✅ **منح وتغيير الأدوار**: تحديد دور كل مستخدم (department_user / planner / super_admin).
- ✅ **إدارة الأقسام والشعب والموظفين** بشكل كامل.
- ✅ يرى جميع بيانات كل الأقسام في النظام.

---

### 📊 2. `planner_manager` — مدير التخطيط
> يمتلك صلاحيات استثنائية على **الأنشطة فقط** (ليس على إدارة المستخدمين).

**ما يستطيع فعله:**
- ✅ يرى أنشطة **جميع الأقسام** (يتخطى الـ Global Scope).
- ✅ تحديد الأنشطة (أسبوعية، شهرية، نصف سنوية، وسنوية) عبر أزرار Toggle.
- ✅ تلقي إشعارات فورية (Database Notifications) عند إضافة أي نشاط جديد من قبل أي قسم، مع زر انتقال مباشر للنشاط.
- ✅ تصدير تقارير (Excel, Word, PDF) الدورية المتقدمة مع خيارات لفرز (المنجز/المخطط).
- ✅ تصدير سجلات محددة (Bulk Actions) بدعم الترويسة المخصصة واسم الموظف المُصدِّر.
- ✅ يرى إحصائيات متقدمة وبطاقات لكافة التقارير (أسبوعي، شهري، نصف سنوي، وسنوي).
- ❌ لا يرى صفحات الأقسام، الشعب، والموظفين (حصرية لمدير النظام).
- ❌ لا يمكنه إضافة مستخدمين أو تغيير أدوارهم.

---

### 📝 3. `planner_data_entry` — موظف إدخال بيانات التخطيط
> نفس صلاحيات أي قسم عادي، لكنه تابع لقسم التخطيط.

**ما يستطيع فعله:**
- ✅ إدخال أنشطة وإنجازات قسم التخطيط فقط.
- ✅ رفع المرفقات واختيار موظفي قسم التخطيط كمشاركين.
- ❌ لا يرى أنشطة الأقسام الأخرى.

---

### 🏢 4. `department_user` — مستخدم قسم عادي
> يخضع لقيود صارمة على مستوى قاعدة البيانات (Global Scope).

**ما يستطيع فعله:**
- ✅ إدخال وعرض أنشطة قسمه فقط.
- ✅ رفع المرفقات واختيار موظفي قسمه كمشاركين.
- ✅ عرض إحصائيات قسمه.
- ❌ لا يرى أي بيانات من أقسام أخرى حتى لو حاول تعديل الرابط (URL).

---

## 🔑 بيانات الدخول

> **كلمة المرور الافتراضية لجميع الحسابات الجديدة والموجودة:** `password`

| نوع الحساب | البريد الإلكتروني | الدور | ملاحظات |
| :--- | :--- | :--- | :--- |
| مدير النظام | `admin@ats.local` | `super_admin` | يمتلك كافة الصلاحيات الإدارية |
| موظف التخطيط | `planner.manager@gcpi.gov.iq` | `planner_manager` | متابعة جميع الأقسام والتقارير |
| حسابات الأقسام | `dg@gcpi.gov.iq` (مثال) | `department_user` | **تم استيراد 35 حساباً حقيقياً لجميع الأقسام بصلاحية إدخال أنشطتهم فقط.** |

---

## ⚙️ طريقة التشغيل

1. تأكد من تشغيل خادم MySQL (XAMPP أو WAMP).
2. افتح Terminal في مسار المشروع (`ats-project`).
3. شغّل السيرفر المحلي:
   ```bash
   php artisan serve --port=8001
   ```
4. افتح النظام في المتصفح (يتم التوجيه تلقائياً للوحة الإدارة):
   **[http://127.0.0.1:8001](http://127.0.0.1:8001)**

---

## 📁 هيكل المجلدات الرئيسية

```
app/
├── Filament/
│   ├── Actions/
│   │   └── ExportReportAction.php      # زر تصدير التقرير الدوري
│   ├── Resources/
│   │   ├── ActivityResource.php        # إدارة الأنشطة (مع فلاتر البحث وإجراءات التصدير الجماعية)
│   │   ├── DepartmentResource.php      # إدارة الأقسام
│   │   ├── DivisionResource.php        # إدارة الشعب
│   │   ├── EmployeeResource.php        # إدارة الموظفين
│   │   └── UserResource.php            # إدارة المستخدمين (super_admin فقط)
│   └── Widgets/
│       ├── ActivityStatsWidget.php     # لوحة الإحصائيات (8 بطاقات لمدير التخطيط)
│       └── ActivityChartWidget.php     # الرسم البياني (30 يوم)
├── Models/
│   ├── Scopes/
│   │   └── DepartmentScope.php         # Global Scope لعزل الأقسام
│   ├── Activity.php
│   ├── Attachment.php
│   ├── Department.php
│   ├── Division.php
│   ├── Employee.php
│   └── User.php
├── Notifications/
│   └── NewActivityNotification.php     # إشعارات قاعدة البيانات لمدير التخطيط
├── Services/
│   └── ExportService.php               # المحرك الموحد لتصدير (PDF, Word, Excel)
resources/
└── views/reports/
    └── activities.blade.php            # قالب تقرير PDF القديم (أصبح الاعتماد على محرك ExportService)
```