# 08 — المالية والفواتير

## نظرة عامة

النظام المالي يعتمد على **القيد المزدوج** — كل عملية مالية تُنشئ قيدين (مدين + دائن). الأموال تُخزّن بال**قروش** (1 ج.م = 100 قرش) لتجنب مشاكل الأرقام العشرية.

```
فاتورة → دفعة → قيد مزدوج (مدين + دائن)
```

---

## الشاشات المنفذة

### 1. النظرة المالية العامة (`/financial-overview`)

**من يراها:** من لديه صلاحية `invoices.list`

**الفلاتر:**
- الفترة: اليوم / هذا الأسبوع / هذا الشهر / الشهر الماضي / هذا الربع
- الفرع

**المحتوى:**
| القسم | الوصف |
|-------|-------|
| الإيرادات | مجموع المدفوعات المؤكدة في الفترة |
| المصروفات | مشتريات مخزون + رواتب + إيجارات |
| الأرباح والخسائر شهرياً | رسم بياني |
| نقطة التعادل | كم مشترك نحتاج لتغطية التكاليف |
| الإيرادات حسب المصدر | اشتراكات / مبيعات / إيجارات |
| نسبة التحصيل | المحصّل ÷ المستحق × 100 |
| تكاليف المنشآت | إيجارات الملاعب الشهرية |

---

### 2. قائمة الفواتير (`/invoices`)

**من يراها:** من لديه صلاحية `invoices.list`

**الفلاتر:**
- بحث برقم الفاتورة أو اسم المشترك
- الحالة
- الفترة

**أعمدة الجدول:**
| العمود | الوصف |
|--------|-------|
| رقم الفاتورة | invoice_number |
| المشترك | billable.name_ar |
| المجموع | total_amount (ج.م) |
| المدفوع | paid_amount (ج.م) |
| المتبقي | due_amount (ج.م) |
| تاريخ الإصدار | issue_date |
| تاريخ الاستحقاق | due_date |
| الحالة | شارة ملونة |
| الإجراءات | عرض، طباعة |

**التصدير:** زر تصدير Excel (`/export/invoices`)

---

### 3. إنشاء فاتورة — ويزارد (`/invoices/wizard`)

**خطوات:**
1. اختيار المشترك
2. إضافة البنود (برنامج / منتج / خدمة)
3. تطبيق الخصم/الكوبون
4. تحديد تاريخ الاستحقاق وطريقة الدفع
5. مراجعة وإصدار

---

### 4. إنشاء فاتورة — نموذج (`/invoices/create`)

**الحقول:**
| الحقل | النوع | مطلوب |
|--------|------|-------|
| المشترك | select/search | ✓ |
| البنود | repeater | ✓ (بند واحد على الأقل) |
| تاريخ الإصدار | date | ✓ |
| تاريخ الاستحقاق | date | ✓ |
| ملاحظات | textarea | ✗ |

**بند الفاتورة:**
| الحقل | النوع | مطلوب |
|--------|------|-------|
| الوصف | text | ✓ |
| الكمية | number | ✓ |
| سعر الوحدة | money | ✓ |
| الخصم | money | ✗ |

---

### 5. تفاصيل فاتورة (`/invoices/{id}`)

**من يراها:** من لديه صلاحية `invoices.view`

**المحتوى:**
- معلومات الفاتورة (رقم، تاريخ، حالة)
- بيانات المشترك
- جدول البنود (وصف، كمية، سعر، إجمالي)
- الإجمالي الفرعي، الخصم، الضريبة، الإجمالي
- المدفوع، المتبقي
- سجل المدفوعات السابقة

**نموذج تسجيل دفعة (مدمج في الصفحة):**
| الحقل | النوع | مطلوب |
|--------|------|-------|
| المبلغ | money | ✓ | يعبأ تلقائياً بالمتبقي |
| طريقة الدفع | select | ✓ | cash, card, bank_transfer, wallet, online, cheque, other |
| تاريخ الدفع | date | ✓ | اليوم افتراضياً |
| ملاحظات | textarea | ✗ | |

**التحقق عند الدفع:**
- المبلغ > 0
- المبلغ ≤ المتبقي
- الفاتورة ليست ملغاة أو مسودة

---

### 6. طباعة فاتورة (`/invoices/{id}/print`)

صفحة قابلة للطباعة تحتوي:
- شعار الأكاديمية
- بيانات المشترك
- البنود
- الإجماليات
- QR code أو رابط عام

---

### 7. فاتورة عامة (`/public/invoice/{uuid}`)

**بدون تسجيل دخول** — رابط عام (signed URL) يُرسل لولي الأمر.

---

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

```mermaid
stateDiagram-v2
    [*] --> مسودة
    مسودة --> مرسلة : إرسال
    مسودة --> ملغاة : إلغاء

    مرسلة --> مدفوعة_جزئياً : دفعة جزئية
    مرسلة --> متأخرة : تجاوز تاريخ الاستحقاق
    مرسلة --> ملغاة : إلغاء (فقط إذا المدفوع = 0)

    متأخرة --> مدفوعة_جزئياً : دفعة جزئية
    متأخرة --> مدفوعة : دفع كامل

    مدفوعة_جزئياً --> مدفوعة : اكتمال الدفع

    مدفوعة --> مستردة : عملية استرداد
```

**قواعد حاسمة:**
- لا يمكن إلغاء فاتورة بها مدفوعات (partially_paid)
- لا يمكن إلغاء فاتورة مدفوعة
- المسترد يمر عبر عملية استرداد رسمية (reversing entries)

---

## القيد المزدوج

**كل دفعة تُنشئ قيدين:**
```
دفعة نقدية 1500 ج.م:
  مدين: حساب النقدية ← 150000 قرش
  دائن: حساب المدينون ← 150000 قرش
```

**استرداد 500 ج.م:**
```
  مدين: حساب المدينون ← 50000 قرش
  دائن: حساب النقدية ← 50000 قرش
```

**القيود لا تُعدّل أبداً ولا تُحذف.** التصحيح = قيد عكسي جديد.

---

### 8. المحافظ الإلكترونية (`/wallets`)

**من يراها:** من لديه صلاحية `wallets.list`

**قائمة المحافظ:**
| العمود | الوصف |
|--------|-------|
| المالك | اسم المشترك |
| الرصيد | balance (ج.م) |
| المجمد | frozen_amount (ج.م) |
| المتاح | available_balance (ج.م) |
| الحالة | active, frozen, closed |

---

### 9. تفاصيل محفظة (`/wallets/{id}`)

**المحتوى:**
- الرصيد الحالي / المجمد / المتاح
- سجل المعاملات (إيداع، سحب، خصم، تجميد)

**عمليات:**
- **إيداع:** إضافة مبلغ (يتطلب وصف)
- **سحب:** خصم مبلغ (يتطلب وصف) — لا يمكن السحب أكثر من المتاح

**قاعدة:** الرصيد لا يصل لسالب أبداً. يُفحص قبل الخصم مع `lockForUpdate()`.

---

### 10. الورديات المالية (`/cash-sessions`)

**من يراها:** من لديه صلاحية `cash_sessions.list`

**القائمة:**
| العمود | الوصف |
|--------|-------|
| المستخدم | من فتح الوردية |
| تاريخ الفتح | opened_at |
| تاريخ الإقفال | closed_at |
| المبلغ الافتتاحي | opening_amount |
| المبلغ الختامي | closing_amount |
| الفرق | variance |
| عدد العمليات | transactions_count |
| الحالة | open/closed |

---

### 11. إدارة الوردية (`/cash-sessions/manage`)

**من يراها:** من لديه صلاحية `cash_sessions.manage`

**فتح وردية:**
- إدخال المبلغ الافتتاحي (كم كاش في الدرج)

**إقفال وردية:**
- إدخال المبلغ الختامي (كم كاش في الدرج الآن)
- النظام يحسب: المتوقع = الافتتاحي + مبيعات الكاش
- الفرق = الختامي - المتوقع
- إذا فرق سلبي (نقص) → يُسجّل ويحتاج تبرير

**قاعدة:** لا يمكن إجراء عمليات بيع/تحصيل بدون وردية مفتوحة.

```mermaid
flowchart TD
    A[بداية اليوم] --> B[فتح وردية + مبلغ افتتاحي]
    B --> C[عمليات بيع/تحصيل خلال اليوم]
    C --> D[إقفال الوردية]
    D --> E[إدخال المبلغ الختامي]
    E --> F{الفرق}
    F -->|صفر| G[✓ مطابقة]
    F -->|موجب| H[⚠ زيادة — تحتاج تبرير]
    F -->|سالب| I[✗ نقص — تحتاج تحقيق]
```

---

### 12. خطط الدفع (Installments) (`/payment-plans/create`)

**من يراها:** من لديه صلاحية `invoices.create`

**الحقول:**
| الحقل | النوع | مطلوب |
|--------|------|-------|
| الفاتورة | select | ✓ |
| عدد الأقساط | number | ✓ |
| تاريخ أول قسط | date | ✓ |
| الفاصل بين الأقساط | select | ✓ | أسبوعي / شهري |

**السلوك:**
- يُقسّم المبلغ المتبقي على عدد الأقساط
- يُنشئ سجل لكل قسط (تاريخ + مبلغ + حالة)
- القسط الأخير يأخذ الفرق (لتجنب مشاكل القسمة)

**تذكير الأقساط:** مهمة مجدولة تذكّر قبل 3 أيام وقبل يوم واحد

**كشف التعثر:** مهمة `payments:detect-defaults` — إذا قسط تجاوز تاريخه بدون دفع → إشعار

---

### 13. النظرة المالية — مصالحة

**المهمة الأسبوعية:** `financials:reconcile` (الأحد 04:00)

**تفحص:**
- مجموع المدين = مجموع الدائن (لكل حساب)
- مجموع المدفوع لكل فاتورة = مجموع الدفعات المؤكدة
- رصيد المحفظة = مجموع الإيداعات - مجموع السحب

---

## أمثلة عملية

### مثال 1: فاتورة اشتراك شهري
> 1. مشترك "أحمد" يُسجّل في مجموعة — السعر 1500 ج.م
> 2. تُنشأ فاتورة: إجمالي = 150,000 قرش
> 3. الأب يدفع كاش: 1500 ج.م
> 4. قيد: مدين نقدية 150000، دائن مدينون 150000
> 5. الفاتورة → "مدفوعة"
> 6. الاشتراك → "نشط"

### مثال 2: دفع جزئي + تقسيط
> 1. فاتورة 3000 ج.م
> 2. الأب يدفع 1000 ج.م الآن → الفاتورة "مدفوعة جزئياً"
> 3. يُنشأ خطة دفع: 2000 ÷ 2 = 1000 شهرياً
> 4. بعد شهر: تذكير بالقسط الأول
> 5. يدفع → 2000/3000 مدفوع
> 6. بعد شهرين: القسط الأخير → "مدفوعة بالكامل"

### مثال 3: دفع من المحفظة
> 1. رصيد محفظة "أحمد" = 2000 ج.م
> 2. فاتورة جديدة = 1500 ج.م
> 3. دفع بالمحفظة → خصم 1500 من المحفظة
> 4. الرصيد الجديد = 500 ج.م
> 5. قيد: مدين محفظة-مدينون 150000، دائن محفظة-أصل 150000

### مثال 4: وردية مالية يومية
> 1. 08:00 — فتح وردية: مبلغ افتتاحي 500 ج.م
> 2. خلال اليوم: 10 عمليات تحصيل = 8000 ج.م كاش
> 3. 17:00 — إقفال: المبلغ في الدرج = 8450 ج.م
> 4. المتوقع = 500 + 8000 = 8500 ج.م
> 5. الفرق = -50 ج.م (نقص)
> 6. يُسجّل النقص + يُطلب تبرير من الموظف

### مثال 5: فاتورة متأخرة
> 1. فاتورة مرسلة بتاريخ استحقاق 1 يوليو
> 2. اليوم 5 يوليو — لم تُدفع
> 3. المهمة المجدولة `invoices:mark-overdue`: الحالة → "متأخرة"
> 4. إرسال تذكير لولي الأمر (الاثنين والخميس)

---

## لماذا يحتاج عملك هذا

| الميزة | الفائدة |
|--------|---------|
| القيد المزدوج | دقة مالية 100% — لا مبالغ ضائعة |
| الأقساط | مرونة في التحصيل — لا تخسر العميل بسبب مبلغ كبير |
| المحفظة | دفع سريع بدون كاش — مناسب لأولياء الأمور |
| الوردية | محاسبة يومية — تعرف أين كل قرش |
| التذكيرات | تحصيل أفضل بدون اتصالات يدوية |
| الفاتورة العامة | ولي الأمر يرى فاتورته من أي مكان |
| المصالحة | يكشف أي خطأ مالي تلقائياً |
| عدم قابلية التعديل | لا أحد يستطيع "تعديل" قيد قديم — أمان مالي |

---

## التكاملات

| الوحدة | العلاقة |
|--------|---------|
| التسجيل | إنشاء فاتورة عند التسجيل |
| التسعير | حساب سعر الفاتورة |
| نقطة البيع | عمليات POS تُنشئ فواتير + مدفوعات |
| المخزون | مشتريات تُنشئ فواتير مشتريات |
| الموارد البشرية | رواتب تُنشئ قيود مالية |
| الإشعارات | تذكيرات الفواتير والأقساط |
| التقارير | تقرير مالي شامل |
