════════════════════════════════════════════════════════════════════════════════
✅ دليل تطبيق فحص حد الفترة التجريبية لفواتير العملاء
════════════════════════════════════════════════════════════════════════════════

📍 الملف المراد تعديله:
   app/Http/Controllers/CustomerInvoiceController.php

════════════════════════════════════════════════════════════════════════════════
📋 الخطوة 1: إضافة الدالة الخاصة
════════════════════════════════════════════════════════════════════════════════

أضف هذا الكود في نهاية class CustomerInvoiceController (قبل الإغلاق النهائي }):

────────────────────────────────────────────────────────────────────────────────

    /**
     * ✅ التحقق من قيود الفترة التجريبية قبل إنشاء فاتورة
     * 
     * الشركات التجريبية مسموح لها بإنشاء فاتورة واحدة فقط
     */
    private function checkTrialLimitForInvoice($companyId)
    {
        $company = \App\Models\Company::find($companyId);
        
        if (!$company) {
            return [
                'allowed' => false,
                'message' => 'خطأ: لم يتم العثور على بيانات الشركة. يرجى التواصل مع مدير النظام.'
            ];
        }

        // إذا لم تكن الشركة تجريبية، السماح بالإنشاء
        if (!$company->has_trial) {
            return ['allowed' => true];
        }

        // التحقق من انتهاء الفترة التجريبية
        if ($company->trial_end_date && now()->isAfter($company->trial_end_date)) {
            return [
                'allowed' => false,
                'message' => '❌ لقد انتهت الفترة التجريبية الخاصة بشركتك!

انتهت فترة التجريب في: ' . $company->trial_end_date->format('Y-m-d H:i') . '

لا يمكنك إنشاء المزيد من الفواتير. يرجى التواصل مع مدير حسابك لتفعيل الاشتراك الكامل والاستمرار في استخدام النظام.

📞 للمساعدة والدعم، يرجى التواصل مع فريق الدعم الخاص بنا.'
            ];
        }

        // عد الفواتير الحالية
        $invoiceCount = CustomerInvoice::where('company_id', $companyId)->count();

        // الشركات التجريبية مسموح لها بفاتورة واحدة فقط
        if ($invoiceCount >= 1) {
            return [
                'allowed' => false,
                'message' => '❌ لقد انتهت الفترة التجريبية الخاصة بشركتك!

لقد قمت بالفعل بإنشاء (1) فاتورة ضمن الفترة التجريبية المسموحة.

لا يمكنك إنشاء المزيد من الفواتير. يرجى التواصل مع مدير حسابك لتفعيل الاشتراك الكامل والاستمرار في استخدام النظام.

📞 للمساعدة والدعم، يرجى التواصل مع فريق الدعم الخاص بنا.'
            ];
        }

        // السماح بإنشاء الفاتورة الأولى
        return ['allowed' => true];
    }

────────────────────────────────────────────────────────────────────────────────

════════════════════════════════════════════════════════════════════════════════
📋 الخطوة 2: إضافة التحقق في دالة store()
════════════════════════════════════════════════════════════════════════════════

في دالة store() ابحث عن السطر:
    $this->authorize('create', CustomerInvoice::class);

أضف بعده مباشرة:

────────────────────────────────────────────────────────────────────────────────

        // ✅ التحقق من حالة الفترة التجريبية
        $trialCheckResult = $this->checkTrialLimitForInvoice($user->company_id);
        if (!$trialCheckResult['allowed']) {
            return back()->with('error', $trialCheckResult['message'])->withInput();
        }

────────────────────────────────────────────────────────────────────────────────

النتيجة النهائية يجب أن تبدو هكذا:

        $this->authorize('create', CustomerInvoice::class);

        // ✅ التحقق من حالة الفترة التجريبية
        $trialCheckResult = $this->checkTrialLimitForInvoice($user->company_id);
        if (!$trialCheckResult['allowed']) {
            return back()->with('error', $trialCheckResult['message'])->withInput();
        }

        $validated = $request->validate([
            ...


════════════════════════════════════════════════════════════════════════════════
🧪 اختبار الميزة
════════════════════════════════════════════════════════════════════════════════

1️⃣ إنشاء شركة تجريبية في قاعدة البيانات:
   
   UPDATE companies 
   SET has_trial = 1, trial_end_date = '2025-12-31 23:59:59' 
   WHERE id = YOUR_COMPANY_ID;

2️⃣ حاول إنشاء أول فاتورة:
   ✅ يجب أن تنجح العملية بدون رسالة خطأ

3️⃣ حاول إنشاء فاتورة ثانية:
   ❌ يجب أن تظهر رسالة الخطأ:
   
   "❌ لقد انتهت الفترة التجريبية الخاصة بشركتك!
    لقد قمت بالفعل بإنشاء (1) فاتورة ضمن الفترة التجريبية المسموحة..."

4️⃣ اختبر انتهاء الفترة التجريبية:
   
   UPDATE companies 
   SET trial_end_date = '2025-01-01 00:00:00' 
   WHERE id = YOUR_COMPANY_ID;
   
   ❌ يجب أن تظهر رسالة: "لقد انتهت الفترة التجريبية الخاصة بشركتك!"


════════════════════════════════════════════════════════════════════════════════
📊 السيناريوهات
════════════════════════════════════════════════════════════════════════════════

الحالة 1: شركة غير تجريبية
├─ النتيجة: ✅ مسموح بإنشاء فواتير بلا حد
└─ الرسالة: بدون خطأ

الحالة 2: شركة تجريبية + لم تنتهِ الفترة + بدون فواتير
├─ النتيجة: ✅ مسموح بإنشاء أول فاتورة
└─ الرسالة: بدون خطأ

الحالة 3: شركة تجريبية + لم تنتهِ الفترة + لديها فاتورة واحدة
├─ النتيجة: ❌ منع إنشاء فاتورة ثانية
└─ الرسالة: "لقد انتهت الفترة التجريبية..."

الحالة 4: شركة تجريبية + انتهت الفترة
├─ النتيجة: ❌ منع أي فاتورة
└─ الرسالة: "لقد انتهت الفترة التجريبية في: YYYY-MM-DD..."


════════════════════════════════════════════════════════════════════════════════
💾 ملفات الدعم
════════════════════════════════════════════════════════════════════════════════

تم إنشاء الملفات التالية لمساعدتك:

1. TRIAL_LIMIT_FIX.md
   - توثيق شامل للتعديلات
   - أمثلة الاستخدام
   - حالات الاختبار

2. ADD_TRIAL_LIMIT.php
   - صفحة HTML تفاعلية
   - تشرح جميع الخطوات
   - يمكن فتحها في المتصفح

3. IMPLEMENTATION_GUIDE.txt (هذا الملف)
   - دليل سريع للتنفيذ
   - الخطوات الأساسية
   - أوامر الاختبار


════════════════════════════════════════════════════════════════════════════════
⚠️  ملاحظات هامة
════════════════════════════════════════════════════════════════════════════════

✅ الحقول المستخدمة:
   - has_trial (boolean) - هل الشركة تجريبية
   - trial_end_date (datetime) - تاريخ انتهاء الفترة

✅ الفاتورة الأولى:
   - مسموح للشركات التجريبية

✅ الفاتورات الإضافية:
   - ممنوعة بعد الفاتورة الأولى للشركات التجريبية

✅ الشركات غير التجريبية:
   - لا توجد قيود


════════════════════════════════════════════════════════════════════════════════
🎯 الخطوات السريعة
════════════════════════════════════════════════════════════════════════════════

1. افتح: app/Http/Controllers/CustomerInvoiceController.php
2. أضف الدالة checkTrialLimitForInvoice() قبل الإغلاق
3. أضف التحقق في بداية دالة store()
4. احفظ الملف (Ctrl+S)
5. اختبر الميزة

✅ تم! 

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