# دليل نشر نظام الإدارة الشامل (ERP) على استضافتك الخاصة

## قبل أن تبدأ: تأكد من نوع استضافتك

هذا النظام هو **تطبيق Node.js** (وليس ملفات HTML أو PHP)، لذلك يجب أن تدعم استضافتك تشغيل Node.js.

| نوع الاستضافة | هل تصلح؟ |
|---|---|
| VPS (خادم خاص افتراضي) مثل Hostinger VPS / Contabo / DigitalOcean / Hetzner | نعم — الأفضل |
| منصات مثل Railway / Render / Fly.io | نعم — سهلة الإعداد |
| استضافة cPanel تدعم "Setup Node.js App" | نعم مع بعض القيود |
| استضافة مشتركة عادية (PHP/HTML فقط) | لا تصلح إطلاقاً |

---

## الخطوة 1: إنشاء قاعدة البيانات (MySQL)

النظام يحتاج قاعدة بيانات **MySQL 8** (أو MariaDB 10.6+).

1. من لوحة تحكم استضافتك (cPanel / Plesk / أو أمر mysql على VPS) أنشئ قاعدة بيانات جديدة، مثلاً باسم `erp_db`.
2. أنشئ مستخدماً لقاعدة البيانات وأعطه **جميع الصلاحيات** (ALL PRIVILEGES) على هذه القاعدة.
3. مهم جداً: اجعل ترميز القاعدة `utf8mb4` حتى تُخزَّن النصوص العربية بدون مشاكل:
```sql
CREATE DATABASE erp_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```
4. نفّذ ملف **`database-setup.sql`** (مرفق مع الملفات) على القاعدة الجديدة — وهو ينشئ جميع الجداول (16 جدولاً) دفعة واحدة:
   - عبر phpMyAdmin: اختر القاعدة → تبويب Import → ارفع الملف → Go
   - أو عبر سطر الأوامر:
```bash
mysql -u USER -p erp_db < database-setup.sql
```

## الخطوة 2: ربط النظام بقاعدة البيانات

الربط يتم عبر متغير واحد فقط اسمه `DATABASE_URL` بصيغة:

```
mysql://اسم_المستخدم:كلمة_المرور@العنوان:3306/اسم_القاعدة
```

أمثلة:

| الحالة | القيمة |
|---|---|
| قاعدة البيانات على نفس الخادم | `mysql://erp_user:MyPass123@localhost:3306/erp_db` |
| قاعدة بيانات خارجية/سحابية | `mysql://erp_user:MyPass123@db.example.com:3306/erp_db` |

أنشئ ملفاً باسم `.env` في مجلد المشروع الرئيسي واكتب فيه:

```env
DATABASE_URL=mysql://erp_user:MyPass123@localhost:3306/erp_db
JWT_SECRET=اكتب-هنا-سلسلة-عشوائية-طويلة-33-حرفاً-على-الأقل
NODE_ENV=production
PORT=3000
```

### نصائح لتجنب المشاكل الشائعة في الربط

1. **كلمة مرور فيها رموز خاصة** (`@` أو `#` أو `%`): يجب ترميزها. مثلاً `P@ss` تُكتب `P%40ss`.
2. **خطأ Access denied**: تأكد أن المستخدم له صلاحيات على القاعدة، وأن الاتصال مسموح من `localhost` (أو من `%` إذا كانت القاعدة على خادم آخر).
3. **خطأ ECONNREFUSED**: تأكد أن MySQL يعمل وأن المنفذ 3306 صحيح، وإذا كانت القاعدة على خادم منفصل افتح المنفذ في الجدار الناري.
4. **قواعد سحابية (PlanetScale/TiDB Cloud/Aiven)**: قد تحتاج إضافة `?ssl={"rejectUnauthorized":true}` في نهاية الرابط.
5. **العربية تظهر كعلامات استفهام**: تأكد أن القاعدة منشأة بترميز `utf8mb4` (الخطوة 1).

## الخطوة 3: تشغيل النظام

على الخادم (يتطلب Node.js 22+ و pnpm):

```bash
# 1) تثبيت pnpm إذا لم يكن موجوداً
npm install -g pnpm

# 2) داخل مجلد المشروع: تثبيت الاعتماديات
pnpm install

# 3) بناء النسخة الإنتاجية
pnpm build

# 4) التشغيل
pnpm start
```

سيعمل النظام على المنفذ المحدد في `PORT`. للتشغيل الدائم استخدم PM2:

```bash
npm install -g pm2
pm2 start dist/index.js --name erp
pm2 save && pm2 startup
```

ثم اربط دومينك عبر Nginx كـ reverse proxy إلى `http://localhost:3000`.

## الخطوة 4 (مهمة): نظام تسجيل الدخول

النظام يستخدم حالياً **Manus OAuth** لتسجيل الدخول، وهذه الخدمة مرتبطة بمنصة Manus وتتطلب المتغيرات التالية في `.env` لتعمل على دومين خارجي:

```env
VITE_APP_ID=...
OAUTH_SERVER_URL=https://api.manus.im
VITE_OAUTH_PORTAL_URL=...
```

هذه القيم مرتبطة بحساب Manus وقد لا تعمل مع دومين خارجي غير مسجل لديهم. لذلك عند النشر الخارجي أمامك خياران:

| الخيار | التفاصيل |
|---|---|
| الأسهل والموصى به | إبقاء النظام على استضافة Manus (https://erp-system-vumnecke.manus.space) وربط دومينك الخاص بها من Settings → Domains — كل شيء يعمل تلقائياً |
| النشر الخارجي الكامل | يتطلب استبدال تسجيل الدخول بنظام بريد إلكتروني/كلمة مرور — أخبرني إن أردت وأنفذه لك |

## هيكل الملفات

| المجلد/الملف | المحتوى |
|---|---|
| `client/` | الواجهة الأمامية (React 19 + Tailwind 4) |
| `server/` | الخادم الخلفي (Express + tRPC) |
| `drizzle/` | مخطط قاعدة البيانات وملفات SQL |
| `shared/roles.ts` | تعريف الأدوار والصلاحيات |
| `database-setup.sql` | ملف إنشاء جميع الجداول (مرفق خارج المشروع أيضاً) |