# مستند القرار المعماري — منصة وكلاء الذكاء لإدارة المطاعم

> وثيقة مرجعية للفريق. تلخّص ما حُسم في جلسة التصميم، والأسباب وراء كل قرار، والحدود الأمنية غير القابلة للتنازل.
> الحالة: **مسوّدة معتمَدة للبناء** — البنود المعلّمة بـ ⏳ لم تُبنَ بعد، رُسمت فقط.

---

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

نبني طبقة ذكاء فوق منصة ERP قائمة (Node.js، تعدّد مستأجرين بـ `company_id`، RBAC جاهز). الطبقة ليست شبكة وكلاء معقّدة، بل **وكيل واحد موجّه** فوق **شبكة أدوات مؤمّنة** تستدعي منطق المنصة الموجود.

المنصة تخدم **ذكاءين لجمهورين**:
- **ذكاء تحليلي** للمُلّاك والإدارة: كشف فجوة التكلفة، الهدر، التوصيات.
- **ذكاء تشغيلي** للموظفين: تسريع إدخال الفواتير عبر OCR/QR مع تأكيد بشري.

يجمعهما وكيل واحد، وطبقة هوية واحدة، وقاعدة حاكمة واحدة: **لا كتابة في الجداول الثابتة أو المالية دون تأكيد بشري.**

---

## ٢. القرارات المحسومة (سجلّ مختصر)

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

---

## ٣. لماذا Gemini لا MAF (تفصيل د-١)

القرار دالة على **لغة المنصة وتعقيد الاحتياج**، لا على «أيّهما أقوى»:

- **لغة المنصة:** المنصة Node. Gemini يدعم Node/TypeScript كـ«مواطن درجة أولى». MAF مستقر على C#/.NET — تبنّيه يعني خدمة منفصلة بلغة ثانية، فريق يعرف لغتين، نشر منفصل، وزمن استجابة إضافي على كل استدعاء.
- **تعقيد الاحتياج:** ما نبنيه = وكيل واحد + أدوات + صياغة عربية. MAF تتفوّق في التنسيق المعقّد (عدة وكلاء يتناقشون، مراحل متوازية تُجمَّع، إعادة تخطيط ديناميكية) — وهي مشاكل **لا نملكها**.
- **متى يُعاد النظر:** لو هاجرت المنصة إلى .NET، أو لو وصل تنسيق الوكلاء فعلاً إلى مستوى «عدة وكلاء يتناقشون ويُجمَّعون». عند ذلك تصبح primitives الـ MAF موفّرة للوقت.
- **حصانة الارتباط بمزوّد:** تُكتب طبقة الأدوات بحيث يكون استدعاء النموذج خلف واجهة بسيطة قابلة للتبديل، تحسّباً للمستقبل.

---

## ٤. دورة حياة المادة في المطعم

نقطة الحقيقة التي خرج منها عدد الأدوات والتكاملات. كل المراحل **داخل المنصة** — وهذه ميزتنا التنافسية.

```mermaid
flowchart LR
    A["١. المورّد والشراء<br/>suppliers · purchase_orders"] --> B["٢. الاستلام<br/>purchase_receipts · stock_entries"]
    B --> C["٣. التخزين<br/>warehouses · stock_ledger"]
    C --> D["٤. الاستهلاك<br/>recipes · waste_entries"]
    D --> E["٥. المبيعات<br/>orders · order_items"]
    E --> F["٦. التحليل والفجوة<br/>النظري ضد الفعلي"]
    F -.توصية.-> A

    style A fill:#E6F1FB,stroke:#185FA5,color:#042C53
    style B fill:#E6F1FB,stroke:#185FA5,color:#042C53
    style C fill:#E1F5EE,stroke:#0F6E56,color:#04342C
    style D fill:#E1F5EE,stroke:#0F6E56,color:#04342C
    style E fill:#FAECE7,stroke:#993C1D,color:#4A1B0C
    style F fill:#F1EFE8,stroke:#5F5E5A,color:#2C2C2A
```

**الخلاصة:** السلسلة كلها استعلام وتحليل وصياغة — لا نمطا تشغيل مختلفان يبرّران وكيلين. لذا وكيل واحد يكفي. الانقسام الوحيد المبرَّر مستقبلاً يخرج من المرحلة ٦: حساب الفجوة على **كل** الأصناف ثقيل، فيصير **عامل تحليل خلفي** مجدول (ليلاً) منفصلاً عن وكيل المحادثة اللحظي.

---

## ٥. شبكة الأدوات (تفصيل د-٣)

العدد الحقيقي. كل أداة مربوطة بمرحلة. التقسيم بالمخاطرة: القراءة أولاً (خطر صفر)، ثم المسودات.

### أدوات القراءة — ابدأ بها كلها (لا تكتب شيئاً)

| الأداة | المرحلة | الوظيفة | الحالة |
|--------|---------|---------|--------|
| `assessReadiness` | ٤ | بوابة جاهزية الوصفات + نسبة التغطية | ✅ مبنية |
| `calcCostVariance` | ٦ | معادلة الفجوة (نظري ضد فعلي) | ⏳ مرسومة |
| `getVarianceReasons` | ٦ | ربط الفجوة بأسبابها المحتملة | ⏳ |
| `getDailySales` | ٥ | ملخّص مبيعات اليوم | ⏳ |
| `getSalesByItem` | ٥ | مبيعات صنف معيّن | ⏳ |
| `getStockLevels` | ٣ | أرصدة المخزون الحالية | ⏳ |
| `getLowStockItems` | ٣ | أصناف تحت حد إعادة الطلب | ⏳ |
| `getWasteReport` | ٤ | تقرير الهدر المسجّل | ⏳ |
| `getSupplierPrices` | ١ | أسعار الموردين | ⏳ |

### أدوات الكتابة — المرحلة الثانية (مسودات قابلة للتراجع فقط)

| الأداة | المرحلة | تكتب في | ضمانة الأمان |
|--------|---------|---------|---------------|
| `draftPurchaseOrder` | ١ | مسودة PO | الإنسان يعتمد قبل الإرسال |
| `logWasteDraft` | ٤ | `waste_entries` (draft) | workflow اعتماد موجود |
| `createNotification` | ٦ | `user_notifications` | إشعار فقط، قابل للتجاهل |

### أدوات الإدخال الذكي — ⏳ المرحلة الثانية

| الأداة | الوظيفة | ملاحظة حرجة |
|--------|---------|--------------|
| `extractInvoiceQR` | قراءة QR المهيكل (ZATCA) | دقة عالية — **ابدأ به** |
| `extractInvoiceOCR` | OCR للصورة الحرة | يرفع درجة ثقة لكل حقل |
| `matchSupplierItems` | مطابقة أصناف المورّد بأصنافنا | مشكلة بحد ذاتها؛ قد تخدمها `menu_synonyms` |

> **قاعدة مطلقة:** لا أداة تكتب في `stock_ledger` أو `journal_entries`. هذان يبقيان بالكتابة المؤمّنة بعد تأكيد بشري دائماً.

---

## ٦. بوابة الجاهزية (تفصيل د-٧) — ✅ مبنية

المبدأ: **جودة المخرجات = جودة الوصفات، حصراً.** المعادلة لا تُطلق على الجميع، بل على من تسمح بياناته فقط.

تصنّف كل منتج مباع:

| الحالة | المعنى | المصير |
|--------|--------|--------|
| `READY` | وصفة سليمة، وحدات متطابقة، كمية ذات دلالة | يدخل حساب الفجوة |
| `NEEDS_FIX` | كمية مفقودة أو وحدة مختلفة | يُرفع للعميل كقائمة إصلاح |
| `NO_RECIPE` | لا وصفة مرتبطة | خطة إكمال وصفات |
| `EMPTY_RECIPE` | وصفة بلا مكوّنات | خطة إكمال |
| `DEFER_SEMI` | سليمة لكن نصف مصنّع (يحتاج تفكيك BOM) | مؤجّل للمرحلة ٢ |
| `LOW_VOLUME` | سليمة لكن كميتها صغيرة | مستبعد من التنبيهات |

**القيمة المزدوجة:** البوابة منتَج بحد ذاته («وصفاتك ناقصة لـ٢٨٪ من مبيعاتك، أكملها لتكشف تسرّباً») — تدفع العميل يحسّن بياناته، فيتحسّن المنتَج تلقائياً. وتحوّل «الإطلاق للجميع» إلى آمن: كل عميل يرى نتائج بقدر جاهزيته، لا أحد يرى رقماً كاذباً.

---

## ٧. معادلة فجوة التكلفة (تفصيل المرحلة ٦) — ⏳ مرسومة

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

| الطرف | المصدر | الحساب |
|-------|--------|--------|
| النظري | `order_items` × `recipe_ingredients` | كمية المنتج المباع × كمية الخام في الوصفة |
| الفعلي | `stock_ledger` + `stock_entries` | رصيد أول + وارد − رصيد آخر |
| المطروح | `waste_entries` | الهدر المعروف المسجّل |

**خمسة تحذيرات هندسية (هنا تموت المعادلات الساذجة):**
1. **توحيد الوحدات (UOM):** كل طرفي المعادلة يُحوَّلان لوحدة أساس واحدة لكل صنف قبل الطرح. شرط صحة لا تفصيل.
2. **نصف المصنّع:** يحتاج تفكيك وصفة (recipe explosion). ابدأ بالأصناف المباشرة، أجّل نصف المصنّع.
3. **حدود الفترة (cutoff):** مبيعات اليوم تُقابَل بحركة مخزون نفس اليوم بـ timestamp دقيق.
4. **الفروع:** الحساب لكل `branch_id` على حدة، لا للشركة ككل.
5. **الضجيج:** حدّ أدنى للكمية/القيمة قبل إظهار الفجوة كتنبيه، تجنّباً للإنذارات الكاذبة.

> **الذكاء لا يحسب رقماً واحداً هنا.** الحساب كلّه SQL. الوكيل يأخذ الجدول الجاهز، يرتّبه بالأثر المالي، يربط كل فجوة بسببها، ويصيغها عربياً.

**أسباب الفجوة الخمسة (للربط في `getVarianceReasons`):** الهدر والتلف، السرقة، أخطاء التحصيص، عدم الالتزام بالوصفة، انجراف أسعار الموردين.

---

## ٨. تدفّق الإدخال الذكي (تفصيل د-٨) — ⏳ مرسوم

أعلى قيمة فورية: يحل ألماً يومياً يشعر به الموظف نفسه. المبدأ: **الذكاء يملأ النموذج، الموظف يدقّق ويعتمد، ثم فقط يُكتب.** يحوّل الموظف من «مُدخِل» (ممل، يتحجج) إلى «مدقّق» (سريع، مسيطر).

```mermaid
flowchart TD
    A["صورة الجوال<br/>الموظف يصوّر الفاتورة"] --> B{"هل فيها QR؟"}
    B -->|نعم| C["قراءة QR المهيكل<br/>دقة عالية · ZATCA"]
    B -->|لا| D["OCR للصورة<br/>استخراج + درجة ثقة"]
    C --> E["مطابقة أصناف المورّد"]
    D --> F["مطابقة أصناف المورّد"]
    E --> G["نموذج معبّأ مسبقاً<br/>أخضر = واثق · أصفر = راجعني"]
    F --> G
    G --> H["تأكيد بشري"]
    H --> I["الآن فقط: حفظ في الجداول<br/>purchase_receipts · stock_entries"]

    style A fill:#F1EFE8,stroke:#5F5E5A,color:#2C2C2A
    style B fill:#E6F1FB,stroke:#185FA5,color:#042C53
    style C fill:#E1F5EE,stroke:#0F6E56,color:#04342C
    style D fill:#FAEEDA,stroke:#854F0B,color:#412402
    style E fill:#FAECE7,stroke:#993C1D,color:#4A1B0C
    style F fill:#FAECE7,stroke:#993C1D,color:#4A1B0C
    style G fill:#EEEDFE,stroke:#534AB7,color:#26215C
    style H fill:#E6F1FB,stroke:#185FA5,color:#042C53
    style I fill:#E1F5EE,stroke:#0F6E56,color:#04342C
```

**قرار البدء:** ابدأ بمسار الـ QR وحده (دقة جاهزة شبه مضمونة)، أطلقه، أثبت قيمته، **ثم** أضف مسار الصورة الحرة. يؤجّل أصعب جزء (OCR للفاتورة العربية بخط حر) حتى يثق بك المستخدمون.

**تحسين الثقة:** الذكاء يعرض درجة ثقته لكل حقل. الواضح أخضر (مرّ بسرعة)، المشكوك أصفر محاط (انتبه). يوجّه عين الموظف للمخاطر بدل مراجعة كل شيء بنفس الجهد.

**تعقيدات خاصة بحالتنا (تحقّق قبل أي وعد):**
- الفاتورة العربية (خط عربي، أرقام هندية ٠١٢٣، تخطيط RTL) أصعب على OCR العام — تحقّق على فواتير سعودية حقيقية.
- مطابقة أصناف المورّد («طماطم بلدي ٥ك» ↔ `item` اسمه «طماطم») مشكلة مطابقة بحد ذاتها.
- فواتير ZATCA تحمل QR مهيكل — قراءته أدقّ ألف مرة من OCR للصورة.

---

## ٩. طبقة الهوية والأمان (غير قابلة للتنازل)

أخطر نقطة في نظام متعدّد المستأجرين. **الهوية لا تأتي أبداً من مخرجات النموذج.**

```mermaid
flowchart TD
    subgraph panel["قناة لوحة التحكم"]
        P1["طلب المستخدم"] --> P2["JWT يحمل الهوية"]
    end
    subgraph wa["قناة واتساب"]
        W1["رسالة من رقم جوال"] --> W2["طبقة ربط:<br/>رقم ← مستخدم معتمد"]
        W2 --> W3{"الرقم مربوط<br/>بشركة واحدة؟"}
        W3 -->|لا| W4["رفض + طلب توثيق"]
        W3 -->|نعم| W5["هوية + صلاحيات أضيق"]
    end
    P2 --> INJ["حقن الهوية في طبقة التنفيذ"]
    W5 --> INJ
    INJ --> AGENT["الوكيل يختار الأداة"]
    AGENT --> EXEC["التنفيذ:<br/>company_id من الجلسة لا من النموذج"]
    EXEC --> RBAC["تطبيق RBAC الموجود على كل أداة"]

    style INJ fill:#FCEBEB,stroke:#A32D2D,color:#501313
    style EXEC fill:#FCEBEB,stroke:#A32D2D,color:#501313
    style W4 fill:#FAEEDA,stroke:#854F0B,color:#412402
    style RBAC fill:#E1F5EE,stroke:#0F6E56,color:#04342C
```

**القواعد:**
1. `company_id` و`branch_id` و`user_id` تُحقن من الـ JWT/session في طبقة التنفيذ، **بعد** اختيار النموذج للأداة. الوكيل يقول «نفّذ الأداة X»، الكود يحدد «لأي شركة».
2. واتساب لا JWT فيه — رقم الجوال هو كل شيء. **طبقة ربط إلزامية** (رقم ← مستخدم ← صلاحيات) قبل أي استدعاء أداة. رقم غير مربوط أو مربوط بأكثر من شركة → رفض وطلب توثيق، لا تخمين.
3. صلاحيات واتساب **أضيق** من اللوحة افتراضياً (قراءة وتنبيهات نعم، كتابة مالية لا) — قناة بلا تسجيل دخول قوي لا تُمنح ثقة الجلسة الموثّقة.
4. نفس RBAC الموجود (`role_permissions`, `user_branches`) يُطبَّق على كل أداة كأنها مستخدم بشري.
5. كل عملية تلقائية/مسودة تُكتب باسم «مستخدم نظام» في `created_by` لتبقى مدقّقة.

---

## ١٠. خارطة المراحل

| المرحلة | المحتوى | الحالة |
|---------|---------|--------|
| **أساس** | بوابة الجاهزية (`assessReadiness`) | ✅ مبنية ومُختبرة منطقياً |
| **١ — قراءة** | كل أدوات القراءة + وكيل يصيغ عربياً + قناة اللوحة | ⏳ التالي |
| **١ب — واتساب** | طبقة ربط الهوية + صلاحيات أضيق | ⏳ |
| **٢ — كتابة محدودة** | `calcCostVariance` + المسودات + تأكيد بشري | ⏳ |
| **٢ب — إدخال ذكي** | مسار QR أولاً، ثم OCR + مطابقة الأصناف | ⏳ |
| **٣ — توسّع** | عامل التحليل الخلفي، الصوت، تكامل المورّد/ZATCA | مؤجّل |

---

## ١١. ما تبقّى للتحقّق (قبل أي وعد للعملاء)

أرقام وحقائق تتغيّر، تحقّق منها من المصادر الرسمية قبل اعتمادها:
- نموذج تسعير Gemini وخصم الـ Prompt Caching الفعلي (من مستندات Google).
- جودة OCR على فواتير سعودية حقيقية بخط حر (اختبار فعلي، لا افتراض).
- مصفوفة دعم MAF للغات (لو أُعيد النظر في د-١ مستقبلاً).
- نسبة تغطية بوابة الجاهزية على بيانات عميل حقيقي — هي التي تقرر: تبدأ معادلة الفجوة الآن أم حملة تحسين وصفات أولاً.

---

*آخر تحديث: جلسة التصميم الأولى. هذا مستند حيّ — حدّثه مع كل قرار جديد أو بند يخرج من ⏳ إلى ✅.*