Structure the tech specs directory (#836)

Tech spec some subdirectories for different languages
2026-04-25 08:26:21 +02:00 · 2026-04-21 16:06:41 +01:00 · 2026-04-21 16:06:41 +01:00 · e7efb673ef
commit e7efb673ef
parent 48da6c5f8b
423 changed files with 0 additions and 0 deletions
--- a/docs/tech-specs/ar/structured-diag-service.ar.md
+++ b/docs/tech-specs/ar/structured-diag-service.ar.md
@ -0,0 +1,281 @@
+---
+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`