# توثيق مشروع EMZatca — دليل المطوّر الشامل

> **آخر تحديث:** أكتوبر 2026  
> **الإصدار:** Laravel 13 / PHP 8.3  
> **اللغة الافتراضية:** العربية (ar)

---

## جدول المحتويات

1. [نظرة عامة على المشروع](#1-نظرة-عامة-على-المشروع)
2. [المتطلبات التقنية والبيئة](#2-المتطلبات-التقنية-والبيئة)
3. [إعداد المشروع وتشغيله](#3-إعداد-المشروع-وتشغيله)
4. [هيكل المشروع](#4-هيكل-المشروع)
5. [قاعدة البيانات](#5-قاعدة-البيانات)
6. [النماذج (Models) وعلاقاتها](#6-النماذج-models-وعلاقاتها)
7. [Controllers وما يفعله كل واحد](#7-controllers-وما-يفعله-كل-واحد)
8. [Services (الخدمات)](#8-services-الخدمات)
9. [مسارات التطبيق (Routes)](#9-مسارات-التطبيق-routes)
10. [نظام المصادقة (Auth)](#10-نظام-المصادقة-auth)
11. [تدفق إنشاء الفاتورة (Invoice Flow)](#11-تدفق-إنشاء-الفاتورة-invoice-flow)
12. [خطوات التهيئة والربط بالهيئة (Onboarding)](#12-خطوات-التهيئة-والربط-بالهيئة-onboarding)
13. [نظام الاشتراكات والخطط](#13-نظام-الاشتراكات-والخطط)
14. [واجهة برمجة التطبيقات (API)](#14-واجهة-برمجة-التطبيقات-api)
15. [الأدوات المجانية العامة](#15-الأدوات-المجانية-العامة)
16. [لوحة الادمن (Admin Panel)](#16-لوحة-الادمن-admin-panel)
17. [لوحة Ops Console](#17-لوحة-ops-console)
18. [متغيرات البيئة (.env)](#18-متغيرات-البيئة-env)
19. [تشغيل الاختبارات](#19-تشغيل-الاختبارات)
20. [نقاط مهمة وملاحظات للمطوّر القادم](#20-نقاط-مهمة-وملاحظات-للمطوّر-القادم)

---

## 1. نظرة عامة على المشروع

**EMZatca** هو تطبيق SaaS (برمجيات كخدمة) موجّه للشركات والمنشآت السعودية، يتيح لها إصدار **فواتير إلكترونية متوافقة مع متطلبات هيئة الزكاة والضريبة والجمارك (ZATCA) — المرحلة الثانية (Phase 2)**.

### الغرض الأساسي

- ربط المنشآت بمنظومة الفوترة الإلكترونية (فاتورة) التابعة لـ ZATCA
- إصدار الفواتير الضريبية القياسية (Standard) والمبسّطة (Simplified)
- دعم إشعارات الدائن (Credit Note) والمدين (Debit Note)
- إرسال الفواتير تلقائياً لإخلاء الطرف (Clearance) أو الإبلاغ (Reporting) عبر API لـ ZATCA
- توفير واجهة API كاملة للتكامل مع أنظمة نقاط البيع (POS) والأنظمة المحاسبية

### نموذج العمل

```
المنشأة (Tenant) → اشتراك في خطة → إنشاء فواتير → رفع للـ ZATCA → قبول / رفض
```

المنصة متعددة المستأجرين (Multi-Tenant) حيث كل شركة (Tenant) تمتلك بياناتها وأجهزتها وفواتيرها بشكل مستقل تماماً.

---

## 2. المتطلبات التقنية والبيئة

### متطلبات الخادم

| المكوّن | الإصدار المطلوب | الملاحظة |
|---------|----------------|----------|
| PHP | 8.3+ | مع إضافات: `openssl`, `mbstring`, `xml`, `curl`, `gd`, `zip` |
| Laravel | 13.x | |
| MySQL | 8.0+ | قاعدة البيانات: `emzatca` |
| Node.js | 18+ | لبناء الـ Frontend |
| Composer | 2.x | لإدارة حزم PHP |
| NPM | 9+ | لإدارة حزم JavaScript |

### المكتبات الرئيسية (PHP)

| الحزمة | الغرض |
|--------|--------|
| `laravel/framework` | إطار عمل التطبيق الأساسي |
| `barryvdh/laravel-dompdf` | توليد ملفات PDF للفواتير |
| `chillerlan/php-qrcode` | توليد رموز QR وفق مواصفات ZATCA |
| `dedoc/scramble` | توليد توثيق API تلقائياً |
| `laravel/socialite` | تسجيل الدخول الاجتماعي (Google / Apple) |
| `khaled.alshamaa/ar-php` | دعم اللغة العربية (تحويل أرقام، تواريخ هجرية) |
| `phpseclib/phpseclib` | إدارة الشهادات الرقمية ومفاتيح ECDSA |

### المكتبات الرئيسية (Frontend)

| الحزمة | الغرض |
|--------|--------|
| Vite | أداة البناء والـ bundling |
| Alpine.js | إضافة تفاعلية خفيفة للـ UI |
| Tailwind CSS | نظام التصميم (Utility-first CSS) |

### بيئة التطوير

- **Laravel Herd** — يخدم التطبيق على `https://zatca-tools.test`
- **Queue**: database (الطابور يُخزَّن في قاعدة البيانات)
- **Cache**: database
- **Session**: database
- **Mail (Dev)**: Mailtrap عبر SMTP

---

## 3. إعداد المشروع وتشغيله

### الخطوة 1: استنساخ المشروع

```bash
git clone <repository-url> emzatca
cd emzatca
```

### الخطوة 2: تثبيت التبعيات

```bash
# تثبيت حزم PHP
composer install

# تثبيت حزم JavaScript
npm install
```

### الخطوة 3: إعداد ملف البيئة

```bash
cp .env.example .env
php artisan key:generate
```

ثم افتح `.env` وعدّل المتغيرات التالية:

```dotenv
APP_NAME=EMZatca
APP_URL=https://zatca-tools.test

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=emzatca
DB_USERNAME=root
DB_PASSWORD=your_password

MAIL_MAILER=smtp
MAIL_HOST=sandbox.smtp.mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=your_mailtrap_username
MAIL_PASSWORD=your_mailtrap_password

GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_REDIRECT_URI=https://zatca-tools.test/auth/google/callback

APPLE_CLIENT_ID=your_apple_client_id
APPLE_CLIENT_SECRET=your_apple_client_secret
APPLE_REDIRECT_URI=https://zatca-tools.test/auth/apple/callback
```

### الخطوة 4: إعداد قاعدة البيانات

```bash
# إنشاء الجداول
php artisan migrate

# (اختياري) زرع بيانات أولية
php artisan db:seed
```

### الخطوة 5: بناء الـ Frontend

```bash
# للتطوير (مع Hot Reload)
npm run dev

# للإنتاج
npm run build
```

### الخطوة 6: تشغيل طابور المهام (Queue)

```bash
php artisan queue:listen
```

> [!IMPORTANT]
> طابور المهام ضروري لمعالجة الفواتير وإرسالها إلى ZATCA بشكل غير متزامن. لا تنسَ تشغيله!

### الخطوة 7: التشغيل الكامل (طريقة مختصرة)

```bash
# يشغّل الخادم + الطابور + Vite في وقت واحد
composer run dev
```

---

## 4. هيكل المشروع

```
emzatca/
├── app/
│   ├── Console/              # أوامر Artisan المخصّصة
│   ├── Enums/                # التعدادات (InvoiceType, InvoiceStatus, إلخ)
│   ├── Http/
│   │   ├── Controllers/
│   │   │   ├── Admin/        # Controllers لوحة الإدارة
│   │   │   ├── Api/          # Controllers واجهة API
│   │   │   ├── Auth/         # Controllers المصادقة
│   │   │   ├── Dashboard/    # Controllers لوحة المستأجر
│   │   │   ├── Ops/          # Controllers لوحة Ops
│   │   │   └── Web/          # Controllers الصفحات العامة
│   │   ├── Middleware/       # Middleware المخصّص
│   │   └── Requests/         # Form Request classes للتحقق
│   ├── Jobs/                 # المهام غير المتزامنة (Queue Jobs)
│   ├── Models/               # نماذج Eloquent
│   └── Services/
│       ├── Dashboard/        # خدمات لوحة التحكم
│       └── Zatca/            # خدمات ZATCA (XML, تشفير، إلخ)
├── bootstrap/                # إعداد التطبيق
├── config/                   # ملفات الإعداد
├── database/
│   ├── factories/            # مصانع بيانات الاختبار
│   ├── migrations/           # ملفات هجرة قاعدة البيانات
│   └── seeders/              # بذور البيانات الأولية
├── public/                   # الملفات العامة (index.php، assets)
├── resources/
│   ├── css/                  # ملفات CSS / Tailwind
│   ├── js/                   # ملفات JavaScript / Alpine.js
│   └── views/                # قوالب Blade
│       ├── admin/            # قوالب لوحة الإدارة
│       ├── auth/             # قوالب تسجيل الدخول والتسجيل
│       ├── dashboard/        # قوالب لوحة المستأجر
│       ├── emails/           # قوالب البريد الإلكتروني
│       ├── pdf/              # قوالب PDF للفواتير
│       └── web/              # قوالب الصفحات العامة
├── routes/
│   ├── web.php               # مسارات الويب
│   ├── api.php               # مسارات API
│   └── console.php           # مسارات الأوامر
├── storage/                  # ملفات التخزين (logs، cache، uploads)
├── tests/
│   ├── Feature/              # اختبارات شاملة (Feature Tests)
│   └── Unit/                 # اختبارات وحدة (Unit Tests)
├── .ai/rules/                # قواعد AI للمشروع
├── composer.json
├── package.json
└── vite.config.js
```

---

## 5. قاعدة البيانات

قاعدة البيانات: `emzatca` (MySQL 8.0+)

### جدول: `tenants` (المستأجرون / الشركات)

| العمود | النوع | الوصف |
|--------|------|-------|
| `id` | bigint PK | المعرّف الأساسي |
| `uuid` | varchar(36) | معرّف فريد عالمي (UUID) |
| `name` | varchar | اسم الشركة بالعربية |
| `name_en` | varchar | اسم الشركة بالإنجليزية |
| `vat_number` | varchar | الرقم الضريبي (15 رقم) |
| `cr_number` | varchar | رقم السجل التجاري |
| `email` | varchar | البريد الإلكتروني للشركة |
| `phone` | varchar | رقم الهاتف |
| `address_street` | varchar | اسم الشارع |
| `address_building_number` | varchar | رقم المبنى |
| `address_city` | varchar | المدينة |
| `address_district` | varchar | الحي |
| `address_postal_code` | varchar | الرمز البريدي |
| `address_country_code` | varchar(2) | رمز الدولة (SA) |
| `org_identifier_type` | varchar | نوع معرّف المنشأة (CRN, MOM, MLS, إلخ) |
| `org_identifier_value` | varchar | قيمة معرّف المنشأة |
| `plan` | varchar | مفتاح خطة الاشتراك الحالية |
| `billing_interval` | enum | `monthly` أو `yearly` |
| `monthly_invoice_limit` | int | الحد الأقصى للفواتير الشهرية |
| `invoices_used_this_month` | int | عداد الفواتير المُصدَرة هذا الشهر |
| `plan_expires_at` | timestamp | تاريخ انتهاء الاشتراك |
| `is_active` | boolean | حالة الحساب (نشط/موقوف) |
| `is_sandbox` | boolean | وضع Sandbox أو Production |
| `zatca_environment` | varchar | بيئة ZATCA المستخدمة |
| `settings` | JSON | إعدادات إضافية (تصميم الفاتورة، إلخ) |
| `created_at` | timestamp | تاريخ الإنشاء |
| `updated_at` | timestamp | تاريخ آخر تعديل |

---

### جدول: `users` (المستخدمون)

| العمود | النوع | الوصف |
|--------|------|-------|
| `id` | bigint PK | |
| `tenant_id` | bigint FK | الشركة المرتبطة |
| `name` | varchar | الاسم |
| `email` | varchar UNIQUE | البريد الإلكتروني |
| `password` | varchar | كلمة المرور (مشفّرة) |
| `google_id` | varchar nullable | معرّف Google للتسجيل الاجتماعي |
| `apple_id` | varchar nullable | معرّف Apple للتسجيل الاجتماعي |
| `is_super_admin` | boolean | هل هو مشرف عام؟ |
| `email_verified_at` | timestamp | تاريخ التحقق من البريد |
| `remember_token` | varchar | رمز "تذكّرني" |
| `created_at` | timestamp | |
| `updated_at` | timestamp | |

---

### جدول: `devices` (الأجهزة / وحدات الحل)

| العمود | النوع | الوصف |
|--------|------|-------|
| `id` | bigint PK | |
| `uuid` | varchar(36) | UUID مميّز للجهاز |
| `tenant_id` | bigint FK | الشركة المالكة |
| `name` | varchar | اسم الجهاز |
| `serial_number` | varchar | الرقم التسلسلي |
| `onboarding_status` | enum | `pending` → `csr_generated` → `compliance_done` → `production_ready` |
| `csr` | text nullable | طلب توقيع الشهادة (CSR) |
| `certificate_pem` | text nullable | الشهادة الرقمية من ZATCA |
| `private_key` | text nullable | المفتاح الخاص (ECDSA) — **محمي جداً** |
| `compliance_request_id` | varchar nullable | معرّف طلب الامتثال من ZATCA |
| `pih` | varchar nullable | هاش الفاتورة السابقة (Previous Invoice Hash) |
| `created_at` | timestamp | |
| `updated_at` | timestamp | |

> [!CAUTION]
> عمود `private_key` يحتوي على المفتاح الخاص للجهاز. يجب أن يكون مشفّراً في قاعدة البيانات ولا يُكشَف أبداً في الـ Logs أو الـ API responses.

---

### جدول: `invoices` (الفواتير)

| العمود | النوع | الوصف |
|--------|------|-------|
| `id` | bigint PK | |
| `uuid` | varchar(36) | UUID مميّز للفاتورة |
| `tenant_id` | bigint FK | الشركة المصدِرة |
| `device_id` | bigint FK | الجهاز المُصدِر |
| `invoice_number` | varchar | رقم الفاتورة التسلسلي |
| `type` | enum | `standard`, `simplified`, `credit_note`, `debit_note` |
| `status` | enum | `draft`, `signed`, `reported`, `cleared`, `failed`, `cancelled` |
| `buyer_name` | varchar | اسم المشتري |
| `buyer_vat_number` | varchar nullable | الرقم الضريبي للمشتري |
| `subtotal` | decimal(15,2) | المجموع قبل الضريبة |
| `vat_amount` | decimal(15,2) | مبلغ ضريبة القيمة المضافة |
| `total` | decimal(15,2) | المجموع الكلي شامل الضريبة |
| `issued_at` | timestamp | تاريخ ووقت الإصدار |
| `zatca_uuid` | varchar nullable | UUID الفاتورة لدى ZATCA |
| `invoice_xml` | longtext nullable | XML الفاتورة الموقّع |
| `invoice_hash` | varchar nullable | هاش SHA-256 للفاتورة |
| `qr_code` | text nullable | بيانات QR المُرمَّزة (TLV) |
| `clearance_status` | varchar nullable | حالة الإخلاء من ZATCA |
| `line_items` | JSON | بنود الفاتورة (المنتجات والخدمات) |
| `notes` | text nullable | ملاحظات الفاتورة |
| `created_at` | timestamp | |
| `updated_at` | timestamp | |

---

### جدول: `customers` (العملاء)

| العمود | النوع | الوصف |
|--------|------|-------|
| `id` | bigint PK | |
| `tenant_id` | bigint FK | الشركة المالكة |
| `name` | varchar | اسم العميل |
| `vat_number` | varchar nullable | الرقم الضريبي |
| `email` | varchar nullable | البريد الإلكتروني |
| `phone` | varchar nullable | الهاتف |
| `type` | enum | `individual` (فرد) أو `business` (شركة) |
| `address` | JSON nullable | العنوان التفصيلي |
| `created_at` | timestamp | |
| `updated_at` | timestamp | |

---

### جدول: `catalog_items` (كتالوج المنتجات والخدمات)

| العمود | النوع | الوصف |
|--------|------|-------|
| `id` | bigint PK | |
| `tenant_id` | bigint FK | الشركة المالكة |
| `name` | varchar | اسم المنتج / الخدمة |
| `description` | text nullable | وصف تفصيلي |
| `unit_price` | decimal(15,2) | سعر الوحدة |
| `vat_rate` | decimal(5,2) | نسبة الضريبة (عادةً 15%) |
| `unit` | varchar nullable | وحدة القياس (قطعة، ساعة، إلخ) |
| `created_at` | timestamp | |
| `updated_at` | timestamp | |

---

### جدول: `quotations` (عروض الأسعار)

| العمود | النوع | الوصف |
|--------|------|-------|
| `id` | bigint PK | |
| `uuid` | varchar(36) | UUID مميّز |
| `tenant_id` | bigint FK | الشركة المالكة |
| `customer_id` | bigint FK nullable | العميل |
| `quotation_number` | varchar | رقم عرض السعر |
| `status` | enum | `draft`, `sent`, `accepted`, `converted` |
| `subtotal` | decimal(15,2) | |
| `vat_amount` | decimal(15,2) | |
| `total` | decimal(15,2) | |
| `valid_until` | date nullable | تاريخ انتهاء الصلاحية |
| `line_items` | JSON | البنود |
| `converted_invoice_id` | bigint nullable | إذا تحوّل لفاتورة |
| `created_at` | timestamp | |
| `updated_at` | timestamp | |

---

### جدول: `plans` (خطط الاشتراك)

| العمود | النوع | الوصف |
|--------|------|-------|
| `id` | bigint PK | |
| `slug` | varchar UNIQUE | مفتاح مميّز (مثل: `starter`, `pro`, `enterprise`) |
| `name` | varchar | اسم الخطة |
| `price` | decimal(10,2) | السعر الشهري (ريال سعودي) |
| `yearly_price` | decimal(10,2) | السعر السنوي |
| `monthly_invoice_limit` | int | الحد الأقصى للفواتير شهرياً |
| `features` | JSON | قائمة المزايا |
| `is_active` | boolean | هل الخطة متاحة؟ |
| `created_at` | timestamp | |
| `updated_at` | timestamp | |

---

### جدول: `api_keys` (مفاتيح API)

| العمود | النوع | الوصف |
|--------|------|-------|
| `id` | bigint PK | |
| `tenant_id` | bigint FK | الشركة المالكة |
| `name` | varchar | اسم وصفي لمفتاح API |
| `key` | varchar UNIQUE | المفتاح (يبدأ بـ `emk_`) |
| `last_used_at` | timestamp nullable | آخر استخدام |
| `expires_at` | timestamp nullable | تاريخ الانتهاء |
| `is_active` | boolean | حالة المفتاح |
| `created_at` | timestamp | |
| `updated_at` | timestamp | |

---

### جدول: `otp_codes` (رموز OTP)

| العمود | النوع | الوصف |
|--------|------|-------|
| `id` | bigint PK | |
| `email` | varchar | البريد الإلكتروني المرتبط |
| `code` | varchar | الرمز السري (6 أرقام) |
| `expires_at` | timestamp | وقت الانتهاء |
| `used_at` | timestamp nullable | وقت الاستخدام |
| `created_at` | timestamp | |
| `updated_at` | timestamp | |

---

### جدول: `plan_upgrade_requests` (طلبات ترقية الخطة)

| العمود | النوع | الوصف |
|--------|------|-------|
| `id` | bigint PK | |
| `tenant_id` | bigint FK | الشركة الطالبة |
| `from_plan` | varchar | الخطة الحالية |
| `to_plan` | varchar | الخطة المطلوبة |
| `billing_interval` | enum | `monthly` أو `yearly` |
| `status` | enum | `pending`, `approved`, `rejected` |
| `receipt_path` | varchar nullable | مسار إيصال التحويل البنكي |
| `admin_notes` | text nullable | ملاحظات الإدارة |
| `reviewed_at` | timestamp nullable | تاريخ المراجعة |
| `created_at` | timestamp | |
| `updated_at` | timestamp | |

---

### جدول: `app_notifications` (الإشعارات)

| العمود | النوع | الوصف |
|--------|------|-------|
| `id` | bigint PK | |
| `tenant_id` | bigint FK nullable | الشركة المستهدفة (null = للإدارة) |
| `type` | varchar | نوع الإشعار |
| `title` | varchar | عنوان الإشعار |
| `body` | text | نص الإشعار |
| `data` | JSON nullable | بيانات إضافية |
| `read_at` | timestamp nullable | وقت القراءة |
| `created_at` | timestamp | |
| `updated_at` | timestamp | |

---

### جدول: `platform_settings` (إعدادات المنصة)

| العمود | النوع | الوصف |
|--------|------|-------|
| `id` | bigint PK | |
| `key` | varchar UNIQUE | مفتاح الإعداد |
| `value` | text nullable | قيمة الإعداد |
| `created_at` | timestamp | |
| `updated_at` | timestamp | |

---

### جداول النظام (Laravel)

| الجدول | الغرض |
|--------|--------|
| `sessions` | تخزين جلسات المستخدمين |
| `cache` | تخزين الـ Cache |
| `jobs` | طابور المهام المعلّقة |
| `failed_jobs` | المهام الفاشلة |
| `job_batches` | مجموعات المهام |

---

## 6. النماذج (Models) وعلاقاتها

### Tenant

```php
// app/Models/Tenant.php
```

**العلاقات:**

| العلاقة | النوع | الوصف |
|---------|------|-------|
| `users()` | hasMany | مستخدمو الشركة |
| `devices()` | hasMany | أجهزة ZATCA المسجّلة |
| `invoices()` | hasMany | فواتير الشركة |
| `apiKeys()` | hasMany | مفاتيح API |
| `customers()` | hasMany | عملاء الشركة |
| `catalogItems()` | hasMany | كتالوج المنتجات |
| `quotations()` | hasMany | عروض الأسعار |
| `upgradeRequests()` | hasMany | طلبات ترقية الخطة |
| `notifications()` | hasMany | إشعارات الشركة |
| `planDetails()` | belongsTo Plan | تفاصيل خطة الاشتراك |

**Methods مهمة:**

```php
// هل الشركة جاهزة لإنشاء CSR للإنتاج؟
$tenant->isReadyForProductionCsr(): bool

// العنوان البريدي بصيغة ZATCA
$tenant->zatcaPostalAddress(): array

// تصميم الفاتورة المحدد
$tenant->invoiceDesign(): string

// هل تجاوزت الحصة الشهرية؟
$tenant->isQuotaExceeded(): bool

// بيئة ZATCA النشطة (sandbox/production)
$tenant->zatcaEnvironment(): ZatcaEnvironment
```

---

### User

```php
// app/Models/User.php
```

| العلاقة | النوع | الوصف |
|---------|------|-------|
| `tenant()` | belongsTo | الشركة المرتبطة |

**ملاحظة:** المستخدم الواحد ينتمي لشركة واحدة فقط. إذا كان `is_super_admin = true` فلديه صلاحيات لوحة الإدارة الكاملة.

---

### Device

```php
// app/Models/Device.php
```

| العلاقة | النوع | الوصف |
|---------|------|-------|
| `tenant()` | belongsTo | الشركة المالكة |
| `invoices()` | hasMany | الفواتير المُصدَرة عبر هذا الجهاز |

**دورة حياة الجهاز (`onboarding_status`):**

```
pending → csr_generated → compliance_done → production_ready
```

---

### Invoice

```php
// app/Models/Invoice.php
```

| العلاقة | النوع | الوصف |
|---------|------|-------|
| `tenant()` | belongsTo | الشركة المُصدِرة |
| `device()` | belongsTo | الجهاز المُصدِر |

---

### Customer

```php
// app/Models/Customer.php
```

| العلاقة | النوع | الوصف |
|---------|------|-------|
| `tenant()` | belongsTo | الشركة المالكة |

---

### Plan

```php
// app/Models/Plan.php
```

| العلاقة | النوع | الوصف |
|---------|------|-------|
| `tenants()` | hasMany | الشركات المشتركة في هذه الخطة |

---

### ApiKey

```php
// app/Models/ApiKey.php
```

| العلاقة | النوع | الوصف |
|---------|------|-------|
| `tenant()` | belongsTo | الشركة المالكة |

---

## 7. Controllers وما يفعله كل واحد

### Controllers الإدارة (`/admin/*`)

| Controller | المسار | الوظيفة |
|------------|--------|---------|
| `AdminAuthController` | `/admin/login` | تسجيل دخول / خروج المشرف |
| `AdminDashboardController` | `/admin` | لوحة الإدارة الرئيسية مع إحصائيات عامة |
| `AdminTenantController` | `/admin/tenants` | عرض / تعديل / انتحال هوية / تفعيل وتعطيل / إعادة تعيين استخدام المستأجرين |
| `AdminInvoiceController` | `/admin/invoices` | استعراض جميع الفواتير في المنصة |
| `AdminQuotationController` | `/admin/quotations` | استعراض جميع عروض الأسعار |
| `AdminPlanController` | `/admin/plans` | إدارة خطط الاشتراك (إنشاء / تعديل / حذف) |
| `AdminSubscriptionController` | `/admin/subscriptions` | إدارة اشتراكات المستأجرين |
| `AdminUpgradeRequestController` | `/admin/upgrade-requests` | قبول / رفض طلبات ترقية الخطة |
| `AdminNotificationController` | `/admin/notifications` | إشعارات الإدارة |
| `AdminBankSettingController` | `/admin/bank-settings` | إعدادات الحساب البنكي لاستقبال التحويلات |
| `AdminZatcaMonitorController` | `/admin/zatca-monitor` | مراقبة حالة الاتصال بـ ZATCA |
| `AdminCustomerController` | `/admin/customers` | استعراض جميع العملاء في المنصة |

---

### Controllers لوحة المستأجر (`/dashboard/*`)

| Controller | المسار | الوظيفة |
|------------|--------|---------|
| `DashboardController` | `/dashboard` | الصفحة الرئيسية مع إحصائيات الفواتير والاشتراك |
| `InvoiceViewController` | `/dashboard/invoices` | إنشاء / عرض / قائمة الفواتير بجميع أنواعها |
| `QuotationController` | `/dashboard/quotations` | إنشاء / عرض عروض الأسعار وتحويلها لفواتير |
| `CustomerController` | `/dashboard/customers` | إدارة قاعدة العملاء |
| `CatalogItemController` | `/dashboard/catalog` | إدارة كتالوج المنتجات والخدمات |
| `OnboardingWizardController` | `/dashboard/onboarding` | معالج التهيئة الثلاثي (VAT → بيانات الشركة → التفعيل) |
| `SettingsController` | `/dashboard/settings` | إعدادات الشركة، القالب، المستخدمون، مفاتيح API، الفروع |
| `SubscriptionController` | `/dashboard/subscription` | عرض خطة الاشتراك وطلب الترقية |
| `NotificationController` | `/dashboard/notifications` | إشعارات المستأجر |
| `ReportController` | `/dashboard/reports` | التقارير والتصدير |
| `ApiKeyViewController` | `/dashboard/api-keys` | إدارة مفاتيح API |
| `ApiDocsController` | `/dashboard/api-docs` | صفحة توثيق API |

---

### Controllers واجهة API (`/api/v1/*`)

| Controller | المسار | الوظيفة |
|------------|--------|---------|
| `InvoiceController` | `/api/v1/invoices` | إنشاء / عرض / تحميل الفواتير برمجياً |
| `DeviceController` | `/api/v1/devices` | إدارة أجهزة POS عبر API |
| `ToolsController` | `/api/v1/tools` | أدوات مساعدة (التحقق من الرقم الضريبي، فك تشفير QR، حساب الضريبة) |

---

### Controllers المصادقة (Auth)

| Controller | الوظيفة |
|------------|---------|
| `AuthController` | تسجيل مستخدم جديد / دخول / إرسال OTP / التحقق من OTP |
| `SocialAuthController` | تسجيل دخول عبر Google أو Apple OAuth |

---

### Controllers عامة (Web)

| Controller | الوظيفة |
|------------|---------|
| `HomeController` | الصفحة الرئيسية (Landing Page) |
| `ToolPageController` | صفحات الأدوات المجانية (التحقق من رقم ضريبي / قراءة QR / حساب ضريبة) |

---

### Controllers Ops (`/ops/*`)

| Controller | الوظيفة |
|------------|---------|
| `OpsConsoleController` | لوحة Ops الداخلية: تشغيل أوامر، عرض المهام، مراجعة الـ logs |

---

## 8. Services (الخدمات)

### خدمات ZATCA (`app/Services/Zatca/`)

| الخدمة | الوظيفة التفصيلية |
|--------|------------------|
| **ZatcaEngine** | المنسّق الرئيسي لجميع خدمات ZATCA. يربط بين بناء XML والتوقيع والإرسال |
| **XmlBuilderService** | يبني XML للفاتورة وفق معيار UBL 2.1 المطلوب من ZATCA بجميع الحقول الإلزامية |
| **XmlSignerService** | يوقّع XML رقمياً باستخدام خوارزمية ECDSA مع SHA-256 ويضمّن الشهادة في XML |
| **ClearanceService** | يرسل الفواتير القياسية (Standard) لنقطة API الإخلاء (Clearance) في ZATCA ويعالج الاستجابة |
| **ReportingService** | يرسل الفواتير المبسّطة (Simplified) لنقطة API الإبلاغ (Reporting) في ZATCA |
| **OnboardingService** | يدير عملية تسجيل الجهاز مع ZATCA: إرسال CSR + OTP لاستلام الشهادة |
| **KeypairService** | يولّد أزواج المفاتيح ECDSA (مفتاح عام + خاص) وطلب CSR بالمعلومات الصحيحة |
| **QrGeneratorService** | يولّد بيانات QR بصيغة TLV وفق مواصفات ZATCA للفواتير المبسّطة والقياسية |
| **PdfService** | يولّد ملف PDF للفاتورة باللغتين العربية والإنجليزية مع QR code مدمج |
| **HashChainService** | يحتفظ بسلسلة هاشات الفواتير (PIH - Previous Invoice Hash) لضمان التسلسل والتكامل |

---

### خدمات لوحة التحكم (`app/Services/Dashboard/`)

| الخدمة | الوظيفة التفصيلية |
|--------|------------------|
| **InvoiceIssuer** | منسّق إصدار الفاتورة: يتحقق من البيانات، يوقّع XML، يولّد QR، ثم يرسل لـ ProcessInvoiceJob |
| **DeviceOnboardingService** | يدير سير عمل تسجيل الجهاز خطوة بخطوة من واجهة المستخدم |

---

### خدمة OTP

| الخدمة | الوظيفة |
|--------|---------|
| **OtpService** | توليد رمز OTP (6 أرقام)، إرساله عبر البريد الإلكتروني، والتحقق منه خلال مدة صلاحيته |

---

## 9. مسارات التطبيق (Routes)

إجمالي المسارات: **148 مساراً**

### تصنيف المسارات الرئيسية

| المجموعة | البادئة | المصادقة | الوصف |
|----------|--------|---------|-------|
| عامة | `/` | بدون | الصفحة الرئيسية والأدوات المجانية |
| مصادقة | `/login`, `/register` | بدون | تسجيل الدخول والتسجيل مع OTP |
| OAuth | `/auth/google`, `/auth/apple` | بدون | تسجيل دخول اجتماعي |
| لوحة المستأجر | `/dashboard/*` | Session (tenant) | إدارة الفواتير والشركة |
| لوحة الإدارة | `/admin/*` | Session (super_admin) | إدارة المنصة |
| API | `/api/v1/*` | API Key | وصول برمجي |
| Ops | `/ops/*` | Ops Auth | لوحة العمليات الداخلية |
| أدوات مجانية | `/tools/*` | بدون | أدوات ZATCA العامة |

### مسارات لوحة المستأجر التفصيلية

| الطريقة | المسار | الوظيفة |
|---------|--------|---------|
| GET | `/dashboard` | الصفحة الرئيسية |
| GET | `/dashboard/invoices` | قائمة الفواتير |
| GET | `/dashboard/invoices/create` | نموذج إنشاء فاتورة |
| POST | `/dashboard/invoices` | حفظ فاتورة جديدة |
| GET | `/dashboard/invoices/{uuid}` | عرض فاتورة |
| GET | `/dashboard/invoices/{uuid}/pdf` | تحميل PDF |
| GET | `/dashboard/quotations` | قائمة عروض الأسعار |
| POST | `/dashboard/quotations/{uuid}/convert` | تحويل عرض سعر لفاتورة |
| GET | `/dashboard/customers` | قائمة العملاء |
| POST | `/dashboard/customers` | إضافة عميل |
| GET | `/dashboard/settings` | إعدادات الشركة |
| GET | `/dashboard/subscription` | تفاصيل الاشتراك |
| GET | `/dashboard/onboarding/vat` | خطوة التحقق من رقم الضريبة |
| GET | `/dashboard/onboarding/organization` | خطوة بيانات الشركة |
| GET | `/dashboard/onboarding/activate-production` | خطوة تفعيل الإنتاج |

### مسارات API التفصيلية

| الطريقة | المسار | الوظيفة |
|---------|--------|---------|
| GET | `/api/v1/invoices` | قائمة الفواتير |
| POST | `/api/v1/invoices` | إنشاء فاتورة |
| GET | `/api/v1/invoices/{uuid}` | تفاصيل فاتورة |
| GET | `/api/v1/invoices/{uuid}/download` | تحميل PDF الفاتورة |
| GET | `/api/v1/devices` | قائمة الأجهزة |
| POST | `/api/v1/devices` | تسجيل جهاز جديد |
| POST | `/api/v1/tools/vat-validate` | التحقق من رقم ضريبي |
| POST | `/api/v1/tools/qr-decode` | فك تشفير QR |
| POST | `/api/v1/tools/vat-calculate` | حساب الضريبة |

---

## 10. نظام المصادقة (Auth)

### طريقة المصادقة الرئيسية (OTP-based)

```
1. المستخدم يدخل بريده الإلكتروني
2. النظام يرسل رمز OTP مكوّن من 6 أرقام عبر البريد
3. المستخدم يدخل الرمز للتحقق
4. يُنشأ الحساب أو تُفتح الجلسة
```

**المكونات:**
- `OtpCode` model — يخزّن الرمز مع وقت انتهاء الصلاحية
- `OtpService` — يتولى التوليد والإرسال والتحقق
- `AuthController` — يدير سير عمل التسجيل والدخول

### المصادقة الاجتماعية

- **Google OAuth** عبر `laravel/socialite`
- **Apple OAuth** عبر `laravel/socialite`
- Controller: `SocialAuthController`
- مسارات: `/auth/google/redirect`، `/auth/google/callback` (وكذلك لـ Apple)

### مصادقة الإدارة

- نظام Session منفصل لمشرفي المنصة
- Middleware: `EnsureSuperAdmin` — يتحقق من `is_super_admin = true`
- Controller: `AdminAuthController`

### مصادقة API

- Header: `X-Api-Key: emk_xxxxx`
- Middleware: `ApiKeyAuth` — يبحث عن المفتاح في جدول `api_keys` ويتحقق من صلاحيته
- يُحدَّث `last_used_at` عند كل طلب

### مصادقة Ops Console

- Middleware: `OpsConsoleAuth`
- يقرأ البيانات من `OPS_ROUTE_PREFIX` في ملف `.env`

---

## 11. تدفق إنشاء الفاتورة (Invoice Flow)

### رسم بياني للتدفق

```
المستخدم يملأ نموذج الفاتورة
           ↓
   InvoiceViewController::store()
           ↓
   InvoiceIssuer::issue()
    ├── التحقق من البيانات
    ├── التحقق من الحصة الشهرية (isQuotaExceeded?)
    ├── XmlBuilderService::build() → XML خام
    ├── QrGeneratorService::generate() → بيانات QR
    ├── XmlSignerService::sign() → XML موقّع
    ├── HashChainService::updatePih() → تحديث PIH
    └── حفظ الفاتورة بحالة "signed"
           ↓
   ProcessInvoiceJob (Queue)
    ├── [Standard]   ClearanceService::submit() → ZATCA
    └── [Simplified] ReportingService::submit() → ZATCA
           ↓
   تحديث حالة الفاتورة:
    ├── نجاح → "cleared" أو "reported" + zatca_uuid
    └── فشل  → "failed" + تسجيل الخطأ
           ↓
   PdfService::generate() (عند الطلب)
    └── PDF بالعربية والإنجليزية مع QR code
```

### أنواع الفواتير وطريقة إرسالها

| النوع | الوصف | طريقة الإرسال لـ ZATCA |
|------|-------|----------------------|
| `standard` | فاتورة ضريبية قياسية (B2B) | Clearance (إخلاء الطرف) |
| `simplified` | فاتورة ضريبية مبسّطة (B2C) | Reporting (إبلاغ) |
| `credit_note` | إشعار دائن (تعديل سالب) | حسب نوع الفاتورة الأصلية |
| `debit_note` | إشعار مدين (تعديل موجب) | حسب نوع الفاتورة الأصلية |

### حالات الفاتورة (Invoice Status)

```
draft → signed → reported/cleared
                    ↘ failed
           ↘ cancelled
```

| الحالة | الوصف |
|--------|-------|
| `draft` | مسودة، لم تُرسَل بعد |
| `signed` | موقّعة رقمياً، في انتظار الإرسال |
| `reported` | تم إبلاغ ZATCA بها (مبسّطة) |
| `cleared` | تم إخلاء طرف ZATCA منها (قياسية) |
| `failed` | فشل الإرسال إلى ZATCA |
| `cancelled` | ملغاة |

---

## 12. خطوات التهيئة والربط بالهيئة (Onboarding)

معالج التهيئة هو عملية إلزامية يجب أن تُكملها كل شركة جديدة قبل إصدار أي فاتورة حقيقية.

### الخطوة 1: التحقق من رقم الضريبة (`/dashboard/onboarding/vat`)

- المستخدم يدخل رقم الضريبة (15 رقماً)
- النظام يتحقق منه عبر API لـ ZATCA
- عند النجاح: يُخزَّن الرقم في `tenants.vat_number`

### الخطوة 2: بيانات الشركة (`/dashboard/onboarding/organization`)

المستخدم يدخل:
- اسم الشركة (عربي + إنجليزي)
- نوع معرّف المنشأة (`org_identifier_type`): CRN / MOM / MLS / 700 / SAG / NAT / GCC / IQA / PAS / OTH
- قيمة المعرّف (`org_identifier_value`)
- العنوان التفصيلي (شارع، مبنى، مدينة، حي، رمز بريدي)

### الخطوة 3: تفعيل الإنتاج (`/dashboard/onboarding/activate-production`)

هذه الخطوة هي لب عملية الربط بـ ZATCA:

```
1. KeypairService → يولّد زوج مفاتيح ECDSA للجهاز
2. OnboardingService → يبني CSR بمعلومات الشركة والجهاز
3. المستخدم يحصل على OTP من منصة FATOORA (فاتورة)
4. OnboardingService → يرسل CSR + OTP إلى ZATCA
5. ZATCA ترد بشهادة رقمية (Certificate PEM)
6. تُخزَّن الشهادة + المفتاح الخاص في جدول devices
7. onboarding_status → production_ready ✓
```

> [!NOTE]
> كل جهاز (Device) له شهادة رقمية مستقلة. يمكن للشركة امتلاك أجهزة متعددة (فروع / نقاط بيع مختلفة).

---

## 13. نظام الاشتراكات والخطط

### هيكل الخطط

الخطط تُعرَّف في جدول `plans` ويمكن للمشرف إدارتها من `/admin/plans`.

```json
{
  "slug": "pro",
  "name": "الخطة المحترفة",
  "price": 299.00,
  "yearly_price": 2990.00,
  "monthly_invoice_limit": 500,
  "features": ["API Access", "Multiple Devices", "Priority Support"]
}
```

### دورة حياة الاشتراك

```
الشركة تختار خطة → تدفع عبر تحويل بنكي → ترفع إيصال → الإدارة تقبل → تُفعَّل الخطة
```

### طلبات ترقية الخطة

1. المستخدم يختار خطة أعلى من `/dashboard/subscription`
2. يرفع إيصال التحويل البنكي (صورة)
3. يُنشأ سجل في `plan_upgrade_requests` بحالة `pending`
4. المشرف يراجع الطلب من `/admin/upgrade-requests`
5. عند القبول: تُحدَّث بيانات الاشتراك في `tenants`
6. عند الرفض: يُبلَّغ المستخدم بالسبب

### حصة الفواتير

- كل شركة لها `monthly_invoice_limit` يحدد أقصى عدد فواتير شهرياً
- `invoices_used_this_month` يتزايد مع كل فاتورة تُصدَر
- يُعاد تعيين العداد مطلع كل شهر (عبر Command/Job مجدوَل)
- الدالة `isQuotaExceeded()` تتحقق قبل إصدار كل فاتورة

---

## 14. واجهة برمجة التطبيقات (API)

### التوثيق التلقائي

يتوفر توثيق API تفاعلي عبر `dedoc/scramble`:
- **URL**: `/dashboard/api-docs`

### المصادقة

```http
X-Api-Key: emk_xxxxxxxxxxxxxxxx
Content-Type: application/json
Accept: application/json
```

### إنشاء فاتورة (مثال)

```http
POST /api/v1/invoices
X-Api-Key: emk_xxxxx

{
  "type": "simplified",
  "buyer_name": "عميل تجريبي",
  "issued_at": "2026-10-25T10:00:00Z",
  "line_items": [
    {
      "name": "استشارة تقنية",
      "quantity": 2,
      "unit_price": 500.00,
      "vat_rate": 15
    }
  ]
}
```

### قراءة فاتورة

```http
GET /api/v1/invoices/{uuid}
X-Api-Key: emk_xxxxx
```

### تحميل PDF

```http
GET /api/v1/invoices/{uuid}/download
X-Api-Key: emk_xxxxx
```

### أدوات ZATCA

```http
# التحقق من رقم ضريبي
POST /api/v1/tools/vat-validate
{ "vat_number": "300000000000003" }

# فك تشفير QR
POST /api/v1/tools/qr-decode
{ "qr_data": "base64_encoded_tlv_data" }

# حساب الضريبة
POST /api/v1/tools/vat-calculate
{ "amount": 1000, "vat_rate": 15 }
```

---

## 15. الأدوات المجانية العامة

متاحة لأي زائر بدون تسجيل دخول على `/tools/*`

| الأداة | المسار | الوظيفة |
|--------|--------|---------|
| التحقق من الرقم الضريبي | `/tools/vat-validator` | التحقق من صحة رقم الضريبة عبر ZATCA API |
| قارئ QR | `/tools/qr-reader` | رفع صورة أو نص QR وفك تشفيره وعرض بيانات الفاتورة |
| حاسبة الضريبة | `/tools/vat-calculator` | حساب مبلغ ضريبة القيمة المضافة (شامل / غير شامل) |

هذه الأدوات تُستخدَم أيضاً كأداة تسويقية لاستقطاب المستخدمين للمنصة.

---

## 16. لوحة الادمن (Admin Panel)

### الوصول

- المسار: `/admin`
- المصادقة: Session منفصل + `is_super_admin = true`
- Controller: `AdminAuthController`

### وظائف لوحة الإدارة

#### إدارة المستأجرين

```
/admin/tenants
├── عرض قائمة جميع الشركات
├── تفاصيل كل شركة (خطتها، عدد فواتيرها، حالتها)
├── تعديل بيانات الشركة
├── تفعيل / تعطيل الحساب (is_active)
├── انتحال هوية مستخدم (Impersonate) للدعم الفني
└── إعادة تعيين عداد الفواتير الشهري
```

#### إدارة الخطط

```
/admin/plans
├── إنشاء خطة جديدة
├── تعديل أسعار وحدود الخطط
└── تفعيل / تعطيل الخطط
```

#### طلبات الترقية

```
/admin/upgrade-requests
├── عرض الطلبات المعلّقة مع إيصالات التحويل
├── قبول الطلب → ترقية الخطة تلقائياً
└── رفض الطلب مع إضافة ملاحظة
```

#### مراقبة ZATCA

```
/admin/zatca-monitor
├── حالة الاتصال بـ ZATCA
├── إحصائيات الفواتير المُرسَلة والمرفوضة
└── تفاصيل الأخطاء
```

#### إعدادات البنك

```
/admin/bank-settings
└── تعديل بيانات الحساب البنكي المعروضة للمستأجرين عند الدفع
```

---

## 17. لوحة Ops Console

لوحة داخلية للفريق الهندسي (ليست للعملاء).

### الوصول

- المسار: `/{OPS_ROUTE_PREFIX}` (مُعرَّف في `.env` كـ `OPS_ROUTE_PREFIX=ops`)
- Middleware: `OpsConsoleAuth`

### الوظائف

| الوظيفة | الوصف |
|---------|-------|
| تشغيل أوامر Artisan | تنفيذ أوامر Laravel مباشرة من المتصفح |
| مراجعة Jobs | عرض المهام المعلّقة والفاشلة |
| قراءة Logs | عرض ملفات السجلات الأخيرة |

> [!WARNING]
> لوحة Ops ذات صلاحيات عالية جداً. يجب تأمين الوصول إليها بكلمة مرور قوية وإخفاء مسارها عن العامة عبر `OPS_ROUTE_PREFIX` في `.env`.

---

## 18. متغيرات البيئة (.env)

### إعدادات التطبيق

```dotenv
APP_NAME=EMZatca
APP_ENV=local          # local | production
APP_KEY=               # يُولَّد بـ php artisan key:generate
APP_DEBUG=true         # false في الإنتاج
APP_URL=https://zatca-tools.test
APP_LOCALE=ar
APP_FALLBACK_LOCALE=en
```

### إعدادات قاعدة البيانات

```dotenv
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=emzatca
DB_USERNAME=root
DB_PASSWORD=
```

### إعدادات الطابور والكاش والجلسات

```dotenv
QUEUE_CONNECTION=database
CACHE_STORE=database
SESSION_DRIVER=database
SESSION_LIFETIME=120
```

### إعدادات البريد

```dotenv
MAIL_MAILER=smtp
MAIL_HOST=sandbox.smtp.mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=
MAIL_PASSWORD=
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS="noreply@emzatca.com"
MAIL_FROM_NAME="${APP_NAME}"
```

### إعدادات المصادقة الاجتماعية

```dotenv
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_REDIRECT_URI=https://zatca-tools.test/auth/google/callback

APPLE_CLIENT_ID=
APPLE_CLIENT_SECRET=
APPLE_REDIRECT_URI=https://zatca-tools.test/auth/apple/callback
```

### إعدادات Ops Console

```dotenv
OPS_ROUTE_PREFIX=ops   # غيّره لشيء سري في الإنتاج
```

---

## 19. تشغيل الاختبارات

### إطار الاختبار

المشروع يستخدم **Pest PHP** — إطار اختبار حديث مبني فوق PHPUnit.

### هيكل الاختبارات

```
tests/
├── Feature/     # اختبارات شاملة تختبر السلوك الكامل مع قاعدة البيانات
└── Unit/        # اختبارات وحدة تختبر منطق الكلاسات منفردةً
```

### أوامر تشغيل الاختبارات

```bash
# تشغيل جميع الاختبارات
php artisan test --compact

# تشغيل ملف اختبار محدد
php artisan test tests/Feature/InvoiceTest.php

# تشغيل اختبارات بفلتر الاسم
php artisan test --filter=InvoiceCreationTest

# استخدام Pest مباشرة
vendor/bin/pest

# Pest مع فلتر
vendor/bin/pest --filter=invoice
```

### إنشاء اختبار جديد

```bash
# اختبار Feature
php artisan make:test --pest InvoiceCreationTest

# اختبار Unit
php artisan make:test --pest --unit InvoiceHashTest
```

> [!TIP]
> دائماً اكتب اختبارات Feature لأي منطق عمل جديد. استخدم Factories لإنشاء البيانات بدلاً من إنشاء سجلات يدوياً.

---

## 20. نقاط مهمة وملاحظات للمطوّر القادم

### 1. متعدد المستأجرين (Multi-Tenancy)

المشروع **ليس** متعدد المستأجرين بقواعد بيانات منفصلة. كل البيانات في قاعدة واحدة، ويتم العزل بعمود `tenant_id`. لذا:

> [!CAUTION]
> **دائماً** أضف `->where('tenant_id', auth()->user()->tenant_id)` في كل query. نسيان هذا يعني أن المستأجر يرى بيانات غيره!

### 2. سلسلة الهاشات (Hash Chain)

الفواتير مترابطة بسلسلة هاشات. كل فاتورة تحتوي على هاش الفاتورة السابقة (`PIH`). لا تُعدِّل هاشات الفواتير يدوياً أو ستكسر التسلسل.

### 3. المفاتيح الخاصة (Private Keys)

- المفاتيح الخاصة للأجهزة تُخزَّن في `devices.private_key`
- يجب أن تكون مشفّرة في قاعدة البيانات في الإنتاج
- لا تُسجَّل في الـ Logs ولا تُرسَل في API responses

### 4. بيئة ZATCA (Sandbox vs Production)

- كل مستأجر له بيئة مستقلة (`is_sandbox`)
- في بيئة Sandbox: الفواتير تذهب لخادم اختبار ZATCA
- لا تخلط بين بيئتي Sandbox و Production

### 5. حصة الفواتير الشهرية

- لا يمكن إصدار فاتورة إذا `isQuotaExceeded() = true`
- يُعاد تعيين العداد مطلع كل شهر — تأكد من وجود Job/Command مجدوَل لذلك

### 6. طابور المهام (Queue)

- طابور المهام **ضروري** لإرسال الفواتير لـ ZATCA
- في الإنتاج: استخدم Supervisor لضمان استمرارية `queue:work`
- راقب جدول `failed_jobs` بانتظام

### 7. تنسيق الكود

```bash
# بعد أي تعديل على ملفات PHP، شغّل:
vendor/bin/pint --dirty --format agent
```

### 8. قواعد AI في المشروع

```
.ai/rules/
└── index.md   # خريطة القواعد — اقرأه قبل أي تعديل
```

### 9. أوامر مفيدة للتطوير اليومي

```bash
# عرض جميع المسارات
php artisan route:list

# فلترة مسارات بالاسم
php artisan route:list --name=invoice

# قراءة إعداد محدد
php artisan config:show app.locale

# مسح الكاش
php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear

# تشغيل Worker للطابور
php artisan queue:listen

# إعادة تشغيل المهام الفاشلة
php artisan queue:retry all

# مسح المهام الفاشلة
php artisan queue:flush
```

### 10. الترتيب الموصى به عند الانضمام للمشروع

1. ✅ اقرأ هذه الوثيقة كاملة
2. ✅ راجع `.ai/rules/index.md` وجميع ملفات القواعد
3. ✅ شغّل `composer install && npm install`
4. ✅ أعدّ ملف `.env` وشغّل `php artisan migrate`
5. ✅ شغّل `composer run dev`
6. ✅ شغّل الاختبارات: `php artisan test --compact`
7. ✅ استعرض المسارات: `php artisan route:list`
8. ✅ جرّب الأدوات المجانية على `https://zatca-tools.test/tools`

---

> **ملاحظة ختامية:** هذا المشروع يتعامل مع بيانات مالية وضريبية حساسة للغاية. أي تعديل على منطق XML أو التوقيع أو إرسال الفواتير يجب اختباره بعناية في بيئة Sandbox قبل الإنتاج. تواصل مع ZATCA عند أي تغيير في متطلبات المنظومة.