trustgraph/docs/tech-specs/structured-diag-service.ar.md

---
layout: default
title: "المواصفات الفنية لخدمة تشخيص البيانات المهيكلة"
parent: "Arabic (Beta)"
---

# المواصفات الفنية لخدمة تشخيص البيانات المهيكلة

> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

## نظرة عامة

تصف هذه المواصفات خدمة جديدة قابلة للاستدعاء لتشخيص وتحليل البيانات المهيكلة داخل TrustGraph. تستخرج الخدمة الوظائف من أداة سطر الأوامر `tg-load-structured-data` الحالية وتعرضها كخدمة طلب/استجابة، مما يتيح الوصول البرمجي إلى قدرات اكتشاف أنواع البيانات وإنشاء الوصف.

تدعم الخدمة ثلاث عمليات رئيسية:

1. **اكتشاف نوع البيانات**: تحليل عينة بيانات لتحديد تنسيقها (CSV أو JSON أو XML)
2. **إنشاء الوصف**: إنشاء وصف بيانات مهيكلة لـ TrustGraph لعينة بيانات معينة ونوع
3. **التشخيص المدمج**: إجراء كل من اكتشاف النوع وإنشاء الوصف بالتسلسل

## الأهداف

**تجزئة تحليل البيانات**: استخراج منطق تشخيص البيانات من واجهة سطر الأوامر إلى مكونات خدمة قابلة لإعادة الاستخدام
**تمكين الوصول البرمجي**: توفير وصول قائم على واجهة برمجة التطبيقات (API) إلى قدرات تحليل البيانات
**دعم تنسيقات بيانات متعددة**: التعامل مع تنسيقات بيانات CSV و JSON و XML بشكل متسق
**إنشاء أوصاف دقيقة**: إنتاج أوصاف بيانات مهيكلة تعكس بدقة بيانات المصدر إلى مخططات TrustGraph
**الحفاظ على التوافق مع الإصدارات السابقة**: التأكد من أن وظائف واجهة سطر الأوامر الحالية تظل تعمل
**تمكين تجميع الخدمات**: السماح للخدمات الأخرى بالاستفادة من قدرات تشخيص البيانات
**تحسين إمكانية الاختبار**: فصل منطق الأعمال عن واجهة سطر الأوامر لتحسين الاختبار
**دعم التحليل المتدفق**: تمكين تحليل عينات البيانات دون تحميل الملفات بأكملها

## الخلفية

حاليًا، يوفر الأمر `tg-load-structured-data` وظائف شاملة لتحليل البيانات المهيكلة وإنشاء الأوصاف. ومع ذلك، فإن هذه الوظائف مرتبطة ارتباطًا وثيقًا بواجهة سطر الأوامر، مما يحد من إمكانية إعادة استخدامها.

تشمل القيود الحالية:
منطق تشخيص البيانات مضمن في كود واجهة سطر الأوامر
لا يوجد وصول برمجي إلى اكتشاف النوع وإنشاء الوصف
من الصعب دمج قدرات التشخيص في خدمات أخرى
قدرة محدودة على تجميع سير عمل تحليل البيانات

تعالج هذه المواصفات هذه الفجوات من خلال إنشاء خدمة مخصصة لتشخيص البيانات المهيكلة. من خلال تعريض هذه القدرات كخدمة، يمكن لـ TrustGraph:
تمكين خدمات أخرى من تحليل البيانات برمجيًا
دعم مسارات معالجة بيانات أكثر تعقيدًا
تسهيل التكامل مع الأنظمة الخارجية
تحسين قابلية الصيانة من خلال الفصل بين المهام

## التصميم الفني

### البنية

تتطلب خدمة تشخيص البيانات المهيكلة المكونات الفنية التالية:

1. **معالج خدمة التشخيص**
   يتعامل مع طلبات التشخيص الواردة
   يقوم بتنسيق اكتشاف النوع وإنشاء الوصف
   يُرجع استجابات مهيكلة مع نتائج التشخيص

   الوحدة: `trustgraph-flow/trustgraph/diagnosis/structured_data/service.py`

2. **كاشف نوع البيانات**
   يستخدم الكشف الخوارزمي لتحديد تنسيق البيانات (CSV أو JSON أو XML)
   يحلل هيكل البيانات والفواصل وأنماط بناء الجملة
   يُرجع التنسيق المكتشف ودرجات الثقة

   الوحدة: `trustgraph-flow/trustgraph/diagnosis/structured_data/type_detector.py`

3. **مولد الوصف**
   يستخدم خدمة المطالبة لإنشاء الأوصاف
   يستدعي المطالبات الخاصة بالتنسيق (diagnose-csv أو diagnose-json أو diagnose-xml)
   يربط حقول البيانات بحقول مخطط TrustGraph من خلال استجابات المطالبة

   الوحدة: `trustgraph-flow/trustgraph/diagnosis/structured_data/descriptor_generator.py`

### نماذج البيانات

#### StructuredDataDiagnosisRequest

رسالة طلب لعمليات تشخيص البيانات المهيكلة:

```python
class StructuredDataDiagnosisRequest:
    operation: str  # "detect-type", "generate-descriptor", or "diagnose"
    sample: str     # Data sample to analyze (text content)
    type: Optional[str]  # Data type (csv, json, xml) - required for generate-descriptor
    schema_name: Optional[str]  # Target schema name for descriptor generation
    options: Dict[str, Any]  # Additional options (e.g., delimiter for CSV)
```

#### استجابة تشخيص البيانات المنظمة

رسالة استجابة تحتوي على نتائج التشخيص:

```python
class StructuredDataDiagnosisResponse:
    operation: str  # The operation that was performed
    detected_type: Optional[str]  # Detected data type (for detect-type/diagnose)
    confidence: Optional[float]  # Confidence score for type detection
    descriptor: Optional[Dict]  # Generated descriptor (for generate-descriptor/diagnose)
    error: Optional[str]  # Error message if operation failed
    metadata: Dict[str, Any]  # Additional metadata (e.g., field count, sample records)
```

#### هيكل الوصف

يتبع الوصف الناتج تنسيق الوصف المنظم للبيانات الموجود:

```json
{
  "format": {
    "type": "csv",
    "encoding": "utf-8",
    "options": {
      "delimiter": ",",
      "has_header": true
    }
  },
  "mappings": [
    {
      "source_field": "customer_id",
      "target_field": "id",
      "transforms": [
        {"type": "trim"}
      ]
    }
  ],
  "output": {
    "schema_name": "customer",
    "options": {
      "batch_size": 1000,
      "confidence": 0.9
    }
  }
}
```

### واجهة الخدمة

ستعرض الخدمة العمليات التالية من خلال نمط الطلب/الاستجابة:

1. **عملية اكتشاف النوع**
   المدخلات: عينة بيانات
   المعالجة: تحليل هيكل البيانات باستخدام الكشف الخوارزمي
   المخرجات: النوع المكتشف مع درجة الثقة

2. **عملية توليد الوصف**
   المدخلات: عينة بيانات، والنوع، واسم المخطط المستهدف
   المعالجة:
     استدعاء خدمة المطالبة بمعرف المطالبة الخاص بالتنسيق (diagnose-csv أو diagnose-json أو diagnose-xml)
     تمرير عينة البيانات والمخططات المتاحة إلى المطالبة
     استقبال الوصف الذي تم إنشاؤه من استجابة المطالبة
   المخرجات: وصف البيانات المنظمة

3. **عملية التشخيص المجمعة**
   المدخلات: عينة بيانات، واسم المخطط (اختياري)
   المعالجة:
     استخدام الكشف الخوارزمي لتحديد التنسيق أولاً
     تحديد معرف المطالبة الخاص بالتنسيق المناسب بناءً على النوع المكتشف
     استدعاء خدمة المطالبة لإنشاء الوصف
   المخرجات: كل من النوع المكتشف والوصف

### تفاصيل التنفيذ

ستتبع الخدمة اتفاقيات خدمة TrustGraph:

1. **تسجيل الخدمة**
   التسجيل كنوع خدمة `structured-diag`
   استخدام مواضيع الطلب/الاستجابة القياسية
   تنفيذ الفئة الأساسية FlowProcessor
   تسجيل PromptClientSpec لتفاعل خدمة المطالبة

2. **إدارة التكوين**
   الوصول إلى تكوينات المخططات عبر خدمة التكوين
   تخزين المخططات مؤقتًا لتحسين الأداء
   التعامل مع تحديثات التكوين ديناميكيًا

3. **تكامل المطالبة**
   استخدام البنية التحتية الحالية لخدمة المطالبة
   استدعاء خدمة المطالبة بمعرفات المطالبة الخاصة بالتنسيق:
     `diagnose-csv`: لتحليل بيانات CSV
     `diagnose-json`: لتحليل بيانات JSON
     `diagnose-xml`: لتحليل بيانات XML
   يتم تكوين المطالبات في تكوين المطالبة، وليس ترميزها بشكل ثابت في الخدمة
   تمرير المخططات وعينات البيانات كمتغيرات للمطالبة
   تحليل استجابات المطالبة لاستخراج الأوصاف

4. **معالجة الأخطاء**
   التحقق من صحة عينات البيانات المدخلة
   توفير رسائل خطأ وصفية
   التعامل مع البيانات التالفة بأمان
   التعامل مع فشل خدمة المطالبة

5. **أخذ العينات من البيانات**
   معالجة أحجام العينات القابلة للتكوين
   التعامل مع السجلات غير المكتملة بشكل مناسب
   الحفاظ على اتساق أخذ العينات

### تكامل واجهة برمجة التطبيقات (API)

ستتكامل الخدمة مع واجهات برمجة تطبيقات TrustGraph الحالية:

المكونات المعدلة:
`tg-load-structured-data` CLI - تم إعادة هيكلتها لاستخدام الخدمة الجديدة لعمليات التشخيص
Flow API - تم توسيعه لدعم طلبات تشخيص البيانات المنظمة

نقاط نهاية الخدمة الجديدة:
`/api/v1/flow/{flow}/diagnose/structured-data` - نقطة نهاية WebSocket لطلبات التشخيص
`/api/v1/diagnose/structured-data` - نقطة نهاية REST للتشخيص المتزامن

### تدفق الرسائل

```
Client → Gateway → Structured Diag Service → Config Service (for schemas)
                                           ↓
                                    Type Detector (algorithmic)
                                           ↓
                                    Prompt Service (diagnose-csv/json/xml)
                                           ↓
                                 Descriptor Generator (parses prompt response)
                                           ↓
Client ← Gateway ← Structured Diag Service (response)
```

## اعتبارات الأمان

التحقق من صحة الإدخال لمنع هجمات الحقن.
حدود الحجم على عينات البيانات لمنع هجمات الحرمان من الخدمة (DoS).
تنقية الواصفات التي تم إنشاؤها.
التحكم في الوصول من خلال مصادقة TrustGraph الحالية.

## اعتبارات الأداء

تخزين تعريفات المخططات مؤقتًا لتقليل عدد استدعاءات خدمة التكوين.
تحديد حدود لحجم العينات للحفاظ على أداء سريع الاستجابة.
استخدام المعالجة المتدفقة لعلاجات البيانات الكبيرة.
تطبيق آليات المهلة للتحليلات التي تستغرق وقتًا طويلاً.

## استراتيجية الاختبار

1. **اختبارات الوحدة**
   اكتشاف النوع لـتنسيقات البيانات المختلفة.
   دقة توليد الواصفات.
   سيناريوهات معالجة الأخطاء.

2. **اختبارات التكامل**
   تدفق طلب/استجابة الخدمة.
   استرجاع المخططات وتخزينها مؤقتًا.
   تكامل واجهة سطر الأوامر (CLI).

3. **اختبارات الأداء**
   معالجة العينات الكبيرة.
   معالجة الطلبات المتزامنة.
   استخدام الذاكرة تحت الحمل.

## خطة الترحيل

1. **المرحلة الأولى**: تنفيذ الخدمة مع الوظائف الأساسية.
2. **المرحلة الثانية**: إعادة هيكلة واجهة سطر الأوامر (CLI) لاستخدام الخدمة (مع الحفاظ على التوافق مع الإصدارات السابقة).
3. **المرحلة الثالثة**: إضافة نقاط نهاية واجهة برمجة التطبيقات (REST API).
4. **المرحلة الرابعة**: إيقاف وظائف واجهة سطر الأوامر (CLI) المضمنة (مع إشعار مسبق).

## الجدول الزمني

الأسبوع 1-2: تنفيذ الخدمة الأساسية واكتشاف النوع.
الأسبوع 3-4: إضافة توليد الواصفات والتكامل.
الأسبوع 5: الاختبار والتوثيق.
الأسبوع 6: إعادة هيكلة واجهة سطر الأوامر (CLI) والترحيل.

## أسئلة مفتوحة

هل يجب أن تدعم الخدمة تنسيقات بيانات إضافية (مثل Parquet، Avro)؟
ما هو الحد الأقصى لحجم العينة للتحليل؟
هل يجب تخزين نتائج التشخيص مؤقتًا للطلبات المتكررة؟
كيف يجب أن تتعامل الخدمة مع السيناريوهات متعددة المخططات؟
هل يجب أن تكون معرفات المطالبات معلمات قابلة للتكوين للخدمة؟

## المراجع

[مواصفات واصف البيانات المنظمة](structured-data-descriptor.md)
[توثيق تحميل البيانات المنظمة](structured-data.md)
`tg-load-structured-data` التنفيذ: `trustgraph-cli/trustgraph/cli/load_structured_data.py`