# 10 — نقطة البيع (POS)

## نظرة عامة

محطة بيع متكاملة لعمليات البيع اليومية: بيع منتجات، تسجيل اشتراكات، تحصيل مدفوعات. تعمل ضمن وردية مالية (Cash Session).

---

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

### 1. محطة البيع (`/pos`)

**من يراها:** من لديه صلاحية `pos.sell`

**الشرط الأساسي:** يجب أن تكون هناك وردية مفتوحة — وإلا تظهر رسالة "يجب فتح وردية أولاً".

**تقسيم الشاشة:**

#### الجانب الأيمن — المنتجات والخدمات:
- بحث سريع
- تصنيفات (tabs)
- بطاقات المنتجات (صورة + اسم + سعر)
- النقر → يضيف للسلة

#### الجانب الأيسر — السلة:
| العنصر | الوصف |
|--------|-------|
| قائمة البنود | اسم + كمية + سعر |
| الإجمالي الفرعي | subtotal |
| الخصم | discount |
| الإجمالي | total |
| حقل الكوبون | مع زر "تحقق" |
| اختيار المشترك | select (اختياري لمبيعات منتجات) |
| طريقة الدفع | cash / card / wallet / split |
| زر "إتمام البيع" | |

**عمليات السلة:**
- تعديل الكمية (+/-)
- حذف بند
- مسح السلة بالكامل

---

### 2. دورة عملية بيع واحدة (10 خطوات)

```mermaid
flowchart TD
    A[1. تحديد المشترك - اختياري] --> B[2. إضافة بنود]
    B --> C[3. حساب الأسعار - محرك التسعير]
    C --> D[4. تطبيق كوبون - اختياري]
    D --> E[5. حساب الإجماليات]
    E --> F[6. اختيار طريقة الدفع]
    F --> G[7. التحقق من الرصيد/المبلغ]
    G --> H[8. تنفيذ العملية - transaction واحدة]
    H --> I[9. إنشاء الإيصال]
    I --> J[10. إطلاق الأحداث]
```

**الخطوة 8 تشمل (كلها في DB::transaction واحدة):**
- إنشاء pos_transaction + items
- إنشاء فاتورة + بنود
- إنشاء دفعة + قيد مزدوج
- خصم من المحفظة (إذا wallet)
- خصم من المخزون (إذا منتج tracked)
- إنشاء سجل تسجيل (إذا برنامج)
- تحديث عداد الوردية

---

### 3. الدفع المقسّم (Split Payment)

- جزء كاش + جزء كارت
- جزء محفظة + جزء كاش
- يجب أن يغطي المجموع = الإجمالي تماماً

---

### 4. تاريخ عمليات البيع (`/pos/history`)

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

**الفلاتر:**
- الفترة
- طريقة الدفع
- الموظف

**أعمدة الجدول:**
| العمود | الوصف |
|--------|-------|
| رقم الإيصال | receipt_number |
| التاريخ | created_at |
| المشترك | اسم (أو "عميل عابر") |
| الإجمالي | total_amount |
| طريقة الدفع | method |
| الموظف | seller |
| الإجراءات | طباعة إيصال |

---

### 5. طباعة إيصال (`/receipts/pos/{id}`)

**المحتوى:**
- شعار الأكاديمية
- رقم الإيصال: `RCP-{BRANCH}-{YYYYMMDD}-{SEQ}`
- بنود البيع
- الإجماليات
- طريقة الدفع
- التاريخ والوقت
- اسم الموظف

---

### 6. إيصال عام (`/public/pos-receipt/{uuid}`)

رابط عام بدون تسجيل دخول — يُرسل للعميل عبر واتساب.

---

## الحراسات (Guards)

| الشرط | النتيجة |
|--------|---------|
| لا وردية مفتوحة | رفض: "يجب فتح وردية أولاً" |
| مشترك موقوف | رفض: "المشترك موقوف — يمكن فقط دفع المستحقات" |
| تسجيل مكرر | رفض: "مسجل بالفعل في هذا البرنامج" |
| مبلغ الدفع المقسّم ≠ الإجمالي | رفض: "المبلغ المدفوع أقل من الإجمالي" |
| السلة فارغة | تعطيل زر الإتمام |
| منتج نفذ | تحذير مع إمكانية override من المدير |

---

## إعدادات الإيصال (`/settings/receipts`)

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

**الحقول:**
- نص الترويسة
- نص التذييل
- إظهار الشعار
- إظهار QR code
- حجم الخط
- عرض الإيصال

---

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

### مثال 1: بيع تيشيرت
> 1. العميل يريد تيشيرت
> 2. الموظف يبحث "تيشيرت" → يضيفه (200 ج.م)
> 3. لا حاجة لتحديد مشترك (بيع منتج)
> 4. دفع كاش → إتمام
> 5. خصم 1 من المخزون
> 6. طباعة إيصال

### مثال 2: تسجيل مشترك + بيع حقيبة
> 1. اختيار المشترك "أحمد"
> 2. إضافة: برنامج "كرة قدم مبتدئين" (1500 ج.م)
> 3. إضافة: حقيبة (150 ج.م)
> 4. تطبيق كوبون "WELCOME": خصم 100 ج.م
> 5. الإجمالي: 1550 ج.م
> 6. دفع: 1000 كاش + 550 كارت (split)
> 7. النتيجة:
>    - فاتورة مدفوعة
>    - اشتراك نشط لأحمد
>    - -1 حقيبة من المخزون
>    - إيصال

### مثال 3: دفع من المحفظة
> 1. اختيار "سارة" — رصيد محفظتها 2000 ج.م
> 2. إضافة اشتراك: 1200 ج.م
> 3. طريقة الدفع: محفظة
> 4. التحقق: 2000 ≥ 1200 → ✓
> 5. خصم من المحفظة → رصيد جديد: 800 ج.م
> 6. إتمام البيع

---

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

| الميزة | الفائدة |
|--------|---------|
| واجهة بيع سريعة | عملية واحدة في أقل من دقيقة |
| الدفع المقسّم | العميل يدفع جزء كاش وجزء فيزا |
| ربط بالمخزون | البيع يخصم تلقائياً — لا أخطاء يدوية |
| ربط بالاشتراكات | تسجيل + دفع في عملية واحدة |
| الإيصال الإلكتروني | يُرسل واتساب بدون طباعة ورق |
| الحراسات | تمنع الأخطاء قبل حدوثها |

---

## التكاملات

| الوحدة | العلاقة |
|--------|---------|
| المالية | كل عملية POS = فاتورة + دفعة + قيد |
| المخزون | بيع منتج = حركة مخزون خارجة |
| التسعير | حساب السعر يمر بمحرك التسعير |
| التسجيل | بيع برنامج = تسجيل مشترك |
| الورديات | عملية POS ترتبط بالوردية المفتوحة |
| الإشعارات | إرسال إيصال بعد البيع |
