================================================================================
                     تقرير شامل لأخطاء حفظ فاتورة العملاء
================================================================================

📍 معلومات عن المشكلة:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
المشكلة: لا نستطيع حفظ الفاتورة
الملف المتحكم: app/Http/Controllers/CustomerInvoiceController.php
الدالة: store() - السطر 73
================================================================================


✋ الخطأ #1: مشاكل المستخدم والشركة
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❌ الخطأ 1.1: "خطأ: المستخدم غير مسجل الدخول. يرجى تسجيل الدخول أولاً."
   السبب: الدالة Auth::user() ترجع null
   رقم السطر: 75
   الحل:
   ✓ تأكد من تسجيل الدخول إلى النظام
   ✓ تحقق من صحة بيانات المستخدم

❌ الخطأ 1.2: "خطأ: لم يتم تعيين الشركة للمستخدم."
   السبب: Auth::user()->company_id غير موجود
   رقم السطر: 84
   الحل:
   ✓ اذهب إلى إدارة المستخدمين
   ✓ حرر المستخدم وتأكد من تعيين شركة
   ✓ احفظ البيانات وسجل خروج ثم تسجيل دخول مجدداً


🔒 الخطأ #2: مشاكل الصلاحيات والتفويض
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❌ الخطأ 2.1: "خطأ في الصلاحيات: أنت لا تملك صلاحية إنشاء فواتير عملاء"
   السبب: المستخدم لا يملك صلاحية 'customer-invoices.create'
   رقم السطر: 80-82
   الحل:
   ✓ اطلب من مسؤول النظام منح صلاحية 'customer-invoices.create'
   ✓ تأكد من أن المستخدم لديه دور (role) صحيح

❌ الخطأ 2.2: "غير مصرح بإنشاء هذا العنصر" (403 Forbidden)
   السبب: السياسة (Policy) في CustomerInvoicePolicy ترفض الإنشاء
   رقم السطر: 88
   الحل:
   ✓ راجع ملف: app/Policies/CustomerInvoicePolicy.php
   ✓ تحقق من شروط الإنشاء في دالة create()


📋 الخطأ #3: بيانات الفاتورة غير صحيحة (Validation Errors)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❌ الخطأ 3.1: "العميل مطلوب / The customer id field is required"
   الحقل: customer_id
   السبب: لم يتم اختيار عميل من القائمة المنسدلة
   الحل:
   ✓ اختر عميل من قائمة "العميل"
   ✓ تأكد من وجود عملاء نشطين في النظام

❌ الخطأ 3.2: "تاريخ الفاتورة مطلوب / The invoice date field is required"
   الحقل: invoice_date
   السبب: لم يتم إدخال تاريخ الفاتورة
   الحل:
   ✓ أدخل تاريخ الفاتورة في حقل "تاريخ الفاتورة"
   ✓ يجب أن يكون التاريخ بصيغة صحيحة (YYYY-MM-DD)

❌ الخطأ 3.3: "تاريخ الاستحقاق يجب أن يكون بعد تاريخ الفاتورة"
   الحقل: due_date
   السبب: due_date < invoice_date
   الحل:
   ✓ تأكد من أن تاريخ الاستحقاق >= تاريخ الفاتورة
   ✓ غيّر تاريخ الاستحقاق إلى تاريخ لاحق

❌ الخطأ 3.4: "يجب إضافة بند واحد على الأقل"
   الحقل: items
   السبب: لا توجد بنود في الفاتورة
   الحل:
   ✓ انقر على زر "إضافة بند جديد"
   ✓ ملء بيانات البند (الوصف، الكمية، السعر)
   ✓ أضف بند واحد على الأقل قبل الحفظ


📦 الخطأ #4: بيانات البنود (Items) غير صحيحة
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❌ الخطأ 4.1: "الوصف مطلوب / items.*.description is required"
   الحقل: items[*].description
   السبب: لم يتم إدخال وصف البند
   الحل:
   ✓ أدخل وصف واضح للبند في كل صف
   ✓ مثال: "مواد البناء - رمل وحصى"

❌ الخطأ 4.2: "الكمية مطلوبة وتكون > 0 / items.*.quantity must be numeric and >= 0.01"
   الحقل: items[*].quantity
   السبب: الكمية فارغة أو قيمتها 0 أو أقل
   الحل:
   ✓ أدخل كمية صحيحة (أكبر من 0)
   ✓ استخدم أرقام عشرية إن لزم الأمر (مثل 0.5)

❌ الخطأ 4.3: "سعر الوحدة مطلوب / items.*.unit_price is required"
   الحقل: items[*].unit_price
   السبب: سعر الوحدة فارغ
   الحل:
   ✓ أدخل سعر الوحدة للبند
   ✓ تأكد من أن السعر > 0

❌ الخطأ 4.4: "نسبة الضريبة يجب أن تكون بين 0-100 / items.*.tax_rate must be numeric and between 0-100"
   الحقل: items[*].tax_rate
   السبب: نسبة ضريبة غير صحيحة
   الحل:
   ✓ أدخل نسبة ضريبة صحيحة (0-100)
   ✓ مثال: 15 للضريبة 15%

❌ الخطأ 4.5: "الخصم يجب أن يكون >= 0 / items.*.discount_amount must be numeric and >= 0"
   الحقل: items[*].discount_amount
   السبب: مبلغ خصم سالب
   الحل:
   ✓ أدخل مبلغ خصم صحيح >= 0
   ✓ اترك الحقل فارغاً إذا لم يكن هناك خصم


💾 الخطأ #5: مشاكل قاعدة البيانات والعلاقات
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❌ الخطأ 5.1: "SQLSTATE[HY000]: General error: 1364 Field 'xxx' doesn't have a default value"
   السبب: حقل مطلوب في الجدول لم يتم ملؤه
   الحل:
   ✓ تحقق من جميع الحقول المطلوبة في دالة store()
   ✓ تأكد من إرسال جميع البيانات المطلوبة

❌ الخطأ 5.2: "SQLSTATE[23000]: Integrity constraint violation: 1452"
   السبب: معرف عميل أو عقد غير موجود في الجداول الأصلية
   الحل:
   ✓ تأكد من أن customer_id موجود في جدول customers
   ✓ تأكد من أن contract_id موجود في جدول customer_contracts
   ✓ استخدم أمر SQL للتحقق:
      SELECT * FROM customers WHERE id = [customer_id];
      SELECT * FROM customer_contracts WHERE id = [contract_id];

❌ الخطأ 5.3: "SQLSTATE[HY000]: General error: 1366 Incorrect integer value"
   السبب: قيمة غير صحيحة لحقل integer
   الحل:
   ✓ تأكد من أن customer_id و contract_id أرقام صحيحة
   ✓ تحقق من أنواع البيانات المرسلة


📚 الخطأ #6: مشاكل القيود اليومية (Journal Entry)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❌ الخطأ 6.1: "لا توجد سنة مالية أو فترة محاسبية نشطة"
   السبب: في دالة createJournalEntry() - لا توجد سنة مالية بحالة open
   الحل:
   ✓ اذهب إلى: الإعدادات → الحسابات → السنوات المالية
   ✓ أنشئ سنة مالية جديدة بحالة "نشطة"
   ✓ أنشئ فترة محاسبية بحالة "مفتوحة"

❌ الخطأ 6.2: "العميل غير مرتبط بحساب في دليل الحسابات"
   السبب: العميل لا يملك chart_of_account_id
   الحل:
   ✓ اذهب إلى: إدارة العملاء
   ✓ افتح تفاصيل العميل
   ✓ اختر حساب من دليل الحسابات
   ✓ احفظ التغييرات

❌ الخطأ 6.3: "حساب المبيعات غير موجود في دليل الحسابات"
   السبب: لا يوجد حساب برمز 4100 أو بكلمة "مبيعات"
   الحل:
   ✓ اذهب إلى: الإعدادات → الحسابات → دليل الحسابات
   ✓ أنشئ حساب جديد برمز "4100" باسم "المبيعات"
   ✓ نوع الحساب: revenue (إيراد)
   ✓ نوع الرصيد: credit (دائن)

❌ الخطأ 6.4: "حساب الضريبة غير موجود في دليل الحسابات"
   السبب: لا يوجد حساب برمز 217001 أو 2170
   الحل:
   ✓ اذهب إلى: الإعدادات → الحسابات → دليل الحسابات
   ✓ أنشئ حساب جديد برمز "217001" باسم "ضريبة القيمة المضافة المحصلة"
   ✓ نوع الحساب: liability (التزام)
   ✓ نوع الرصيد: credit (دائن)


🔧 الخطأ #7: أخطاء البرمجة والكود
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❌ الخطأ 7.1: "Call to undefined method..."
   السبب: دالة غير موجودة أو لم يتم استيرادها
   الحل:
   ✓ افتح ملف السجل: storage/logs/laravel.log
   ✓ ابحث عن اسم الدالة المفقودة
   ✓ تحقق من استيراد الفئة الصحيحة

❌ الخطأ 7.2: "TypeError: Argument 1 passed to function... must be of type string"
   السبب: نوع بيانات غير متطابق
   الحل:
   ✓ تحقق من أنواع البيانات المرسلة
   ✓ تأكد من أن البيانات نص (string) أو رقم (int/float)


✅ خطوات حل المشكلة خطوة بخطوة:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1️⃣ تسجيل الدخول والتحقق الأساسي
   □ تأكد من تسجيل الدخول إلى النظام
   □ تأكد من ربط المستخدم بشركة
   □ تأكد من وجود صلاحية 'customer-invoices.create'

2️⃣ الإعدادات المحاسبية
   □ أنشئ سنة مالية بحالة "نشطة"
   □ أنشئ فترة محاسبية بحالة "مفتوحة"
   □ أنشئ حساب مبيعات برمز 4100
   □ أنشئ حساب ضريبة برمز 217001

3️⃣ إعداد العملاء
   □ تأكد من وجود عملاء نشطين
   □ ربط كل عميل بحساب محاسبي

4️⃣ ملء بيانات الفاتورة
   □ اختر عميل
   □ اختر (أو اترك فارغاً) عقد
   □ أدخل تاريخ الفاتورة
   □ أدخل تاريخ الاستحقاق

5️⃣ إضافة البنود
   □ انقر "إضافة بند جديد"
   □ أدخل الوصف والكمية والسعر
   □ أدخل الضريبة والخصم (اختياري)
   □ أضف بندين على الأقل للتأكد

6️⃣ الحفظ
   □ تحقق من أن جميع الحقول ممتلئة
   □ انقر زر "حفظ الفاتورة"
   □ انتظر ظهور رسالة النجاح


🔍 كيفية عرض الأخطاء الفعلية من السيرفر:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. ابحث عن ملف السجل: storage/logs/laravel.log
2. افتح الملف بمحرر نصوص
3. ابحث عن أحدث خطأ (عادة ما يكون في النهاية)
4. انسخ رسالة الخطأ كاملة
5. ابحث عن الخطأ في هذا التقرير


📞 معلومات تقنية مساعدة:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
الملفات المهمة:
- app/Http/Controllers/CustomerInvoiceController.php
- app/Models/CustomerInvoice.php
- app/Models/CustomerInvoiceItem.php
- app/Services/CustomerInvoiceJournalService.php
- resources/views/customer-invoices/create.blade.php
- database/migrations/[date]_create_customer_invoices_table.php

أوامر MySQL مساعدة:
SELECT * FROM customers WHERE company_id = [company_id];
SELECT * FROM fiscal_years WHERE company_id = [company_id];
SELECT * FROM accounting_periods WHERE company_id = [company_id];
SELECT * FROM chart_of_accounts WHERE code IN ('4100', '217001');

================================================================================
                            النهاية
================================================================================
