# دليل المطور: إنشاء الرسم البياني لاستدعاء الخدمة

يصف هذا المستند الطريقة القوية والآمنة لإنشاء رسم بياني للاتصال المرئي لـ "aura_engine.py" الذي يعمل لفترة طويلة. نستخدم ملف التعريف yappi (لدعم الخيوط المتعددة) وgprof2dot للتصور.

                                      ### المتطلبات الأساسية

تأكد من تثبيت الأدوات اللازمة عالميًا أو في بيئتك الافتراضية:

```bash
# Required Python libraries for profiling
pip install yappi gprof2dot

# Required system library for visualization
# Linux: sudo apt install graphviz 
```

    ### الخطوة 1: تعديل الخدمة الخاصة بالتوصيف

يجب تعديل البرنامج النصي `aura_engine.py` لبدء تشغيل ملف تعريف `yappi` يدويًا وحفظ بيانات ملفات التعريف بأمان عند المقاطعة (`Ctrl+C`).

               **التغييرات الرئيسية في `aura_engine.py`:**

1. ** معالج الواردات والإشارة: ** قم باستيراد `yappi` وحدد وظيفة `generate_graph_on_interrupt` (كما تم تنفيذها سابقًا) لاستدعاء `yappi.stop()` و`stats.save(...)`.
2. **Start/Stop:** أضف `yappi.start()` و`signal.signal(signal.SIGINT, ...)` داخل الكتلة `if __name__ == "__main__":` لتغليف تنفيذ `main(...)`.

### الخطوة الثانية: تشغيل الخدمة وجمع البيانات

قم بتشغيل البرنامج النصي المعدل مباشرة واسمح له بمعالجة البيانات لفترة كافية (على سبيل المثال، 10-20 ثانية) لضمان استدعاء جميع الوظائف الأساسية، بما في ذلك الوظائف المترابطة (مثل تصحيح LanguageTool).

```bash
# Execute the service directly (do NOT use the pycallgraph wrapper)
python3 aura_engine.py
```

اضغط على **Ctrl+C** مرة واحدة لتشغيل معالج الإشارة. سيؤدي هذا إلى إيقاف ملف التعريف وحفظ البيانات الأولية في:

                                          `\mathbf{yappi\_profile\_data.prof`

### الخطوة 3: إنشاء الرسم البياني المرئي وتصفيته

نستخدم "gprof2dot" لتحويل بيانات "pstats" الأولية إلى تنسيق SVG. نظرًا لأن خيارات التصفية المتقدمة مثل `--include` و`--threshold` قد لا تكون مدعومة من قبل بيئتنا المحددة، فإننا نستخدم مرشح **`--strip`** الأساسي لتنظيف معلومات المسار وتقليل الفوضى من الأجزاء الداخلية للنظام.

                                          **تنفيذ أمر التصور:**

```bash
python3 -m gprof2dot -f pstats yappi_profile_data.prof --strip | dot -Tsvg -o yappi_call_graph_stripped.svg
```

                           ### الخطوة 4: التوثيق (قص يدوي)

سيكون الملف الناتج `yappi_call_graph_stripped.svg` (أو `.png`) كبيرًا، ولكنه يحتوي بدقة على تدفق التنفيذ الكامل، بما في ذلك جميع سلاسل الرسائل.

لأغراض التوثيق، **قم بقص الصورة يدويًا** للتركيز على المنطق المركزي (العقد الأساسية 10-20 واتصالاتها) لإنشاء رسم بياني مركز وقابل للقراءة لوثائق المستودع.

                                                           ### الأرشفة

يجب أرشفة ملف التكوين المعدل والتصور النهائي لـ Call Graph في دليل مصدر الوثائق:

                                       | قطعة أثرية | الموقع |
                                                              | :--- | :--- |
| **ملف الخدمة المعدل** | `doc_sources/profiling/aura_engine_profiling_base.py` |
| **الصورة النهائية التي تم اقتصاصها** | `doc_sources/profiling/core_logic_call_graph.svg` |
| **بيانات ملفات التعريف الأولية** | *(اختياري: يجب استبعاده من وثائق المستودع النهائية)* |


                                                                    ![yappi_call_graph](../yappi_call_graph_stripped.svg_20251024_010459.png "yappi_call_graph_stripped.svg_20251024_010459.png")