# 📦 نظام POS الاحترافي - دليل التثبيت والاستخدام

## 🚀 التثبيت

### 1️⃣ تحديث قاعدة البيانات
قم بتنفيذ السكريبت التالي في phpMyAdmin:

```sql
-- افتح ملف: modules/pos/database_upgrade.sql
-- قم بتنفيذه كاملاً
```

الملف سيقوم بـ:
- إضافة حقول جديدة لجدول `tblpos_branches` (warehouse_id, create_invoice, update_inventory, إلخ)
- إضافة حقول لجدول `tblpos_sales` (invoice_id, warehouse_id, qr_code, إلخ)
- إضافة حقول لجدول `tblpos_sale_items` (stock_before, stock_after, warehouse_id)
- إنشاء جدول `tblpos_settings` للإعدادات
- إنشاء جدول `tblpos_inventory_log` لتتبع حركة المخزون
- إضافة Indexes للأداء

### 2️⃣ التحقق من الملفات
تأكد من وجود الملفات التالية:

```
modules/pos/
├── controllers/
│   └── Pos.php (محدّث)
├── models/
│   └── Pos_model.php (محدّث)
├── views/
│   ├── screen/
│   │   ├── pos.php (قديم - أساسي)
│   │   └── pos_professional.php (جديد - احترافي) ✨
│   ├── receipt/
│   │   └── thermal.php (فاتورة حرارية 80mm) 🖨️
│   └── branches/
│       └── settings.php (إعدادات الفروع) ⚙️
├── language/
│   └── arabic/
│       └── pos_lang.php (محدّث بترجمات جديدة)
└── database_upgrade.sql (سكريبت التحديث)
```

---

## ⚙️ الإعداد الأولي

### 1. إعداد الفروع
1. اذهب إلى: **POS → الفروع**
2. اضغط على **⚙️ (أيقونة الإعدادات)** بجانب أي فرع
3. قم بتكوين:
   - **المخزن المرتبط**: اختر المخزن الذي سيتم خصم المنتجات منه
   - **عرض كل المنتجات**: ON = عرض كل المنتجات | OFF = فلترة حسب الفئات
   - **الفئات المسموح بها**: حدد فئات معينة إذا أردت تقييد المنتجات
   - **إنشاء فاتورة تلقائياً**: تفعيل لإنشاء فاتورة في `tblinvoices` عند كل عملية بيع
   - **تحديث المخزون تلقائياً**: تفعيل لخصم الكميات من المخزن تلقائياً
   - **طباعة تلقائية**: تفعيل لفتح نافذة الطباعة تلقائياً
   - **رأس/ذيل الفاتورة**: نصوص مخصصة للفاتورة

### 2. إعداد الكاشيرات
1. اذهب إلى: **POS → الكاشيرات**
2. تأكد من ربط كل كاشير بالفرع الصحيح

---

## 🛒 دليل الاستخدام

### فتح جلسة POS
1. اذهب إلى: **POS → الجلسات** → **فتح جلسة جديدة**
2. اختر الكاشير
3. أدخل رصيد البداية (Opening Balance)
4. اضغط **فتح الجلسة**

### شاشة البيع الاحترافية
بعد فتح الجلسة، ستظهر واجهة POS الاحترافية:

#### 🎨 المميزات:
- **تصميم حديث**: واجهة تجارية بألوان متدرجة
- **صور المنتجات**: عرض صور حقيقية من `tblfiles`
- **حالة المخزون**: بادج ملون (متاح/منخفض/غير متاح)
- **فلترة بالفئات**: أزرار سريعة للفئات
- **دعم الباركود**: امسح أي منتج بسكانر HID
- **سلة تفاعلية**: صور + تحكم بالكمية + حذف
- **حساب تلقائي**: ضريبة 15% + خصومات

#### 🔍 البحث والإضافة:
1. **البحث**: اكتب اسم المنتج أو الباركود
2. **الفلترة**: اضغط على فئة لتصفية المنتجات
3. **الإضافة**: اضغط على أي منتج لإضافته للسلة
4. **الباركود**: امسح الباركود = إضافة تلقائية

#### 💳 إتمام البيع:
1. اضغط **الدفع (Checkout)**
2. اختر طريقة الدفع:
   - **نقدي**: أدخل المبلغ المستلم (سيحسب الباقي تلقائياً)
   - **بطاقة**: أدخل مبلغ البطاقة
   - **مختلط**: نقدي + بطاقة
3. اضغط **إتمام البيع**

#### 🖨️ بعد البيع:
- **تلقائياً**:
  - ✅ إنشاء فاتورة في `tblinvoices` (إذا مفعّل)
  - ✅ خصم الكميات من المخزن (إذا مفعّل)
  - ✅ فتح نافذة الفاتورة الحرارية
  - ✅ تسجيل في `tblpos_inventory_log`

---

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

### المميزات:
- **مقاس**: 80mm (مناسب للطابعات الحرارية)
- **محتوى**:
  - شعار الشركة
  - معلومات الشركة (عنوان، هاتف، رقم ضريبي)
  - رقم الفاتورة الفريد
  - تاريخ ووقت البيع
  - معلومات الفرع والكاشير والبائع
  - جدول المنتجات (اسم، كمية، سعر، مجموع)
  - المجموع الفرعي + الضريبة + الخصم = الإجمالي
  - طريقة الدفع + المدفوع + الباقي
  - **QR Code**: للتحقق من صحة الفاتورة ✨
  - نص مخصص (شروط، شكراً، إلخ)

### الطباعة:
- **تلقائية**: ستفتح نافذة طباعة تلقائياً
- **يدوية**: اضغط زر "طباعة الفاتورة"
- **متوافقة**: مع جميع الطابعات الحرارية والعادية

### التحقق من QR Code:
عند مسح QR Code، سيتم فتح رابط:
```
https://yoursite.com/admin/pos/verify_receipt/{sale_id}
```

سيعرض:
```json
{
  "valid": true,
  "sale_number": "POS-2024-001",
  "date": "2024-01-15 14:30:00",
  "total": "1250.00",
  "branch": "الفرع الرئيسي",
  "items_count": 5,
  "status": "completed"
}
```

---

## 📊 التقارير والمراجعة

### عرض المبيعات
**POS → المبيعات**
- قائمة كاملة بجميع المبيعات
- تفاصيل كل عملية بيع
- الفواتير المرتبطة
- حالة المخزون

### سجل المخزون
**جدول**: `tblpos_inventory_log`
- يسجل كل حركة مخزون من POS
- الكمية قبل/بعد
- المخزن المستخدم
- المستخدم المسؤول

### لوحة التحكم
**POS → لوحة التحكم**
- مبيعات اليوم
- الجلسات المفتوحة
- عدد الفروع والكاشيرات
- إحصائيات سريعة

---

## 🔧 الربط مع الأنظمة الأخرى

### ✅ الربط بالمخزون (Warehouse Module)
- **جداول مستخدمة**:
  - `tblitems` - المنتجات
  - `tblitems_groups` - فئات المنتجات
  - `tblwarehouse` - المخازن
  - `tblwarehouse_quantity` - كميات المنتجات
  - `tblfiles` - صور المنتجات

- **كيفية العمل**:
  1. يتم جلب المنتجات من `tblitems` مع صورها
  2. يتم التحقق من الكميات في `tblwarehouse_quantity`
  3. عند البيع، يتم خصم الكمية تلقائياً
  4. يتم تسجيل الحركة في `tblpos_inventory_log`

### ✅ الربط بالفواتير (Invoice Module)
- **جدول مستخدم**: `tblinvoices`
- **كيفية العمل**:
  1. عند إتمام البيع، يتم إنشاء سجل في `tblinvoices`
  2. يتم ربط المنتجات في `tblitemable`
  3. يتم تسجيل الدفع في `tblinvoicepaymentrecords`
  4. يتم حفظ رقم الفاتورة في `tblpos_sales.invoice_id`

### ✅ الربط بـ QR Module
- **API مستخدم**: https://api.qrserver.com/v1/create-qr-code/
- **البيانات**: رابط التحقق من الفاتورة
- **يمكن استبداله**: بأي QR module داخلي

---

## 🎯 الميزات الاحترافية

### 1. دعم الباركود (Barcode Scanner)
- **HID Support**: يعمل مع أي سكانر USB
- **منطق العمل**:
  ```javascript
  // يستمع لضغط المفاتيح السريع من السكانر
  // عند قراءة الباركود، يتم البحث تلقائياً
  // وإضافة المنتج للسلة مباشرة
  ```

### 2. إدارة الجلسات
- **Session Locking**: جلسة واحدة فقط لكل مستخدم
- **Opening/Closing Balance**: تتبع النقدية
- **Cash Movements**: سجل السحب والإيداع

### 3. التصميم المتجاوب
- **Desktop**: شاشة عريضة مقسمة (منتجات + سلة)
- **Tablet**: تكيف تلقائي
- **Touch-Friendly**: أزرار كبيرة سهلة اللمس

### 4. الأمان
- **Permissions**: صلاحيات متعددة المستويات
- **Session Validation**: التحقق من الجلسة في كل عملية
- **User Tracking**: تسجيل كل عملية بمستخدم محدد

---

## 🐛 استكشاف الأخطاء

### المشكلة: لا تظهر المنتجات
**الحل**:
1. تأكد من وجود منتجات في `tblitems`
2. تأكد من تفعيل `active = 1`
3. إذا اخترت مخزن محدد، تأكد من وجود كميات في `tblwarehouse_quantity`

### المشكلة: الصور لا تظهر
**الحل**:
1. تأكد من رفع صور للمنتجات في `tblfiles`
2. `rel_type = 'item'`
3. `rel_id = {product_id}`

### المشكلة: لا يتم خصم المخزون
**الحل**:
1. اذهب لإعدادات الفرع
2. فعّل "تحديث المخزون تلقائياً"
3. تأكد من ربط الفرع بمخزن

### المشكلة: لا يتم إنشاء فاتورة
**الحل**:
1. اذهب لإعدادات الفرع
2. فعّل "إنشاء فاتورة تلقائياً"
3. تأكد من وجود جدول `tblinvoices`

---

## 📝 ملاحظات مهمة

### الأداء:
- يتم تحميل أول 50 منتج فقط (قابل للتعديل)
- استخدام Indexes على الجداول للسرعة
- AJAX لتحميل المنتجات بدون reload

### التخصيص:
- **الألوان**: في `pos_professional.php` - CSS الداخلي
- **نسبة الضريبة**: في JavaScript (`taxRate = 15`)
- **نص الفاتورة**: في إعدادات كل فرع

### الأمان:
- جميع الدوال تتحقق من الصلاحيات
- `has_permission('pos', '', 'view')`
- `is_admin()` للإداريين

---

## 🎉 النتيجة النهائية

### ما تم إنجازه:
✅ واجهة POS احترافية بتصميم تجاري
✅ صور حقيقية للمنتجات
✅ فلترة بالفئات والمخازن
✅ دعم الباركود سكانر
✅ فاتورة حرارية 80mm مع QR Code
✅ ربط كامل مع الفواتير
✅ تحديث تلقائي للمخزون
✅ سجل كامل لحركة المخزون
✅ إعدادات مخصصة لكل فرع
✅ دعم اللغة العربية بالكامل

### المميزات التجارية:
🔥 مثل أي نظام POS عالمي (Walmart, Carrefour, etc.)
🔥 سريع وسلس في الاستخدام
🔥 متكامل مع ERP
🔥 قابل للتطوير والتوسع

---

## 📞 الدعم
لأي استفسارات أو مشاكل، يمكنك:
- مراجعة ملفات الـ log في `modules/pos/logs/`
- التحقق من `error_log` في root
- مراجعة جدول `tblactivitylog`

---

**تم تطويره بواسطة**: GitHub Copilot ❤️
**التاريخ**: نوفمبر 2025
**الإصدار**: Professional 2.0
