# منصة كفالة

منصة عربية لإدارة كفالة الأيتام باستخدام Next.js وSupabase، بواجهة RTL وصلاحيتين: مسؤول ومتبرع. المنصة توثق المساهمات والتحويلات الخارجية ولا تعالج الدفع داخلها.

## الوظائف

- لا توجد قوائم حالات أو ملفات أطفال أو طلبات كفالة عامة.
- ينشئ المسؤول حساب المتبرع بالاسم ورقم الهاتف وكلمة مرور مؤقتة، مع التفعيل والإيقاف وإعادة تعيين كلمة المرور.
- يسجل النظام رقم الحالة تلقائياً بصيغة `ORP-000001` ويمنع تغييره.
- جميع بيانات الحالة ووثائقها اختيارية، ويمكن إنشاء ملف برقم الحالة التلقائي فقط ثم استكماله لاحقاً.
- يفحص الخادم الاسم والميلاد والهاتف والحساب البنكي وبصمات SHA-256 لوثائق الهوية، ويحذر المسؤول قبل إنشاء حالة محتملة التكرار.
- يدعم أكثر من متبرع للحالة الواحدة وأكثر من حالة للمتبرع، مع مساهمة شهرية مستقلة وتاريخ محفوظ للعلاقات المنتهية.
- تحفظ `sponsor_monthly_payments` التزام كل متبرع للشهر ومبلغه المتوقع والمستلم، مع حالة غير مدفوع أو مدفوع جزئياً أو مدفوع.
- تحفظ `orphan_transfers` الأموال الخارجة من المبادرة إلى اليتيم بصورة مستقلة؛ يختار المسؤول اليتيم والمتبرع ويستنتج النظام السجل الشهري من تاريخ التحويل.
- يرى المتبرع الحالات المرتبطة به ووثائقها ودفعاته وتحويلاته وإيصالاته هو فقط.
- تعرض التقارير كبيانات تفاعلية داخل لوحة الإدارة، مع البحث والتصفية والبطاقات المتجاوبة، دون إنشاء ملفات تقارير.
- تحفظ الصور بأسماء UUID داخل `public/uploads/orphans/<orphan-id>/documents` و`receipts`، ويمنع الوصول المباشر إليها وتعرض فقط عبر المسار المحمي بعد التحقق من الصلاحية.
- تطبق قاعدة البيانات RLS، وتوثق العمليات الحساسة في سجل التدقيق.

## التشغيل المحلي

يتطلب Node.js 20.9 أو أحدث.

```powershell
Copy-Item .env.example .env.local
npm install
npm run dev
```

افتح `http://localhost:3000`. استخدم قيماً صحيحة لمتغيرات Supabase، وتأكد أن `public/uploads` قابل للكتابة من مستخدم التطبيق.

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

ملفات الترحيل:

- `supabase/migrations/202607250001_initial_schema.sql`
- `supabase/migrations/202607250002_security_hardening.sql`
- `supabase/migrations/202607260001_private_sponsor_workflow.sql`
- `supabase/migrations/202607260002_auth_phone_hardening.sql`
- `supabase/migrations/202607260003_optional_orphans_financial_refactor.sql`
- `supabase/migrations/202607260004_orphan_upload_folders.sql`

لتطبيق الترحيلات عبر Supabase CLI:

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

لا يضيف `supabase/seed.sql` بيانات مستفيدين أو وثائق حقيقية.

## أول مسؤول

بعد تطبيق الترحيلات، عيّن كلمة مرور مؤقتة قوية في متغير البيئة، ثم شغّل:

```powershell
$env:FIRST_ADMIN_PASSWORD = "temporary-strong-password"
npm run first-admin -- --email "admin@example.org" --name "اسم المسؤول"
Remove-Item Env:FIRST_ADMIN_PASSWORD
```

الحد الأدنى التقني لكلمات المرور 6 أحرف، ويوصى بكلمة أطول وفريدة. البريد الإلكتروني مخصص لحساب المسؤول فقط، وحسابات المتبرعين تستخدم رقم الهاتف حصراً. يرفض السكربت إنشاء مسؤول ثانٍ ولا يطبع كلمة المرور أو المفتاح السري.

## التحقق

```powershell
npm run lint
npm run typecheck
npm test
npm run build
npm run test:e2e
```

## بنية مهمة

- `src/app/(public)`: معلومات المؤسسة والدخول، دون أي بيانات حالات.
- `src/app/admin`: لوحة المسؤول.
- `src/app/donor`: بوابة المتبرع.
- `src/app/api/files/[id]`: تقديم الملفات بعد التحقق من الجلسة والعلاقة النشطة.
- `src/lib/storage.ts`: تنظيم ملفات كل يتيم والتحقق من الصور ومنع تجاوز المسارات.
- `src/lib/auth.ts`: الجلسات والأدوار وحالة الحساب.
- `supabase/migrations`: المخطط وRLS والتوابع والمشغلات.

راجع [DEPLOYMENT-CPANEL.md](./DEPLOYMENT-CPANEL.md) للنشر و[SECURITY.md](./SECURITY.md) لنموذج الحماية والاستجابة للحوادث.
