feat: implement splash and onboarding flows, update app assets, and add project design documentation

docs/33-addons-packaging.md

@@ -0,0 +1,206 @@
+# 33 — الوحدات والإضافات: كيف نحزّمها ونسعّرها ونسوّق لها
+
+> أُنشئ 2026-07-24 بطلب المالك: «التطبيق الكبير فيه المواصلات والذكاء الصناعي واستخبارات التسعير ومنصة نبيه — بدنا نسوّق لها كباقات وإضافات على الموقع.»
+> يُقرأ مع: `docs/27` (كتالوج الميزات + حالة كل ميزة) · `docs/05` (التسعير) · `docs/32` (نصوص الإعلانات) · `docs/34` (أي باك إند سيحملها).
+
+---
+
+## 0) الفكرة الاستراتيجية — لماذا الوحدات تحل مشكلتنا السعرية
+
+في المراجعة السابقة ظهر توتر: السعر الأساسي منخفض جداً في بعض البنود (**$0.02/رحلة = 20% من السوق**) لدرجة أنه يقرأ كإغراق.
+
+**الوحدات تحلّ هذا التوتر تماماً:**
+
+> **النواة رخيصة عمداً (سلاح اكتساب) — والربح يأتي من الوحدات (محرّك توسّع).**
+
+| الطبقة | الدور | التسعير |
+|---|---|---|
+| **النواة** (تطبيقان + لوحة + dispatch) | كسر الاعتراض السعري، الدخول السريع | ~55% من أرخص منافس |
+| **الوحدات** | هامش الربح الحقيقي + التمايز الذي لا يُقلَّد | سعر كامل — لا يوجد منافس يبيعها أصلاً |
+| **الاستهلاك** (نسبة GMV) | ينمو مع نمو العميل | 1–3.5% تنازلي |
+
+هذا نموذج **land-and-expand** الكلاسيكي: العميل يدخل بـ$2,500، وبعد 6 أشهر يدفع $700/شهر لأنه أضاف ثلاث وحدات. **متوسط الإيراد لكل عميل يتضاعف بلا حملة اكتساب جديدة** — وهو أرخص نمو ممكن.
+
+---
+
+## 1) ⚠️ ملاحظة حرجة: حالة الميزات تختلف باختلاف الباك إند
+
+هذه أهم نقطة في الملف، ولها أثر مباشر على القرار في `docs/34`:
+
+| الوحدة | حالتها في **NestJS** (docs/27) | حالتها في **سيرو PHP** (مقروءة من الكود 2026-07-24) |
+|---|---|---|
+| استخبارات التسعير | ⬜ لم تُبنَ (L4) | ✅ **محرّك TypeScript كامل** — `backend/pricing-engine/` |
+| محرّك التسويق | ⬜ (O3/O4) | ✅ `marketing_engine/` + `socialBot` + مولّد تعليقات Gemini |
+| الخريطة الحرارية | ⬜ (O1) | ✅ `bot/cron_generate_heatmap_cache.php` |
+| الطلب التنبؤي | ⬜ (O1) | ✅ `bot/cron_predictive_demand.php` |
+| منصة نبيه (واتساب) | 🔵 OTP فقط | ✅ `nabeh/` — 8 نقاط نهاية (شكاوى، وثائق، دفع، حالة سائق) |
+| المواصلات | 🔵 microservice + لوحة | ✅ `transit/` كامل + لوحة + كرونات تنبيه |
+| تأمين السائق | ⬜ مؤجَّلة | ✅ `driver_assurance/` |
+| التلعيب (Gamification) | ⬜ غير مذكورة أصلاً | ✅ `ride/gamification/` — تحديات، لوحة صدارة، streak، إحالات |
+
+**الخلاصة الصادقة:** الميزات التي تريد بيعها كوحدات مدفوعة — **موجودة في سيرو، وغير موجودة في NestJS.** هذه ليست حجة عاطفية لصالح سيرو، بل حجة تجارية: كل وحدة مبنية = منتج يمكن بيعه الشهر القادم بدل الربع القادم.
+
+---
+
+## 2) الوحدات السبع المقترحة (التحزيم التسويقي)
+
+### النواة — في كل باقة، غير قابلة للإزالة
+طلب رحلة · فئات سيارات · تعرفة كاملة · OTP · تتبّع حيّ · كاش · محفظة · تقييم · دردشة · إشعارات · لوحة تحكم · Dispatch.
+
+---
+
+### ① حزمة الذكاء الاصطناعي — «AI Suite»
+**الاسم التسويقي:** «موظفك الذي لا ينام»
+
+| المكوّن | الحالة (سيرو) |
+|---|---|
+| معالجة وثائق السائق (استخراج + مطابقة وجه) | ✅ |
+| تدقيق الشكاوى آلياً | ✅ (`nabeh/submit_complaint`) |
+| تسوية المدفوعات من رسائل SMS الخام عبر Gemini | ✅ |
+| مستشار تشغيلي أسبوعي (`cron_gemini_advisor`) | ✅ |
+| كشف الاحتيال (اتصال ثم إلغاء = صفقة خارج التطبيق) | ✅ |
+
+**السعر المقترح:** **$149/شهر** · إعداد $0
+**الحجة البيعية:** «سائق واحد وثائقه مزوّرة يكلّفك قضية. المراجعة اليدوية لـ200 سائق = موظف بدوام كامل.»
+
+---
+
+### ② استخبارات التسعير — «Pricing Intelligence» 🔥
+**الاسم التسويقي:** «اعرف كيف يسعّر منافسك — قبل أن يعرف هو»
+
+هذه **أقوى وحدة تملكها، وأكثرها تمايزاً على الإطلاق.** لا توجد منصة white-label في العالم تبيع هذا.
+
+| المكوّن | الحالة |
+|---|---|
+| جمع أسعار المنافسين (`scraped_competitor_prices`) | ✅ |
+| كشف الشواذ إحصائياً (MAD) | ✅ |
+| تجميع الفئات (K-Means على السعر/كم) | ✅ |
+| **انحدار خطي متعدد يستخرج معادلة تسعير المنافس** (`competitor_secret_formulas`) | ✅ |
+| كشف الحد الأدنى للأجرة عند المنافس | ✅ |
+| تحليل الـsurge والمناطق | ✅ |
+| ضبط سعرك آلياً بناءً على النتيجة (`cron_ai_engine` + `kazan_adjuster` + `pricing_stability`) | ✅ |
+| التسعير الموسمي | ✅ (`cron_seasonal_pricing`) |
+
+**السعر المقترح:** **$249/شهر** · إعداد $1,000 (يشمل ضبط السوق المحلي)
+**الحجة البيعية:** «تغيير 5% في سعرك يغيّر أرباحك 30%. هذه الوحدة تقرّر الـ5% بالبيانات لا بالحدس.»
+**تحذير قانوني يجب حسمه:** جمع أسعار المنافسين آلياً قد يخالف شروط استخدام تطبيقاتهم في بعض الولايات القضائية. **صِغ الوصف التسويقي حول "استخبارات السوق" لا حول "كشط تطبيق منافس بالاسم"**، واستشر محامياً قبل إبراز الوحدة في سوق خليجي/أوروبي.
+
+---
+
+### ③ حزمة النمو — «Growth Suite»
+**الاسم التسويقي:** «حرّك ركابك النائمين»
+
+| المكوّن | الحالة |
+|---|---|
+| حملات واتساب عبر منصة نبيه | ✅ القناة مبنية |
+| بوت نبيه (استعلام رحلات، شكاوى، وثائق، دفع) | ✅ |
+| إعادة تنشيط الركاب الخاملين | ✅ (`cron_passenger_reengagement`) |
+| دفع تسويقي آلي | ✅ (`cron_auto_marketing_pusher`) |
+| بوتات اجتماعية + مولّد تعليقات Gemini | ✅ |
+| كوبونات + برومو مستهدف بالمنطقة (Geofence) | ✅ |
+| التلعيب: تحديات، صدارة، streak، إحالات | ✅ |
+
+**السعر المقترح:** **$129/شهر** + رسوم الرسائل بالتمرير (pass-through)
+**الحجة البيعية:** «راكب عاد بعد شهرين أرخص عشر مرات من راكب جديد.»
+
+---
+
+### ④ المواصلات العامة — «Transit»
+**الاسم التسويقي:** «الباصات على نفس المنصة»
+
+خطوط · مواقيت · تتبّع مباشر للباص · تسجيل ركاب/مشتركين · تنبيه اقتراب · لوحة مشرف · بث للمجموعات. ✅ مبنية.
+
+**السعر المقترح:** **$299/شهر** · إعداد **$2,500**
+**لماذا منفصلة:** جمهورها مختلف كلياً — **بلديات، جامعات، شركات نقل موظفين، مدارس**. تُباع كـ*منتج قائم بذاته* بقمع بيع مستقل، لا كإضافة صغيرة.
+
+---
+
+### ⑤ ذكاء الأسطول — «Fleet Intelligence»
+الخريطة الحرارية للسائق ✅ · الطلب التنبؤي ✅ · لقطة لوحة يومية ✅ · تقرير صحة أسبوعي ✅ · تتبّع متقدّم ✅ · سلوك السائق ✅ · شرائح السائقين ⬜
+
+**السعر المقترح:** **$99/شهر**
+**الحجة البيعية:** «سائقوك يقفون في المكان الخطأ. الخريطة تقول لهم أين يقفون قبل أن يبدأ الطلب.»
+
+---
+
+### ⑥ حزمة المدفوعات — «Payments+»
+PayMob ✅ · CliQ · MTN/سيرياتيل كاش · شام كاش · كازان · تسوية SMS ✅ · محفظة ✅ · طلبات السحب
+
+**السعر المقترح:** **$99/شهر** + رسم لكل معاملة
+**الحجة البيعية:** «كل بوابة دفع محلية جديدة = تكامل من شهرين. عندنا محوّل جاهز.»
+> ⛔ **بوابة إلزامية:** لا تُباع هذه الوحدة قبل إصلاح عيوب المال في `docs/21` (ثغرة IDOR في السحب · لا حجز رصيد · رسم 3500 متناقض · المال مخزّن `varchar(10)`). بيع وحدة مالية معطوبة لمشغّل آخر = مسؤولية قانونية مباشرة عليك.
+
+---
+
+### ⑦ الأمان والامتثال — «Trust & Safety»
+التسجيل الصوتي داخل الرحلة ⬜ · كشف الاحتيال ✅ · تأمين السائق ✅ · زر الطوارئ · تقارير المنظّم
+
+**السعر المقترح:** **$79/شهر**
+**ملاحظة قانونية:** التسجيل الصوتي يستوجب إشعاراً وإقراراً من الطرفين + سياسة احتفاظ/حذف صريحة. **لا يُعلَن قبل حسم الغطاء القانوني في كل دولة.**
+
+---
+
+### 🟡 بند مفتوح — «سوق الركاب»
+ذكره المالك ولم يتضح المقصود. الاحتمالان:
+1. **وضع المزايدة/التفاوض** (نمط inDrive: الراكب يعرض سعراً والسائقون يزايدون) — يقابل `negotiator` في docs/27، **مؤجَّل بقرار سابق ولم يُبنَ**.
+2. **مشواري** — موجود فعلاً في سيرو (`ride/mishwari/`): حجز مسبق لسائق محدد بوقت محدد.
+
+**مطلوب توضيح من المالك قبل وضعه على الموقع.** إن كان الأول: هو وحدة قوية جداً في أسواق حساسة للسعر (سوريا/مصر) وتستحق $99/شهر — لكنها **لم تُبنَ بعد** وتُعلن كـ«على خارطة الطريق».
+
+---
+
+## 3) الباقات — كيف تُركَّب الوحدات فوق النواة
+
+| | انطلاقة | علامة ⭐ | أسطول+ | سيادة |
+|---|---|---|---|---|
+| النواة | ✅ | ✅ | ✅ | ✅ |
+| وحدات مشمولة | — | **1 بالاختيار** | **3 بالاختيار** | **الكل** |
+| باقي الوحدات | بسعرها | خصم 15% | خصم 25% | مشمولة |
+| المواصلات | إضافة منفصلة | إضافة منفصلة | إضافة منفصلة | مشمولة |
+
+**لماذا «بالاختيار» لا «محدّدة سلفاً»:** يجعل العميل يبني باقته بنفسه → التزام نفسي أعلى، ويكشف لك **أي وحدة يطلبها الناس فعلاً** — أثمن بيانات تسويقية ستحصل عليها.
+
+---
+
+## 4) كيف تُعرض على الموقع
+
+### 4.1 قسم جديد `#modules` بين «المنتج» و«التسعير»
+
+- عنوان: **«منصة قابلة للتركيب — خذ ما تحتاجه فقط»**
+- شبكة 7 بطاقات (2×4 على الديسكتوب، عمود على الجوال)
+- كل بطاقة: أيقونة SVG بألوان الهوية · الاسم · جملة واحدة · **السعر** · **شارة حالة**
+- شارات الحالة (نظام لونين لا أكثر):
+  - 🔵 **متاح الآن** — أزرق `--brand-500`
+  - ⚪ **قريباً · الربع القادم** — رمادي بحد منقّط
+
+> **قاعدة أخلاقية وقانونية غير قابلة للتفاوض:** لا تُعرض ميزة كـ«متاحة» إن لم تكن تعمل فعلاً في نسخة إنتاج. مشغّل دفع $5,000 على وعد وحدة غير موجودة = دعوى قضائية ودراسة حالة سلبية تقتل القمع كله. الشارة الرمادية **تصنع شوقاً** وتحميك في آن واحد.
+
+### 4.2 ربط الحاسبة بالوحدات
+أضف لقسم الحاسبة صف **«أضف وحدات»** بمربعات اختيار — يُحدَّث المجموع الشهري فوراً. هذا:
+- يرفع متوسط قيمة الصفقة المتصوّرة قبل أول مكالمة
+- يُرسل مع رسالة الواتساب **قائمة الوحدات التي اختارها** → مندوب المبيعات يبدأ من عرض شبه جاهز
+
+### 4.3 صفحة لكل وحدة (لاحقاً — مهم للـSEO)
+`/modules/pricing-intelligence` وأخواتها. كل صفحة: المشكلة → كيف تعمل → لقطة حقيقية → السعر → CTA.
+**هذه صفحات الهبوط لإعلانات إعادة الاستهداف في docs/32 §2.4.**
+
+---
+
+## 5) خطوات التنفيذ بالترتيب
+
+1. ✅ توثيق الوحدات (هذا الملف)
+2. ⬜ **قرار المالك:** تثبيت الأسعار السبعة + توضيح «سوق الركاب»
+3. ⬜ **جرد صدق:** لكل وحدة — هل تعمل في إنتاج سيرو *اليوم*؟ الشارة تُبنى على هذه الإجابة حصراً
+4. ⬜ بناء قسم `#modules` بأربع لغات (~60 مفتاح ترجمة)
+5. ⬜ ربط مربعات الوحدات بالحاسبة ورسالة الواتساب
+6. ⬜ إعلانات الوحدات (docs/32 §2.4) لإعادة الاستهداف
+7. ⬜ صفحات الوحدات المستقلة للـSEO
+8. ⬜ جدول `feature_catalog` في الباك إند (N6) + الاستحقاقات (`FeatureGuard`) — **الحدّ الأمني يبقى السيرفر دائماً** (docs/19)
+
+---
+
+## سجل التغييرات
+
+| التاريخ | التغيير |
+|---|---|
+| 2026-07-24 | إنشاء الملف — 7 وحدات، تسعيرها، تحزيمها، عرضها على الموقع + جرد حالتها الفعلية في سيرو مقابل NestJS |