═════════════════════════════════════════════════════════════════════════════════
  نظام فوترة المستخلصات - مرجع سريع (Quick Reference)
═════════════════════════════════════════════════════════════════════════════════

🎯 الفكرة الأساسية:
───────────────────
المستخلص المعتمد → فاتورة المستخلص → قيد محاسبي تلقائي
الإيراد المستحق → الذمة العميل

═════════════════════════════════════════════════════════════════════════════════

📊 المراحل:

مرحلة 1: المستخلص (Certificate)
├─ حالة: معتمد (approved)
├─ الفكرة: إثبات الإيراد المستحق
└─ المبلغ: معتمد من الإدارة

↓

مرحلة 2: الفاتورة (Invoice)
├─ نوع: progress_billing
├─ الفكرة: تحويل الإيراد للعميل
├─ المبلغ: نفس المستخلص
└─ الحالة: مسودة (draft)

↓

مرحلة 3: القيد المحاسبي (Journal Entry)
├─ من: ح/ العميل (10204)
├─ إلى: ح/ الإيرادات المستحقة (10208)
├─ المبلغ: نفس الفاتورة
└─ الحالة: مسودة (draft)

═════════════════════════════════════════════════════════════════════════════════

🔑 الملفات الرئيسية:

قاعدة البيانات:
  database/migrations/2025_11_22_173055_create_progress_billing_invoices_system.php

النماذج:
  app/Models/PaymentCertificate.php (+ علاقة progressBillingInvoice)
  app/Models/CustomerInvoice.php (+ علاقات جديدة)

الخدمات:
  app/Services/ProgressBillingInvoiceJournalService.php

المتحكم:
  app/Http/Controllers/ProgressBillingInvoiceController.php

المسارات:
  routes/customers.php

الواجهات:
  resources/views/progress-billing-invoices/certificates-list.blade.php
  resources/views/progress-billing-invoices/create.blade.php
  resources/views/progress-billing-invoices/show.blade.php

═════════════════════════════════════════════════════════════════════════════════

🚀 سير العمل السريع:

1. ادخل: /progress-billing-invoices/certificates-list
   ↓ عرض المستخلصات المعتمدة والتي لم يتم فوترتها

2. اختر مستخلص
   ↓ انقر "إنشاء فاتورة"

3. ملء البيانات
   ├─ العميل (مطلوب)
   ├─ التاريخ (مطلوب)
   ├─ الملاحظات (اختياري)
   └─ البقية تملأ تلقائياً

4. انقر "إنشاء الفاتورة"
   ↓ إنشاء فاتورة بحالة "draft"

5. انقر "اعتماد الفاتورة"
   ↓ إنشاء قيد محاسبي تلقائي

═════════════════════════════════════════════════════════════════════════════════

📱 المسارات الرئيسية:

GET  /progress-billing-invoices/certificates-list
     → عرض المستخلصات المعتمدة

GET  /progress-billing-invoices/create/{id}
     → نموذج إنشاء فاتورة

POST /progress-billing-invoices
     → حفظ الفاتورة

GET  /progress-billing-invoices/{id}
     → عرض الفاتورة

POST /progress-billing-invoices/{id}/approve
     → اعتماد الفاتورة

DELETE /progress-billing-invoices/{id}
       → حذف الفاتورة

═════════════════════════════════════════════════════════════════════════════════

✅ القيد المحاسبي:

من (مدين):
  الحساب: حساب العميل (10204)
  المبلغ: إجمالي الفاتورة

إلى (دائن):
  الحساب: الإيرادات المستحقة (10208)
  المبلغ: إجمالي الفاتورة

═════════════════════════════════════════════════════════════════════════════════

💡 نقاط مهمة:

✓ كل مستخلص يمكن فوترته مرة واحدة فقط
✓ الفاتورة تأخذ المبلغ من المستخلص مباشرة
✓ لا يتم إضافة ضريبة إضافية على الفاتورة
✓ البيانات تملأ تلقائياً: المشروع، مركز التكلفة
✓ القيد ينشأ تلقائياً عند الاعتماد
✓ يمكن حذف الفاتورة من حالة "draft" فقط

═════════════════════════════════════════════════════════════════════════════════

⚠️ الأخطاء الشائعة:

❌ "هذا المستخلص تم فوترته بالفعل"
   → المستخلص مفوتر بالفعل (is_invoiced = true)

❌ "يجب أن يكون المستخلص معتمداً"
   → حالة المستخلص ليست "approved"

❌ "لا يوجد مستخلص مرتبط بهذه الفاتورة"
   → payment_certificate_id فارغ

❌ "العميل غير مرتبط بحساب"
   → العميل لم يتم ربطه بحساب في دليل الحسابات

❌ "لا توجد سنة مالية نشطة"
   → السنة المالية محغلقة (status != 'open')

═════════════════════════════════════════════════════════════════════════════════

🔍 التحقق من الفاتورة:

✓ الرقم: PBI-YYYYMM-XXXX (مثل: PBI-202511-0001)
✓ النوع: progress_billing
✓ الحالة: draft أو sent
✓ المبلغ: من المستخلص مباشرة
✓ المشروع: من المستخلص
✓ مركز التكلفة: من المستخلص
✓ القيد: من ح/ العميل إلى ح/ الإيرادات المستحقة

═════════════════════════════════════════════════════════════════════════════════

📈 مثال عملي كامل:

المستخلص:
  - الرقم: PC-2025-001
  - المبلغ: 100,000 ريال
  - المشروع: بناء المستشفى
  - مركز التكلفة: المرحلة الأولى
  - الحالة: معتمد

الفاتورة:
  - الرقم: PBI-202511-0001
  - المبلغ: 100,000 ريال
  - العميل: وزارة الصحة
  - التاريخ: 22 نوفمبر 2025

القيد:
  من: وزارة الصحة (10204) ........... 100,000 (مدين)
  إلى: الإيرادات المستحقة (10208) ... 100,000 (دائن)

═════════════════════════════════════════════════════════════════════════════════

🎓 متطلبات الاستخدام:

✓ سنة مالية نشطة
✓ فترة محاسبية نشطة
✓ حساب العميل موجود (10204)
✓ حساب الإيرادات المستحقة موجود (10208)
✓ صلاحية customer-invoices.create
✓ صلاحية customer-invoices.update

═════════════════════════════════════════════════════════════════════════════════

📞 الدعم السريع:

مشكلة         | الحل
──────────────┼────────────────────────────────
لا يوجد مستخلصات  | تحقق من وجود مستخلصات معتمدة
الفاتورة لم تُحفظ   | تحقق من الصلاحيات والبيانات
القيد لم ينشأ     | تحقق من السنة المالية والفترة
لا يمكن حذف      | الفاتورة ليست بحالة "draft"

═════════════════════════════════════════════════════════════════════════════════

📝 الملفات الموصى بها:

1. PROGRESS_BILLING_SYSTEM_GUIDE.md
   → شرح مفصل للنظام بالكامل

2. PROGRESS_BILLING_SETUP.md
   → خطوات التشغيل والاختبار

3. PROGRESS_BILLING_QUICK_REFERENCE.txt
   → هذا الملف (مرجع سريع)

═════════════════════════════════════════════════════════════════════════════════

✨ الإصدار: 1.0.0
📅 التاريخ: 22 نوفمبر 2025
✅ الحالة: جاهز للإنتاج

═════════════════════════════════════════════════════════════════════════════════
