دليل المطور الشامل

نظرة عامة — ما هي إضافة سيطرة؟

إضافة سيطرة هي حزمة برمجية (Python + HTML) تُوسّع وظائف النظام. يمكنها:

⚡بداية سريعة — 3 دقائق!

1. حمّل القالب الجاهز: saytara_starter_plugin.zip
2. فك الضغط وعدّل: غيّر id وname في manifest.json، واكتب منطقك في main.py
3. اضغط كـ ZIP:

   zip -r my_plugin.zip custom_my_plugin/

4. ارفع وفعّل: ادخل الإعدادات → مدير الإضافات → رفع ZIP → تثبيت → تفعيل ✅

1هيكل ملفات الإضافة

custom_my_plugin/
├── manifest.json          ← إجباري — تعريف الإضافة (الاسم، الصلاحيات، الأحداث)
├── main.py                ← إجباري — الكلاس الرئيسي (يرث SaytaraPlugin)
├── __init__.py            ← فارغ (مطلوب لـ Python)
├── templates/
│   └── ext_custom_my_plugin/
│       ├── index.html     ← الصفحة الرئيسية (تستخدم {% extends "base.html" %})
│       └── widget.html    ← ويدجت الداشبورد (اختياري)
├── static/
│   ├── css/style.css      ← أنماط CSS مخصصة
│   └── js/main.js         ← JavaScript مخصص
└── README.md              ← توثيق (اختياري)

2ملف manifest.json — التعريف الكامل

{
    "id": "custom.my_report",
    "name": "تقرير الأرباح المتقدم",
    "name_en": "Advanced Profit Report",
    "version": "1.0.0",
    "description": "تقرير أرباح تفصيلي مع رسوم بيانية وتصدير PDF",
    "description_en": "Detailed profit report with charts and PDF export",
    "category": "reports",
    "icon": "chart-line",
    "color": "#28a745",
    "author": {
        "name": "أحمد المطور",
        "email": "ahmed@example.com",
        "url": "https://example.com"
    },
    "entry_point": "main.py",
    "min_system_version": "1.0.0",
    "permissions": [
        "accounting.invoices.read",
        "accounting.reports.read",
        "customers.list.read"
    ],
    "events": {
        "listen": ["accounting.invoice.created", "accounting.payment.received"],
        "emit": ["custom.my_report.generated"]
    },
    "settings": [
        {"key": "show_charts", "label": "إظهار رسوم بيانية", "type": "boolean", "default": true},
        {"key": "currency", "label": "عملة التقرير", "type": "select",
         "options": [{"value":"IQD","label":"دينار عراقي"}, {"value":"USD","label":"دولار"}]}
    ],
    "ui": {
        "menu_items": [
            {"label": "تقرير الأرباح", "icon": "chart-line", "url": "/ext/my-report/", "order": 50}
        ]
    },
    "tags": ["reports", "analytics", "charts"]
}

جميع حقول manifest.json:

3ملف main.py — الكلاس الرئيسي

يجب أن يحتوي على كلاس واحد يرث من SaytaraPlugin:

from extensions.plugin_base import SaytaraPlugin, PluginContext

class MyPlugin(SaytaraPlugin):

    @property
    def plugin_id(self):   return 'custom.my_plugin'   # يطابق id في manifest
    @property
    def plugin_name(self): return 'إضافتي'
    @property
    def plugin_version(self): return '1.0.0'

    # ─── الدوال الإجبارية (Properties) ───
    # plugin_id, plugin_name, plugin_version (أعلاه)

    # ─── دورة الحياة (اختياري) ───
    def on_install(self, ctx):    ctx.log('info', 'تم التثبيت')
    def on_activate(self, ctx):   ctx.log('info', 'تم التفعيل')
    def on_deactivate(self, ctx): ctx.log('info', 'تم التعطيل')
    def on_uninstall(self, ctx):  ctx.log('info', 'تم الحذف')

    # ─── الأحداث ───
    def register_events(self, ctx):
        ctx.on_event('accounting.invoice.created', self._on_invoice)

    def _on_invoice(self, event):
        print(f"فاتورة: {event.data.get('invoice_id')}")

    # ─── الصفحات ───
    def register_routes(self, app):
        from flask import Blueprint, render_template
        bp = Blueprint('ext_my_plugin', __name__,
                       template_folder='templates', url_prefix='/ext/my-plugin')
        @bp.route('/')
        def index(): return render_template('ext_custom_my_plugin/index.html')
        return bp

    # ─── القائمة ───
    def get_menu_items(self):
        return [{'label': 'إضافتي', 'icon': 'rocket', 'url': '/ext/my-plugin/', 'order': 100}]

دورة حياة الإضافة (Lifecycle)

4إضافة صفحات (Routes & Templates)

register_routes() تُنشئ Flask Blueprint. الصفحات تظهر على /ext/{name}/:

def register_routes(self, app):
    bp = Blueprint('ext_my_report', __name__,
                   template_folder='templates',
                   static_folder='static',
                   url_prefix='/ext/my-report')

    @bp.route('/')
    def index():
        return render_template('ext_my_report/index.html')

    @bp.route('/api/data')
    def api_data():
        return jsonify({'success': True, 'items': [...]})

    return bp  # مهم! أرجع الـ Blueprint

القالب (index.html): استخدم {% extends "base.html" %} لورث تصميم النظام:

{% extends "base.html" %}
{% block title %}تقريري{% endblock %}
{% block content %}
<div class="container-fluid py-4">
    <h2>مرحباً من الإضافة!</h2>
    <!-- محتوى صفحتك هنا -->
</div>
{% endblock %}

القوائم والويدجت

get_menu_items(): يضيف روابط في الشريط العلوي (قائمة الإعدادات):

def get_menu_items(self):
    return [
        {'label': 'تقريري', 'icon': 'chart-line', 'url': '/ext/my-report/', 'order': 50},
    ]

get_dashboard_widgets(): يضيف ويدجت في الداشبورد:

def get_dashboard_widgets(self):
    return [{'title': 'إضافتي', 'icon': 'rocket', 'color': '#667eea',
             'template': 'ext_my_plugin/widget.html', 'order': 100}]

نظام الأحداث — كيف يعمل؟

نظام سيطرة يطلق أحداث عند كل عملية مهمة. إضافتك تسجّل مستمعين لهذه الأحداث:

def register_events(self, ctx):
    # استمع لحدث واحد أو أكثر
    ctx.on_event('accounting.invoice.created', self._on_invoice)
    ctx.on_event('accounting.payment.received', self._on_payment)

def _on_invoice(self, event):
    # event.data يحتوي بيانات الحدث
    invoice_id = event.data.get('invoice_id')
    total = event.data.get('total_amount')
    user_id = event.data.get('user_id')
    print(f"فاتورة #{invoice_id} — المبلغ: {total}")

EventContext يحتوي:

• event.event_name — اسم الحدث
• event.data — بيانات الحدث (dict)
• event.tenant_id — معرف المشترك
• event.user_id — معرف المستخدم الحالي
• event.timestamp — وقت الحدث

جميع الأحداث المتاحة — المرجع الكامل (65+ حدث)

محاسبة الفواتير والسندات

محاسبة الشيكات

الزبائن والمجهزين

المخزون والمواد

نقاط البيع (POS)

المطاعم

CRM — إدارة علاقات العملاء

HRM — الموارد البشرية

النظام والتكاملات

أحداث أخرى

أحداث ما قبل التنفيذ (Pre-Events) — إلغاء العمليات

الأحداث التي تبدأ بـ before_ تسمح لإضافتك بـ إلغاء العملية قبل حدوثها:

def register_events(self, ctx):
    ctx.on_event('accounting.invoice.before_create', self._validate, priority=10)

def _validate(self, event):
    total = event.data.get('total_amount', 0)
    if total > 50000000:  # 50 مليون
        event.cancel('المبلغ يتجاوز الحد المسموح!', by=self.plugin_id)

الأحداث المتاحة للإلغاء: accounting.invoice.before_create, accounting.invoice.before_update, accounting.invoice.before_delete, accounting.voucher.before_create

6الوصول للبيانات (Data API)

# قراءة فواتير
invoices = ctx.query('invoices', filters={'payment_status': 'unpaid'}, limit=50)

# قراءة عميل بالمعرف
customer = ctx.get_by_id('customers', 42)

# استعلام SQL مخصص (قراءة فقط!)
results = ctx.execute_query("SELECT * FROM invoices WHERE total_amount > %s", (1000000,))

# إنشاء سجل في جدول الإضافة
ctx.create('ext_plugin_data', {'key': 'sync', 'value': '2026-01-01'})

# تحديث سجل
ctx.update('customers', 5, {'notes': 'VIP'})

# إطلاق حدث مخصص
ctx.emit_event('custom.report.generated', {'report_id': 1})

# إرسال إشعار
ctx.send_notification('تنبيه!', 'تقرير الأرباح جاهز للتحميل')

7الإعدادات (Settings)

def get_settings_schema(self):
    return [
        {'key': 'api_key',   'label': 'مفتاح API',     'type': 'password'},
        {'key': 'auto_sync',  'label': 'مزامنة تلقائية', 'type': 'boolean',  'default': True},
        {'key': 'interval',  'label': 'الفترة (دقائق)', 'type': 'number',   'default': 60},
        {'key': 'currency',  'label': 'العملة',        'type': 'select',
         'options': [{'value':'IQD','label':'دينار'},{'value':'USD','label':'دولار'}]},
    ]

أنواع الإعدادات: text, password, number, boolean, select, textarea

الصلاحيات المتاحة

8التعبئة والرفع

1. اضغط المجلد كملف ZIP:

   zip -r custom_my_plugin.zip custom_my_plugin/

2. ارفع عبر مدير الإضافات: الإعدادات → مدير الإضافات → رفع إضافة (ZIP)
3. ثبّت وفعّل: إضافات متاحة → تثبيت → تفعيل

9النشر في متجر سيطرة

1. أكمل manifest.json (اسم، وصف، أيقونة، tags)
2. اختبر جيداً على حساب تجريبي
3. ارفع ZIP عبر مدير الإضافات
4. فريق سيطرة يراجع الإضافة (أمان + جودة + أداء)
5. بعد الموافقة: تُنشر في المتجر لجميع المشتركين

مرجع API الكامل — PluginContext (ctx)

جداول البيانات المتاحة للإضافات

أسئلة شائعة