# استراتيجية دمج الذكاء الاصطناعي — منصة ERP للمطاعم

> **النطاق:** `erp.sayedkhattab.com` — Node.js microservices · React admin panel · MySQL  
> **الجمهور:** فريق التطوير، الإدارة، وصناع القرار  
> **الحالة:** مسودة معتمدة للتنفيذ — يُحدَّث مع كل مرحلة  
> **مرجع البنية:** [DATABASE_ARCHITECTURE.md](./DATABASE_ARCHITECTURE.md)

---

## ١. الملخّص التنفيذي

نضيف **طبقة ذكاء** فوق ERP قائم — لا نظاماً منفصلاً. الطبقة:

- **وكيل واحد موجّه** (Orchestrator) يختار الأدوات ويصوغ الإجابات بالعربية
- **شبكة أدوات مؤمّنة** تستدعي منطق المنصة الموجود (مبيعات، مخزون، مشتريات، محاسبة…)
- **قاعدة حاكمة واحدة:** لا كتابة في الجداول المالية أو المخزنية الحساسة دون **تأكيد بشري**

### نوعان من الذكاء — جمهوران

| النوع | الجمهور | أمثلة |
|-------|---------|-------|
| **تحليلي** | المُلّاك والإدارة | فجوة التكلفة، تسرب الإيرادات، توقع المبيعات، إقفال شهري |
| **تشغيلي** | موظفو الفروع | إدخال فواتير المورد (QR/OCR)، مسودات PO، تسجيل هدر |

### القيمة المتوقعة

| الموديول | أعلى أثر | آلية |
|----------|----------|------|
| **المشتريات** | ↓ تكلفة + ↓ نفاد مخزون | توقع طلب، شذوذ أسعار، OCR فواتير |
| **المبيعات** | ↑ إيراد + ↑ تخطيط | كشف تسرب، توقع مبيعات، مطابقة منصات |
| **المالية** | ↑ امتثال + ↑ سرعة إقفال | ZATCA، قيود شاذة، إقفال شهري |
| **المخزون/الوصفات** | ↑ دقة تحليل | بوابة جاهزية، فجوة تكلفة |

---

## ٢. مبادئ التصميم (غير قابلة للتفاوض)

1. **الأداة تنفّذ — الوكيل يقرر:** الحسابات الثقيلة SQL؛ LLM للتفسير والصياغة فقط
2. **القراءة قبل الكتابة:** كل أداة كتابة = مسودة + workflow اعتماد موجود
3. **بوابة جاهزية قبل التحليل:** لا أرقام واثقة على بيانات ناقصة
4. **الهوية من الجلسة لا من النموذج:** `company_id` / `branch_id` / `user_id` تُحقن بعد اختيار الأداة
5. **RBAC كما هو:** كل أداة تخضع لـ `role_permissions` و `user_branches`
6. **قابلية تبديل المزوّد:** Gemini خلف واجهة `LLMProvider` — ليس ارتباطاً دائماً
7. **Pilot أولاً:** فرع واحد + أصناف خام مباشرة قبل التعميم على كل الشركة

### جداول محظورة على الكتابة التلقائية

| جدول | السبب |
|------|-------|
| `stock_ledger` | سجل تدقيقي — يُنشأ عبر `stock_entries` المعتمدة فقط |
| `journal_entries` / `journal_entry_lines` | GL — بعد اعتماد بشري |
| `tax_invoices` (إصدار/إرسال) | ZATCA — بعد مراجعة |

---

## ٣. القرارات المعمارية المحسومة

| # | القرار | البديل المرفوض | السبب |
|---|--------|----------------|-------|
| د-١ | **Gemini SDK** (`@google/genai`) في Node | Microsoft Agent Framework | المنصة Node؛ MAF على .NET — لغة ثانية وجسر زمني |
| د-٢ | **وكيل واحد** للإطلاق | شبكة وكلاء متعددة | بيانات موحّدة بـ `company_id` — لا مشكلة تشتّت |
| د-٣ | **أدوات كثيرة، وكلاء قليلون** | وكيل لكل دومين | أرخص، أأمن، أسهل تتبّعاً |
| د-٤ | **القنوات = مداخل** | وكيل لكل قناة | نفس الوكيل؛ الفرق أمني (الهوية) |
| د-٥ | **النص أولاً، الصوت لاحقاً** | صوت من الإطلاق | الصوت العربي طبقة إضافية — `voice-order` موجود لاحقاً |
| د-٦ | **تكامل خارجي محدود للإطلاق** | موردون/بنوك من البداية | داخلي أولاً؛ **استثناء:** التحقق ZATCA داخلي (QR + `tax_invoices`) |
| د-٧ | **بوابة جاهزية** قبل الفجوة | تحليل على كل البيانات | يحمي المنتج من أرقام كاذبة |
| د-٨ | **OCR يقترح ولا يحفظ** | حفظ تلقائي | خطأ رقم واحد يسمّم المخزون والتحليل |

### لماذا Gemini وليس MAF؟

- **لغة المنصة:** Node/TypeScript — Gemini «مواطن درجة أولى»
- **تعقيد الاحتياج:** orchestration بسيط + tools + عربية — لا multi-agent debate
- **إعادة الاستخدام:** `voice-order` يستخدم Gemini و `menu_synonyms` للمطابقة
- **متى يُعاد النظر:** هجرة إلى .NET، أو حاجة فعلية لتنسيق وكلاء معقّد

---

## ٤. البنية التقنية المقترحة

```
┌─────────────────────────────────────────────────────────────┐
│  panel/  —  AI Hub (Insights · Chat · Monitoring · Alerts)  │
└────────────────────────────┬────────────────────────────────┘
                             │ HTTPS + JWT
┌────────────────────────────▼────────────────────────────────┐
│  services/ai-assistant/  (خدمة جديدة)                       │
│  ├── POST /chat          — محادثة + tool calling            │
│  ├── GET  /insights      — تنبيهات مجدولة + فورية          │
│  ├── POST /invoice/scan  — QR/OCR → مسودة receipt           │
│  ├── GET  /readiness     — بوابة جاهزية الوصفات             │
│  └── lib/                                                   │
│      ├── orchestrator.js — وكيل واحد + LLMProvider          │
│      ├── toolRegistry.js — تعريف الأدوات + RBAC             │
│      ├── contextInjector.js — حقن company_id من JWT         │
│      └── tools/          — read · write-draft · validate    │
└────────────────────────────┬────────────────────────────────┘
                             │ createPool() — read-only افتراضي
     ┌───────────┬───────────┼───────────┬───────────┐
     ▼           ▼           ▼           ▼           ▼
  inventory    sales/      purchasing  accounting   hr
  waste        orders      marketing   loyalty      menu
```

### قاعدة بيانات AI (اختيارية — `DB_AI_NAME`)

| جدول | الغرض |
|------|-------|
| `ai_tool_calls` | audit: tool, params_hash, latency, tokens, user_id, company_id |
| `ai_suggestions` | insight, confidence, status (pending/accepted/dismissed) |
| `ai_readiness_snapshots` | لقطة جاهزية دورية per company/branch |
| `ai_invoice_scans` | OCR/QR raw + confidence + linked receipt draft |
| `ai_scheduled_jobs` | variance calc ليلي، forecast أسبوعي |
| `whatsapp_user_links` | رقم جوال ↔ user_id (مرحلة لاحقة) |

---

## ٥. دورة حياة المادة + حلقة القيمة

```mermaid
flowchart LR
    A["١ المورد<br/>purchasing"] --> B["٢ الاستلام<br/>receipts · stock"]
    B --> C["٣ التخزين<br/>inventory"]
    C --> D["٤ الاستهلاك<br/>recipes · waste"]
    D --> E["٥ المبيعات<br/>orders"]
    E --> F["٦ التحليل<br/>variance · alerts"]
    F -.-> A
    G["٧ المالية<br/>GL · ZATCA"] -.-> E
    G -.-> B
```

**ملاحظة:** المرحلة ٦ ثقيلة على كل الأصناف → **عامل خلفي مجدول** (ليلاً) منفصل عن المحادثة اللحظية.

---

## ٦. قدرات الذكاء حسب الموديول

### ٦.١ المشتريات (Purchasing)

| القدرة | الوصف | أدوات | مرحلة |
|--------|-------|-------|-------|
| **توقع الطلب** | مبيعات + وصفات + هدر + lead time → اقتراح كميات PO | `forecastPurchaseDemand`, `getLowStockItems` | ٢ |
| **شذوذ الأسعار** | مقارنة سعر السطر مع تاريخ المورد والمتوسط | `detectPriceAnomalies`, `getSupplierPrices` | ١ |
| **إدخال ذكي للفواتير** | QR ZATCA → OCR → مطابقة أصناف → مسودة receipt | `extractInvoiceQR`, `extractInvoiceOCR`, `matchSupplierItems` | ٢ب |
| **تقييم الموردين** | التزام، جودة، دقة فواتير، استقرار أسعار | `getSupplierScorecard` | ٣ |
| **مسودة PO** | اقتراح أمر شراء — اعتماد بشري إلزامي | `draftPurchaseOrder` | ٢ |

**حدود `draftPurchaseOrder`:**
- حد أقصى مبلغ configurable بدون موافقة مدير
- `supplier_id` من قائمة الشركة فقط — لا من النموذج
- لا إرسال للمورد تلقائياً

---

### ٦.٢ المبيعات و POS (Sales)

| القدرة | الوصف | أدوات | مرحلة |
|--------|-------|-------|-------|
| **توقع المبيعات** | يومي/أسبوعي per branch × order_type | `forecastSales`, `getDailySales` | ٢ |
| **تسرب الإيرادات** | طلبات غير مرحّلة، خصومات شاذة، كupon مشبوه | `getRevenueLeakageAlerts` | ١ |
| **فجوات ZATCA** | طلب مدفوع بدون `tax_invoice_id` | `getZatcaGaps` | ١ |
| **مطابقة المنصات** | `platform_invoices` vs `orders` المحلية | `getPlatformInvoiceMismatches` | ٢ |
| **ذكاء العملاء** | VIP، نائم، عالي القيمة | `getCustomerSegments` | ٣ |
| **Upsell** | اقتراحات combo من `order_items` | `getCrossSellSuggestions` | ٣ |
| **استعلام NLQ** | «قارن مبيعات الأسبوع» | `getDailySales`, `getSalesByItem` + LLM | ١ |

**تنبيهات Quick Win (مرحلة ١):**

| الأولوية | الشرط | المصدر |
|----------|-------|--------|
| 🔴 | `financial_status = pending` > 24h | `orders` |
| 🔴 | `payment_status = paid` بدون `tax_invoice_id` | `orders` |
| 🟡 | `discount_amount` > 3× متوسط الفرع | `orders` |
| 🟡 | `platform_invoices.status != synced` | `platform_invoices` |

---

### ٦.٣ المالية والمحاسبة (Accounting)

| القدرة | الوصف | أدوات | مرحلة |
|--------|---------|-------|-------|
| **مدقق ZATCA** | فحص قبل الإرسال: VAT, CR, hash chain | `validateZatcaInvoice` | ١ |
| **قيود شاذة** | غير متوازن، حساب غير معتاد، تكرار | `detectJournalAnomalies` | ٢ |
| **مساعد الإقفال** | checklist: فواتير، مخزون، رواتب، ZATCA | `getPeriodCloseChecklist` | ٢ |
| **توقع تدفق نقدي** | مبيعات + POs + payroll | `forecastCashFlow` | ٣ |
| **مطابقة VAT** | `tax_invoice_lines` vs GL vs POS | `getVatReconciliation` | ٢ |
| **استعلام مالي NLQ** | «هامش الربح لفرع X» | أدوات قراءة + LLM | ٢ |

**تعديل على د-٦:** التحقق ZATCA **داخلي** (قراءة QR + مقارنة `tax_invoices`) — لا تكامل خارجي API في المرحلة ١.

---

### ٦.٤ المخزون والوصفات (Inventory)

| القدرة | الوصف | أدوات | مرحلة |
|--------|-------|-------|-------|
| **بوابة الجاهزية** | تغطية وصفات المنتجات المباعة | `assessReadiness` | **أساس** |
| **فجوة التكلفة** | نظري vs فعلي − هدر | `calcCostVariance`, `getVarianceReasons` | ٢ |
| **ربط وصفة–قائمة** | `recipes.menu_product_id` ↔ `ocims_products` | `linkRecipeCoverage` | ١ |
| **أرصدة ومخاطر** | low stock، expiry قريب | `getStockLevels`, `getLowStockItems` | ١ |

---

### ٦.٥ الهدر والجودة (Waste · Quality)

| القدرة | الوصف | أدوات | مرحلة |
|--------|-------|-------|-------|
| **تقرير الهدر** | trends + تجاوز thresholds | `getWasteReport` | ١ |
| **مسودة هدر** | `waste_entries` draft | `logWasteDraft` | ٢ |
| **جودة + فجوة** | ربط inspections/temp logs بالفجوة | `getQualityAlerts` | ٣ |

---

### ٦.٦ الموارد البشرية (HR) — مرحلة ٣

| القدرة | الوصف |
|--------|-------|
| **تخطيط شifts** | توقع مبيعات → اقتراح جدولة |
| **تنبيهات امتثال** | iqama، تأمين، qiwa — يُبنى على `hr_compliance_alert_log` |
| **WPS readiness** | قبل `payroll_runs` — IBAN ناقص، GOSI |

---

### ٦.٧ التسويق والولاء (Marketing · Loyalty) — مرحلة ٣

| القدرة | الوصف |
|--------|-------|
| **كupon abuse** | أنماط `marketing_redemptions` |
| **حملات مستهدفة** | `getCustomerSegments` + loyalty tiers |

---

## ٧. سجل الأدوات الموحّد (Tool Registry)

### ٧.١ أدوات القراءة — `risk: read` (مرحلة ١)

| الأداة | الموديول | DB pools |
|--------|----------|----------|
| `assessReadiness` | Inventory/Menu | inventory, menu, orders |
| `getDailySales` | Sales | orders |
| `getSalesByItem` | Sales | orders |
| `getStockLevels` | Inventory | inventory |
| `getLowStockItems` | Inventory | inventory |
| `getWasteReport` | Waste | waste |
| `getSupplierPrices` | Purchasing | purchasing |
| `getRevenueLeakageAlerts` | Sales | orders, sales |
| `getZatcaGaps` | Finance | orders, accounting |
| `getUnpostedFinancialOrders` | Finance | orders |
| `linkRecipeCoverage` | Inventory/Menu | inventory, menu |
| `createNotification` | Platform | auth |

### ٧.٢ أدوات التحليل — `risk: compute` (مرحلة ٢)

| الأداة | الموديول |
|--------|----------|
| `calcCostVariance` | Inventory |
| `getVarianceReasons` | Inventory |
| `detectPriceAnomalies` | Purchasing |
| `forecastSales` | Sales |
| `forecastPurchaseDemand` | Purchasing + Inventory |
| `validateZatcaInvoice` | Accounting |
| `detectJournalAnomalies` | Accounting |
| `getPeriodCloseChecklist` | Multi |
| `getPlatformInvoiceMismatches` | Sales |
| `getVatReconciliation` | Accounting |

### ٧.٣ أدوات الكتابة — `risk: draft` (مرحلة ٢)

| الأداة | يكتب في | شرط |
|--------|---------|-----|
| `draftPurchaseOrder` | `purchase_orders` (draft) | اعتماد + حد مبلغ |
| `logWasteDraft` | `waste_entries` (draft) | workflow موجود |
| `createNotification` | `user_notifications` | إشعار فقط |

### ٧.٤ أدوات الإدخال الذكي — `risk: extract` (مرحلة ٢ب)

| الأداة | الترتيب |
|--------|---------|
| `extractInvoiceQR` | **أولاً** |
| `matchSupplierItems` | ثانياً — ي reuse `menu_synonyms` |
| `extractInvoiceOCR` | **أخيراً** — بعد ثقة المستخدم |

---

## ٨. بوابة الجاهزية (`assessReadiness`)

**المبدأ:** جودة التحليل = جودة الوصفات + الربط مع القائمة.

| الحالة | المعنى | المصير |
|--------|--------|--------|
| `READY` | وصفة سليمة، UOM متطابق، حجم كافٍ | يدخل `calcCostVariance` |
| `NEEDS_FIX` | كمية/UOM ناقص | قائمة إصلاح للعميل |
| `NO_RECIPE` | لا `recipes` مربوطة بـ `menu_product_id` | حملة إكمال وصفات |
| `EMPTY_RECIPE` | وصفة بلا مكوّنات | إصلاح |
| `DEFER_SEMI` | نصف مصنّع — يحتاج BOM explosion | مرحلة ٣ |
| `LOW_VOLUME` | مبيعات ضعيفة — ضجيج إحصائي | مستبعد من التنبيهات |

**رسالة منتج:** «وصفاتك تغطي 72% من مبيعاتك — أكمل الـ 28% لتكشف تسرّباً محتملاً.»

**حالة التنفيذ:** ⏳ spec جاهز — **يُبنى** في `services/ai-assistant/tools/assessReadiness.js`

---

## ٩. معادلة فجوة التكلفة

```
الفجوة غير المفسَّرة = (الاستهلاك الفعلي − الاستهلاك النظري) − الهدر المسجّل
```

| الطرف | المصدر |
|-------|--------|
| **النظري** | `order_items` × `recipe_ingredients` (منتجات `READY` فقط) |
| **الفعلي** | `stock_ledger` — رصيد أول + وارد − رصيد آخر |
| **المطروح** | `waste_entries` (posted) |

### تحذيرات هندسية (إلزامية)

1. **UOM:** تحويل كل الأطراف لوحدة أساس واحدة per item
2. **نصف المصنّع:** أجّل — ابدأ خام مباشر (دجاج، خبز، مشروبات)
3. **Cutoff:** نفس `posting_date` / timestamp للمبيعات والمخزون
4. **Per branch:** `branch_id` — لا company-wide في المرحلة ١
5. **Noise floor:** حد أدنى qty/value قبل التنبيه
6. **Pilot:** فرع واحد + 10–20 صنف خام قبل التعميم

### أسباب الفجوة (لـ `getVarianceReasons`)

الهدر · السرقة · أخطاء تحصيص · عدم التزام بالوصفة · انجراف أسعار الموردين

> **LLM لا يحسب.** SQL يحسب → LLM يرتّب بالأثر المالي ويصوغ عربياً.

---

## ١٠. تدفّق الإدخال الذكي للفواتير

```mermaid
flowchart TD
    A[صورة / QR] --> B{QR ZATCA?}
    B -->|نعم| C[extractInvoiceQR]
    B -->|لا| D[extractInvoiceOCR]
    C --> E[matchSupplierItems]
    D --> E
    E --> F[نموذج: أخضر/أصفر حسب الثقة]
    F --> G[تأكيد بشري]
    G --> H[purchase_receipts → stock_entries]
```

- **أخضر:** confidence ≥ 0.95 — مرّ سريع
- **أصفر:** مراجعة إلزامية للحقل
- **لا حفظ** قبل زر «اعتماد»

---

## ١١. الأمان والهوية

```mermaid
flowchart TD
    JWT[JWT / Session] --> INJ[Context Injector]
    WA[WhatsApp رقم] --> LINK[ربط رقم ↔ user]
    LINK --> INJ
    INJ --> AGENT[Orchestrator]
    AGENT --> TOOL[Tool + company_id من الجلسة]
    TOOL --> RBAC[role_permissions]
```

| # | قاعدة |
|---|-------|
| 1 | `company_id` من JWT — **never** من arguments النموذج |
| 2 | واتساب: رقم غير مربوط → رفض |
| 3 | واتساب: صلاحيات أضيق — لا كتابة مالية |
| 4 | كل tool call في `ai_tool_calls` |
| 5 | Rate limit per company (مثلاً 100 chat/hr) |
| 6 | Fallback: «تعذّر التحليل» — لا hallucinate أرقام |

---

## ١٢. واجهة المستخدم (Admin Panel)

توسيع `panel/src/config/aiActions.js`:

| شاشة | المحتوى |
|------|---------|
| **AI Insights** | بطاقات تنبيهات (تسرب، ZATCA، أسعار، low stock) |
| **AI Assistant** | محادثة + citations للأدوات المستخدمة |
| **AI Monitoring** | readiness %، variance trend، tool usage |
| **AI Reports** | PDF/export للفجوة، الموردين، الإقفال |
| **Invoice Scan** | رفع صورة → مسودة receipt |

---

## ١٣. خارطة التنفيذ

### المرحلة ٠ — أساس (أسبوع 1–2) ⏳

- [ ] `services/ai-assistant/` scaffold
- [ ] `LLMProvider` + `toolRegistry` + `contextInjector`
- [ ] `assessReadiness`
- [ ] DB: `ai_tool_calls`, `ai_suggestions`
- [ ] Gateway route + JWT middleware

### المرحلة ١ — قراءة + Quick Wins (أسبوع 3–6) ⏳

- [ ] أدوات: `getDailySales`, `getLowStockItems`, `getWasteReport`, `getRevenueLeakageAlerts`, `getZatcaGaps`
- [ ] `validateZatcaInvoice` (pre-check)
- [ ] `detectPriceAnomalies` (basic)
- [ ] Orchestrator + chat API
- [ ] Panel: AI Insights dashboard
- [ ] `linkRecipeCoverage` report

### المرحلة ٢ — تحليل + مسودات (أسبوع 7–12) ⏳

- [ ] `calcCostVariance` + worker ليلي
- [ ] `getVarianceReasons`, `forecastSales`, `forecastPurchaseDemand`
- [ ] `draftPurchaseOrder`, `logWasteDraft`
- [ ] `getPeriodCloseChecklist`, `getPlatformInvoiceMismatches`
- [ ] Panel: variance + close checklist

### المرحلة ٢ب — إدخال ذكي (أسبوع 10–14) ⏳

- [ ] `extractInvoiceQR` → `matchSupplierItems`
- [ ] Panel: Invoice Scan UI
- [ ] `extractInvoiceOCR` (بعد pilot QR)

### المرحلة ٣ — توسّع ⏳

- [ ] WhatsApp channel + `whatsapp_user_links`
- [ ] `getSupplierScorecard`, `forecastCashFlow`, HR shifts
- [ ] Voice re-use (نفس orchestrator)
- [ ] BOM explosion لـ `DEFER_SEMI`

---

## ١٤. ما لا نفعله (Anti-patterns)

| ❌ | لماذا |
|----|-------|
| ترحيل GL تلقائي | مسؤولية مالية — خطأ كارثي |
| PO تلقائي بدون سقف | مخاطرة مالية + مخزون |
| تعديل أسعار القائمة من AI | قرار تجاري — اقتراح فقط |
| OCR → save مباشرة | يسمّم `stock_ledger` |
| واتساب بصلاحيات كاملة | attack surface |
| تحليل فجوة بدون readiness | أرقام كاذبة بثقة |

---

## ١٥. Observability & Cost

| البند | التطبيق |
|-------|---------|
| **Logging** | `ai_tool_calls` — كل استدعاء |
| **Metrics** | latency p95, tokens/company, error rate |
| **Caching** | Gemini prompt caching للـ system prompt + tool defs |
| **Budget** | soft cap tokens/company/month → degrade to SQL-only insights |
| **Testing** | golden tests لـ `assessReadiness`, `calcCostVariance` — لا LLM في CI للحسابات |

---

## ١٦. قائمة التحقق قبل وعد العملاء

- [ ] نسبة `READY` على بيانات عميل حقيقي ≥ 60% قبل إطلاق الفجوة
- [ ] OCR على 20+ فاتورة سعودية حقيقية (خط عربي + أرقام هندية)
- [ ] تسعير Gemini + prompt caching من docs Google
- [ ] Pilot branch: variance manually validated vs Excel
- [ ] Pen test: محاولة حقن `company_id` عبر prompt
- [ ] RBAC: user بدون `accounting.read` لا يرى `getZatcaGaps`

---

## ١٧. المراجع الداخلية

| مستند | المحتوى |
|-------|---------|
| [DATABASE_ARCHITECTURE.md](./DATABASE_ARCHITECTURE.md) | جداول وقواعد البيانات |
| [new.md](../new.md) | مستند القرار المعماري الأصلي (صديقك) |
| `services/voice-order/` | Gemini + `menu_synonyms` — إعادة استخدام |
| `panel/src/config/aiActions.js` | placeholder UI hub |
| `docs/hr/04-HR_DATA_MODEL_SPEC.md` | HR — مرحلة ٣ |

---

## ١٨. سجل التغييرات

| التاريخ | التغيير |
|---------|---------|
| 2026-06-27 | دمج مقترح المعمارية + قدرات الموديولات (Purchasing/Sales/Finance) + مراجعة تقنية |

---

*هذا مستند حيّ. حدّث `[ ]` → `[x]` مع كل deliverable، و`⏳` → `✅` مع كل أداة مُنشرة.*