Update: 2026-06-21 18:58:05

competitors_and_marketing/marketing_integration_plan_ar.md

@@ -0,0 +1,291 @@
+<div dir="rtl" align="right">
+
+# خطة عمل: دمج مقارنة الأسعار مع النظام التسويقي للركاب وتكامل الذكاء الاصطناعي (Siro AI)
+
+تحدد هذه الخطة البنية البرمجية والتسويقية لربط بيانات أسعار المنافسين التي يجمعها البوت بقاعدة البيانات، وتفعيل تحليلات متقدمة عبر الذكاء الاصطناعي (Gemini AI)، لتوجيه الحملات الترويجية التلقائية والتحكم في لوحة الإدارة بالتسعير عبر دول متعددة (سوريا، الأردن، مصر، العراق).
+
+---
+
+## 1. هيكلية قاعدة البيانات وتعدد الدول (Multi-Country GIS Database)
+
+يخدم تطبيق Siro عدة دول ومناطق جغرافية، لذا يتطلب فصل القراءات وتحليلها حسب حقل الدولة.
+
+تم تحديث وتعديل الجداول لتشمل ترميز الدولة كالتالي:
+
+</div>
+
+```sql
+-- جدول قراءات أسعار المنافسين
+CREATE TABLE `competitor_prices` (
+  `id` int NOT NULL AUTO_INCREMENT,
+  `competitor_name` varchar(50) NOT NULL,
+  `from_latitude` varchar(30) NOT NULL,
+  `from_longitude` varchar(30) NOT NULL,
+  `to_latitude` varchar(30) NOT NULL,
+  `to_longitude` varchar(30) NOT NULL,
+  `distance_km` decimal(8,2) NOT NULL,
+  `total_price` decimal(10,2) NOT NULL,
+  `price_per_km` decimal(8,2) NOT NULL,
+  `country_code` varchar(5) NOT NULL DEFAULT 'SY',
+  `created_at` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (`id`),
+  KEY `idx_competitor_country` (`competitor_name`, `country_code`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+-- جدول تواجد الركاب الجغرافي
+CREATE TABLE `passenger_opening_locations` (
+  `id` int NOT NULL AUTO_INCREMENT,
+  `passenger_id` varchar(100) NOT NULL,
+  `latitude` varchar(30) NOT NULL,
+  `longitude` varchar(30) NOT NULL,
+  `country_code` varchar(5) NOT NULL DEFAULT 'SY',
+  `created_at` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  `location_point` point NOT NULL /*!80003 SRID 4326 */,
+  PRIMARY KEY (`id`),
+  KEY `idx_passenger_id` (`passenger_id`),
+  KEY `idx_country` (`country_code`),
+  SPATIAL KEY `idx_location_point` (`location_point`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+```
+
+<div dir="rtl" align="right">
+
+---
+
+## 2. الأفكار الثورية الستة عشر لاستغلال البيانات (16 Revolutionary Use Cases)
+
+تم تقسيم الأفكار إلى ست تصنيفات لتغطية التسعير، التسويق، الكباتن، الإدارة، والمستقبل:
+
+### أ. التسعير الذكي (Smart Pricing)
+
+1. **التسعير التلقائي المتكيف (Auto-Adaptive Pricing)**:
+   يقوم النظام بحساب السعر المقترح تلقائياً لرحلات Siro ليكون أرخص بنسبة محددة (مثل 5-10%) من المنافس الأقرب في المنطقة فوراً، مع حماية هامش الربح الأدنى.
+
+2. **مؤشر فرصة الذروة (Surge Opportunity Index)**:
+   عند قيام جميع المنافسين بتفعيل تسعير الذروة (Surge) في منطقة جغرافية معينة، يتم تنبيه لوحة الإدارة لزيادة سعر Siro بنسبة طفيفة للاستفادة من الطلب المرتفع مع البقاء كخيار أوفر للركاب.
+
+3. **محاكي التسعير الافتراضي (What-If Pricing Simulator)**:
+   أداة ذكية للمدير لاختبار تأثير خفض أو رفع الأسعار بمعدلات معينة على حجم الطلبات المتوقع بناءً على سلوك المنافسين التاريخي.
+
+### ب. ذكاء الأعمال والتحليلات (Business Intelligence)
+
+4. **تقرير صحة السوق التلقائي (Weekly Market Health Report)**:
+   تصدير ملف تحليلي يوضح للادارة نسبة تنافسية Siro السعرية مقارنة بكل شركة منافسة في كل دولة بشكل أسبوعي.
+
+5. **خريطة فجوة الأسعار الجغرافية (Price Gap Heatmap)**:
+   خريطة حرارية تفاعلية تعرض في أي الأحياء أو المحافظات يتسع فارق الأسعار لصالحنا أو لصالح المنافسين لتوجيه الدعم المالي.
+
+6. **مؤشر التنافسية السعري (Pricing Competitiveness Index - PCI)**:
+   معامل رقمي يتم احتسابه ديناميكياً لكل منطقة لتحديد مدى جاذبية أسعارنا للركاب مقارنة بالبدائل المتاحة.
+
+### ج. التسويق والاستهداف الذكي للركاب (Marketing & Passenger Targeting)
+
+7. **استعادة الركاب المنقطعين (Win-Back for Churned Passengers)**:
+   استهداف الركاب الذين لم يطلبوا رحلات منذ فترة طويلة برسائل ترويجية لحظية (SMS / WhatsApp) في الأوقات التي ترتفع فيها أسعار المنافسين بشكل جنوني في مناطقهم الحالية.
+
+8. **العروض الترويجية الديناميكية المحددة جغرافياً (Hyper-Targeted Dynamic Promos)**:
+   إنشاء كوبونات خصم مؤقتة وتلقائية وتوجيهها للركاب في الأحياء التي يكتشف البوت أن المنافسين يقدمون فيها أسعاراً منافسة جداً لاستعادة الحصة السوقية.
+
+9. **استهداف المواقع الحساسة للأسعار (Price-Sensitive Hotspot Campaigns)**:
+   توجيه عروض خاصة للمستخدمين المتواجدين في الجامعات، مراكز التسوق الكبرى، والأسواق الشعبية عند رصد زيادة سعرية للمنافسين هناك.
+
+### د. إدارة الكباتن (Captain Management)
+
+10. **توجيه الكباتن الذكي (Captain Heatmaps & Guidance)**:
+    إرسال إشعارات فورية للكباتن تفيد بوجود طلب هائل وأسعار ذروة لدى المنافسين في منطقة مجاورة (مثال: المزة في دمشق) لتشجيعهم على التوجه إليها لخدمة ركاب Siro.
+
+11. **تعديل عمولة كازان المرن (Flexible Kazan Commission adjusting)**:
+    خفض نسبة عمولة Siro المقتطعة من السائق (عمولة كازان) تلقائياً في المناطق ذات التنافسية العالية لجذب المزيد من الكباتن وزيادة سرعة قبول الرحلات.
+
+12. **حوافز السائقين المرتبطة بالذروة المنافسة (Surge-Based Incentives)**:
+    منح السائقين مكافآت إضافية (Bonuses) عند قبول رحلات من مناطق تشهد ذروة سعرية لدى الشركات الأخرى لمنع تسرب الكباتن للعمل معهم.
+
+### هـ. تحليلات ودعم المستثمرين (Investor Analytics)
+
+13. **تحليلات الحصة السوقية السعرية (Pricing Market Share Analytics)**:
+    مؤشر بياني يثبت للمستثمرين النسبة المئوية من اليوم أو المناطق التي يعتبر فيها Siro هو الأرخص على الإطلاق في السوق مقارنة بالمنافسين.
+
+### و. الذكاء الاصطناعي والأفكار المتقدمة (Advanced & Future AI)
+
+14. **التنبؤ بأسعار المنافسين (AI Price Prediction)**:
+    استخدام خوارزميات التعلم لتوقع فترات وأسعار ذروة المنافسين خلال الساعات القادمة بناءً على البيانات التاريخية والاستعداد لها تسعيرياً.
+
+15. **التسعير الموسمي والمناسبات (Seasonal Pricing Logic)**:
+    ضبط قواعد التسعير ديناميكياً لتلائم المواسم (مثل فترة ما قبل الإفطار في رمضان، الأعياد الرسمية، والظروف الجوية السيئة).
+
+16. **مقارنة جودة الخدمة الشاملة (Service Quality ETA Benchmark)**:
+    إضافة فحص وقت الوصول المتوقع (ETA) إلى جانب السعر في البوت، لمقارنة سرعة الاستجابة السعرية والخدمية معاً.
+
+---
+
+## 3. التكامل البرمجي مع ذكاء اصطناعي Gemini AI (Gemini Backend Integration)
+
+يتصل خادم Siro بالذكاء الاصطناعي عبر دالة مخصصة لتحليل شواذ الأسعار (Anomalies) وصياغة الرسائل الترويجية المناسبة للهجة المحلية لكل دولة.
+
+### أ. الهيكل البرمجي الموصى به للفئة (SiroGeminiService):
+
+تم تصميم الكود بلغة PHP ليتكامل مع مفتاح API المخزن في السيرفر:
+
+</div>
+
+```php
+<?php
+
+class SiroGeminiService {
+    private $apiKey;
+    private $apiUrl;
+
+    public function __construct() {
+        $this->apiKey = getenv('GEMINI_API_KEY');
+        if (!$this->apiKey) {
+            error_log("CRITICAL: GEMINI_API_KEY environment variable is not set.");
+        }
+        // استخدام النموذج المعتمد في السيرفر
+        $this->apiUrl = "https://generativelanguage.googleapis.com/v1beta/models/gemini-flash-lite-latest:generateContent?key=" . $this->apiKey;
+    }
+
+    /**
+     * إرسال طلب إلى Gemini لتحليل التنافسية وطلب توصيات وصياغة رسالة تسويقية
+     */
+    public function analyzeMarketAndDraftCampaign($competitorPrices, $siroBasePrice, $regionName, $countryCode) {
+        if (!$this->apiKey) {
+            return false;
+        }
+
+        // تحديد اللهجة المحلية بناءً على رمز الدولة
+        $dialect = 'الفصحى المبسطة';
+        if ($countryCode === 'SY') {
+            $dialect = 'اللهجة السورية المحلية العامية البسيطة والودية';
+        } elseif ($countryCode === 'JO') {
+            $dialect = 'اللهجة الأردنية المحلية العامية';
+        } elseif ($countryCode === 'EG') {
+            $dialect = 'اللهجة المصرية الشعبية الودية';
+        } elseif ($countryCode === 'IQ') {
+            $dialect = 'اللهجة العراقية العامية اللطيفة';
+        }
+
+        $prompt = "
+أنت المحلل الذكي لتطبيق Siro لخدمات نقل الركاب. قمنا برصد قراءات أسعار المنافسين التالية في منطقة ($regionName):
+" . json_encode($competitorPrices, JSON_UNESCAPED_UNICODE) . "
+
+السعر الأساسي الحالي لتطبيقنا Siro في هذه الرحلة هو: $siroBasePrice.
+
+المطلوب منك تنفيذ المهام التالية بدقة:
+1. تحليل الفارق السعري وتحديد إن كان هناك فرصة تسويقية (عندما يرتفع سعر المنافس بشكل ملحوظ عن Siro).
+2. اقتراح التعديل السعري الأمثل لـ Siro (إن لزم الأمر) لزيادة الربح مع البقاء أرخص من المنافسين.
+3. كتابة نص ترويجي جذاب وقصير جداً لإرساله للركاب عبر WhatsApp أو SMS، على أن تكون لغة الرسالة بـ ($dialect)، تركز على التوفير وتذكر اسم المنطقة ($regionName)، وتدعوهم لفتح تطبيق Siro فوراً لطلب الرحلة دون إضافة هاشتاغات أو إيموجيات مفرطة.
+
+أعد الرد بصيغة JSON فقط، بالهيكل التالي تماماً ودون أي نصوص خارج الـ JSON:
+{
+  \"opportunity_detected\": true/false,
+  \"analysis_reason\": \"سبب التحليل الفني\",
+  \"recommended_price\": 12500,
+  \"suggested_surge_multiplier\": 1.10,
+  \"draft_marketing_message\": \"نص الرسالة التسويقية المقترحة باللهجة المحددة\"
+}
+";
+
+        $payload = [
+            'contents' => [
+                ['parts' => [['text' => $prompt]]]
+            ]
+        ];
+
+        $ch = curl_init($this->apiUrl);
+        curl_setopt_array($ch, [
+            CURLOPT_RETURNTRANSFER => true,
+            CURLOPT_POST => true,
+            CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
+            CURLOPT_POSTFIELDS => json_encode($payload),
+            CURLOPT_TIMEOUT => 30
+        ]);
+
+        $response = curl_exec($ch);
+        if (curl_errno($ch)) {
+            error_log("Gemini API Error: " . curl_error($ch));
+            curl_close($ch);
+            return false;
+        }
+        curl_close($ch);
+
+        $data = json_decode($response, true);
+        $rawText = $data['candidates'][0]['content']['parts'][0]['text'] ?? '';
+        
+        // تنظيف وتجهيز الـ JSON من مخرجات النموذج
+        $cleanJson = trim(preg_replace('/```json|```/', '', $rawText));
+        return json_decode($cleanJson, true);
+    }
+}
+```
+
+<div dir="rtl" align="right">
+
+---
+
+## 4. تكامل لوحة تحكم المدير (Siro Admin Panel Integration)
+
+لمواكبة هذه القدرات التحليلية والذكية، يجب توفير واجهات الإدارة المناسبة لتفعيل ومراقبة التحليلات:
+
+### أ. لوحة تحليلات الأسعار والمنافسة (Pricing Intelligence Dashboard):
+1. **شريط اختيار الدولة (Dropdown Multi-Country Filter)**:
+   - قائمة منسدلة لاختيار الدولة الفعالة (سوريا، الأردن، مصر، العراق)، لتقوم الشاشات بتحديث الرسوم التوضيحية بناءً على رمز الدولة المختار.
+2. **الرسوم البيانية للمقارنة اللحظية والتاريخية**:
+   - مؤشر خطي (Line Chart) يوضح تقلبات أسعار Siro مقابل المنافسين على مدار الـ 24 ساعة الماضية، والـ 7 أيام الماضية.
+3. **خارطة توزيع الفجوات السعرية (Geospatial Heatmap)**:
+   - تمثيل جغرافي للمناطق الأكثر سخونة وتنافساً، وتلوينها بناءً على مؤشر التنافسية السعري (PCI).
+
+### ب. لوحة التحكم بالذكاء الاصطناعي (Gemini AI Configuration & Autopilot Settings):
+1. **لوحة ضبط التشغيل الآلي (Autopilot Status Toggle)**:
+   - خيار لتشغيل الحملات الذكية تلقائياً:
+     - **آلي بالكامل (Full Autopilot)**: يرسل الرسائل الترويجية فور رصد فرصة سعرية دون تدخل بشري.
+     - **شبه آلي (Semi-Autopilot / Approval Mode)**: يعرض الرسائل المكتوبة بواسطة Gemini في صندوق وارد المراجعة (Approval Queue)، ولا يتم إرسالها للركاب إلا بعد موافقة المدير.
+2. **تعديل نص التوجيه الأساسي (System Instruction / Prompt Editor)**:
+   - صندوق نصي يسمح للمدير بتعديل القواعد والنبرة التي يستخدمها Gemini لصياغة العروض والتحليلات.
+3. **مؤشر استهلاك الرموز والطلبات (API Usage & Cost Monitor)**:
+   - شاشة تعرض عدد الطلبات المرسلة لـ Gemini، والرموز المستهلكة (Tokens)، والتكلفة التقديرية لضمان الاستهلاك الأمثل لخدمات الذكاء الاصطناعي.
+
+### ج. مركز إرسال الحملات الترويجية (Campaign Dispatcher Center):
+- شاشة للمدير لاستعراض الركاب المستهدفين في منطقة جغرافية معينة قبل إرسال الرسائل عبر قنوات البث المعتمدة (WhatsApp Graph API أو SMS) وضمان الفلترة الدقيقة.
+
+---
+
+## 5. محرك استعلام فرز الركاب الجغرافي والزمني (Targeting SQL Queries)
+
+عندما يكتشف النظام فرصة سعرية في منطقة المزة بدمشق (إحداثيات مركزية: `33.5074, 36.2530`)، يتم فلترة واستهداف الركاب المتواجدين في محيط 2 كيلومتر والذين فتحوا التطبيق مؤخراً لإرسال التنبيه الفوري لهم:
+
+</div>
+
+```sql
+-- جلب الركاب المستهدفين في محيط منطقة الفرصة السعرية
+SELECT DISTINCT passenger_id 
+FROM passenger_opening_locations pol
+WHERE pol.country_code = 'SY'
+-- التأكد من تصفية آخر موقع تم تسجيله لكل راكب
+AND pol.id = (
+    SELECT MAX(id) 
+    FROM passenger_opening_locations 
+    WHERE passenger_id = pol.passenger_id
+)
+-- حساب المسافة الجغرافية (نصف قطر 2000 متر)
+AND ST_Distance_Sphere(pol.location_point, ST_PointFromText('POINT(36.2530 33.5074)', 4326)) <= 2000
+-- حصر التواجد خلال آخر 24 ساعة لضمان استهداف الفئات النشطة
+AND pol.created_at >= NOW() - INTERVAL 1 DAY;
+```
+
+<div dir="rtl" align="right">
+
+---
+
+## 6. خطة التحقق والاختبار (Verification & Evaluation Plan)
+
+تعتمد خطة فحص النظام على الخطوات التالية لضمان السلامة البرمجية والتحليلية:
+
+### أ. اختبار تكامل كود الذكاء الاصطناعي (Gemini Integration Test):
+- إنشاء نص برميجي تجريبي لتمرير عينات أسعار منافسين وهمية والتأكد من نجاح الاتصال واستقبال ملف الاستجابة (JSON) وتوافقه الكامل مع الحقول البرمجية المحددة.
+- التحقق من ملاءمة النصوص الترويجية المكتوبة بلهجات الدول المختلفة وصحتها لغوياً وتسويقياً.
+
+### ب. اختبار الواجهات البرمجية والتسويقية (Admin Dashboard Evaluation):
+- محاكاة قراءات أسعار في دولتين مختلفتين (سوريا والأردن) والتحقق من استجابة لوحة تحكم المدير للفلاتر الجغرافية وتحديث المؤشرات والرسوم فورياً بناءً على الدولة الفعالة.
+- اختبار وضع الموافقة المسبقة (Approval Mode) وتعديل صياغة الرسائل وحفظها قبل الإرسال الفعلي.
+
+</div>