# دليل المحركات — Engines Reference

## نظرة عامة على المعمارية

```
المستخدم/API
     ↓
┌────────────────────────────────────────────────┐
│              Gateway.php (HARD GATE)            │
│  نقطة الدخول الوحيدة — لا bypass مسموح         │
└──────┬──────────────┬──────────────────────────┘
       ↓              ↓
AssistantEngine   InferenceEngine
(14 domain)       (610 rules / 19 sector)
       ↓              ↓
BillingEngine ← PolicyEngine
       ↓
ProviderDecisionEngine
  REAL | AI_FIRST | AI
       ↓
StepController | AIClient
(9 flows)      (Gemini/Claude/OpenAI)
       ↓
FinancialAgent (double-entry ledger)
```

---

## 1. Gateway.php — نقطة الدخول الوحيدة

**الملف:** `engine/Gateway.php` | **الحجم:** ~879L

### الوظيفة
كل طلب في المنصة يمر عبر Gateway. لا يوجد أي مسار آخر للوصول للـ AI.

### التدفق الداخلي
```
handle(req) {
  1. detectService(question, ie_result) → sector
  2. AssistantEngine::route(question, ie, forceDomain) → domain + prompt
  3. PolicyEngine::evaluate(action, sector) → ALLOW | BLOCK
  4. BillingEngine::evaluate(userId, sector) → cost + hold
  5. ProviderDecisionEngine::decide(sector) → REAL | AI_FIRST | AI

  HARD GATE:
  if (REAL && sector ∈ [medical, legal, family, pharmacy, emergency]):
    → StepController::startFlow() [لا AI مباشرة]

  else if (AI_FIRST):
    → try StepController → fallback AI

  else (AI):
    → AIClient::ask() → response
}
```

### HARD GATE — القاعدة الذهبية
```php
// القطاعات التي تمنع الـ AI مطلقاً:
$hardGateSectors = ['medical','family','pharmacy','emergency','legal','business','bde'];
// → دائماً StepController → مزود حقيقي
```

### detectService() — كشف الخدمة من النص
```
المدخل: السؤال النصي + نتيجة InferenceEngine
المخرج: sector string

الأولوية:
  1. InferenceEngine result (إذا متاح)
  2. Regex patterns على النص
  3. Fallback: 'general'
```

---

## 2. AssistantEngine.php — 14 مساعد متخصص

**الملف:** `engine/AssistantEngine.php` | **الحجم:** ~305L

### الـ 14 Domain

| Domain | Sectors | Guard الأساسي |
|--------|---------|---------------|
| `hub` | platform, general, government | تنقل المنصة فقط |
| `medical` | medical, pharmacy, family, emergency | لا تشخيص — توجيه لطبيب |
| `legal` | legal | لا رأي ملزم — توجيه لمحامي |
| `finance` | finance, banking | معاملات SDG فقط |
| `education` | education, academic | محتوى تعليمي |
| `agriculture` | agriculture | السودان فقط |
| `mental` | mental | تعاطف — لا تشخيص |
| `career` | career | سوق العمل السوداني |
| `community` | community | خدمات محلية |
| `market` | market | بيع وشراء |
| `sales` | business, bde | وثائق تجارية |
| `developer` | developer, tech | API سودانا فقط |
| `investment` | finance | فرص الاستثمار السوداني |
| `enterprise` | enterprise | B2B فقط |

### قواعد الأمان الإضافية (safety_rules)
```
medical:
  • لا تشخيص أبداً
  • لا وصفات دوائية
  • طوارئ → 999 فوراً
  • دائماً: "راجع طبيباً"

mental:
  • لا تشخيص نفسي
  • أزمة → خط الدعم
  • تعاطف دون تعليق

legal:
  • لا رأي ملزم
  • دائماً: "استشر محامياً"
```

### route() — التوجيه الذكي
```php
route(question, ieResult, forceDomain=''):
  if forceDomain: use it (مثل developer.html)
  else:
    sector = ieResult['sector'] ?? 'general'
    domain = sectorToDomain(sector)
    
  → buildContext(domain, question, ieResult)
    return: { system_prompt, domain, guard, safety_rules }
```

---

## 3. InferenceEngine.php — 610 قاعدة استدلال

**الملف:** `engine/InferenceEngine.php` | **الحجم:** ~979L

### الوظيفة
تحليل السؤال بالنمط الهرمي وإرجاع: sector + intent + confidence.

### الـ 19 Sector
```
medical, legal, finance, education, agriculture,
mental, career, community, market, bde, pharmacy,
family, tech, business, developer, platform,
emergency, academic, investment
```

### بنية القاعدة
```php
$R[] = [
    'id'     => 'rule_id',
    'sector' => 'medical',
    'conf'   => 0.95,           // confidence 0-1
    'p'      => ['/regex/ui'],  // patterns
    'x'      => ['/exclusion/'] // استثناءات
];
```

### خوارزمية التشغيل
```
1. مرور على 610 قاعدة بالترتيب
2. كل قاعدة: regex match على السؤال
3. تجميع النتائج بـ weighted scoring
4. أعلى confidence → winner
5. إذا confidence < 0.3 → 'general'
```

---

## 4. BillingEngine.php — محرك الفوترة

**الملف:** `engine/BillingEngine.php` | **الحجم:** ~543L

### Hold Model (نموذج الحجز)
```
1. evaluate()   → تحقق الرصيد + حجز المبلغ (hold_balance)
2. [تنفيذ الخدمة]
3. commitFunds() → تحويل من hold إلى deducted
   OR
   rollbackFunds() → إلغاء الحجز عند الفشل
```

```sql
-- الجداول المستخدمة
wallet          (balance, hold_balance)
billing_reserves (hold references)
wallet_transactions (audit trail)
```

### checkAILimit() — حد الاستخدام اليومي
```php
$limits = ['free'=>20, 'plus'=>60, 'pro'=>200, 'corp'=>200];
// يقرأ من execution_log (COUNT today)
// يقارن بـ platform_settings إذا متاح
```

### getDocumentCost() — سعر الوثيقة
```php
getDocumentCost(userId, docType):
  1. جلب plan_key من users
  2. PricingEngine::getDocumentPrice(docType, planKey)
  3. فحص subscription_credits (أولاً)
  4. فحص wallet (ثانياً)
  return: { cost_sdg, can_afford, source, credit_id }
```

### chargeDocument() — خصم تكلفة الوثيقة
```
مصدر الخصم بالأولوية:
  1. subscription_credits (رصيد وثائق Plus/Pro الشهري)
  2. wallet balance
  3. رفض إذا لا رصيد
```

---

## 5. FinancialAgent.php — الوكيل المالي

**الملف:** `engine/FinancialAgent.php` | **الحجم:** ~464L | **SEALED 🔒**

### نموذج القيد المزدوج (Double-Entry)
```
كل معاملة = 4 قيود محاسبية:
  1. DR: حساب المستخدم (خصم)
  2. CR: حساب المزود (إيداع مبدئي)
  3. DR: حساب عمولة المنصة (10%)
  4. CR: حساب الإيرادات

الجداول: financial_ledger, financial_entries
```

### generateReceiptNo()
```
Format: SUD-{YEAR}{MONTH}-{6-digit-sequence}
مثال:  SUD-202604-001234
```

### commitFunds() — تأكيد الدفع (بعد التحقق)
```
beginTransaction()
  UPDATE wallet (deduct)
  INSERT ledger entries (4 entries)
  UPDATE billing_reserves (mark committed)
  INSERT payment_receipts
commit()
```

---

## 6. PolicyEngine.php — محرك السياسات

**الملف:** `engine/PolicyEngine.php` | **الحجم:** ~105L+**

### DSL: ALLOW | BLOCK
```php
PolicyEngine::evaluate('medical.ai_diagnosis', 'medical')
→ BLOCK (لا AI diagnosis مسموح)

PolicyEngine::evaluate('booking.create', 'medical')
→ ALLOW
```

### الـ 28 Case
```
pharmacy.suggest        followup.schedule      followup.recovery
usage.track             subscription.offer     provider.assign
provider.notify         provider.rate          billing.reserve
billing.commit          billing.rollback       medical.ai_diagnosis
medical.triage          legal.ai_advice        financial.transfer
ai.request              booking.create         admin.override
system.maintenance      notification.send      kyc.upgrade
corporate.intake        doc_issuance.paid      doc_issuance.credit_check
corporate.proposal_view suggestion.submit      suggestion.spam
suggestion.vote
```

### Hot Reload
```php
// السياسات تُقرَأ من policy_versions table
// Admin يُعدِّلها من admin.php → tab=policy_editor
// تُطبَّق فوراً بدون إعادة تشغيل
```

---

## 7. StepController.php — التحكم في الخطوات

**الملف:** `engine/StepController.php` | **الحجم:** ~967L+**

### الـ 9 Flows

| Flow | الخدمة | الخطوات |
|------|---------|---------|
| `medical_telemedicine_v1` | طب عن بعد | triage → specialty → book → consult → followup |
| `family_support_v1` | دعم الأسرة | intake → assess → route → support |
| `service_booking_v1` | حجز عام | search → select → confirm → pay → execute |
| `legal_consultation_v1` | قانوني | intake → area → urgency → match → consult |
| `business_consulting_v1` | أعمال | discover → analyze → plan → execute |
| `corporate_solutions_v1` | شركات | redirect → corporate-solutions.php |
| `engineering_consulting_v1` | هندسة | intake → spec → quote → execute |
| `agriculture_consulting_v1` | زراعة | region → crop → issue → advise |
| `business_plan_v1` | خطة أعمال | sector → goals → market → financials → output |

---

## 8. PricingEngine.php — محرك الأسعار

**الملف:** `engine/PricingEngine.php` | **الحجم:** ~305L**

### مبدأ التشغيل
```
Admin يُحدِّث platform_settings →
PricingEngine::flushCache() →
كل الصفحات تعكس الأسعار الجديدة فوراً
```

### getAll() — جميع الأسعار
```json
{
  "rate": 4100,
  "plans": {
    "plus": { "sdg": 20000, "doc_credit_sdg": 15000 },
    "pro":  { "sdg": 50000, "doc_credit_sdg": 50000 }
  },
  "documents": {
    "contract": { "free": 5000, "plus": 3500, "pro": 2000 }
  },
  "corporate": {
    "starter": { "usd": 99, "sdg": 405900 }
  }
}
```

### updateRate() — تحديث سعر الصرف
```php
updateRate(newRate=4200, adminId=1, note="تحديث أبريل"):
  1. UPDATE exchange_rates SET is_active=0
  2. INSERT exchange_rates (new rate, is_active=1)
  3. UPDATE platform_settings WHERE key='usd_to_sdg_rate'
  4. flushCache()
  return: { change_pct, alert: true if >5%, preview_prices }
```

---

## 9. CorporateAgent.php — محرك الشركات

**الملف:** `engine/CorporateAgent.php` | **الحجم:** ~220L**

### analyze() — تحليل طلب الشركة
```
المدخل: بيانات الـ 5 مراحل (org + challenges + services + tech + contact)
المخرج:
  monthly_usd, monthly_sdg
  setup_usd, setup_sdg
  year1_sdg (12 شهر + setup)
  roi_percent, breakeven_months
  recommended_package (starter|business|scale|custom)
```

### حساب التكلفة
```
base_cost = Σ(service.usd + service.per_user × users)
sla_multiplier = { standard:1.0, professional:1.3, enterprise:1.8 }
total_usd = base_cost × sla_multiplier
total_sdg = total_usd × current_exchange_rate
```

---

## 10. SuggestionsAgent.php — محرك المقترحات

**الملف:** `engine/SuggestionsAgent.php` | **الحجم:** ~273L**

### analyze() — تحليل الاقتراح
```
priority_score = (
  type_weight    × 0.40 +  // bug=0.9, improvement=0.7
  simplicity     × 0.25 +  // أقصر = أسهل = أعلى
  novelty        × 0.20 +  // مكرر؟ → 0.2
  votes_impact   × 0.15    // كل 100 صوت = +0.3
) × plan_multiplier         // pro=1.2, plus=1.1

priority_label:
  ≥ 0.80 → urgent
  ≥ 0.60 → high
  ≥ 0.40 → medium
  ≥ 0.20 → low
  duplicate detected → duplicate
```

### findSimilar() — كشف التكرار (Jaccard)
```python
jaccard(A, B) = |A ∩ B| / |A ∪ B|
# على keywords > 3 أحرف
# إذا similarity > 0.35 → potential duplicate
```

### awardPoints() — نقاط الإنجاز
```
suggestion_submitted  → +10 نقطة
suggestion_accepted   → +50 نقطة
suggestion_implemented → +200 نقطة
```

---

## ProviderDecisionEngine.php — قرار المزود

**الملف:** `engine/ProviderDecisionEngine.php` | **الحجم:** ~167L**

| القرار | المعنى | متى |
|--------|---------|-----|
| `REAL` | مزود حقيقي فقط | طب + قانون + طوارئ |
| `AI_FIRST` | AI أولاً، مزود عند الطلب | تعليم + زراعة |
| `AI` | AI فقط | عام + منصة + مطورين |

---

## FlowEngine.php — تعيين الـ Flows

```php
// Sector → Flow mapping
'medical'    → 'medical_telemedicine_v1'
'legal'      → 'legal_consultation_v1'
'enterprise' → 'corporate_solutions_v1'
// ...
```

---

## قواعد التعامل مع المحركات

```
⚠️  BillingEngine    → SEALED — لا تُعدِّل دون مراجعة
⚠️  FinancialAgent   → SEALED — double-entry لا يُلمَس
✅  PolicyEngine     → قابل للتعديل من admin.php
✅  PricingEngine    → يُحدَّث عبر platform_settings
✅  AssistantEngine  → domains قابلة للإضافة
```
