محرك التقارير بالذكاء الاصطناعي

كيف يعمل

مسار من 7 خطوات

كل سؤال يمرّ بنفس المسار. المحرك يُنتج DSL فقط — والتنفيذ يُفوَّض إلى dynamic-hybrid-reporting-engine، المُغذّى ببيانات من dual-layer-reporting-engine.

01PromptNormalizer

تشذيب، حروف عربية، تشكيل وترقيم ← بصمة

02فحص الكاش

إصابة ← تحميل DSL مخزّن، تخطّي التحليل

03RegexParser

مطابقة بلا توكن ← IntermediateQuery

04OpenAiParser

عند فشل Regex ← JSON مُهيكل ← IntermediateQuery

05DslBuilder

المكان الوحيد لبناء DSL — تحقّق ومطابقة

06تخزين الكاش

حفظ النية + DSL (بلا صفوف)

07ReportEngine.run

تنفيذ الـ DSL — محرك التقارير غير المتغيّر

كائن الاستعلام الموحّد

شكل واحد — Regex أو AI، لا فرق للنظام

كلا المحلّلين يُرجعان نفس IntermediateQuery تمامًا. المحلّل وحده يعرف مصدره؛ أما باني الـ DSL وبقية التطبيق فيبقيان غير مبالين بالمصدر.

⚙️ مخرجات RegexParser

{
  "module": "students",
  "operation": "list",
  "filters": [
    { "field":"class_id", "operator":"=", "value":1 }
  ],
  "projection": ["first_name_ar","status"],
  "limit": 20,
  "_source": "regex"
}

🧠 مخرجات OpenAiParser

{
  "module": "books",
  "operation": "list",
  "filters": [
    { "field":"title_ar", "operator":"like", "value":"مقدمة" }
  ],
  "projection": ["title_ar","author"],
  "limit": 20,
  "_source": "openai"
}

محرّكان، عقد واحد

Regex أولًا، ثم OpenAI عند الفشل

طريقة التحليل قابلة للتبديل: auto (regex ثم OpenAI)، regex (بلا توكن)، أو openai. كل عنصر خلف واجهة.

⚙️

RegexParser

حتمي وبلا توكن. يطابق mappings ومفاهيم أعمدة قابلة للتعديل في MongoDB. يحوّل «طلاب الصف 1-A» إلى فلتر class_id عبر EntityResolver قابل للاستبدال.

🧠

OpenAiParser

يعمل فقط عند فشل Regex. يُرجع JSON صارمًا — لا DSL ولا SQL خام. يتتبّع زمن الاستجابة واستهلاك التوكن لسجل التنفيذ.

🔑

كاش البصمة

الأسئلة المتكافئة (مسافات، تشكيل، صور الألف) تشترك في بصمة واحدة، فيتخطّى السؤال المكرّر التحليل تمامًا بلا توكن.

تجربة المطوّر

أمثلة كود

احقن المسار، احصل على DSL، سلّمه لمحرك التقارير.

use Mostafax\AiReportingEngine\ReportQueryPipeline;
use Mostafax\ReportingEngine\Core\Engine\ReportEngine;

public function search(Request $request, ReportQueryPipeline $pipeline, ReportEngine $engine)
{
    $result = $pipeline->process($request->string('question'));
    // ['source'=>'regex|openai|cache', 'collection'=>…, 'query'=>…, 'dsl'=>…, 'cached'=>bool]

    $rows = $engine->run($result['dsl']);   // نفّذ عبر محرك التقارير

    return response()->json(['data' => $rows->data, 'source' => $result['source']]);
}

// تفعيل تحويل اسم الصف → class_id (خاص بالمشروع)
$this->app->bind(
    EntityResolverInterface::class,
    MyClassResolver::class,
);

// استبدال مصدر إعدادات الـ AI (مثلاً من قاعدة البيانات)
$this->app->singleton(
    AiConfigInterface::class,
    SystemSettingAiConfig::class,
);

// config/ai-reporting.php
return [
    'enabled'      => true,
    'parse_method' => 'auto',   // auto | regex | openai
    'openai' => [
        'api_key'       => env('OPENAI_API_KEY'),
        'model'         => 'gpt-4o-mini',
        'schema_prompt' => '…أقسامك وأعمدتك…',
    ],
    'storage' => [ 'connection' => 'mongodb' ],
];

المميزات

مبني لإعادة الاستخدام — لا شيء مثبّت بصلابة

🧹

تطبيع عربي

توحيد الألف والتاء المربوطة، وإزالة التشكيل والترقيم.

🔑

كاش البصمة

SHA-256 للنص المُطبَّع — صفر توكن عند التكرار.

🎯

كائن موحّد

Regex و AI يُرجعان نفس IntermediateQuery.

🏗️

باني DSL مركزي

المكان الوحيد الذي يُنتج DSL قابلًا للتنفيذ.

🔌

SOLID + DI

كل عنصر واجهة قابلة للاستبدال.

🍃

تخزين MongoDB

mappings ومفاهيم وكاش قابلة للتعديل.

🧩

مُحلِّل الكيانات

تحويل الأسماء («الصف 1-A») إلى معرّفات للتصفية.

📊

سجل التنفيذ

المحلّل، إصابة الكاش، الزمن، التوكن، والـ DSL.

التثبيت

جاهز خلال دقائق

حزمتا التقارير مطلوبتان إجباريًا وتُسحبان تلقائيًا.

$ composer require mostafax/ai-reporting-engine
$ php artisan vendor:publish --tag=ai-reporting-config

يتطلّب

mostafax/dynamic-hybrid-reporting-engine — ينفّذ الـ DSL.
mostafax/dual-layer-reporting-engine — يُكرّر البيانات للتقارير.

طريقة التحليل

auto — regex أولًا، OpenAI عند الفشل (موصى به).
regex — محلي فقط، بلا توكن.
openai — AI فقط.