# نشر منصة كفالة على cPanel

## المتطلبات

- cPanel يدعم تطبيقات Node.js بإصدار 20.9 أو أحدث.
- نطاق فرعي أو نطاق مخصص مع HTTPS.
- مشروع Supabase مطبق عليه ترحيلات المنصة.
- مجلد `public/uploads` دائم وقابل للكتابة من مستخدم تطبيق Node.js، مع إبقاء ملف الحظر `.htaccess` داخله.

## 1. تجهيز قاعدة البيانات

من جهاز إدارة موثوق:

```powershell
npm install
npx supabase login --token $env:SUPABASE_ACCESS_TOKEN
npx supabase link --project-ref $env:SUPABASE_PROJECT_ID
npx supabase db push
```

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

## 2. إنشاء التطبيق في cPanel

1. افتح **Setup Node.js App**.
2. اختر Production وإصدار Node.js 20 أو أحدث.
3. حدّد Application root، مثلاً `/home/account/apps/kafala`.
4. حدّد Application URL والنطاق.
5. اجعل Startup file هو `server.js`.
6. ارفع المشروع إلى Application root دون ملفات `.env` المحلية أو `node_modules`.

## 3. متغيرات البيئة

أضف القيم من واجهة cPanel:

```text
NODE_ENV
NEXT_PUBLIC_APP_URL
NEXT_PUBLIC_SUPABASE_URL
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY
SUPABASE_PROJECT_ID
SUPABASE_SECRET_KEY
MAX_UPLOAD_BYTES
SESSION_IDLE_MINUTES
CONTACT_EMAIL
RATE_LIMIT_REQUESTS
RATE_LIMIT_WINDOW_SECONDS
```

لا تضف `SUPABASE_SECRET_KEY` إلى أي متغير يبدأ بـ `NEXT_PUBLIC_`. يستخدم `UPLOAD_ROOT` مؤقتاً فقط عند ترقية نسخة قديمة لتحديد مجلد الملفات المسطح السابق.

## 4. التثبيت والبناء

من Terminal داخل Application root:

```bash
npm ci
npm run lint
npm run typecheck
npm test
npm run build
```

أنشئ مسار الملفات واجعله قابلاً للكتابة من حساب التطبيق:

```bash
mkdir -p public/uploads/orphans
chmod 700 public/uploads public/uploads/orphans
```

من cPanel اضغط **Restart Application**. يفحص cPanel المنفذ عبر متغير `PORT`، ويستخدم `server.js` القيمة تلقائياً.

## 5. أول مسؤول

عيّن `FIRST_ADMIN_PASSWORD` مؤقتاً من واجهة متغيرات التطبيق، ثم:

```bash
npm run first-admin -- --email "admin@example.org" --name "اسم المسؤول"
```

احذف `FIRST_ADMIN_PASSWORD` فور نجاح الأمر، ثم أعد تشغيل التطبيق. بعد ذلك ينشئ المسؤول حسابات المتبرعين برقم الهاتف من لوحة الإدارة.

## 6. التحقق بعد النشر

- افتح `/api/health` وتحقق من `status: ok` و`databaseConfigured: true`.
- افتح الصفحة العامة وتأكد أن اتجاهها RTL.
- تحقق أن `/available-orphans` و`/request-sponsorship` يعيدان 404.
- تحقق أن `/admin` و`/donor` يعيدان الزائر إلى صفحة الدخول المناسبة.
- أنشئ حساب متبرع تجريبياً، واختبر الدخول برقم الهاتف، وإيقاف الحساب، وإعادة تعيين كلمة المرور، ثم احذف بيانات الاختبار.
- أنشئ حالة تجريبية دون أي بيانات يدوية، وتأكد أن رقمها مولد تلقائياً، ثم ارفع وثيقة وتأكد أن الرابط المحمي لا يعمل لمستخدم غير مرتبط.
- أنشئ دفعة متبرع شهرية وتحويلاً منفصلاً بإيصال، وتأكد أن الإيصال يظهر للمتبرع المحدد فقط.
- تحقق أن أي رابط يبدأ بـ `/uploads/` يعيد 404 حتى بعد تسجيل الدخول، وأن العرض يعمل فقط من `/api/files/[id]`.
- تأكد أن المسار الفعلي للملف لا يظهر في الاستجابة.
- فعّل شهادة SSL واجبر HTTPS من cPanel أو إعدادات النطاق.

## النسخ الاحتياطي والاستعادة

### قاعدة البيانات

استخدم نسخ Supabase الاحتياطية المجدولة، وأجرِ نسخة منطقية دورية قبل الترحيلات الكبيرة. اختبر الاستعادة في مشروع منفصل.

### الملفات الخاصة

انسخ مجلد `public/uploads/orphans` كاملاً مع الحفاظ على أسماء الملفات والصلاحيات. يجب أن تكون نسخة قاعدة البيانات ومجلد الملفات من نفس النقطة الزمنية قدر الإمكان.

للاستعادة:

1. أوقف التطبيق مؤقتاً.
2. استعد قاعدة البيانات.
3. استعد محتويات ملفات الأيتام إلى `public/uploads/orphans`.
4. طبّق ملكية المستخدم و`chmod 700` للمجلد و`chmod 600` للملفات.
5. أعد تشغيل التطبيق واختبر عدة إيصالات ووثائق.

## التحديثات

```bash
npm ci
npx supabase db push
npm run build
```

عند الترقية لأول مرة من نسخة تستخدم `UPLOAD_ROOT` القديم، شغّل `npm run migrate-uploads` بعد `db push` وقبل البناء، ثم احذف المتغير. لا تشغل أداة النقل في التحديثات اللاحقة. أعد تشغيل التطبيق بعد نجاح البناء فقط، وخذ نسخة احتياطية قبل أي ترحيل يغير بيانات موجودة.
