# منصة دراسات الجدوى — دستور المشروع

## هوية المشروع

منصة سعودية (الرياض أولاً) لبيع دراسات جدوى جاهزة والتعديل عليها تفاعلياً.
اللغة: عربية فقط، RTL كامل. العملة الافتراضية: ريال سعودي.
**الاسم المعتمد: «جدوى» — النطاق الرسمي: www.jadwa.biz** (ثبّتهما إبراهيم في 20 أغسطس 2026).

## القواعد الحاكمة — غير قابلة للكسر

1. **الفصل الصارم:** كل عملية حسابية (IRR, NPV, نقطة التعادل, الإهلاك, الزكاة,
   GOSI...) تُنفذ حصراً في `packages/engine` بكود TypeScript حتمي.
   يُمنع منعاً باتاً أن يولّد نموذج الذكاء الاصطناعي أي رقم مالي أو يعدّله.
   النموذج يستقبل نتائج المحرك كـ JSON ويكتب نصوصاً فقط.

2. **الدراسة الأصلية مقدسة:** لا يُعدَّل صف الدراسة الأصلية في قاعدة البيانات أبداً.
   كل تعديل مستخدم = صف جديد في جدول `study_versions` يشير للأصل.

3. **دفتر النقاط محاسبي:** رصيد النقاط لا يُخزَّن كرقم يُعدَّل، بل يُحسب من جدول
   حركات (ledger) append-only: شحن، خصم، استرداد. كل خصم مرتبط بمعرف عملية AI.
   فشل استدعاء AI = استرداد تلقائي للنقاط في نفس المعاملة.

4. **لا ثقة بالعميل:** كل تحقق (ملكية الدراسة، رصيد النقاط، حالة الاشتراك)
   يتم في الخادم. المتصفح يعرض فقط.

5. **عزل البيانات:** كل استعلام على بيانات المستخدمين يمر عبر شرط `user_id`
   إلزامي. لا نقطة نهاية تُرجع بيانات مستخدم آخر تحت أي ظرف.

6. **المال بالهللة:** كل المبالغ تُخزَّن أعداداً صحيحة بالهللة (integer halalas).
   يُمنع Float في أي حقل مالي.

7. **الذكاء الاصطناعي مقيَّد:** موجّه النظام يحصر النموذج في دراسات الجدوى
   والمالية وريادة الأعمال، ويرفض ما سواها، ويُمنع من ذكر أرقام غير موجودة
   في الـ JSON المُمرَّر له.

8. **كل ميزة لها اختبار:** المحرك المالي تغطيته 100% بحالات مرجعية محسوبة يدوياً.
   لا يُدمج كود محرك بدون اختبار.

9. **سجل تدقيق:** كل عملية (تعديل، توليد، شراء، خصم نقاط) تُسجل في `audit_log`.

10. **العربية أولاً:** كل نص واجهة يُكتب عربياً فصيحاً مباشرة (لا ترجمة آلية)،
    والأرقام في الواجهة أرقام غربية (1234.56) مع فواصل آلاف عربية الأسلوب.

## الحزمة التقنية

Next.js 15 (App Router) / TypeScript strict / Tailwind + RTL /
PostgreSQL 16 + Drizzle / Auth.js / Claude API (طبقة عزل في packages/ai) /
Puppeteer للـ PDF / Docker Compose للنشر على Hostinger VPS.

## بنية المستودع (Monorepo)

- `apps/web` — تطبيق Next.js (الواجهة + Route Handlers)
- `packages/engine` — المحرك المالي الحتمي (صفر تبعيات خارجية)
- `packages/schema` — أنواع الدراسة الموحدة + Zod validators (مصدر الحقيقة الوحيد)
- `packages/ai` — طبقة الذكاء الاصطناعي (الموجهات + العزل عن المزود)
- `packages/db` — Drizzle schema + migrations

## أسلوب العمل

- التزم بالمرحلة المطلوبة فقط؛ لا تبنِ ميزات من مراحل لاحقة.
- عند أي غموض في قاعدة عمل مالية سعودية (زكاة، GOSI، مقابل مالي...)
  ضع القيمة في ملف `packages/engine/src/constants/saudi-rules.ts`
  مع تعليق يشرح المصدر وتاريخ آخر تحديث — لا تدفنها في الكود.
- التسعير: دراسة 19900 هللة / اشتراك شهري 9900 هللة / 100 نقطة = 2500 هللة /
  دراسة مخصصة 199000 هللة.

## المهارات (Skills) المثبتة في `.claude/skills/`

| المهارة                         | متى تُستدعى                                        |
| :------------------------------ | :------------------------------------------------- |
| webapp-testing                  | التحقق الآلي من معايير قبول كل مرحلة (Playwright)  |
| frontend-design                 | أي عمل تصميم واجهات (المرحلة 4 والصفحات التسويقية) |
| claude-api                      | بناء `packages/ai` (المرحلة 5)                     |
| test-driven-development         | المحرك المالي (المرحلة 2): اختبار قبل كود          |
| systematic-debugging            | أي تشخيص عطل في كل المراحل                         |
| verification-before-completion  | قبل إعلان "تم" في أي مرحلة                         |
| writing-plans / executing-plans | تخطيط وتنفيذ المراحل الكبيرة (4، 5، 6)             |
| shadcn                          | مكونات الواجهة (بطاقات، جداول، Sliders، Dialogs)   |

المهارات المخصصة الثماني (jadwa-schema، saudi-finance-rules، jadwa-engine-contracts،
arabic-rtl-ui، jadwa-ai-prompts، moyasar-payments، jadwa-deploy، jadwa-etl)
تُصنع كل واحدة في نهاية مرحلتها بمهارة skill-creator — لا تُصنع مسبقاً.