AssetHub الوثائق

نظرة عامة

AssetHub نظام إدارة أصول متكامل مبني على Laravel 11 وVue 3 وTailwind CSS. الإصدار 3.0 يضيف Translation Editor كاملًا، locales مخصصة، استيراد/تصدير CSV، وتوطين فعّال للمنطقة الزمنية والعملة — فوق تتبّع الدُفعات/اللوت في v2 والتخصيصات والتخلص وصفحات QR العامة للتسليم.

متطلبات الخادم

• PHP 8.2 أو أعلى
• MySQL 5.7+ أو MariaDB 10.3+
• Composer 2.x
• Node.js 18+ وnpm 9+
• خادم ويب: Apache أو Nginx

ملحقات PHP المطلوبة

• OpenSSL, PDO, PDO_MySQL, Mbstring, Tokenizer, XML, Ctype, JSON, GD, Fileinfo

مساحة القرص

200 ميغابايت على الأقل تقريبًا. خصّص مساحة إضافية لصور الأصول ومرفقات الوثائق.

التثبيت

الخيار A — المثبّت الويب (موصى به)

1. ارفع ملفات المشروع إلى خادم الويب الخاص بك.
2. وجّه document root للنطاق إلى public/.
3. اضبط الصلاحيات: يجب أن تكون storage/ وbootstrap/cache/ قابلة للكتابة (chmod 775).
4. انسخ .env.example إلى .env واضبط APP_KEY (نفّذ php artisan key:generate إذا كان لديك SSH/Terminal، أو راجع إعداد cPanel → الخطوة 5 لبدائل File Manager).
5. افتح https://yourdomain.com/install في متصفحك.
6. اتبع المعالج — Requirements ← Database ← Migrate ← Admin Account ← Done.

الخيار B — التثبيت عبر CLI

# 1. تثبيت الاعتماديات
composer install --no-dev --optimize-autoloader
npm install
npm run build

# 2. ضبط البيئة
cp .env.example .env
php artisan key:generate

# 3. تحرير .env لإعداد بيانات DB
# DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD

# 4. إنشاء جداول قاعدة البيانات وزرع البيانات الأولية
php artisan migrate --seed

# 5. إنشاء storage symlink للتحميلات
php artisan storage:link

# 6. تخزين مؤقت للإعدادات للإنتاج
php artisan config:cache
php artisan route:cache
php artisan view:cache

# 7. التعليم كمثبّت
echo "Installed" > storage/installed.lock

الخطوة 2 في المعالج — إعداد قاعدة البيانات

عند وصول المعالج إلى الخطوة 2، يجب إدخال تفاصيل اتصال MySQL لقاعدة البيانات التي أنشأتها في لوحة الاستضافة. يجب أن تكون قاعدة البيانات موجودة مسبقًا (يمكن أن تكون فارغة — الخطوة التالية في المعالج ستنشئ الجداول).

أين تجد هذه البيانات حسب لوحة الاستضافة

• Hostinger: hPanel → Databases → Management → انقر قاعدة البيانات. تعرض الصفحة الاسم واسم المستخدم وزر "Show password".
• cPanel: cPanel → MySQL Databases. قائمة قواعد البيانات تعرض الأسماء؛ المستخدمون مدرجون أدناه. استخدم "Change Password" عند الحاجة.
• Plesk: Plesk → Databases → انقر اسم قاعدة البيانات. صفحة التفاصيل تعرض البيانات وتوفّر إعادة تعيين كلمة المرور.
• DirectAdmin: DirectAdmin → MySQL Management → انقر قاعدة البيانات. البيانات وإعادة تعيين كلمة المرور في صفحة تفاصيل قاعدة البيانات.
• DB خارجي / مُدار: AWS RDS، DigitalOcean Managed Database، إلخ. استخدم اسم المضيف المخصص والمنفذ (غالبًا 3306 لكن تحقّق)، اسم DB، المستخدم وكلمة المرور من وحدة التحكم السحابية. تأكّد من إدراج IP الخادم في قائمة السماح بجدار حماية DB.

أخطاء شائعة وكيفية إصلاحها

الجهاز المحلي (التطوير المحلي)

دليل سريع لتشغيل AssetHub على جهاز الكمبيوتر الخاص بك لأغراض الاختبار أو التطوير قبل النشر إلى الإنتاج. اختر البيئة التي تطابق نظام التشغيل لديك.

الخيار 1 — Laravel Herd (موصى به، macOS و Windows)

Laravel Herd هي البيئة المحلية الرسمية من فريق Laravel — مجانية، أصلية، بدون Docker. تتضمّن PHP 8.2/8.3/8.4 وNginx و(في Herd Pro) MySQL/Redis.

1. حمّل وثبّت Laravel Herd من herd.laravel.com.
2. ضع مجلد مشروع AssetHub داخل ~/Herd/ (macOS) أو %USERPROFILE%\Herd\ (Windows). يُنشئ Herd تلقائيًا نطاقًا بصيغة .test — مثلًا http://assethub.test.
3. افتح Herd ← Sites وتحقّق من أن إصدار PHP هو 8.2 أو 8.3. انقر بالزر الأيمن على الموقع ← Secure لتفعيل HTTPS (مطلوب لماسح QR).
4. أنشئ قاعدة بيانات MySQL. مع Herd Pro، استخدم Services ← MySQL ← Open in TablePlus. وإلا ثبّت MySQL Community أو استخدم SQLite (DB_CONNECTION=sqlite، touch database/database.sqlite).
5. انسخ .env.example إلى .env، املأ بيانات اعتماد قاعدة البيانات، ثم نفّذ php artisan key:generate من جذر المشروع.
6. افتح http://assethub.test/install في متصفحك واتبع معالج التثبيت.

الخيار 2 — XAMPP (Windows وmacOS وLinux)

XAMPP يجمع Apache وMySQL/MariaDB وPHP. مجاني ومتعدد المنصات. احرص على اختيار إصدار بـ PHP 8.2 أو أحدث.

1. حمّل XAMPP 8.2+ من apachefriends.org وثبّته.
2. انسخ مشروع AssetHub إلى C:\xampp\htdocs\AssetHub\ (Windows) أو /Applications/XAMPP/htdocs/AssetHub/ (macOS).
3. افتح XAMPP Control Panel وشغّل Apache وMySQL. إذا كانت المنافذ مشغولة، استخدم Config ← service.conf لتغيير Apache إلى 8080.
4. اذهب إلى http://localhost/phpmyadmin ← جديد ← أنشئ قاعدة بيانات باسم assethub بترتيب utf8mb4.
5. في مجلد المشروع: انسخ .env.example إلى .env، اضبط DB_DATABASE=assethub، DB_USERNAME=root، اترك DB_PASSWORD فارغًا (افتراضي XAMPP). نفّذ php artisan key:generate.
6. زر http://localhost/AssetHub/public/install لتشغيل معالج التثبيت.

الخيار 3 — Laragon (Windows)

Laragon بيئة Windows محمولة مصمّمة لـ Laravel — vhosts تلقائية، روابط نظيفة، MySQL/MariaDB وHeidiSQL مدمج.

1. حمّل Laragon Full من laragon.org وثبّته.
2. في Laragon: القائمة ← PHP ← Version — بدّل إلى PHP 8.2 أو 8.3.
3. انسخ مشروع AssetHub إلى C:\laragon\www\AssetHub\.
4. اضغط على Start All. ينشئ Laragon vhost تلقائيًا: http://assethub.test (يشير إلى مجلد public/).
5. افتح HeidiSQL (مدمج) ← أنشئ قاعدة البيانات assethub. بيانات الاعتماد الافتراضية: المستخدم root، كلمة المرور فارغة.
6. حرّر .env ببيانات اعتماد قاعدة البيانات، نفّذ php artisan key:generate، ثم زر http://assethub.test/install.

الخيار 4 — خادم PHP المدمج (لا حاجة لخادم ويب)

أبسط الخيارات: يأتي Laravel مع artisan serve الذي يشغّل خادم PHP للتطوير. لا حاجة لـ Apache أو Nginx. الأفضل للاختبار السريع.

# تثبيت الاعتماديات والتهيئة
cd /path/to/AssetHub
composer install
cp .env.example .env
php artisan key:generate

# تشغيل migration وبذر البيانات الأولية
php artisan migrate --seed

# تشغيل خادم التطوير
php artisan serve
# ثم زر: http://127.0.0.1:8000/install

مزالق شائعة في الجهاز المحلي

ماسح QR لا يفتح الكاميرا على http://

تتطلّب واجهات الكاميرا في المتصفح HTTPS، مع استثناء واحد: http://localhost وhttp://127.0.0.1 يُعامَلان كسياقات آمنة. إذا فتحت AssetHub عبر IP الشبكة المحلية (مثلًا http://192.168.1.10)، فسترفض الكاميرا. استخدم localhost للتطوير، أو فعّل HTTPS عبر Herd / mkcert.

Permission denied على storage (macOS / Linux)

إذا رأيت أخطاء كتابة عند محاولة التطبيق تسجيل أو التخزين المؤقّت، صحّح الصلاحيات: chmod -R 775 storage bootstrap/cache. على Windows ليس ضروريًا عادةً.

المنفذ مستخدم بالفعل

إذا كان المنفذ 8000 محجوزًا من تطبيق آخر، استخدم منفذًا مختلفًا:

php artisan serve --port=8001

اختبار البريد محليًا

SMTP الحقيقي غير متاح في معظم إعدادات الجهاز المحلي. خياران آمنان: (1) اضبط MAIL_MAILER=log في .env — تُكتب الرسائل في storage/logs/laravel.log بدلًا من إرسالها؛ أو (2) استخدم Mailtrap / MailHog لالتقاط البريد الصادر في صندوق وارد وهمي.

MAIL_MAILER=log
# كل الرسائل تُكتب في storage/logs/laravel.log

أصول الواجهة الأمامية (Vite / Tailwind)

واجهة Vue/Tailwind لـ AssetHub مبنية مسبقًا في الحزمة. إذا حرّرت مكوّنات Vue أو إعدادات Tailwind فستحتاج Node.js 18+:

npm install
npm run dev    # إعادة تحميل ساخنة أثناء التطوير
npm run build  # بناء الإنتاج (يُنفَّذ قبل النشر)

النشر على Hostinger Single (استضافة مشتركة)

هذا هو المسار الموصى به للمستخدمين الذين لا يملكون VPS أو خبرة تقنية. AssetHub متوافق تمامًا مع باقة Hostinger Single Web Hosting الأرخص (~$2.99/شهر). لا SSH ولا Composer ولا سطر أوامر — تتضمّن Single cron jobs أصلية وPHP 8.3 وSSL مجاني.

الخطوة 1 — تجهيز الاستضافة

1. سجّل الدخول إلى Hostinger hPanel.
2. اذهب إلى الاستضافة ← إدارة لنطاقك.
3. اضبط إصدار PHP إلى 8.2 أو 8.3 عبر المتقدّم ← إعدادات PHP.
4. تأكّد من تفعيل ملحقات PHP التالية (عادةً مفعّلة افتراضيًا):
   • OpenSSL, PDO, PDO_MySQL, Mbstring, GD, Tokenizer, XML, Ctype, JSON, Fileinfo

الخطوة 2 — إنشاء قاعدة بيانات MySQL

1. في hPanel، اذهب إلى قواعد البيانات ← MySQL Databases.
2. اضغط على إنشاء قاعدة بيانات جديدة.
3. دوّن هذه القيم الثلاث:
   • اسم قاعدة البيانات — مثلًا u123_AssetHub
   • اسم المستخدم — مثلًا u123_admin
   • كلمة المرور — تُولَّد تلقائيًا، احتفظ بها بأمان

الخطوة 3 — رفع الملفات

1. اذهب إلى الملفات ← File Manager في hPanel.
2. انتقل إلى public_html/ (هذا هو جذر نطاقك).
3. احذف أي index.html أو default.php افتراضي في هذا المجلد.
4. اضغط على رفع الملفات وارفع source.zip بأكمله من الحزمة.
   أو ارفع محتويات مجلد /source/ مباشرة عبر FTP إذا فضّلت.
5. إذا رفعت ZIP، انقر بالزر الأيمن ← استخراج. بعد الاستخراج، يجب أن تكون كل الملفات في جذر public_html/.
6. تأكّد من أن public_html/ يحتوي على: app/، public/، vendor/، .htaccess، index.php (في public/)، .env، إلخ.

الخطوة 4 — تشغيل المثبّت

1. افتح متصفحك واذهب إلى https://yourdomain.com/install.
2. ستظهر شاشة AssetHub Installer.
3. الخطوة 1: Requirements — يجب أن تنجح كل الفحوصات (خضراء). إذا فشل أيّ فحص، تواصل مع دعم Hostinger لتفعيل ملحق PHP المفقود.
4. الخطوة 2: Database — أدخل بيانات الاعتماد من الخطوة 2 أعلاه:
   • المضيف: localhost
   • المنفذ: 3306
   • قاعدة البيانات: u123_AssetHub
   • اسم المستخدم: u123_admin
   • كلمة المرور: (التي ولّدها Hostinger)
5. الخطوة 3: Migrate — اضغط على "Run Migrations & Seed". تستغرق ~10 ثوان. لا تُحدّث الصفحة.
6. الخطوة 4: Admin — أنشئ حساب المسؤول. استخدم كلمة مرور قوية.
7. تم! — سترى رابط Cron (احفظه!) وزر تسجيل الدخول.

الخطوة 5 — إعداد تنبيهات البريد التلقائية عبر Hostinger Cron

يستخدم AssetHub مجدّول Laravel لمهام الخلفية: تنبيهات الضمان، تذكيرات الصيانة، انتهاء الوثائق، تحديث الإهلاك، وعمليات الإخراج المتأخرة. اضبط cron job واحدًا في hPanel وسيقرّر Laravel أيّ مهمة تُنفَّذ ومتى.

1. في hPanel، اذهب إلى المتقدّم ← Cron Jobs.
2. اضغط على إنشاء Cron job.
3. اختر النوع: Custom (وليس "PHP" — نحتاج إلى تمرير وسيط).
4. للأمر، أدخل (استبدل uXXXXXX باسم مستخدم حسابك في Hostinger):

   /usr/bin/php /home/uXXXXXX/public_html/artisan schedule:run

   نصيحة: افتح File Manager، حدّد ملف artisan (جذر المشروع)، انقر بالزر الأيمن ← الخصائص لنسخ المسار الكامل.
5. اضبط الجدولة على كل دقيقة — كل الحقول الخمسة (الدقيقة، الساعة، اليوم، الشهر، يوم الأسبوع) على *.
6. اضغط على حفظ.

هذا كل شيء — يرسل AssetHub الآن تلقائيًا تذكيرات عمليات الإخراج المتأخرة، وتنبيهات الصيانة، وتنبيهات انتهاء الوثائق، وتنبيهات الضمان، ويُحدّث قيم إهلاك الأصول. يجدول Laravel داخليًا كل مهمة بترددها الصحيح (يوميًا 08:00، شهريًا، إلخ).

الخطوة 6 — إعداد البريد (SMTP)

يوفّر Hostinger حسابات بريد مع كل باقة. لاستخدامها في إشعارات AssetHub:

1. في hPanel، اذهب إلى البريد ← حسابات البريد وأنشئ حسابًا (مثلًا noreply@yourdomain.com).
2. حرّر ملف .env في public_html/ عبر File Manager:

   MAIL_MAILER=smtp
   MAIL_HOST=smtp.hostinger.com
   MAIL_PORT=587
   MAIL_USERNAME=noreply@yourdomain.com
   MAIL_PASSWORD=your_email_password
   MAIL_ENCRYPTION=tls
   MAIL_FROM_ADDRESS=noreply@yourdomain.com
   MAIL_FROM_NAME="Your Company Name"

3. احفظ الملف.
4. سجّل الدخول إلى AssetHub ← الإعدادات ← تبويب البريد ← إرسال بريد تجريبي. إذا استلمته فقد انتهيت.

المشكلات الشائعة على Hostinger Single

"500 Internal Server Error" بعد الرفع

• تحقّق من وجود .htaccess في جذر public_html/ واحتوائه على قواعد rewrite.
• تحقّق من ضبط إصدار PHP على 8.2 أو 8.3 في hPanel.
• افحص storage/logs/laravel.log عبر File Manager لمعرفة الخطأ الفعلي.

"Permission denied" عند التحميل

عادةً يضبط Hostinger الصلاحيات الصحيحة، وإلا:

• انقر بالزر الأيمن على storage/ في File Manager ← الصلاحيات ← اضبطها على 755 بشكل تكراري.
• ونفس الشيء لـ bootstrap/cache/.

ماسح QR لا يفتح الكاميرا

تتطلّب واجهات كاميرا المتصفح HTTPS. يوفّر Hostinger SSL مجاني عبر Let's Encrypt — فعّله في hPanel ضمن SSL ← إدارة.

رسائل البريد المجدولة لا تُرسَل

• في hPanel ← Cron Jobs ← تحقّق من عمود Last run في مدخل cron. إذا كان فارغًا فإن cron لا يعمل — تحقّق من صحة مسار artisan.
• اختبر الأمر يدويًا: افتح Terminal في hPanel (إن توفّر) ونفّذ أمر cron. إذا فشل، ستحدّد رسالة الخطأ المشكلة (إصدار PHP خاطئ، مسار خاطئ، إلخ).
• تحقّق من ضبط SMTP بشكل صحيح (الإعدادات ← البريد ← إرسال اختبار).
• افحص storage/logs/laravel.log لأخطاء المجدول.

أداء بطيء

Hostinger Single يستخدم CPU/RAM مشتركة. إذا كان فريقك يفوق 20 مستخدمًا، فكّر في:

• الترقية إلى Premium (~$3.99/شهر) — خوادم أسرع، موارد أكثر، قواعد بيانات متعدّدة.
• أو Business (~$5.99/شهر) — موارد مخصّصة، نسخ احتياطية يومية، بيئة staging.

النشر على cPanel (الاستضافة المشتركة)

يغطي هذا الدليل الاستضافة المشتركة cPanel القياسية (Namecheap وBluehost وGoDaddy ومعظم المضيفين الاقتصاديين). تأتي حزمة AssetHub مع vendor/ وأصول الواجهة الأمامية جاهزة مسبقًا — لا يلزم Composer أو npm أو Terminal. إذا كان cPanel الخاص بك يفتقر إلى Terminal، استخدم SSH Access أو حلول File Manager أدناه.

الخطوة 1 — ضبط إصدار PHP والامتدادات

1. سجّل الدخول إلى cPanel.
2. افتح MultiPHP Manager (أو Select PHP Version) واضبط نطاقك على PHP 8.2 أو 8.3.
3. افتح MultiPHP INI Editor أو PHP Extensions وتأكّد من تفعيل هذه الامتدادات:
   • OpenSSL, PDO, PDO_MySQL, Mbstring, GD, Tokenizer, XML, Ctype, JSON, Fileinfo
4. إذا كان أحد الامتدادات مفقودًا، فعّله من قائمة الامتدادات أو تواصل مع دعم مضيفك.

الخطوة 2 — تفعيل SSL (HTTPS)

1. اذهب إلى SSL/TLS Status (أو Let's Encrypt SSL / AutoSSL).
2. شغّل AutoSSL أو ثبّت شهادة مجانية لنطاقك.
3. HTTPS مطلوب لكي يتمكن ماسح QR في المتصفح من الوصول إلى الكاميرا.

الخطوة 3 — إنشاء قاعدة بيانات MySQL ومستخدم

1. افتح Manage My Databases (ضمن Databases).
2. في Create New Database، أدخل اسمًا (مثلًا assethub) وانقر على إنشاء. يضيف cPanel بادئة حسابك تلقائيًا — سيبدو الاسم الكامل مثل cpaneluser_assethub.
3. في MySQL Users، أنشئ مستخدمًا بكلمة مرور قوية. انسخ اسم المستخدم الكامل مع البادئة.
4. في Add User To Database، اختر المستخدم وقاعدة البيانات، انقر على إضافة، ثم امنح ALL PRIVILEGES. هذه الخطوة سهلة النسيان — بدونها ستحصل على أخطاء Access denied (1045).
5. دوّن هذه القيم الثلاث كما تظهر في cPanel:
   • اسم قاعدة البيانات — مثلًا u123_AssetHub
   • اسم المستخدم — مثلًا u123_admin
   • كلمة المرور — تُولَّد تلقائيًا، احتفظ بها بأمان

الخطوة 4 — رفع الملفات

1. افتح File Manager وانتقل إلى public_html/ (جذر مستندات نطاقك).
2. فعّل Settings → Show Hidden Files حتى تتمكن من رؤية .htaccess و.env.
3. احذف أي index.html افتراضي في public_html/ إن وُجد.
4. ارفع حزمة source.zip واستخرجها، أو ارفع محتويات مجلد /source/ عبر FTP.
5. بعد الاستخراج، يجب أن يحتوي public_html/ على app/ وpublic/ وvendor/ وملف .htaccess الجذري وملف artisan في نفس المستوى.

الخطوة 5 — تجهيز .env قبل تشغيل المثبّت

أكمل هذه الخطوة قبل زيارة /install. يتطلب Laravel وجود APP_KEY صالح وإعدادات قاعدة بيانات صحيحة في .env.

1. في File Manager، انسخ .env.example إلى .env (نفس مجلد artisan).
2. حرّر .env واضبط كحد أدنى:

   APP_NAME=AssetHub
   APP_ENV=production
   APP_DEBUG=false
   APP_URL=https://yourdomain.com
   
   DB_CONNECTION=mysql
   DB_HOST=127.0.0.1
   DB_PORT=3306
   DB_DATABASE=cpaneluser_assethub
   DB_USERNAME=cpaneluser_admin
   DB_PASSWORD="your_password"
   
   SESSION_DRIVER=file
   CACHE_STORE=file

3. اضبط DB_CONNECTION=mysql — ملف .env.example الافتراضي يستخدم SQLite؛ الاستضافة المشتركة تتطلب MySQL.
4. اضبط SESSION_DRIVER=file وCACHE_STORE=file قبل أول migration (يتجنب أخطاء "جدول sessions غير موجود").
5. غلّف DB_PASSWORD بعلامات اقتباس مزدوجة إذا كانت تحتوي على أحرف خاصة (#، $، !، إلخ).

توليد APP_KEY (لا يلزم Terminal)

كثير من خطط cPanel لا تتضمن Terminal على الويب. استخدم إحدى هذه الطرق:

• SSH Access (cPanel → Security → SSH Access): اتصل باستخدام PuTTY أو PowerShell، ثم نفّذ cd ~/public_html && php artisan key:generate.
• مساعد File Manager — أنشئ public/genkey.php مؤقتًا، زره في متصفحك، انسخ المخرج في APP_KEY=، ثم احذف الملف فورًا.

  <?php
  echo 'base64:' . base64_encode(random_bytes(32));

• على جهاز الكمبيوتر — إذا كان PHP مثبتًا محليًا، نفّذ php -r "echo 'base64:'.base64_encode(random_bytes(32));" والصق النتيجة في .env.

• اضبط صلاحيات storage/ وbootstrap/cache/ على 755 (تكراري) إذا أبلغ المثبّت عن أخطاء كتابة.

الخطوة 6 — تشغيل مثبّت الويب

1. افتح https://yourdomain.com/install في متصفحك.
2. الخطوة 1: Requirements — يجب أن تنجح جميع الفحوصات (خضراء). أصلح أي امتدادات PHP مفقودة من الخطوة 1 أعلاه.
3. الخطوة 2: Database — أدخل الأسماء الدقيقة مع البادئة من الخطوة 3:
   • المضيف: 127.0.0.1 or localhost
   • المنفذ: 3306
   • قاعدة البيانات: cpaneluser_assethub
   • المستخدم: cpaneluser_admin
   • كلمة المرور: (your MySQL password)
4. الخطوة 3: Migrate — انقر على "Run Migrations & Seed". تستغرق ~10 ثوانٍ. لا تُحدّث الصفحة.
5. ألغِ تحديد Include demo data لتثبيت إنتاجي نظيف.
6. الخطوة 4: Admin — أنشئ حساب المسؤول.
7. تم! — احفظ رابط Cron المعروض في الشاشة الأخيرة.

الخطوة 7 — إعداد Cron Jobs لتنبيهات البريد

يحتاج AssetHub إلى cron job واحد يعمل كل دقيقة حتى يتمكن Laravel من إرسال تنبيهات الضمان وتذكيرات الصيانة والبريد المجدول الآخر.

1. في cPanel، اذهب إلى Advanced → Cron Jobs.
2. في Add New Cron Job، اضبط الجدول على كل دقيقة (* * * * *).
3. أدخل الأمر (استبدل CPANELUSER باسم مستخدم cPanel من General Information):

   /usr/local/bin/php /home/CPANELUSER/public_html/artisan schedule:run

   نصيحة: قد يكون مسار PHP هو /usr/local/bin/php أو /usr/bin/php — اسأل مضيفك إذا لم تكن متأكدًا. مسار artisan هو المكان الذي رفعت فيه المشروع (عادةً /home/CPANELUSER/public_html/artisan).
4. انقر على Add New Cron Job للحفظ.

الخطوة 8 — إعداد البريد الإلكتروني (SMTP)

أنشئ حساب بريد cPanel للإشعارات الصادرة:

1. اذهب إلى Email Accounts ← أنشئ مثلًا noreply@yourdomain.com.
2. حرّر .env في File Manager:

   MAIL_MAILER=smtp
   MAIL_HOST=mail.yourdomain.com
   MAIL_PORT=587
   MAIL_USERNAME=noreply@yourdomain.com
   MAIL_PASSWORD=your_email_password
   MAIL_ENCRYPTION=tls
   MAIL_FROM_ADDRESS=noreply@yourdomain.com
   MAIL_FROM_NAME="Your Company Name"

3. احفظ، ثم في AssetHub: الإعدادات ← البريد ← إرسال بريد تجريبي.

المشكلات الشائعة على cPanel

"Access denied for user" (SQLSTATE 1045)

• انسخ اسم قاعدة البيانات واسم المستخدم بدقة من cPanel — بما في ذلك بادئة الحساب.
• تأكّد من إتمام Add User To Database مع ALL PRIVILEGES.
• أعد تعيين كلمة مرور MySQL في cPanel وحدّث .env — استخدم علامات اقتباس حول DB_PASSWORD إذا كانت تحتوي على أحرف خاصة.

فشل Migration بعد نجاح خطوة Database

• يختبر المثبّت بيانات اعتماد النموذج، لكن Migrate يقرأ من .env. تأكّد من تطابق الاثنين.
• احذف bootstrap/cache/config.php إن وُجد، ثم أعد المحاولة.
• تأكّد من ضبط DB_CONNECTION=mysql في .env (وليس sqlite).

"Invalid default value" أثناء Migration (1067)

تم الإصلاح في AssetHub v2.1.0+ (جدول checkouts يستخدم أعمدة dateTime). إذا كان لديك نسخة أقدم، حدّث ملف migration أو نزّل الحزمة الأحدث من CodeCanyon.

"500 Internal Server Error" بعد الرفع

• تأكّد من وجود .htaccess الجذري وأن PHP هو 8.2+.
• افحص storage/logs/laravel.log للاطلاع على الخطأ الفعلي.
• تأكّد من ضبط APP_KEY في .env — المفتاح الفارغ يسبب أخطاء 500.

لا يوجد Terminal في cPanel

هذا أمر طبيعي على كثير من خطط الاستضافة المشتركة. استخدم SSH Access (إذا كان مفعّلًا)، أو طريقة genkey.php المؤقتة في الخطوة 5، أو ولّد المفتاح على جهاز الكمبيوتر الشخصي.

كاميرا ماسح QR لا تفتح

فعّل SSL عبر SSL/TLS Status → AutoSSL وادخل إلى الموقع عبر https://.

الإعدادات

ملف .env

الإعدادات داخل التطبيق

معظم الخيارات غير الحسّاسة قابلة للضبط من المسؤول ← الإعدادات:

• عام: اسم/بريد/هاتف الشركة، بادئة asset tag
• البريد: إرسال بريد تجريبي للتحقّق من SMTP
• الإشعارات: عتبات تنبيه الضمان، نافذة تذكير الصيانة
• التوطين: المنطقة الزمنية (قائمة قابلة للبحث تشمل Europe/Skopje)، تنسيق التاريخ، رمز العملة (يشمل MKD — Denar مقدوني)، الرمز وموضعه — يُطبَّق على التطبيق بالكامل بعد الحفظ
• عام → صفحة الأصل العامة: ظهور QR (عام / تسجيل دخول / معطّل) وإعادة توليد جميع رموز QR بعد تغيير URL
• تبويب التوطين يربط بـ Administration → Translations لـ Translation Editor الكامل (للمسؤول فقط)
• Branding: اسم التطبيق والشعار — يحدّث شعار الدخول والتذييل والشارة وعنوان تبويب المتصفح (v4.0+). العنوان الفرعي: عدّل auth.login_subtitle في Administration → Translations
• Appearance (v4.0+): خصّص ألوان العلامة والحالة والنص للوضعين الفاتح والداكن — راجع دليل إعادة العلامة في الأسئلة الشائعة

دعم متعدد اللغات

يأتي AssetHub مع 11 لغة جاهزة، بما في ذلك العربية RTL والهندية. يبدّل المستخدمون اللغة عبر قائمة العلم في الرأس العلوي الأيمن.

اللغات المضمنة

كيفية تبديل اللغة

1. انقر على أيقونة العلم في الزاوية اليمنى العلوية لفتح القائمة المنسدلة.
2. اختر لغتك من القائمة.
3. يتم إعادة تحميل الصفحة؛ وتتبدل جميع تسميات الواجهة والتواريخ وتنسيقات العملة.
4. يتم حفظ اختيارك في كل من حساب المستخدم وكوكي (سنة واحدة).

إضافة لغة مخصصة (المشرف)

اذهب إلى Administration → Translations (مستخدمو admin بصلاحية manage translations):

• انقر "Add Locale" — قدّم رمزًا (مثل mk للمقدونية)، اسم العرض، الاسم الأصلي، اسم ملف SVG للعلم، الاتجاه (LTR/RTL)، وlocale أساس لنسخ الترجمات منه.
• يظهر locale الجديد في مبدّل اللغة وقائمة اللغة الافتراضية في Settings → Localization.
• الترجمات المخزّنة في DB تتجاوز تلقائيًا ترجمات الملف في lang/{code}/.

Translation Editor

يعرض المحرّر كل مفتاح ترجمة مجمّعًا حسب الملف (مثل assets، nav، settings). تعرض المفاتيح baseline الملف وأي تجاوز DB.

• تصفية حسب locale أو مجموعة الترجمة أو نص البحث.
• انقر قيمة للتحرير مباشرة؛ تُحفظ التغييرات في DB فورًا.
• أعد تعيين مفتاح للعودة إلى baseline الملف.
• Locales المدمجة (en، vi، es، …) قابلة للتحرير؛ locales المخصصة تعتمد كليًا على DB.
• فقط المستخدمون بصلاحية manage translations يمكنهم الوصول إلى هذه الصفحة.

CSV import / export

• Export — نزّل جميع المفاتيح لـ locale كـ CSV (group,key,value).
• Import — ارفع CSV بنفس الأعمدة؛ تُحدَّث تجاوزات DB الموجودة، تُدرَج المفاتيح الجديدة.

اللغة الافتراضية لكل مستخدم

لكل مستخدم عمود locale. ترسل إشعارات البريد الإلكتروني تلقائيًا بلغة المستلم المفضلة بفضل عقد HasLocalePreference الخاص بـ Laravel.

اللغة الافتراضية للموقع تُضبط تحت Settings → Localization → Default Language. المستخدمون الفرديون يتجاوزون هذا عبر مبدّل اللغة في الرأس.

قائمة الميزات

المستخدمون والأدوار

يأتي AssetHub مع 5 أدوار جاهزة:

تُخزَّن الصلاحيات كأدوار Spatie — يمكن للمسؤولين الضبط الدقيق لكل صلاحية عبر قاعدة البيانات.

إدارة الأصول

إنشاء الأصول

1. انتقل إلى الأصول ← أصل جديد.
2. املأ الاسم والفئة والعلامة التجارية والطراز والرقم التسلسلي.
3. أضف تاريخ الشراء والسعر (مطلوب للإهلاك).
4. ارفع الصور (يدعم ملفات متعدّدة، حد أقصى 5 ميغابايت لكل ملف).
5. احفظ — يُولَّد asset tag ورمز QR تلقائيًا.

تنسيق Asset Tag

افتراضيًا: {PREFIX}-{YEAR}-{NNNN}، مثلًا AS-2026-0001. قابل للضبط عبر الإعدادات ← عام ← بادئة Asset Tag.

استيراد جماعي

1. اضغط على استيراد في صفحة الأصول.
2. نزّل قالب Excel.
3. املأ بياناتك — الأعمدة المطلوبة: name، category_name.
4. ارفع الملف.

أصول الدُفعات / اللوت (v2)

للعناصر المتطابقة بالكمية (كراسٍ، لوحات مفاتيح، زي موحّد)، اختر نوع التتبّع → Batch / Lot في نموذج أصل جديد بدلًا من إنشاء سجلات مكررة.

1. أدخل الكمية والوحدة (قطعة، طقم، صندوق). عند الحفظ، يُوضَع المخزون في مجموعة المستودع.
2. افتح الأصل ← تبويب Allocations ← Allocate وحدات لموظّف أو قسم.
3. استخدم Return، Adjust (تالف/مفقود/إصلاح)، أو إجراءات التصرف — يجب أن تتسوّى الملخّص المباشر مع إجمالي الكمية.
4. أصول الدُفعات تدعم سعر الوحدة فقط؛ الإهلاك اختياري ومعطّل افتراضيًا للإعداد السريع.

رموز QR

كل أصل يتلقى رمز QR تلقائيًا عند الإنشاء. المسح يفتح الصفحة العامة أو المصادق عليها للأصل (انظر أدناه). المسح داخل التطبيق ينقلك إلى شاشة تفاصيل الأصل.

طباعة البطاقات

• بطاقة واحدة: اضغط على أيقونة الطابعة في أيّ صف أصل.
• صيغة PDF: A4، بطاقتان لكل صف، تشمل asset tag والاسم والعلامة والرقم التسلسلي.

المسح

اضغط على مسح QR في صفحة الأصول. اسمح بصلاحية الكاميرا. يستخدم الماسح html5-qrcode ويعمل على أيّ متصفح حديث. ملاحظة: يتطلّب الوصول إلى الكاميرا HTTPS أو localhost.

صفحة تسليم QR العامة (v2)

لكل أصل أيضًا URL عام قابل للطباعة على /a/{asset_tag} — مفيد للتسليم المادي دون تسجيل دخول.

• اضبط في Settings → General → Public Asset Page: Public، Login required، أو Disabled.
• تعرض الصفحة الصورة والحقول الرئيسية و(للدُفعات) تفصيل الكمية. يمكن للمستخدمين طباعتها كورقة تسليم.
• بعد تغيير APP_URL، انقر Regenerate all QR codes في نفس لوحة الإعدادات.

سير العمل

إسناد الأصل

1. افتح صفحة تفاصيل أصل.
2. اضغط على إسناد (يظهر إذا كان الأصل متاحًا).
3. اختر المستخدم وتاريخ الإرجاع الاختياري والملاحظات.
4. أرسل — تُنشأ المعاملة ويُرسَل إشعار البريد.

طلبات الأصول

يمكن للموظفين تقديم طلبات للأصول التي يحتاجونها. للطلبات 4 حالات: pending ← approved ← fulfilled، أو rejected. تُرسَل رسائل الموافقة تلقائيًا.

Check-in / Check-out

للأصول المشتركة (الكاميرات، أجهزة العرض، المركبات). للحجوزات نطاقات تواريخ؛ يمنع النظام تداخل عمليات الإخراج. يُظهر عرض التقويم كل الحجوزات في لمحة.

التخلص — شطب رسمي (v2)

تُشطب العناصر البالية أو التالفة في دُفعات موثّقة مع فصل المهام (المقترح ≠ الموافق). يتطلب صلاحيات manage disposals وapprove disposals.

1. الشريط الجانبي ← Disposals ← New Disposal. حدّد العنوان والفترة (Q1–Q4، سنوي، أو ad-hoc).
2. افتح المسودة ← Add items — وحدات دُفعة تالفة مؤهّلة أو أصول مفردة بحالة Poor.
3. انقر Submit for approval — تُقفَل الدُفعة.
4. موافق مختلف ينقر Approve & execute — تُعلَّم الأصول/الوحدات كمُتخلَّص منها.
5. اطبع disposal minutes (PDF) لسجلات الامتثال.

الإهلاك

يحسب AssetHub إهلاك الأصول بواحدة من ثلاث طرق:

تُرث الإعدادات الافتراضية من فئة الأصل. تُولَّد إدخالات الجدول شهريًا. تُحدَّث current_value للأصل تلقائيًا في أول كل شهر.

الحقول المخصصة

المسؤول ← الحقول المخصصة يتيح لك إضافة سمات مخصّصة بلا حدود للأصول:

• الأنواع: نص، رقم، تاريخ، اختيار (dropdown)، منطقة نص، ملف، مربع اختيار
• النطاق: تطبيق على كل الفئات أو فئة محدّدة
• إعادة الترتيب: اسحب المقبض
• يتم التحقّق من الحقول الإلزامية عند حفظ الأصل

التقارير

اثنا عشر تقريرًا مدمجًا، يمكن الوصول إليها من قائمة التقارير:

1. ملخّص الأصول — الإجماليات حسب الحالة والوضع والفئة والقسم
2. الإهلاك — فقد القيمة لكل فئة، أكثر الأصول إهلاكًا
3. المعاملات — نشاط الإسناد والإرجاع والنقل عبر الزمن
4. تكلفة الصيانة — الإنفاق حسب الشهر والفئة والنوع
5. انتهاء الضمان — الأصول التي تحتاج اهتمامًا خلال 30/60/180 يومًا
6. أصول الأقسام — توزيع الأصول واستخدام الميزانية حسب القسم
7. الأصول حسب المصدر — التوزيع بين الشراء والمشروع والتبرّع والنقل
8. ملخّص جرد المخزون — الفروقات بين دورات الجرد الدورية
9. Employee Assignments (v2) — من يحمل ماذا، بما في ذلك تخصيصات الدُفعات
10. Department / Location (v2) — الأصول والكميات حسب القسم أو الموقع
11. Inventory Reconciliation (v2) — المخزون مقابل المخصّص مقابل التالف/المفقود/المُتخلَّص منه
12. Damaged Assets (v2) — عناصر مُعلَّمة للإصلاح أو الشطب

جميع التقارير تدعم تصدير Excel وPDF عبر أزرار في رأس الصفحة. تقارير v2 واعية بالكمية (عدد الأصول + إجمالي الوحدات).

خطافات الويب

يمكن لـ AssetHub إخطار الخدمات الخارجية عند الأحداث الرئيسية.

الأحداث المتاحة

• asset.created, asset.updated, asset.deleted
• asset.assigned, asset.returned, asset.transferred
• request.created, request.approved, request.rejected, request.fulfilled
• maintenance.scheduled, maintenance.started, maintenance.completed
• checkout.created, checkout.returned

صيغة Payload

{
  "event": "asset.assigned",
  "timestamp": "2026-05-05T08:00:00+00:00",
  "data": {
    "asset_id": 1,
    "asset_tag": "AS-2026-0001",
    "asset_name": "HP EliteDesk 800",
    "to_user_id": 4,
    "transaction_id": 12
  }
}

التحقّق من التوقيع

إذا ضُبط secret، تتضمّن الطلبات الترويسة X-AssetHub-Signature الحاوية على HMAC-SHA256 للـ payload body. تحقّق في طرفك:

$expected = hash_hmac('sha256', $rawBody, $secret);
if (hash_equals($expected, $request->header('X-AssetHub-Signature'))) {
  // صالح
}

سياسة إعادة المحاولة

يُعاد التسليم 3 مرات بفاصل 200 مللي ثانية عند الفشل. بعد 10 إخفاقات متتالية، يُعطَّل webhook تلقائيًا.

المهام المجدولة

يستخدم AssetHub مجدّول Laravel لمهام الخلفية. تحتاج فقط إلى مدخل cron واحد — يُوزّع Laravel داخليًا كل مهمة على الوقت الصحيح.

الاستضافة المشتركة (واجهة Cron Jobs لـ cPanel / Hostinger)

راجع قسم إعداد cPanel → الخطوة 7 أو إعداد Hostinger → الخطوة 5 للحصول على تعليمات مع لقطات الشاشة. باختصار: Advanced → Cron Jobs، الأمر:

/usr/bin/php /home/uXXXXXX/public_html/artisan schedule:run

الجدول: كل دقيقة (* في كل الحقول الخمسة).

أمر cron لـ cPanel

استبدل CPANELUSER باسم مستخدم cPanel الخاص بك:

/usr/local/bin/php /home/CPANELUSER/public_html/artisan schedule:run

VPS / خادم مخصّص (crontab)

نفّذ crontab -e كمستخدم الويب (غالبًا www-data) وأضف:

* * * * * cd /path/to/AssetHub && php artisan schedule:run >> /dev/null 2>&1

حلّ بديل: pinger URL خارجي

إذا لم يكن لدى مضيفك cron على الإطلاق، استخدم رابط Cron داخل التطبيق (الإعدادات ← تبويب النظام) مع cron-job.org (مجاني، كل 15 دقيقة).

المهام التي تعمل تلقائيًا

Upgrade Guides

Step-by-step guides for updating an existing installation. Open the guide that matches your current version.

• v3.1 → v4.0 — Full upgrade guide — Appearance settings, browser tab title from Branding. No migration required.
• v3.0 → v3.1 — Full upgrade guide — Visible languages checklist in navbar picker. No migration required.
• v2.x → v3.0 — Full upgrade guide — Translation Editor, custom locales, localization settings.
• v1.x → v2.0 — Full upgrade guide — Batch assets, disposals, public QR page, operational reports.

حل المشكلات

"Permission denied" على storage

chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

ماسح QR لا يفتح الكاميرا

تتطلّب واجهات كاميرا المتصفح HTTPS. ثبّت شهادة SSL أو استخدم localhost للاختبار.

البريد لا يصل

افحص storage/logs/laravel.log بحثًا عن أخطاء. استخدم الإعدادات ← البريد ← إرسال بريد تجريبي للتحقّق من بيانات SMTP. تأكّد من أن خادم SMTP يسمح لـ IP المرسِل.

قاعدة البيانات "Access denied" (1045) على cPanel

اسم مستخدم/كلمة مرور خاطئة، عدم ربط المستخدم بقاعدة البيانات، أو أحرف خاصة في كلمة المرور تُعطّل تحليل .env. راجع إعداد cPanel → المشكلات الشائعة.

خطأ Migration 1067 (Invalid default value)

وضع MySQL الصارم على الاستضافة المشتركة يرفض أعمدة timestamp متعددة NOT NULL. تم الإصلاح في v2.1.0+. حدّث حزمتك أو غيّر checkout_date / expected_return_date إلى dateTime في migration الـ checkouts.

APP_KEY مفقود / خطأ 500 قبل التثبيت

يتطلب Laravel وجود APP_KEY في .env قبل تحميل التطبيق. إذا لم يكن لدى cPanel Terminal، راجع إعداد cPanel → الخطوة 5 لطرق SSH أو genkey.php أو التوليد المحلي.

إعادة ضبط التثبيت

احذف storage/installed.lock وزر /install مجدّدًا. سيتم محو البيانات الموجودة إذا أعدت تشغيل الـ migrations.

الأداء — قائمة أصول بطيئة

نفّذ php artisan optimize لتخزين الإعدادات والمسارات والـ views مؤقتًا. تأكّد من وجود فهارس MySQL على assets.asset_tag، assets.serial_number، assets.status (تُنشأ تلقائيًا بواسطة الـ migrations).

Upgrading from v3.0.x to v3.1

Download the v3.1 package from CodeCanyon, replace application files (keep your .env and storage/ uploads). No new migrations are required. The new visible_locales setting is optional — if unset, all languages remain visible in the navbar picker.

v3.0 → v3.1 — Full upgrade guide

الترقية من v2.x إلى v3.0

نزّل ZIP v3 من CodeCanyon، استبدل ملفات التطبيق (احتفظ بـ .env وتحميلات storage/)، ثم نفّذ php artisan migrate. تُضاف جداول locales المخصصة وتجاوزات الترجمة تلقائيًا. الإعدادات والأصول الحالية محفوظة.

v2.x → v3.0 — Full upgrade guide

الترقية من v1.x إلى v2.0

نزّل ZIP v2 من CodeCanyon، استبدل ملفات التطبيق (احتفظ بـ .env وتحميلات storage/)، ثم نفّذ php artisan migrate. الترقية غير مُدمِرة — أصول v1 المفردة تستمر بالعمل؛ جداول batch/disposal تُضاف تلقائيًا.

v1.x → v2.0 — Full upgrade guide

سجل التغييرات

v3.1.0 — Visible Language Picker (2026-06)

• Settings → Localization: checklist to choose which languages appear in the navbar language dropdown (built-in + custom locales)
• Default language is always visible; picker auto-hides when only one language is selected
• Backend validates locale switches; users on a hidden locale fall back to the default language
• No database migration required — upgrade is file-replace only
• علامة صفحة الدخول: التذييل والشارة تتبع Settings → Branding → App Name (بدون تعديل كود)

v3.0.0 — التوطين وTranslation Editor (2026-06)

• واجهة Translation Editor في Administration → Translations (Add Locale، تحرير مباشر، بحث/تصفية حسب المجموعة)
• Locales مخصصة مخزّنة في DB — الرمز، اسم العرض، الاسم الأصلي، SVG العلم، الاتجاه، locale الأساس
• استيراد/تصدير CSV لتحديثات الترجمة الجماعية
• إعدادات المنطقة الزمنية والعملة تُطبَّق الآن على التطبيق بالكامل (config/localization.php يشمل Europe/Skopje، MKD)
• Settings → Localization: قوائم منسدلة للمنطقة الزمنية/العملة قابلة للبحث مع دعم القيم المخصصة
• إضافة Hindi (hi) كلغة مدمجة 11؛ date_format محترم عبر صفحات Vue
• manage translations محمية بالصلاحيات؛ تجاوزات DB تدمج مع baseline ملف lang/

v2.0.0 — إصدار تشغيلي (2026-06)

• أصول دُفعات / لوت — تتبّع الكمية، التخصيصات، الإرجاع، التسوية المباشرة
• 4 تقارير تشغيلية: Employee Assignments، Department/Location، Inventory Reconciliation، Damaged Assets
• وحدة التخلص — دُفعات شطب، موافقة فصل المهام، محضر PDF قابل للطباعة
• صفحة QR عامة للأصل على /a/{tag} مع ظهور قابل للضبط
• التقارير القديمة محدّثة لعرض عدد الأصول + إجمالي الوحدات
• رموز QR ترتبط بصفحة التسليم العامة؛ سجل المعاملات يسجّل الكمية عند نقل الدُفعات
• بيانات demo محدّثة، دليل المستخدم (يُشحن منفصلًا في documentation/)، وسلاسل i18n

v1.0.0 — الإصدار الأول (2026-05)

• CRUD الأصول مع توليد QR تلقائيًا
• 5 أدوار مستخدمين (Admin، مدير IT، محاسب، مشرف، موظف) بصلاحيات دقيقة
• تتبّع مصدر الأصل (شراء مركزي، شراء لامركزي، مشروع استثماري، تبرّع، نقل داخلي)
• سير عمل الإسناد والإرجاع مع إشعارات بالبريد
• سير عمل الموافقة على النقل (pending ← approved/rejected) مع بوّابة الصلاحيات
• سير الموافقة على طلبات الأصول
• Check-in/check-out مع عرض التقويم
• جدولة الصيانة مع التجديد التلقائي
• مرفقات الوثائق مع تنبيهات الانتهاء
• الإهلاك بـ 3 طرق حساب + تنبيهات نهاية العمر
• وحدة جرد المخزون — جرد دوري مع تتبّع الفروقات
• الحقول المخصصة بـ 7 أنواع إدخال وفرز drag-drop
• 8 تقارير مع مخطّطات وتصدير Excel وPDF (تشمل الأصول حسب المصدر، ملخّص الجرد)
• سجل تدقيق عبر Spatie Activitylog مع عارض diff
• Webhooks مع توقيع HMAC وإعادة محاولة تلقائية
• واجهة متعدّدة اللغات: 10 لغات (en، vi، es، fr، de، zh، ja، pt-BR، ru، ar مع RTL)
• واجهة إعدادات للشركة والبريد والإشعارات والتوطين والترجمات
• معالج تثبيت قائم على الويب
• وضع داكن بلوحة ألوان emerald-teal

الاعتمادات

المكتبات مفتوحة المصدر المستخدمة

• Laravel 11 — MIT
• Vue 3 — MIT
• Inertia.js — MIT
• Tailwind CSS — MIT
• Spatie Permission, Media Library, Activitylog — MIT
• Phosphor Icons — MIT (duotone weight)
• ApexCharts — MIT
• html5-qrcode — Apache 2.0
• Simple QrCode — MIT
• Laravel Excel — MIT
• Laravel DomPDF — MIT