# KEMET Retail POS — حزمة RC1

نسخة مستقلة للريتال مبنية على نسخة السيرفر المستلمة بتاريخ 27 سبتمبر 2026، مع كونسول إدارة الشركات والاشتراكات والفروع والدومينات والدعم والنسخ والاسترجاع. الهوية والأيقونة والشعار من الريتال الأصلي، مع تابات وخط أوضح للعربية.

الإصدار: Laravel **13.33.0**، PHP **8.3**؛ جرى التحقق محليًا باستخدام PHP 8.3.35. تم تثبيت الاعتماديات من `composer.lock` وإرفاق مكتبات التشغيل داخل ZIP دون مكتبات التطوير.

## محتويات التسليم

- `KEMET-Retail-L13-PHP83-RC1.zip`: التطبيق ومكتبات التشغيل، دون `.env` أو مفاتيح أو بيانات تجريبية.
- `KEMET-Retail-New-Database.sql`: قاعدة تركيب جديد بها 185 جدولًا وبيانات العملات والصلاحيات والباركود ومناطق الكويت الأساسية. لا تحتوي شركات أو مستخدمين أو طلبات.
- `SHA256SUMS.txt`: بصمات الملفات للتحقق بعد النقل.
- تقارير الاختبارات في `docs/platform/` داخل التطبيق.

ملف SQL الأصلي المستلم كان هيكلًا دون بيانات عملاء. هذه الحزمة **تركيب مستقل جديد**، وليست ترحيلًا لبيانات عملاء موجودين. جداول أرشيف الإصلاحات القديمة البالغ عددها 62 جدولًا ليست جزءًا من قاعدة التركيب الجديد؛ لم تُحذف من المصدر.

## 1. تجهيز الاستضافة

استخدم PHP 8.3 مع `pdo_mysql`, `mbstring`, `xml`, `dom`, `curl`, `fileinfo`, `gd`, `zip`, `bcmath`, `intl`, `sodium`, `openssl`، وMySQL حديثًا متوافقًا مع `utf8mb4` وInnoDB. الاختبارات المحلية كانت على MySQL 8.4. أنشئ قاعدة جديدة ومستخدمًا لها، وافصلها عن قواعد المطاعم والريتال القديمة.

فك ZIP في مجلد مستقل، واجعل Document Root هو مجلد `public` داخل التطبيق. اسمح بالكتابة لحساب التطبيق في `storage` و`bootstrap/cache` و`public/uploads`. لا تستخدم صلاحيات 777، ولا تجعل جذر التطبيق كله مجلدًا عامًا.

انسخ `deploy/.env.production.example` إلى `.env` واضبط اسم قاعدة البيانات والمستخدم وكلمة المرور. اترك `PLATFORM_ENABLED=false` حتى انتهاء التجهيز.

## 2. تركيب قاعدة البيانات

اختر **طريقة واحدة فقط**:

1. استورد `KEMET-Retail-New-Database.sql` في القاعدة الجديدة الفارغة باستخدام phpMyAdmin أو عميل MySQL.
2. أو شغّل `php artisan platform:init-new EXACT_DATABASE_NAME`؛ الأمر يرفض قاعدة غير فارغة ويضيف نفس الهيكل والبيانات الأساسية.

لا تشغّل `php artisan migrate` العام على هذه النسخة؛ تاريخ migrations القديم في الريتال لا يمثّل ترتيب تركيب الهيكل المستلم. تحديثات المنصة اللاحقة تستخدم manifest والأمر `platform:release`.

من مجلد التطبيق، باستخدام مسار PHP 8.3 في الاستضافة:

```sh
php artisan key:generate
php artisan package:discover
php artisan platform:operator owner@example.com --role=owner
```

استبدل البريد ببريد مدير المنصة. الأمر يسأل عن الاسم وكلمة مرور قوية، ويطلب ربط تطبيق المصادقة ثم إدخال الرمز الحالي. لا توجد كلمة مرور افتراضية في الحزمة.

ولّد مفتاح نسخ مستقلًا عن `APP_KEY`:

```sh
php -r 'echo base64_encode(random_bytes(32)), PHP_EOL;'
```

ضعه في `PLATFORM_BACKUP_KEY` واحتفظ بنسخة آمنة خارج السيرفر. فقدان المفتاح يمنع فك النسخ القديمة. فعّل `PLATFORM_BACKUPS_ENABLED=true` بعد تهيئة التخزين الخاص ومراجعة سياسة الاحتفاظ.

## 3. الدومينات وHTTPS

الخريطة المعتمدة: `kmet.io` للموقع العام، `console.kmet.io` للكونسول، و`company.kmet.io` لكل شركة. وجّه سجلات DNS المناسبة إلى **عنوان السيرفر الفعلي**، ثم اربط الجذر والـwildcard بنفس مجلد `public`. لا تضع عنوان سيرفر المطاعم تلقائيًا دون التحقق من هدف النشر.

أصدر شهادة تغطي `kmet.io` و`*.kmet.io`. شهادة wildcard الخاصة بالمنصة لا تغطي دومين عميل مستقل. لكل دومين عميل: أضفه في ملف الشركة، انسخ سجل TXT الذي يولده النظام، اربطه بالاستضافة نفسها، أصدر شهادة HTTPS له، ثم اضغط «فحص وتفعيل».

بعد نجاح HTTPS وضبط المشغل، غيّر `PLATFORM_ENABLED=true`، ثم:

```sh
php artisan optimize:clear
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan platform:readiness
```

الكوكيز يجب أن تبقى Host-only: اترك `SESSION_DOMAIN` فارغًا. لا تستخدم `.kmet.io` كنطاق جلسة مشترك. المضيف غير المسجل لا يُوجّه لشركة افتراضية.

## 4. التشغيل والاشتراكات

أضف الباقات الفعلية والأسعار والموديولات من الكونسول؛ لا توجد أسعار تجارية مفترضة. أنشئ شركة ومالكًا وفرعًا، فعّل الاشتراك، ثم استكمل المنتجات وإعدادات البيع. الحسابات الأساسية ودليل الحسابات يُنشآن للشركات الجديدة.

للمتجر الإلكتروني: انشر المنتجات وحدد أسعارها ومتغيراتها وفروعها، ثم اختر الفروع والدومين وفعل استقبال الطلبات. التوصيل يحتاج مراجعة المناطق والرسوم الفعلية. من نقطة البيع افتح جرس الطلبات واضغط «تفعيل واختبار صوت التنبيه»؛ المتصفح يتطلب تفاعل المستخدم لتشغيل الصوت.

إعادة الطباعة من الكونسول تجهز معاينة فاتورة ريتال وتسجل الطلب والسبب والمستخدم. الطباعة عبر المتصفح؛ فتح المعاينة لا يمثل تأكيدًا من الطابعة المادية.

أضف مهمة Cron كل دقيقة، مع استبدال المسار ومسار PHP:

```cron
* * * * * cd /home/ACCOUNT/kemet-retail && /PATH/TO/PHP83 artisan schedule:run >> /dev/null 2>&1
```

الإعداد المرفق يستخدم `QUEUE_CONNECTION=sync`. إذا غيّرته لطابور خلفي فجهز العمال والإشراف عليهم قبل التشغيل. اضبط SMTP من `.env` بدل `MAIL_MAILER=log` لتعمل رسائل استعادة كلمة المرور الفعلية. بيانات بوابات الدفع وحساباتها وشروطها تخص بيئة التشغيل ولم تُفترض في الحزمة.

## 5. استخدام XBRL الآن

من **المحاسبة → التقارير المالية → تصدير XBRL داخلي**، اختر الفترة واضغط التصدير. تنزل حزمة بها `report.xbrl` و`taxonomy.xsd` والمخططات الأساسية و`manifest.json` الذي يحتوي حسابات المصدر وبصمات الملفات. الحسابات تظهر بعملة الشركة، ويُسجل المستخدم والفترة وبصمة التصدير.

التصدير الداخلي يعمل مباشرة مع دفتر أستاذ سليم ومُرحّل. يرفض اختلال التوازن أو العمليات المؤهلة غير المرحّلة. راجع دليل الحسابات والربط المحاسبي مع محاسبك؛ لا تُعتبر قيود أولية أو ملفات مستوردة اعتمادًا محاسبيًا تلقائيًا.

**هذا XBRL داخلي بتصنيف KEMET، وليس ملف إيداع رقابي معتمدًا.** لم تحدد جهة الإيداع أو توفر taxonomy رسميًا لهذه النسخة. ملفات `financial_reporting.profiles` الرسمية متروكة غير مفعلة حتى تحديد الجهة وربط الحسابات وإجراء فحصها وقبولها. اجتياز XSD يثبت صحة البنية فقط.

## 6. ما تم التحقق منه وما يلزم عند النشر

تحقق محلي: الاختبارات الآلية، واجهات الكونسول عربي/إنجليزي وموبايل/كمبيوتر، عزل الشركات والجلسات، الطلب والاستلام والتوصيل بأسعار السيرفر، طابور نقطة البيع، أول تنبيه بعد قائمة فارغة، تصدير XBRL من طلب HTTP فعلي، معاينة الفاتورة، تركيب قاعدة فارغة واستيراد SQL، واستعادة شركة وملفاتها إلى قاعدة مستقلة دون بيانات الشركة الثانية.

قبل فتح الخدمة للعملاء، اختبر على السيرفر الفعلي: DNS والشهادات، البريد، Cron والطابور إن استُخدم، استرجاع نسخة خارج السيرفر، طابعة وسماعة الفرع، الدفع الفعلي إن فُعّل، والسيناريوهات اليومية للريتال والأوفلاين. تقارير الاختبار المحلية لا تثبت نشرًا أو قبولًا رقابيًا أو عمل الأجهزة المادية.

مصادر الإصدار: [Laravel releases](https://laravel.com/framework/docs/releases)، [Laravel 13 upgrade](https://laravel.com/framework/docs/13.x/upgrade)، [XBRL essentials](https://specifications.xbrl.org/xbrl-essentials.html). مصادر مخططات XBRL وبصماتها محفوظة في `resources/xbrl/schemas/sources.json`.