# دليل الـ Flows — StepController Reference

**الملف:** `engine/StepController.php`  
**عدد الـ Flows:** 9  
**المحرك:** StepController::startFlow(flowName, question, user)

---

## معمارية الـ Flows

```
Gateway → HARD GATE → StepController::startFlow()
               ↓
         [flow definition]
               ↓
         Step execution:
           type=question  → سؤال للمستخدم
           type=ai_answer → رد AI محدود
           type=match     → بحث عن مزود
           type=book      → حجز
           type=redirect  → توجيه لصفحة
               ↓
         flow_sessions (حفظ الحالة)
         flow_messages (سجل المحادثة)
```

---

## 1. medical_telemedicine_v1

**الخدمة:** الطب عن بعد  
**المحرك:** REAL (لا AI مباشرة)

```
المستخدم: "عندي ألم في المعدة"
     ↓
Step 1: triage
  → "هل الألم شديد أو متوسط أو خفيف؟"
     ↓
Step 2: specialty_select
  → "هل تريد طبيب باطنة أم جراح أم طوارئ؟"
     ↓
Step 3: provider_match
  → بحث عن أطباء متاحين (provider_list API)
  → عرض 3 خيارات مع التقييم والسعر
     ↓
Step 4: booking_confirm
  → اختيار الوقت + تأكيد الحجز
     ↓
Step 5: payment
  → فاتورة → دفع
     ↓
Step 6: consultation
  → جلسة الاستشارة (consultation_sessions)
     ↓
Step 7: followup (اختياري)
  → "هل تحسنت؟" بعد 24 ساعة
```

**قاعدة الطوارئ:**
```php
if (isEmergency($question)) {
    return [
        'answer' => '⚠️ اتصل بـ 999 فوراً',
        'source' => 'emergency_gate',
    ];
}
```

---

## 2. legal_consultation_v1

**الخدمة:** الاستشارات القانونية  
**المحرك:** REAL

```
Step 1: intake
  → "ما نوع المسألة القانونية؟"
  → [عقود | ميراث | طلاق | تجاري | عمالي | جنائي]

Step 2: jurisdiction
  → "في أي ولاية؟"

Step 3: urgency
  → "هل المسألة عاجلة؟"

Step 4: provider_match
  → بحث عن محامين متخصصين

Step 5: consultation
  → الاستشارة المباشرة
```

**القاعدة:** `لا رأي قانوني ملزم من AI — المحامي فقط`

---

## 3. service_booking_v1

**الخدمة:** حجز عام (مهندس، مزارع، إلخ)  
**المحرك:** AI_FIRST

```
Step 1: service_type → نوع الخدمة
Step 2: location     → الموقع
Step 3: match        → بحث وعرض مزودين
Step 4: confirm      → تأكيد
Step 5: pay          → دفع
Step 6: execute      → التنفيذ
```

---

## 4. business_consulting_v1

**الخدمة:** استشارات أعمال عامة  
**المحرك:** AI_FIRST

```
Step 1: business_type → نوع النشاط
Step 2: challenge     → التحدي الرئيسي
Step 3: ai_advice     → رد AI محدود (BDE focus)
Step 4: doc_offer     → عرض إصدار وثيقة مدفوعة
Step 5: book_expert   → حجز مستشار (اختياري)
```

---

## 5. corporate_solutions_v1

**الخدمة:** حلول الشركات B2B  
**المحرك:** REAL → redirect

```
Step 1: start
  → redirect → /app/corporate-solutions.php
  → 5-phase wizard (intake → analyze → proposal → submit)
  → Admin يتواصل (لا automated)
```

---

## 6. engineering_consulting_v1

```
Step 1: specialty → [مدني | كهربائي | ميكانيكي | معماري]
Step 2: project_type
Step 3: location
Step 4: match → مهندسون معتمدون
Step 5: quote → عرض سعر
Step 6: book
```

---

## 7. agriculture_consulting_v1

```
Step 1: region → [ولاية + نوع مناخ]
Step 2: crop_type → [زراعة | ثروة حيوانية | سمكية]
Step 3: issue → [آفات | ري | تربة | أسعار]
Step 4: ai_advice → (AI مسموح للزراعة)
Step 5: expert → خبير زراعي (اختياري)
```

---

## 8. family_support_v1

```
Step 1: concern_type → [طفل | حمل | علاقة | طلاق | ميراث]
Step 2: urgency
Step 3: route:
  صحة الطفل → medical_telemedicine_v1
  طلاق/ميراث → legal_consultation_v1
  دعم نفسي → mental domain
  استشارة منزلية → service_booking_v1
```

---

## 9. business_plan_v1

**الخدمة:** توليد خطة أعمال  
**المحرك:** AI + BDE

```
Step 1: sector → قطاع المشروع
Step 2: goals  → الأهداف
Step 3: market → السوق المستهدف
Step 4: financials → رأس المال + العائد المتوقع
Step 5: ai_generate → خطة أعمال كاملة (Claude/Gemini)
Step 6: export → PDF أو Word (مدفوع)
```

---

## جداول الـ Flow في DB

```sql
-- حالة الجلسة
flow_sessions:
  session_id, user_id, flow_name, current_step,
  context JSON, started_at, last_activity

-- سجل المحادثة
flow_messages:
  session_id, role (user|assistant|system),
  content, step_name, created_at
```

---

## إضافة Flow جديد

```php
// في StepController.php
'new_service_v1' => [
    'version'     => 'v1',
    'description' => 'وصف الخدمة',
    'steps' => [
        'start' => [
            'type'      => 'question',
            'prompt_ar' => 'السؤال الأول',
            'options'   => ['خيار 1', 'خيار 2'],
            'next'      => 'step_two',
        ],
        'step_two' => [
            'type' => 'match',
            'sector' => 'new_service',
            'next' => 'confirm',
        ],
    ],
],
```

```php
// في FlowEngine.php — ربط القطاع بالـ Flow
'new_service' => 'new_service_v1',
```
