📊 4 مشاهدة

KOSMOS v1.0 — المواصفة الهندسية الكاملة

من التصور إلى التنفيذ — Blueprint تنفيذي كامل

هذه ليست مقالة. هذه مواصفة هندسية (Engineering Spec) جاهزة للتسليم لفريق تطوير. كل جدول، كل class، كل endpoint، كل hook — موثّق ومبرر.

🎯 الجزء 0: إعادة تعريف المنصة — النسخة النهائية

الاسم النهائي: KOSMOS Studio

النوع: Subscription-as-a-Service Knowledge & Commerce Bridge

الرؤية (جملة واحدة):

جسر رقمي يربط المعرفة بـ التجارة: منصة اشتراكية تمنح التجار والوكالات القدرة على سحب منتجاتهم ومحتواهم ومهاراتهم من مصادر متعددة، وضخّها في قنوات البيع (سلة، شوبيفاي، ووكومرس) — مع مدرّب AI ومكتبة معرفة حية تُغلق تلقائياً عند انقطاع الاشتراك.

القيمة الفريدة (3 محاور):

المحور	الوصف
🔌 Content Bridge	اسحب من أي مصدر (Shopify، WooCommerce، AliExpress، CSV، API)، ادفع إلى سلة/غيرها بضغطة
🧠 Knowledge Layer	كل منتج يتحول إلى عقدة معرفة + AI Tutor يشرح استخدامه
💰 Subscription Lock	إذا توقف الاشتراك — المنتجات والتصنيفات والخدمات تُقفل فوراً

الشعار التسويقي:

“معرفتك، منتجاتك، أرباحك — في مدار واحد. توقف الدفع؟ يتوقف الكون.”

الجمهور المستهدف:

التاجر في سلة الذي يريد استيراد منتجات من منصات أخرى بذكاء
الوكالة الرقمية التي تدير متاجر متعددة لعملائها
صاحب المعرفة/المدرب الذي يريد بيع دورات + منتجات رقمية
المبرمج/المصمم الذي يريد بيع قوالبه وخدماته باشتراك

📐 الجزء 1: المعمارية العامة (System Architecture)

المكونات الأساسية (Bounded Contexts):

#	المكون	المسؤولية
1	Tenant Service	إدارة الحسابات، النطاقات، الفواتير
2	Subscription Engine	الباقات، التجديد، الإلغاء، Dunning
3	Entitlements Engine	“هل هذا المستخدم يحق له الوصول؟” — نقطة القرار المركزية
4	Content Bridge	سحب/دفع المنتجات بين المصادر
5	AI Gateway	تجميع كل استدعاءات AI + Metering
6	Knowledge Graph	رسم المهارات والمنتجات والعلاقات
7	Job Queue	المهام غير المتزامنة (Sync, Publish)
8	Audit & Compliance	تسجيل كل حركة، GDPR، Export

البرومبت الهندسي الشامل — منصة “سلة بريدج” (Salla Bridge Platform)

🎯 الهدف العام (Master Prompt)

أنت مهندس برمجيات رئيسي (Lead Software Architect) متخصص في WordPress Plugin Development وWooCommerce وSaaS Multi-Tenant Systems. مطلوب منك تصميم وتنفيذ مواصفة هندسية كاملة v1.0 لمنصة SaaS وسيطة (Middleware Platform) تربط متجر سلة (Salla) بمصادر خارجية للمنتجات (AliExpress, Amazon, Noon, Shopify, Taobao, 1688, CJ Dropshipping, وغيرها)، مع نظام اشتراكات مُحكم يقفل المحتوى تلقائيًا عند انتهاء الاشتراك.

المطلوب: من التصور إلى التنفيذ — كتابة المواصفة كاملة بحيث يمكن لمبرمج تنفيذها حرفيًا.

📐 القسم 1: تعريف المنصة (Platform Definition)

الاسم المقترح: SallaBridge — جسر المنتجات الذكي.

الوصف:
منصة SaaS متعددة المستأجرين (Multi-Tenant) تعمل كـ WordPress Plugin + بوابة ويب خارجية، تُمكّن أصحاب متاجر سلة من:

سحب المنتجات والصور والأسعار من منصات عالمية (AliExpress, Amazon, Noon, Taobao, 1688, CJ, Shopify…).
إعادة هيكلتها وترجمتها وتحسينها بالذكاء الاصطناعي.
دفعها تلقائيًا إلى متجر سلة (Products, Categories, Images, Variants).
إدارة ذلك عبر لوحة تحكم واحدة مع نظام باقات واشتراكات شهري/سنوي.

القيمة المضافة:

أتمتة الاستيراد (Bulk Import) بمعدل آلاف المنتجات/ساعة.
ترجمة عربية/إنجليزية تلقائية عبر AI Gateway.
مزامنة الأسعار والمخزون.
نظام قفل (Lock): عند عدم الدفع → إخفاء/قفل المنتجات والأقسام والتصنيفات من متجر سلة تلقائيًا.

🗄️ القسم 2: بنية قاعدة البيانات (Database Schema v1.0)

اكتب الجداول بصيغة wp_sb_* مع dbDelta():

2.1 الجداول الأساسية

الجدول	الحقول الرئيسية	العلاقات
`wp_sb_tenants`	id, user_id, salla_store_id, salla_access_token, salla_refresh_token, plan_id, status, trial_ends_at, created_at	→ wp_users, → wp_sb_plans
`wp_sb_plans`	id, name, slug, price_monthly, price_yearly, max_products, max_images, max_sources, features_json, is_active	→ wp_sb_entitlements
`wp_sb_subscriptions`	id, tenant_id, plan_id, gateway, gateway_sub_id, status, current_period_start, current_period_end, cancel_at, created_at	→ tenants, plans
`wp_sb_entitlements`	id, plan_id, feature_key, limit_value, reset_period	→ plans
`wp_sb_sources`	id, tenant_id, source_type (aliexpress/amazon/noon…), api_key, api_secret, is_active, last_sync_at	→ tenants
`wp_sb_import_jobs`	id, tenant_id, source_id, status, total_items, processed, failed, payload_json, started_at, finished_at	→ tenants, sources
`wp_sb_products_map`	id, tenant_id, source_product_id, salla_product_id, sku, price_source, price_salla, markup_percent, image_count, locked TINYINT, synced_at	→ tenants
`wp_sb_images`	id, product_map_id, source_url, salla_media_id, checksum, status	→ products_map
`wp_sb_categories_map`	id, tenant_id, source_cat_id, salla_cat_id, locked	→ tenants
`wp_sb_ai_jobs`	id, tenant_id, job_type (translate/rewrite/seo), input_hash, output_json, tokens_used, provider, status	→ tenants
`wp_sb_webhooks_log`	id, tenant_id, event, payload, signature, status, created_at	→ tenants
`wp_sb_audit_log`	id, tenant_id, actor_id, action, object_type, object_id, meta_json, ip, created_at	→ tenants
`wp_sb_lock_events`	id, tenant_id, reason (expired/cancelled/suspended), locked_items_count, unlocked_at, created_at	→ tenants

2.2 الفهارس (Indexes)

UNIQUE(tenant_id, source_product_id) على products_map.
INDEX(status, current_period_end) على subscriptions.
INDEX(tenant_id, locked) على products_map وcategories_map.

🧩 القسم 3: هيكل الـPlugin (Folder & Namespace Structure)

text

salla-bridge/
├── salla-bridge.php                 (Bootstrap + Plugin Header)
├── composer.json                    (PSR-4: SallaBridge\)
├── uninstall.php
├── src/
│   ├── Core/
│   │   ├── Plugin.php
│   │   ├── Activator.php
│   │   ├── Deactivator.php
│   │   ├── Installer.php            (dbDelta migrations)
│   │   └── Container.php            (DI Container)
│   ├── Admin/
│   │   ├── Menu.php
│   │   ├── Dashboards/
│   │   │   ├── TenantDashboard.php
│   │   │   ├── AdminDashboard.php
│   │   │   └── BillingDashboard.php
│   │   └── Views/
│   ├── Api/
│   │   ├── RestController.php       (Base)
│   │   ├── AuthController.php
│   │   ├── ImportController.php
│   │   ├── SyncController.php
│   │   ├── BillingController.php
│   │   └── LockController.php
│   ├── Salla/
│   │   ├── Client.php               (OAuth2 + REST)
│   │   ├── ProductPusher.php
│   │   ├── CategoryPusher.php
│   │   ├── MediaUploader.php
│   │   └── Webhooks.php
│   ├── Sources/
│   │   ├── SourceInterface.php
│   │   ├── AliExpressSource.php
│   │   ├── AmazonSource.php
│   │   ├── NoonSource.php
│   │   ├── ShopifySource.php
│   │   └── SourceFactory.php
│   ├── AI/
│   │   ├── Gateway.php
│   │   ├── Providers/
│   │   │   ├── OpenAIProvider.php
│   │   │   ├── AnthropicProvider.php
│   │   │   └── GeminiProvider.php
│   │   ├── TranslateJob.php
│   │   └── SeoRewriteJob.php
│   ├── Billing/
│   │   ├── SubscriptionManager.php
│   │   ├── EntitlementChecker.php
│   │   ├── WooCommerceHooks.php
│   │   ├── Gateways/
│   │   │   ├── StripeGateway.php
│   │   │   ├── PaypalGateway.php
│   │   │   ├── MoyasarGateway.php    (سعودي)
│   │   │   └── TapGateway.php        (خليجي)
│   │   └── WebhookHandler.php
│   ├── Locking/
│   │   ├── LockManager.php
│   │   ├── SallaLocker.php           (unpublish products/cats on Salla)
│   │   └── CronGuard.php
│   ├── Roles/
│   │   ├── RoleManager.php
│   │   └── Capabilities.php
│   ├── Cron/
│   │   ├── SyncPrices.php
│   │   ├── CheckSubscriptions.php    (hourly)
│   │   └── RetryFailedJobs.php
│   └── Support/
│       ├── Logger.php
│       ├── Crypto.php                (encrypt tokens at rest)
│       └── Helpers.php
├── assets/  (js, css, react build)
├── languages/
└── tests/

Namespace root: SallaBridge\
Text Domain: salla-bridge

🔌 القسم 4: REST Endpoints (v1)

Base: /wp-json/sb/v1/
Auth: Bearer JWT + HMAC signature for Salla webhooks.

Method	Route	Purpose	Capability
POST	`/auth/salla/callback`	استقبال OAuth code	public
POST	`/import/start`	بدء مهمة استيراد	`sb_start_import`
GET	`/import/{job_id}/status`	حالة المهمة	`sb_view_jobs`
POST	`/sync/products`	مزامنة منتجات	`sb_sync_products`
POST	`/sync/prices`	تحديث الأسعار	`sb_sync_prices`
POST	`/billing/subscribe`	إنشاء اشتراك	`sb_manage_billing`
POST	`/billing/cancel`	إلغاء اشتراك	`sb_manage_billing`
GET	`/billing/status`	حالة الاشتراك والـentitlements	`sb_view_billing`
POST	`/lock/enforce`	تشغيل القفل يدويًا (admin)	`sb_manage_lock`
POST	`/lock/release`	رفع القفل بعد الدفع	`sb_manage_lock`
POST	`/ai/translate`	ترجمة دفعة	`sb_use_ai`
POST	`/ai/seo`	تحسين SEO	`sb_use_ai`
GET	`/dashboard/stats`	إحصائيات	`sb_view_dashboard`
POST	`/webhooks/salla`	Webhooks من سلة	public+HMAC
POST	`/webhooks/woo`	Webhooks من WooCommerce	public+HMAC

كل endpoint يمر عبر RestController::permission_callback() يتحقق من tenant_id + EntitlementChecker.

🛒 القسم 5: تكامل سلة (Salla Integration)

OAuth2 Flow: https://accounts.salla.sa/oauth2/auth → token → تخزين مُشفّر في wp_sb_tenants.
Endpoints المُستخدمة من Salla API:
- POST /products — إنشاء منتج
- PUT /products/{id} — تحديث
- POST /products/{id}/images
- POST /categories
- PUT /products/{id} مع status: hidden → للقفل
Mapping الحقول:
- source.title → salla.name
- source.description → salla.description
- source.price * (1 + markup/100) → salla.price
- source.stock → salla.quantity
Rate Limiting: 60 req/min → Backoff + Queue.
Retry: 3 محاولات (exponential: 5s, 30s, 5m).

💳 القسم 6: نظام الباقات والاشتراكات (Plans & Entitlements)

6.1 الباقات المقترحة

الباقة	شهري	سنوي	منتجات	صور	مصادر	AI tokens
Starter	99 SAR	990 SAR	500	2,000	1	100K
Growth	299 SAR	2,990 SAR	5,000	20,000	3	1M
Pro	799 SAR	7,990 SAR	25,000	100,000	8	5M
Enterprise	تسعير مخصص	—	Unlimited	Unlimited	Unlimited	Custom

6.2 Entitlements Logic

php

EntitlementChecker::can($tenant_id, 'import_products', $qty)

يفحص: subscription.status = active + now <= current_period_end + used + qty <= limit.
عند التجاوز → يرجع WP_Error('quota_exceeded').

6.3 WooCommerce Hooks (لأن المنصة نفسها تُبنى على Woo)

woocommerce_checkout_order_processed → تفعيل اشتراك.
woocommerce_order_status_completed → تمديد current_period_end.
woocommerce_order_status_refunded → إلغاء فوري.
woocommerce_subscription_status_updated (إن وُجد WCS).
woocommerce_payment_complete → ربط gateway_sub_id.

6.4 دورة حياة الاشتراك

trialing → active → past_due (grace 3 أيام) → locked → cancelled

🔒 القسم 7: نظام القفل التلقائي (Auto-Lock System) — القلب النابض

السيناريو:

العميل توقف عن الدفع → بعد انتهاء current_period_end + grace period → تُقفل جميع المنتجات والأقسام والتصنيفات التي استوردها عبر المنصة في متجر سلة، وتختفي من الواجهة.

7.1 Cron: `sb_check_subscriptions` (كل ساعة)

php

foreach (subscriptions where status IN ('active','past_due')) {
    if (now > current_period_end + grace_days) {
        LockManager::lock($tenant_id, 'expired');
    }
}

7.2 LockManager::lock()

جلب كل products_map WHERE tenant_id AND locked = 0.
لكل منتج: استدعاء Salla API PUT /products/{id} {status: 'hidden'}.
نفس الشيء للتصنيفات categories_map.
تسجيل في lock_events.
تحديث locked = 1.
إرسال إيميل + إشعار Dashboard.
تسجيل webhook subscription.locked.

7.3 LockManager::release()

عكس العملية status: 'sale'.
فقط بعد تأكيد الدفع من Gateway webhook.

7.4 Cron Guard

يمنع أي import/sync جديد إذا locked = 1.
REST endpoints ترجع 403 subscription_locked.

🤖 القسم 8: AI Gateway

Interface موحّد:

php

interface AiProviderInterface {
    public function translate(string $text, string $to, string $from = 'auto'): string;
    public function rewrite(string $text, string $tone): string;
    public function seo(string $title, string $desc): array;
}

Routing: يختار Provider حسب التكلفة واللغة (OpenAI للعربية، Anthropic للـSEO، Gemini للترجمة الجماعية).
Caching: input_hash → يمنع إعادة الدفع لنفس النص.
Rate Limit per tenant: حسب الباقة.
Fallback: إذا فشل OpenAI → Anthropic → Gemini.

👥 القسم 9: Roles & Capabilities

Role	Capabilities
`sb_tenant_owner`	كل صلاحيات المستأجر
`sb_tenant_manager`	import, sync, view (بدون billing)
`sb_tenant_viewer`	view فقط
`sb_support`	view_all_tenants, impersonate
`sb_platform_admin`	كل شيء + manage_lock, manage_plans

php

add_role('sb_tenant_owner', 'SallaBridge Tenant', [
    'sb_start_import' => true,
    'sb_sync_products' => true,
    'sb_manage_billing' => true,
    'sb_manage_lock' => false,   // admin only
    'sb_use_ai' => true,
    'sb_view_dashboard' => true,
]);

📊 القسم 10: Dashboards

10.1 Tenant Dashboard (React SPA)

بطاقات: منتجات مستوردة | صور | AI tokens مستخدمة | حالة الاشتراك (عدّاد تنازلي).
رسم بياني: imports/day.
جدول: آخر 20 مهمة استيراد + حالتها.
تحذير أحمر إذا current_period_end - now < 7 days.

10.2 Admin Dashboard

عدد المستأجرين، MRR، Churn، Locked Tenants.
زر Force Lock / Release.
سجل audit_log.

10.3 Billing Dashboard

Upgrade/Downgrade، الفواتير، طريقة الدفع، Cancel.

⏱️ القسم 11: خطة تنفيذ أول 60 دقيقة (Minute-by-Minute)

الدقيقة	الملف	المخرج
0–5	`salla-bridge.php`	Plugin Header + Autoload + Activation Hook
5–10	`src/Core/Installer.php`	dbDelta لكل الجداول
10–15	`src/Core/Plugin.php` + `Container.php`	Bootstrap + DI
15–20	`src/Roles/RoleManager.php` + `Capabilities.php`	تسجيل الأدوار
20–25	`src/Api/RestController.php`	Base REST + namespace
25–30	`src/Api/AuthController.php`	OAuth callback
30–35	`src/Salla/Client.php`	OAuth2 + request wrapper
35–40	`src/Sources/SourceInterface.php` + `SourceFactory.php`	واجهة المصادر
40–45	`src/Sources/AliExpressSource.php`	أول مصدر فعلي
45–50	`src/Billing/SubscriptionManager.php` + `EntitlementChecker.php`	منطق الباقات
50–55	`src/Locking/LockManager.php` + `SallaLocker.php`	نظام القفل
55–60	`src/Cron/CheckSubscriptions.php` + تسجيله	Cron كل ساعة

الناتج بعد 60 دقيقة: Plugin يُفعّل، ينشئ الجداول، يسجّل REST، يربط سلة OAuth، يستورد من AliExpress، يدير اشتراك، ويقفل تلقائيًا عند الانتهاء.

🧪 القسم 12: معايير القبول (Acceptance Criteria)

✅ تفعيل Plugin يُنشئ 13 جدولًا بدون أخطاء.
✅ OAuth مع سلة يعمل ويخزّن tokens مُشفّرة.
✅ استيراد 100 منتج من AliExpress في < 5 دقائق.
✅ منتجات تظهر في سلة بالصور والتصنيفات.
✅ اشتراك شهري عبر Moyasar يُنشئ subscription.active.
✅ عند انتهاء current_period_end + grace → كل المنتجات hidden في سلة خلال ساعة.
✅ عند تجديد الدفع → release() يرجّع كل شيء.
✅ Dashboard يعرض العدّاد والإحصائيات.
✅ REST endpoints محمية بـCapabilities.
✅ Audit log يسجّل كل عملية حساسة.

📦 القسم 13: مخرجات مطلوبة منك (Deliverables)

اكتب الآن، بالترتيب:

كود SQL كامل لكل الجداول (MySQL 8, utf8mb4).
كود PHP كامل للملفات في خطة الـ60 دقيقة (لا pseudo-code).
مخطط ERD نصي للعلاقات.
OpenAPI 3.0 YAML لكل REST endpoints.
Schema للـPayloads (Salla webhook, Woo webhook, AI job).
Pseudo-code لـCron CheckSubscriptions وLockManager::lock/release.
خطة اختبار (Unit + Integration + E2E).
Roadmap لـv1.1 (Multi-store, WhatsApp notifications, Mobile app).

🚫 قيود صارمة

لا تستخدم eval, لا base64 للكود.
كل الـSQL عبر $wpdb->prepare.
كل الـTokens مُشفّرة بـCrypto::encrypt() (Sodium).
الالتزام بـWordPress Coding Standards + PSR-12.
الـMulti-Tenancy عبر tenant_id في كل جدول (Row-level isolation).
لا تحذف بيانات عند الإلغاء — فقط locked = 1.

ابدأ الآن بكتابة المواصفة الهندسية الكاملة v1.0، ملفًا بملف، سطرًا بسطر، جاهزة للنسخ إلى IDE.

📚 الملحق الهندسي الموسّع — SallaBridge v1.1

استكمالًا للمواصفة v1.0، هذا الملحق يغطي الطبقات العميقة: التشفير، الطوابير، الأمان، التوسع، الاختبارات، DevOps، والتفاصيل التنفيذية الكاملة.

🔐 القسم 14: طبقة التشفير والأمان (Crypto & Security)

14.1 `src/Support/Crypto.php`

php

<?php
declare(strict_types=1);
namespace SallaBridge\Support;

final class Crypto {
    private const CIPHER = 'sodium_crypto_secretbox';
    private static string $key;

    public static function boot(): void {
        $raw = defined('SB_ENCRYPTION_KEY') ? SB_ENCRYPTION_KEY : get_option('sb_encryption_key');
        if (!$raw) {
            $raw = base64_encode(random_bytes(32));
            update_option('sb_encryption_key', $raw, false);
        }
        self::$key = base64_decode($raw);
    }

    public static function encrypt(string $plain): string {
        $nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
        $cipher = sodium_crypto_secretbox($plain, $nonce, self::$key);
        return base64_encode($nonce . $cipher);
    }

    public static function decrypt(string $encoded): string {
        $decoded = base64_decode($encoded, true);
        if ($decoded === false) return '';
        $nonce  = substr($decoded, 0, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
        $cipher = substr($decoded, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
        $plain  = sodium_crypto_secretbox_open($cipher, $nonce, self::$key);
        return $plain === false ? '' : $plain;
    }
}

14.2 قواعد الأمان الإلزامية

البند	التنفيذ
Tokens at Rest	Sodium secretbox (أعلاه)
HTTPS Only	`force_ssl_admin()` + HSTS header
REST Auth	JWT + HMAC-SHA256 للـ webhooks
SQL Injection	`$wpdb->prepare` دائمًا
XSS	`esc_html`, `esc_attr`, `wp_kses_post`
CSRF	`wp_nonce` لكل form
Rate Limit	Transient-based per IP + tenant
File Uploads	فحص MIME + `wp_check_filetype_and_ext`
Secrets	لا تُخزّن في Git — `.env` + `wp-config.php`
Audit	كل عملية كتابة → `audit_log`

14.3 HMAC Webhook Verification

php

public static function verify_salla_webhook(string $raw, string $signature, string $secret): bool {
    $expected = base64_encode(hash_hmac('sha256', $raw, $secret, true));
    return hash_equals($expected, $signature);
}

⚙️ القسم 15: نظام الطوابير (Job Queue)

15.1 لماذا لا نعتمد على `wp_cron` فقط؟

wp_cron يعتمد على زيارات المستخدم → غير موثوق للـSaaS.
الحل: Action Scheduler (مدمج مع WooCommerce) + Queue مخصّص.

15.2 بنية Queue

php

namespace SallaBridge\Core;

final class Queue {
    public const HOOK = 'sb_process_job';

    public static function push(string $job_type, array $payload, int $priority = 10, int $delay = 0): int {
        return as_schedule_single_action(
            time() + $delay,
            self::HOOK,
            ['type' => $job_type, 'payload' => $payload],
            'salla-bridge',
            $priority
        );
    }

    public static function register(): void {
        add_action(self::HOOK, [self::class, 'handle'], 10, 2);
    }

    public static function handle(string $type, array $payload): void {
        $handler = JobRegistry::resolve($type);
        if (!$handler) return;
        try {
            $handler->handle($payload);
        } catch (\Throwable $e) {
            Logger::error("Job failed: {$type}", ['error' => $e->getMessage()]);
            $attempts = ($payload['_attempts'] ?? 0) + 1;
            if ($attempts < 3) {
                $payload['_attempts'] = $attempts;
                self::push($type, $payload, 10, 30 * $attempts);
            } else {
                self::move_to_dlq($type, $payload, $e);
            }
        }
    }
}

15.3 أنواع الـJobs

Job Type	Handler	Batch
`import.product`	`ImportProductJob`	1 منتج
`import.batch`	`ImportBatchJob`	50 منتج
`sync.price`	`SyncPriceJob`	100 منتج
`upload.image`	`UploadImageJob`	1 صورة
`ai.translate`	`TranslateJob`	20 نص
`lock.tenant`	`LockTenantJob`	tenant كامل
`release.tenant`	`ReleaseTenantJob`	tenant كامل
`notify.email`	`EmailJob`	1

15.4 Dead Letter Queue (DLQ)

جدول wp_sb_dlq (id, job_type, payload, error, failed_at) + Dashboard لعرضها وإعادة تشغيلها.

🏗️ القسم 16: Multi-Tenancy العميق

16.1 Row-Level Isolation

قاعدة ذهبية: كل جدول (عدا plans وentitlements) يحمل tenant_id BIGINT UNSIGNED NOT NULL.
كل Query يمر عبر TenantScope::apply($sql).

php

final class TenantScope {
    public static function id(): int {
        return (int) (Container::get('current_tenant')?->id ?? 0);
    }
    public static function where(string $table): string {
        global $wpdb;
        return $wpdb->prepare("{$table}.tenant_id = %d", self::id());
    }
}

16.2 Tenant Context Resolution

text

Request → Middleware:
  1. JWT decode → user_id
  2. users → tenants (1:1 أو 1:N مع owner)
  3. تحميل Tenant object + Subscription + Entitlements
  4. Container::set('current_tenant', $tenant)
  5. التحقق من Lock status → رفض إن مفعّل

16.3 Tenant Lifecycle

text

registered → trial (14 يوم) → active → past_due → locked → cancelled
                │                  │
                └── soft delete ───┘

🔌 القسم 17: محوّلات المصادر (Source Adapters) بالتفصيل

17.1 الواجهة الموحدة

php

interface SourceInterface {
    public function authenticate(array $credentials): bool;
    public function search(string $query, int $page = 1): array;
    public function fetch_product(string $external_id): array;   // DTO موحّد
    public function fetch_images(string $external_id): array;
    public function fetch_categories(): array;
    public function normalize(array $raw): ProductDTO;
}

17.2 `ProductDTO` الموحّد

php

final class ProductDTO {
    public string $external_id;
    public string $title;
    public string $description;
    public float  $price;
    public string $currency;
    public int    $stock;
    public string $sku;
    public array  $images = [];      // ['url' => '', 'alt' => '']
    public array  $variants = [];    // ['name'=>'', 'price'=>0, 'stock'=>0]
    public string $category_path;    // "Electronics > Phones"
    public array  $attributes = [];  // ['color'=>'red']
    public array  $raw = [];         // الأصل للرجوع
}

17.3 جدول المصادر المدعومة

المصدر	Auth	Rate Limit	ملاحظات
AliExpress	AppKey + AppSecret + OAuth	100/min	عبر `aliexpress.open.api`
Amazon PA-API	AccessKey + Secret + PartnerTag	1 req/s	يحتاج Associate
Noon	Partner API	60/min	يحتاج اتفاق تجاري
Shopify	Store URL + Admin Token	2 req/s	REST Admin API
Taobao	AppKey + Session	60/min	يحتاج وسيط صيني
1688	AppKey + Session	60/min	مماثل Taobao
CJ Dropshipping	API Key	120/min	الأسهل للبداية
Alibaba	OAuth	30/min	للجملة

17.4 خوارزمية اختيار المصدر

php

SourceFactory::make($type, $tenant) // يتحقق من:
  - المصدر مدعوم في الباقة (max_sources)
  - credentials صحيحة + غير منتهية
  - rate limit متاح
  - circuit breaker مغلق

🤖 القسم 18: AI Gateway المتقدم

18.1 Routing Strategy (Cost-Aware)

php

final class Gateway {
    public function translate(string $text, string $to): string {
        $provider = $this->pick_provider('translate', strlen($text), $to);
        return $provider->translate($text, $to);
    }

    private function pick_provider(string $task, int $len, string $lang): AiProviderInterface {
        // قواعد:
        // - نصوص <500 char + عربي → Gemini Flash (رخيص)
        // - نصوص >2000 char → OpenAI GPT-4o-mini
        // - SEO/rewrite → Claude Sonnet
        // - fallback chain عند الفشل
    }
}

18.2 AI Caching Layer

جدول wp_sb_ai_cache (hash, provider, output, tokens, created_at) — يمنع إعادة الدفع لنفس المدخل.

18.3 Prompt Templates

php

final class Prompts {
    public const TRANSLATE = <<<PROMPT
    Translate the following e-commerce product text to %s.
    Preserve: brand names, units, numbers, HTML tags.
    Tone: persuasive, marketing.
    Input: %s
    Output (JSON): {"title":"","description":"","tags":[]}
    PROMPT;

    public const SEO = <<<PROMPT
    Rewrite as SEO-optimized Arabic product listing.
    Include: primary keyword, 3 long-tail, meta description (155 char).
    Input: %s
    PROMPT;
}

18.4 حدود AI حسب الباقة

الباقة	Tokens/شهر	Rate/min	Providers
Starter	100K	10	Gemini
Growth	1M	30	+ OpenAI
Pro	5M	100	+ Anthropic
Enterprise	Custom	Custom	All + Dedicated

💰 القسم 19: الفوترة والاشتراكات (Billing Deep Dive)

19.1 دورة حياة الاشتراك (State Machine)

text

          ┌──────────┐
          │ trialing │
          └────┬─────┘
               │ (14 يوم)
               ▼
          ┌──────────┐   فشل دفع   ┌───────────┐
          │  active  ├────────────►│ past_due  │
          └────┬─────┘             └─────┬─────┘
               │ تجديد                    │ (3 أيام)
               │                          ▼
               │                    ┌──────────┐
               │                    │  locked  │
               │                    └────┬─────┘
               │                         │ دفع
               └────────────◄────────────┘
                            │ إلغاء
                            ▼
                       ┌───────────┐
                       │ cancelled │
                       └───────────┘

19.2 `SubscriptionManager::renew()`

php

public function renew(int $subscription_id, string $gateway_txn): bool {
    $sub = $this->repo->find($subscription_id);
    $plan = $this->plans->find($sub->plan_id);

    $sub->current_period_start = time();
    $sub->current_period_end   = $sub->billing_cycle === 'yearly'
        ? strtotime('+1 year')
        : strtotime('+1 month');
    $sub->status = 'active';
    $sub->gateway_sub_id = $gateway_txn;
    $this->repo->save($sub);

    $this->entitlements->reset_usage($sub->tenant_id, $sub->current_period_start);
    $this->events->dispatch('subscription.renewed', $sub);

    // رفع القفل إن وُجد
    if ($this->lock->is_locked($sub->tenant_id)) {
        $this->lock->release($sub->tenant_id, 'renewal');
    }
    return true;
}

19.3 Webhook Handlers لكل Gateway

Gateway	حدث الدفع	حدث الإلغاء	التوقيع
Stripe	`invoice.paid`	`customer.subscription.deleted`	`Stripe-Signature`
PayPal	`BILLING.SUBSCRIPTION.ACTIVATED`	`...CANCELLED`	`PAYPAL-TRANSMISSION-SIG`
Moyasar	`payment_paid`	`subscription_canceled`	HMAC-SHA256
Tap	`charge.succeeded`	`subscription.cancelled`	`hashstring`

19.4 الفواتير (Invoices)

توليد PDF عبر dompdf أو TCPDF.
تخزين في wp-content/uploads/sb-invoices/{tenant_id}/.
إرسال تلقائي بالبريد + رابط دائم.

🔒 القسم 20: نظام القفل — التنفيذ الكامل

20.1 `LockManager.php` (كامل)

php

<?php
declare(strict_types=1);
namespace SallaBridge\Locking;

final class LockManager {
    public function __construct(
        private \SallaBridge\Salla\SallaLocker $locker,
        private \SallaBridge\Core\Repositories\ProductsMapRepo $products,
        private \SallaBridge\Core\Repositories\CategoriesMapRepo $categories,
        private \SallaBridge\Core\Events\Dispatcher $events,
        private \SallaBridge\Support\Logger $logger
    ) {}

    public function lock(int $tenant_id, string $reason): int {
        $this->logger->info("Locking tenant {$tenant_id}", ['reason' => $reason]);

        $product_ids = $this->products->get_unlocked_ids($tenant_id);
        $cat_ids     = $this->categories->get_unlocked_ids($tenant_id);
        $total       = 0;

        foreach (array_chunk($product_ids, 50) as $chunk) {
            $total += $this->locker->hide_products($tenant_id, $chunk);
            $this->products->mark_locked($tenant_id, $chunk);
            usleep(500_000); // 0.5s للـrate limit
        }

        foreach ($cat_ids as $cat_id) {
            $this->locker->hide_category($tenant_id, $cat_id);
            $this->categories->mark_locked($tenant_id, $cat_id);
        }

        $this->events->dispatch('tenant.locked', [
            'tenant_id' => $tenant_id,
            'reason'    => $reason,
            'products'  => count($product_ids),
            'categories'=> count($cat_ids),
        ]);

        $this->log_lock_event($tenant_id, $reason, $total);
        return $total;
    }

    public function release(int $tenant_id, string $trigger): int {
        $this->logger->info("Releasing tenant {$tenant_id}", ['trigger' => $trigger]);

        $product_ids = $this->products->get_locked_ids($tenant_id);
        $cat_ids     = $this->categories->get_locked_ids($tenant_id);
        $total       = 0;

        foreach (array_chunk($product_ids, 50) as $chunk) {
            $total += $this->locker->publish_products($tenant_id, $chunk);
            $this->products->mark_unlocked($tenant_id, $chunk);
            usleep(500_000);
        }

        foreach ($cat_ids as $cat_id) {
            $this->locker->publish_category($tenant_id, $cat_id);
            $this->categories->mark_unlocked($tenant_id, $cat_id);
        }

        $this->events->dispatch('tenant.released', [
            'tenant_id' => $tenant_id,
            'trigger'   => $trigger,
            'products'  => count($product_ids),
        ]);

        return $total;
    }

    public function is_locked(int $tenant_id): bool {
        return (bool) get_transient("sb_locked_{$tenant_id}");
    }
}

20.2 `SallaLocker.php`

php

final class SallaLocker {
    public function __construct(private \SallaBridge\Salla\Client $client) {}

    public function hide_products(int $tenant_id, array $salla_product_ids): int {
        $count = 0;
        foreach ($salla_product_ids as $pid) {
            $res = $this->client->for_tenant($tenant_id)
                ->put("/products/{$pid}", ['status' => 'hidden']);
            if (!is_wp_error($res)) $count++;
        }
        return $count;
    }

    public function publish_products(int $tenant_id, array $ids): int {
        $count = 0;
        foreach ($ids as $pid) {
            $res = $this->client->for_tenant($tenant_id)
                ->put("/products/{$pid}", ['status' => 'sale']);
            if (!is_wp_error($res)) $count++;
        }
        return $count;
    }

    public function hide_category(int $tenant_id, int $cat_id): bool {
        $res = $this->client->for_tenant($tenant_id)
            ->put("/categories/{$cat_id}", ['status' => 'hidden']);
        return !is_wp_error($res);
    }

    public function publish_category(int $tenant_id, int $cat_id): bool {
        $res = $this->client->for_tenant($tenant_id)
            ->put("/categories/{$cat_id}", ['status' => 'active']);
        return !is_wp_error($res);
    }
}

20.3 Cron: `CheckSubscriptions`

php

final class CheckSubscriptions {
    public const HOOK = 'sb_hourly_check';

    public static function register(): void {
        if (!wp_next_scheduled(self::HOOK)) {
            wp_schedule_event(time(), 'hourly', self::HOOK);
        }
        add_action(self::HOOK, [self::class, 'run']);
    }

    public static function run(): void {
        global $wpdb;
        $grace_days = (int) get_option('sb_grace_days', 3);
        $now        = time();
        $threshold  = $now - ($grace_days * DAY_IN_SECONDS);

        $subs = $wpdb->get_results($wpdb->prepare("
            SELECT id, tenant_id, status, current_period_end
            FROM {$wpdb->prefix}sb_subscriptions
            WHERE status IN ('active','past_due')
              AND current_period_end < %d
        ", $threshold));

        $lock = Container::get(LockManager::class);

        foreach ($subs as $sub) {
            // 1) حاول تحصيل الدفع أولاً (Retry)
            if ($sub->status === 'active') {
                $wpdb->update("{$wpdb->prefix}sb_subscriptions",
                    ['status' => 'past_due'], ['id' => $sub->id]);
                continue;
            }

            // 2) past_due + انتهت المهلة → اقفل
            if ($sub->status === 'past_due') {
                $lock->lock((int) $sub->tenant_id, 'expired');
                $wpdb->update("{$wpdb->prefix}sb_subscriptions",
                    ['status' => 'locked'], ['id' => $sub->id]);
                self::notify_tenant($sub->tenant_id);
            }
        }
    }

    private static function notify_tenant(int $tenant_id): void {
        $email = get_userdata(get_user_by('id', $tenant_id)->user_email ?? 0);
        wp_mail(
            $email?->user_email ?? get_option('admin_email'),
            'تم إيقاف متجرك مؤقتًا',
            'انتهى اشتراكك في SallaBridge. جدّد الآن لإعادة تفعيل منتجاتك.'
        );
    }
}

🌐 القسم 21: تكامل سلة (Salla) — الطبقة الكاملة

21.1 `Salla\Client.php`

php

final class Client {
    private const API_BASE = 'https://api.salla.dev/admin/v2';
    private const OAUTH_AUTH = 'https://accounts.salla.sa/oauth2/auth';
    private const OAUTH_TOKEN = 'https://accounts.salla.sa/oauth2/token';

    private ?int $tenant_id = null;

    public function for_tenant(int $tenant_id): self {
        $clone = clone $this;
        $clone->tenant_id = $tenant_id;
        return $clone;
    }

    private function token(): string {
        $tenant = Container::get(TenantRepo::class)->find($this->tenant_id);
        $token  = Crypto::decrypt($tenant->salla_access_token);

        // تحقق من الانتهاء
        if ($tenant->salla_expires_at < time() + 300) {
            $token = $this->refresh($tenant);
        }
        return $token;
    }

    private function refresh(object $tenant): string {
        $res = wp_remote_post(self::OAUTH_TOKEN, [
            'body' => [
                'grant_type'    => 'refresh_token',
                'refresh_token' => Crypto::decrypt($tenant->salla_refresh_token),
                'client_id'     => SB_SALLA_CLIENT_ID,
                'client_secret' => SB_SALLA_CLIENT_SECRET,
            ],
        ]);
        $body = json_decode(wp_remote_retrieve_body($res), true);
        if (!empty($body['access_token'])) {
            Container::get(TenantRepo::class)->update_tokens($tenant->id, $body);
            return $body['access_token'];
        }
        throw new \RuntimeException('Salla token refresh failed');
    }

    public function get(string $endpoint, array $query = []): array|\WP_Error {
        return $this->request('GET', $endpoint, $query);
    }

    public function post(string $endpoint, array $body): array|\WP_Error {
        return $this->request('POST', $endpoint, $body);
    }

    public function put(string $endpoint, array $body): array|\WP_Error {
        return $this->request('PUT', $endpoint, $body);
    }

    private function request(string $method, string $endpoint, array $data): array|\WP_Error {
        $args = [
            'method'  => $method,
            'headers' => [
                'Authorization' => 'Bearer ' . $this->token(),
                'Content-Type'  => 'application/json',
                'Accept'        => 'application/json',
            ],
            'timeout' => 30,
        ];
        if ($method === 'GET') {
            $url = add_query_arg($data, self::API_BASE . $endpoint);
        } else {
            $url = self::API_BASE . $endpoint;
            $args['body'] = wp_json_encode($data);
        }

        $res = wp_remote_request($url, $args);
        if (is_wp_error($res)) return $res;

        $code = wp_remote_retrieve_response_code($res);
        $body = json_decode(wp_remote_retrieve_body($res), true);

        if ($code >= 400) {
            return new \WP_Error("salla_http_{$code}", $body['message'] ?? 'Salla error', $body);
        }
        return $body ?? [];
    }
}

21.2 Rate Limiter لسلة

php

final class SallaRateLimiter {
    private const MAX_PER_MIN = 60;

    public static function acquire(int $tenant_id): void {
        $key = "sb_salla_rl_{$tenant_id}";
        $count = (int) get_transient($key);
        if ($count >= self::MAX_PER_MIN) {
            sleep(2); // backoff
            $count = 0;
        }
        set_transient($key, $count + 1, MINUTE_IN_SECONDS);
    }
}

21.3 Webhooks من سلة

الحدث	الاستجابة
`order.created`	مزامنة المخزون
`product.updated`	كشف التضارب
`app.store.authorize`	تخزين tokens
`app.uninstalled`	soft delete للـtenant

📊 القسم 22: قاعدة البيانات — SQL الكامل

sql

-- 1. الخطط
CREATE TABLE {$prefix}sb_plans (
  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  name VARCHAR(100) NOT NULL,
  slug VARCHAR(50) NOT NULL,
  price_monthly DECIMAL(10,2) NOT NULL DEFAULT 0,
  price_yearly DECIMAL(10,2) NOT NULL DEFAULT 0,
  currency CHAR(3) NOT NULL DEFAULT 'SAR',
  max_products INT UNSIGNED NOT NULL DEFAULT 500,
  max_images INT UNSIGNED NOT NULL DEFAULT 2000,
  max_sources TINYINT UNSIGNED NOT NULL DEFAULT 1,
  max_ai_tokens INT UNSIGNED NOT NULL DEFAULT 100000,
  features_json JSON NULL,
  is_active TINYINT(1) NOT NULL DEFAULT 1,
  sort_order SMALLINT NOT NULL DEFAULT 0,
  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  UNIQUE KEY uk_slug (slug),
  KEY idx_active_sort (is_active, sort_order)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

-- 2. المستأجرون
CREATE TABLE {$prefix}sb_tenants (
  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  user_id BIGINT UNSIGNED NOT NULL,
  store_name VARCHAR(200) NOT NULL,
  salla_store_id VARCHAR(64) NULL,
  salla_access_token TEXT NULL,
  salla_refresh_token TEXT NULL,
  salla_expires_at DATETIME NULL,
  plan_id BIGINT UNSIGNED NULL,
  status ENUM('trial','active','past_due','locked','cancelled') NOT NULL DEFAULT 'trial',
  trial_ends_at DATETIME NULL,
  locale CHAR(5) NOT NULL DEFAULT 'ar',
  timezone VARCHAR(64) NOT NULL DEFAULT 'Asia/Riyadh',
  meta_json JSON NULL,
  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  UNIQUE KEY uk_user (user_id),
  KEY idx_status (status),
  KEY idx_plan (plan_id),
  CONSTRAINT fk_tenant_plan FOREIGN KEY (plan_id) REFERENCES {$prefix}sb_plans(id) ON DELETE SET NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

-- 3. الاشتراكات
CREATE TABLE {$prefix}sb_subscriptions (
  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  tenant_id BIGINT UNSIGNED NOT NULL,
  plan_id BIGINT UNSIGNED NOT NULL,
  billing_cycle ENUM('monthly','yearly') NOT NULL DEFAULT 'monthly',
  gateway VARCHAR(32) NOT NULL,
  gateway_sub_id VARCHAR(128) NULL,
  gateway_customer_id VARCHAR(128) NULL,
  status ENUM('trialing','active','past_due','locked','cancelled') NOT NULL DEFAULT 'trialing',
  amount DECIMAL(10,2) NOT NULL DEFAULT 0,
  currency CHAR(3) NOT NULL DEFAULT 'SAR',
  current_period_start DATETIME NULL,
  current_period_end DATETIME NULL,
  cancel_at DATETIME NULL,
  cancelled_at DATETIME NULL,
  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  KEY idx_tenant_status (tenant_id, status),
  KEY idx_period_end (status, current_period_end),
  CONSTRAINT fk_sub_tenant FOREIGN KEY (tenant_id) REFERENCES {$prefix}sb_tenants(id) ON DELETE CASCADE,
  CONSTRAINT fk_sub_plan FOREIGN KEY (plan_id) REFERENCES {$prefix}sb_plans(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

-- 4. المصادر
CREATE TABLE {$prefix}sb_sources (
  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  tenant_id BIGINT UNSIGNED NOT NULL,
  source_type VARCHAR(32) NOT NULL,
  label VARCHAR(100) NOT NULL,
  credentials TEXT NULL,
  config_json JSON NULL,
  is_active TINYINT(1) NOT NULL DEFAULT 1,
  last_sync_at DATETIME NULL,
  last_error TEXT NULL,
  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  KEY idx_tenant_type (tenant_id, source_type),
  CONSTRAINT fk_source_tenant FOREIGN KEY (tenant_id) REFERENCES {$prefix}sb_tenants(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

-- 5. خريطة المنتجات
CREATE TABLE {$prefix}sb_products_map (
  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  tenant_id BIGINT UNSIGNED NOT NULL,
  source_id BIGINT UNSIGNED NOT NULL,
  source_product_id VARCHAR(128) NOT NULL,
  salla_product_id VARCHAR(64) NULL,
  sku VARCHAR(128) NULL,
  title VARCHAR(500) NULL,
  price_source DECIMAL(12,2) NOT NULL DEFAULT 0,
  price_salla DECIMAL(12,2) NOT NULL DEFAULT 0,
  markup_percent DECIMAL(5,2) NOT NULL DEFAULT 0,
  currency CHAR(3) NOT NULL DEFAULT 'SAR',
  image_count SMALLINT UNSIGNED NOT NULL DEFAULT 0,
  stock INT NOT NULL DEFAULT 0,
  locked TINYINT(1) NOT NULL DEFAULT 0,
  sync_status ENUM('pending','synced','failed','outdated') NOT NULL DEFAULT 'pending',
  last_error TEXT NULL,
  synced_at DATETIME NULL,
  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  UNIQUE KEY uk_tenant_source (tenant_id, source_id, source_product_id),
  KEY idx_salla (tenant_id, salla_product_id),
  KEY idx_locked (tenant_id, locked),
  CONSTRAINT fk_pm_tenant FOREIGN KEY (tenant_id) REFERENCES {$prefix}sb_tenants(id) ON DELETE CASCADE,
  CONSTRAINT fk_pm_source FOREIGN KEY (source_id) REFERENCES {$prefix}sb_sources(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

-- 6. الصور
CREATE TABLE {$prefix}sb_images (
  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  tenant_id BIGINT UNSIGNED NOT NULL,
  product_map_id BIGINT UNSIGNED NOT NULL,
  source_url VARCHAR(1000) NOT NULL,
  salla_media_id VARCHAR(64) NULL,
  checksum CHAR(64) NULL,
  position SMALLINT UNSIGNED NOT NULL DEFAULT 0,
  status ENUM('pending','uploaded','failed') NOT NULL DEFAULT 'pending',
  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  KEY idx_pm (product_map_id),
  KEY idx_status (status),
  CONSTRAINT fk_img_pm FOREIGN KEY (product_map_id) REFERENCES {$prefix}sb_products_map(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

-- 7. خريطة التصنيفات
CREATE TABLE {$prefix}sb_categories_map (
  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  tenant_id BIGINT UNSIGNED NOT NULL,
  source_id BIGINT UNSIGNED NOT NULL,
  source_cat_id VARCHAR(128) NOT NULL,
  salla_cat_id VARCHAR(64) NULL,
  name VARCHAR(255) NULL,
  parent_source_id VARCHAR(128) NULL,
  locked TINYINT(1) NOT NULL DEFAULT 0,
  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  UNIQUE KEY uk_tenant_source_cat (tenant_id, source_id, source_cat_id),
  KEY idx_locked (tenant_id, locked),
  CONSTRAINT fk_cm_tenant FOREIGN KEY (tenant_id) REFERENCES {$prefix}sb_tenants(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

-- 8. مهام الاستيراد
CREATE TABLE {$prefix}sb_import_jobs (
  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  tenant_id BIGINT UNSIGNED NOT NULL,
  source_id BIGINT UNSIGNED NOT NULL,
  job_type ENUM('search','category','manual','bulk') NOT NULL DEFAULT 'manual',
  status ENUM('queued','running','paused','completed','failed','cancelled') NOT NULL DEFAULT 'queued',
  total_items INT UNSIGNED NOT NULL DEFAULT 0,
  processed_items INT UNSIGNED NOT NULL DEFAULT 0,
  failed_items INT UNSIGNED NOT NULL DEFAULT 0,
  payload_json JSON NULL,
  started_at DATETIME NULL,
  finished_at DATETIME NULL,
  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  KEY idx_tenant_status (tenant_id, status),
  CONSTRAINT fk_ij_tenant FOREIGN KEY (tenant_id) REFERENCES {$prefix}sb_tenants(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

-- 9. مهام AI
CREATE TABLE {$prefix}sb_ai_jobs (
  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  tenant_id BIGINT UNSIGNED NOT NULL,
  job_type ENUM('translate','rewrite','seo','categorize') NOT NULL,
  provider VARCHAR(32) NOT NULL,
  input_hash CHAR(64) NOT NULL,
  output_json JSON NULL,
  tokens_used INT UNSIGNED NOT NULL DEFAULT 0,
  cost_usd DECIMAL(10,6) NOT NULL DEFAULT 0,
  status ENUM('queued','running','completed','failed') NOT NULL DEFAULT 'queued',
  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  KEY idx_hash (input_hash),
  KEY idx_tenant (tenant_id),
  CONSTRAINT fk_ai_tenant FOREIGN KEY (tenant_id) REFERENCES {$prefix}sb_tenants(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

-- 10. استخدام الميزات
CREATE TABLE {$prefix}sb_usage (
  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  tenant_id BIGINT UNSIGNED NOT NULL,
  feature_key VARCHAR(64) NOT NULL,
  period_start DATE NOT NULL,
  used_value BIGINT UNSIGNED NOT NULL DEFAULT 0,
  limit_value BIGINT UNSIGNED NOT NULL DEFAULT 0,
  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  UNIQUE KEY uk_tenant_feature_period (tenant_id, feature_key, period_start)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

-- 11. سجل القفل
CREATE TABLE {$prefix}sb_lock_events (
  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  tenant_id BIGINT UNSIGNED NOT NULL,
  action ENUM('lock','release') NOT NULL,
  reason VARCHAR(64) NOT NULL,
  products_affected INT UNSIGNED NOT NULL DEFAULT 0,
  categories_affected INT UNSIGNED NOT NULL DEFAULT 0,
  actor_id BIGINT UNSIGNED NULL,
  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  KEY idx_tenant (tenant_id, created_at),
  CONSTRAINT fk_le_tenant FOREIGN KEY (tenant_id) REFERENCES {$prefix}sb_tenants(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

-- 12. سجل التدقيق
CREATE TABLE {$prefix}sb_audit_log (
  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  tenant_id BIGINT UNSIGNED NULL,
  actor_id BIGINT UNSIGNED NULL,
  action VARCHAR(64) NOT NULL,
  object_type VARCHAR(64) NULL,
  object_id BIGINT UNSIGNED NULL,
  meta_json JSON NULL,
  ip VARCHAR(45) NULL,
  user_agent VARCHAR(255) NULL,
  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  KEY idx_tenant_time (tenant_id, created_at),
  KEY idx_action (action)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

-- 13. DLQ
CREATE TABLE {$prefix}sb_dlq (
  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  job_type VARCHAR(64) NOT NULL,
  payload LONGTEXT NOT NULL,
  error TEXT NULL,
  attempts TINYINT UNSIGNED NOT NULL DEFAULT 0,
  failed_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  resolved_at DATETIME NULL,
  PRIMARY KEY (id),
  KEY idx_type_time (job_type, failed_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

🧪 القسم 23: الاختبارات (Testing Strategy)

23.1 الهرم

text

       ┌─────────────┐
       │   E2E (5%)  │  Playwright + WP test env
       ├─────────────┤
       │Integration  │  PHPUnit + wp-phpunit
       │   (25%)     │
       ├─────────────┤
       │  Unit (70%) │  PHPUnit + Brain Monkey
       └─────────────┘

23.2 أمثلة اختبارات حرجة

php

// tests/Unit/EntitlementCheckerTest.php
public function test_blocks_when_subscription_expired(): void {
    $tenant = $this->factory->tenant(['status' => 'locked']);
    $checker = new EntitlementChecker();
    $this->assertFalse($checker->can($tenant->id, 'import_products', 1));
}

public function test_allows_when_within_quota(): void {
    $tenant = $this->factory->tenant(['plan' => 'growth']);
    $this->assertTrue((new EntitlementChecker())->can($tenant->id, 'import_products', 100));
}

// tests/Integration/LockManagerTest.php
public function test_lock_hides_all_products_on_salla(): void {
    $mock = $this->mock_salla_client();
    $mock->expects($this->exactly(50))->method('put')
         ->with($this->stringContains('/products/'), ['status' => 'hidden']);

    $lock = Container::get(LockManager::class);
    $count = $lock->lock($this->tenant->id, 'test');
    $this->assertEquals(50, $count);
}

23.3 E2E Scenarios

مستأجر جديد → تسجيل → ربط سلة → استيراد 10 منتجات → التحقق من الظهور.
اشتراك → انتهاء → قفل تلقائي → تجديد → رفع القفل.
AI translate 100 نص → التحقق من التخزين والفاتورة.

🚀 القسم 24: DevOps والنشر

24.1 CI/CD Pipeline

yaml

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with: { php-version: '8.2' }
      - run: composer install
      - run: composer lint       # PHPCS + PSR-12
      - run: composer test       # PHPUnit
      - run: composer phpstan    # Level 6
      - run: npm ci && npm run build

24.2 Release Process

npm run build → assets/dist/
composer install --no-dev --optimize-autoloader
wp i18n make-pot . languages/salla-bridge.pot
wp dist-archive . → salla-bridge-x.y.z.zip
GitHub Release + تحديث readme.txt.

24.3 Monitoring

المقياس	الأداة
Uptime	UptimeRobot
Errors	Sentry (PHP SDK)
Performance	New Relic / Query Monitor
Business	Metabase على replica DB
Logs	ملفات يومية في `wp-content/uploads/sb-logs/`

24.4 Backup Strategy

DB: نسخة كل 6 ساعات → S3.
wp-content/uploads/sb-*: نسخة يومية.
الاحتفاظ: 30 يومًا.

📈 القسم 25: الأداء والتوسع (Performance & Scale)

25.1 القياسات المستهدفة

العملية	الهدف
استيراد منتج واحد	< 2s
استيراد 1000 منتج	< 30 دقيقة
Lock tenant (10K منتج)	< 5 دقائق
REST response p95	< 300ms
Dashboard load	< 1.5s

25.2 استراتيجيات التحسين

Indexes: كما في SQL أعلاه.
Chunking: دائمًا array_chunk(..., 50).
Object Cache: Redis/Memcached للـTenant, Plan, Entitlements.
DB Read Replica: للـDashboard queries.
CDN: للصور قبل رفعها لسلة.
HTTP/2 + Connection Pool لمصادر خارجية.

25.3 Circuit Breaker للمصادر

php

final class CircuitBreaker {
    public static function call(string $service, callable $fn): mixed {
        if (get_transient("sb_cb_open_{$service}")) {
            throw new \RuntimeException("Circuit open for {$service}");
        }
        try {
            $res = $fn();
            delete_transient("sb_cb_fail_{$service}");
            return $res;
        } catch (\Throwable $e) {
            $fails = (int) get_transient("sb_cb_fail_{$service}") + 1;
            set_transient("sb_cb_fail_{$service}", $fails, 300);
            if ($fails >= 5) {
                set_transient("sb_cb_open_{$service}", 1, 60);
            }
            throw $e;
        }
    }
}

🛡️ القسم 26: معالجة الأخطاء والمراقبة

26.1 Error Codes الموحّدة

Code	المعنى	HTTP
`SB_1001`	Entitlement exceeded	402
`SB_1002`	Subscription locked	403
`SB_1003`	Invalid source credentials	401
`SB_1004`	Salla rate limited	429
`SB_1005`	AI provider failed	502
`SB_1006`	Product not found	404
`SB_1007`	Duplicate import	409
`SB_2001`	Internal error	500

26.2 Logger

php

final class Logger {
    public function info(string $msg, array $ctx = []): void { $this->write('info', $msg, $ctx); }
    public function error(string $msg, array $ctx = []): void {
        $this->write('error', $msg, $ctx);
        if (function_exists('sentry_capture_exception')) {
            \Sentry\captureMessage($msg, \Sentry\Severity::error());
        }
    }
    private function write(string $level, string $msg, array $ctx): void {
        $file = WP_CONTENT_DIR . '/uploads/sb-logs/' . date('Y-m-d') . ".log";
        wp_mkdir_p(dirname($file));
        @file_put_contents($file, sprintf(
            "[%s] %s: %s %s\n",
            date('c'), strtoupper($level), $msg, wp_json_encode($ctx)
        ), FILE_APPEND | LOCK_EX);
    }
}

🎨 القسم 27: واجهة المستخدم (UI/UX)

27.1 الصفحات الرئيسية

الصفحة	العناصر
Onboarding	Wizard 4 خطوات: حساب → باقة → ربط سلة → أول استيراد
Dashboard	4 بطاقات KPI + رسم + جدول آخر المهام + تنبيه الاشتراك
Import	اختيار مصدر، بحث، فلترة، إضافة للسلة، استيراد بالجملة
Products	جدول 10K صف افتراضي (Virtual Scroll)، فلترة، bulk actions
Categories	شجرة قابلة للسحب، mapping
AI Tools	ترجمة، SEO، إعادة كتابة
Billing	خطط، فواتير، طريقة دفع، إلغاء
Settings	API keys، webhooks، timezone، تفضيلات
Logs	audit + lock events + DLQ

27.2 Stack الواجهة

React 18 + TypeScript
Vite للبناء
Tailwind CSS
TanStack Query للـstate
@wordpress/data للتكامل مع WP admin
RTL native (دعم عربي كامل)

27.3 المكونات المشتركة

<PlanCard>, <QuotaMeter>, <LockBanner>, <SourceSelector>, <ImportWizard>, <ProductTable>, <AiPanel>.

📅 القسم 28: خارطة الطريق (Roadmap)

المرحلة	المدة	المخرجات
v1.0 MVP	8 أسابيع	Core + Salla + 1 source (AliExpress) + Billing + Lock
v1.1	4 أسابيع	3 مصادر إضافية + AI متكامل + Dashboards كاملة
v1.2	4 أسابيع	Multi-store + Mobile API + Webhooks كاملة
v2.0	8 أسابيع	Multi-currency + Marketplace للمواصفات + Plugin SDK
v2.1	4 أسابيع	WhatsApp/Twitter notifications + Auto-scaling on K8s
v3.0	—	Mobile App (Flutter) + Public API للمطورين

✅ القسم 29: Definition of Done (DoD)

لأي مهمة:

□ Unit tests ≥ 80% coverage
□ Integration test للمسار الكامل
□ PHPCS + PHPStan level 6 يمرّان
□ التوثيق محدّث في /docs
□ CHANGELOG.md يذكر التغيير
□ Migration آمنة (rollback متاح)
□ Audit log يسجّل العملية
□ مراجعة أمان (checklist)
□ i18n strings محضّرة
□ Performance مقاس

🧭 القسم 30: الخطوة التالية (Next Action)

للبدء فورًا:

composer create-project أو أنشئ هيكل المجلدات.
انسخ SQL من القسم 22 إلى Installer.php.
نفّذ خطة الـ60 دقيقة (القسم 11).
شغّل CheckSubscriptions يدويًا لاختبار القفل.
اربط أول مصدر (AliExpress) عبر Sandbox.
اختبر دورة: تسجيل → اشتراك → انتهاء → قفل → تجديد → رفع.

هل تريد أن أبدأ الآن بكتابة الكود الفعلي لأي ملف بعينه؟ (مثلًا: Installer.php كاملًا، LockManager.php، Client.php، أو React Dashboard). اختر وابدأ.

🗄️ الجزء 2: قاعدة البيانات

— المواصفة الكاملة

Convention:

Prefix: kosmos_
Engine: InnoDB
Charset: utf8mb4_unicode_ci
كل الجداول لها: id, created_at, updated_at, deleted_at (soft delete)

📋 جدول 1: `kosmos_tenants` — الحسابات الرئيسية

sql

CREATE TABLE kosmos_tenants (
    id              BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    uuid            CHAR(36) NOT NULL UNIQUE,
    slug            VARCHAR(64) NOT NULL UNIQUE,
    name            VARCHAR(191) NOT NULL,
    owner_user_id   BIGINT UNSIGNED NOT NULL,
    plan_slug       VARCHAR(32) NOT NULL DEFAULT 'trial',
    status          ENUM('active','suspended','cancelled','trial') DEFAULT 'trial',
    
    -- Domain & branding
    subdomain       VARCHAR(64) NOT NULL UNIQUE,
    custom_domain   VARCHAR(191) NULL UNIQUE,
    logo_url        VARCHAR(500) NULL,
    primary_color   VARCHAR(7) DEFAULT '#7c3aed',
    
    -- Salla integration
    salla_store_id      VARCHAR(64) NULL,
    salla_access_token  TEXT NULL,
    salla_refresh_token TEXT NULL,
    salla_token_expires DATETIME NULL,
    salla_webhook_secret VARCHAR(64) NULL,
    
    -- Limits (denormalized for speed)
    max_products    INT DEFAULT 100,
    max_users       INT DEFAULT 3,
    max_sources     INT DEFAULT 2,
    ai_credits      INT DEFAULT 500,
    
    -- Trial & billing
    trial_ends_at   DATETIME NULL,
    current_period_start DATETIME NULL,
    current_period_end   DATETIME NULL,
    
    metadata        JSON NULL,
    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at      DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    deleted_at      DATETIME NULL,
    
    INDEX idx_status (status),
    INDEX idx_plan (plan_slug),
    INDEX idx_owner (owner_user_id),
    INDEX idx_trial_end (trial_ends_at),
    INDEX idx_period_end (current_period_end)
) ENGINE=InnoDB;

📋 جدول 2: `kosmos_subscriptions` — الاشتراكات

sql

CREATE TABLE kosmos_subscriptions (
    id                  BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    tenant_id           BIGINT UNSIGNED NOT NULL,
    plan_slug           VARCHAR(32) NOT NULL,
    
    -- Billing cycle
    billing_cycle       ENUM('monthly','yearly','lifetime') NOT NULL,
    amount              DECIMAL(10,2) NOT NULL,
    currency            CHAR(3) DEFAULT 'SAR',
    
    -- Status
    status              ENUM('pending','active','past_due','suspended',
                             'cancelled','expired','paused') DEFAULT 'pending',
    
    -- Periods
    started_at          DATETIME NULL,
    current_period_start DATETIME NOT NULL,
    current_period_end   DATETIME NOT NULL,
    cancelled_at        DATETIME NULL,
    paused_at           DATETIME NULL,
    grace_period_ends_at DATETIME NULL, -- 3 أيام بعد الفشل
    
    -- Payment gateway
    gateway             ENUM('stripe','paypal','moyasar','tap','manual') NOT NULL,
    gateway_subscription_id VARCHAR(191) NULL,
    gateway_customer_id     VARCHAR(191) NULL,
    
    -- Dunning
    failed_payment_count    INT DEFAULT 0,
    last_payment_attempt    DATETIME NULL,
    next_retry_at           DATETIME NULL,
    
    metadata            JSON NULL,
    created_at          DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at          DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    
    FOREIGN KEY (tenant_id) REFERENCES kosmos_tenants(id) ON DELETE CASCADE,
    INDEX idx_tenant_status (tenant_id, status),
    INDEX idx_period_end (current_period_end),
    INDEX idx_grace (grace_period_ends_at),
    INDEX idx_retry (next_retry_at)
) ENGINE=InnoDB;

📋 جدول 3: `kosmos_entitlements` — صلاحيات الوصول (القلب)

sql

CREATE TABLE kosmos_entitlements (
    id              BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    tenant_id       BIGINT UNSIGNED NOT NULL,
    feature_key     VARCHAR(64) NOT NULL, -- 'products.sync', 'ai.tutor', 'export.salla'
    
    -- Scope
    scope_type      ENUM('global','source','target','product') DEFAULT 'global',
    scope_id        BIGINT UNSIGNED NULL,
    
    -- Limits
    limit_value     INT NULL,              -- NULL = unlimited
    used_value      INT DEFAULT 0,
    reset_period    ENUM('never','daily','monthly','yearly') DEFAULT 'monthly',
    last_reset_at   DATETIME NULL,
    
    -- Flags
    is_enabled      TINYINT(1) DEFAULT 1,
    expires_at      DATETIME NULL,
    
    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at      DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    
    FOREIGN KEY (tenant_id) REFERENCES kosmos_tenants(id) ON DELETE CASCADE,
    UNIQUE KEY uk_tenant_feature_scope (tenant_id, feature_key, scope_type, scope_id),
    INDEX idx_feature (feature_key),
    INDEX idx_expires (expires_at)
) ENGINE=InnoDB;

📋 جدول 4: `kosmos_plans` — تعريف الباقات

sql

CREATE TABLE kosmos_plans (
    id              BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    slug            VARCHAR(32) NOT NULL UNIQUE,
    name            VARCHAR(191) NOT NULL,
    description     TEXT NULL,
    
    -- Pricing
    price_monthly   DECIMAL(10,2) NOT NULL,
    price_yearly    DECIMAL(10,2) NOT NULL,
    currency        CHAR(3) DEFAULT 'SAR',
    trial_days      INT DEFAULT 14,
    
    -- Limits (JSON للقراءة السريعة)
    limits          JSON NOT NULL,
    /* مثال:
    {
        "products": 500,
        "sources": 5,
        "targets": 3,
        "users": 10,
        "ai_credits": 5000,
        "storage_mb": 2048
    }
    */
    
    features        JSON NOT NULL,
    /* مثال:
    {
        "salla_integration": true,
        "shopify_integration": true,
        "ai_tutor": true,
        "knowledge_graph": true,
        "white_label": false,
        "api_access": false,
        "priority_support": false
    }
    */
    
    is_active       TINYINT(1) DEFAULT 1,
    sort_order      INT DEFAULT 0,
    
    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at      DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
) ENGINE=InnoDB;

📋 جدول 5: `kosmos_sources` — مصادر المحتوى

sql

CREATE TABLE kosmos_sources (
    id              BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    tenant_id       BIGINT UNSIGNED NOT NULL,
    
    source_type     ENUM('shopify','woocommerce','salla','aliexpress',
                         'amazon','csv','json','api_custom','rss') NOT NULL,
    name            VARCHAR(191) NOT NULL,
    
    -- Credentials (encrypted)
    credentials     TEXT NULL,            -- AES-256 encrypted JSON
    config          JSON NULL,            -- filters, categories, etc.
    
    -- Sync state
    status          ENUM('idle','syncing','error','disabled') DEFAULT 'idle',
    last_sync_at    DATETIME NULL,
    last_error      TEXT NULL,
    sync_frequency  ENUM('manual','hourly','daily','weekly') DEFAULT 'daily',
    next_sync_at    DATETIME NULL,
    
    -- Stats
    total_products  INT DEFAULT 0,
    synced_products INT DEFAULT 0,
    
    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at      DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    deleted_at      DATETIME NULL,
    
    FOREIGN KEY (tenant_id) REFERENCES kosmos_tenants(id) ON DELETE CASCADE,
    INDEX idx_tenant_type (tenant_id, source_type),
    INDEX idx_next_sync (next_sync_at)
) ENGINE=InnoDB;

📋 جدول 6: `kosmos_targets` — قنوات الإخراج (سلة، شوبيفاي…)

sql

CREATE TABLE kosmos_targets (
    id              BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    tenant_id       BIGINT UNSIGNED NOT NULL,
    
    target_type     ENUM('salla','shopify','woocommerce','custom') NOT NULL,
    name            VARCHAR(191) NOT NULL,
    
    -- Credentials
    credentials     TEXT NOT NULL,        -- encrypted
    store_url       VARCHAR(500) NULL,
    store_id        VARCHAR(191) NULL,
    
    -- Sync policy
    auto_publish    TINYINT(1) DEFAULT 0,
    auto_update     TINYINT(1) DEFAULT 1,
    auto_delete     TINYINT(1) DEFAULT 0, -- عند فشل الاشتراك
    
    -- Lock state
    is_locked       TINYINT(1) DEFAULT 0,
    locked_at       DATETIME NULL,
    lock_reason     VARCHAR(64) NULL,     -- 'subscription_expired', 'manual'
    
    -- Stats
    published_count INT DEFAULT 0,
    last_publish_at DATETIME NULL,
    last_error      TEXT NULL,
    
    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at      DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    deleted_at      DATETIME NULL,
    
    FOREIGN KEY (tenant_id) REFERENCES kosmos_tenants(id) ON DELETE CASCADE,
    INDEX idx_tenant_type (tenant_id, target_type),
    INDEX idx_locked (is_locked)
) ENGINE=InnoDB;

📋 جدول 7: `kosmos_products` — كتالوج موحّد

sql

CREATE TABLE kosmos_products (
    id              BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    tenant_id       BIGINT UNSIGNED NOT NULL,
    source_id       BIGINT UNSIGNED NULL,
    
    -- Identity
    external_id     VARCHAR(191) NULL,    -- ID في المصدر
    sku             VARCHAR(100) NULL,
    hash            CHAR(64) NOT NULL,    -- SHA256 للتغييرات
    
    -- Content
    title           VARCHAR(500) NOT NULL,
    description     LONGTEXT NULL,
    short_desc      TEXT NULL,
    
    -- Pricing
    price           DECIMAL(10,2) NULL,
    compare_price   DECIMAL(10,2) NULL,
    cost_price      DECIMAL(10,2) NULL,
    currency        CHAR(3) DEFAULT 'SAR',
    
    -- Inventory
    stock           INT NULL,
    stock_status    ENUM('in_stock','out_of_stock','backorder') DEFAULT 'in_stock',
    
    -- Media
    images          JSON NULL,            -- [{url, alt, order}]
    videos          JSON NULL,
    primary_image   VARCHAR(500) NULL,
    
    -- Categorization
    categories      JSON NULL,            -- [{id, name, path}]
    tags            JSON NULL,
    brand           VARCHAR(191) NULL,
    
    -- Type
    product_type    ENUM('simple','variable','digital','service',
                         'subscription','bundle') DEFAULT 'simple',
    variants        JSON NULL,
    
    -- AI enrichment
    ai_summary      TEXT NULL,
    ai_tags         JSON NULL,
    embedding_id    VARCHAR(64) NULL,     -- Qdrant point ID
    
    -- Sync status
    sync_status     ENUM('pending','synced','outdated','error','locked') DEFAULT 'pending',
    locked_by_subscription TINYINT(1) DEFAULT 0,
    
    metadata        JSON NULL,
    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at      DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    deleted_at      DATETIME NULL,
    
    FOREIGN KEY (tenant_id) REFERENCES kosmos_tenants(id) ON DELETE CASCADE,
    FOREIGN KEY (source_id) REFERENCES kosmos_sources(id) ON DELETE SET NULL,
    UNIQUE KEY uk_tenant_source_external (tenant_id, source_id, external_id),
    INDEX idx_tenant_status (tenant_id, sync_status),
    INDEX idx_hash (hash),
    INDEX idx_locked (locked_by_subscription)
) ENGINE=InnoDB;

📋 جدول 8: `kosmos_publish_log` — سجل النشر

sql

CREATE TABLE kosmos_publish_log (
    id              BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    tenant_id       BIGINT UNSIGNED NOT NULL,
    product_id      BIGINT UNSIGNED NOT NULL,
    target_id       BIGINT UNSIGNED NOT NULL,
    
    action          ENUM('create','update','delete','lock','unlock','skip') NOT NULL,
    status          ENUM('pending','success','failed','retrying') DEFAULT 'pending',
    
    external_id     VARCHAR(191) NULL,    -- ID في الهدف
    request_payload JSON NULL,
    response_body   TEXT NULL,
    error_message   TEXT NULL,
    
    attempts        INT DEFAULT 1,
    duration_ms     INT NULL,
    
    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
    completed_at    DATETIME NULL,
    
    FOREIGN KEY (tenant_id) REFERENCES kosmos_tenants(id) ON DELETE CASCADE,
    FOREIGN KEY (product_id) REFERENCES kosmos_products(id) ON DELETE CASCADE,
    FOREIGN KEY (target_id) REFERENCES kosmos_targets(id) ON DELETE CASCADE,
    INDEX idx_tenant_status (tenant_id, status),
    INDEX idx_target (target_id, created_at),
    INDEX idx_product (product_id, created_at)
) ENGINE=InnoDB;

📋 جدول 9: `kosmos_ai_usage` — استهلاك AI

sql

CREATE TABLE kosmos_ai_usage (
    id              BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    tenant_id       BIGINT UNSIGNED NOT NULL,
    user_id         BIGINT UNSIGNED NULL,
    
    feature         VARCHAR(64) NOT NULL, -- 'tutor', 'enrich', 'translate', 'generate'
    model           VARCHAR(64) NOT NULL,
    provider        ENUM('openai','anthropic','google','local') NOT NULL,
    
    tokens_in       INT UNSIGNED DEFAULT 0,
    tokens_out      INT UNSIGNED DEFAULT 0,
    credits_used    DECIMAL(10,4) DEFAULT 0,
    cost_usd        DECIMAL(10,6) DEFAULT 0,
    
    duration_ms     INT NULL,
    success         TINYINT(1) DEFAULT 1,
    error_message   TEXT NULL,
    
    context_id      VARCHAR(191) NULL,    -- لربطها بمنتج أو محادثة
    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
    
    FOREIGN KEY (tenant_id) REFERENCES kosmos_tenants(id) ON DELETE CASCADE,
    INDEX idx_tenant_date (tenant_id, created_at),
    INDEX idx_feature (feature),
    INDEX idx_user (user_id)
) ENGINE=InnoDB;

📋 جدول 10: `kosmos_audit_log` — الأمان والامتثال

sql

CREATE TABLE kosmos_audit_log (
    id              BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    tenant_id       BIGINT UNSIGNED NULL,
    user_id         BIGINT UNSIGNED NULL,
    
    action          VARCHAR(64) NOT NULL,
    entity_type     VARCHAR(64) NULL,
    entity_id       BIGINT UNSIGNED NULL,
    
    old_value       JSON NULL,
    new_value       JSON NULL,
    
    ip_address      VARCHAR(45) NULL,
    user_agent      VARCHAR(500) NULL,
    
    severity        ENUM('info','warning','error','critical') DEFAULT 'info',
    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
    
    INDEX idx_tenant_date (tenant_id, created_at),
    INDEX idx_entity (entity_type, entity_id),
    INDEX idx_severity (severity, created_at)
) ENGINE=InnoDB;

📋 جدول 11: `kosmos_jobs` — طابور المهام

sql

CREATE TABLE kosmos_jobs (
    id              BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    tenant_id       BIGINT UNSIGNED NOT NULL,
    
    job_type        VARCHAR(64) NOT NULL,  -- 'sync_source', 'publish_product', 'bulk_lock'
    payload         JSON NOT NULL,
    
    status          ENUM('queued','running','completed','failed','cancelled') DEFAULT 'queued',
    priority        TINYINT DEFAULT 5,     -- 1 = highest
    
    attempts        INT DEFAULT 0,
    max_attempts    INT DEFAULT 3,
    
    scheduled_at    DATETIME DEFAULT CURRENT_TIMESTAMP,
    started_at      DATETIME NULL,
    completed_at    DATETIME NULL,
    
    result          JSON NULL,
    error_message   TEXT NULL,
    worker_id       VARCHAR(64) NULL,
    
    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
    
    FOREIGN KEY (tenant_id) REFERENCES kosmos_tenants(id) ON DELETE CASCADE,
    INDEX idx_status_priority (status, priority, scheduled_at),
    INDEX idx_tenant (tenant_id, created_at)
) ENGINE=InnoDB;

📋 جدول 12: `kosmos_webhook_events` — الأحداث الواردة

sql

CREATE TABLE kosmos_webhook_events (
    id              BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    tenant_id       BIGINT UNSIGNED NULL,
    
    source          ENUM('salla','shopify','stripe','paypal','moyasar','internal') NOT NULL,
    event_type      VARCHAR(64) NOT NULL,
    event_id        VARCHAR(191) NULL UNIQUE,
    
    payload         JSON NOT NULL,
    signature       VARCHAR(500) NULL,
    signature_valid TINYINT(1) DEFAULT 0,
    
    processed       TINYINT(1) DEFAULT 0,
    processed_at    DATETIME NULL,
    error_message   TEXT NULL,
    
    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
    
    INDEX idx_source_event (source, event_type),
    INDEX idx_processed (processed, created_at)
) ENGINE=InnoDB;

📊 مخطط العلاقات (ERD)

🧩 الجزء 3: هيكل Plugin الكامل

text

kosmos-studio/
├── kosmos-studio.php                    # Main plugin file
├── composer.json
├── composer.lock
├── readme.txt
├── uninstall.php
├── .env.example
│
├── src/
│   ├── Core/
│   │   ├── Plugin.php                   # Bootstrap
│   │   ├── Container.php                # Simple DI container
│   │   ├── Config.php
│   │   ├── Hooks.php                    # Hook loader
│   │   └── Constants.php
│   │
│   ├── Database/
│   │   ├── Migrator.php
│   │   ├── Schema.php
│   │   ├── QueryBuilder.php
│   │   └── Migrations/
│   │       ├── Migration_001_CreateTenants.php
│   │       ├── Migration_002_CreateSubscriptions.php
│   │       ├── Migration_003_CreateEntitlements.php
│   │       ├── Migration_004_CreatePlans.php
│   │       ├── Migration_005_CreateSources.php
│   │       ├── Migration_006_CreateTargets.php
│   │       ├── Migration_007_CreateProducts.php
│   │       ├── Migration_008_CreatePublishLog.php
│   │       ├── Migration_009_CreateAiUsage.php
│   │       ├── Migration_010_CreateAuditLog.php
│   │       ├── Migration_011_CreateJobs.php
│   │       └── Migration_012_CreateWebhookEvents.php
│   │
│   ├── Domain/
│   │   ├── Tenant/
│   │   │   ├── Tenant.php               # Entity
│   │   │   ├── TenantRepository.php
│   │   │   ├── TenantService.php
│   │   │   └── TenantProvisioner.php    # إنشاء tenant جديد
│   │   │
│   │   ├── Subscription/
│   │   │   ├── Subscription.php
│   │   │   ├── SubscriptionRepository.php
│   │   │   ├── SubscriptionService.php
│   │   │   ├── Plan.php
│   │   │   ├── PlanRepository.php
│   │   │   └── DunningManager.php       # إدارة فشل الدفع
│   │   │
│   │   ├── Entitlement/
│   │   │   ├── Entitlement.php
│   │   │   ├── EntitlementRepository.php
│   │   │   ├── EntitlementService.php   # can(), consume(), grant()
│   │   │   └── Feature.php              # Enum-like
│   │   │
│   │   ├── Product/
│   │   │   ├── Product.php
│   │   │   ├── ProductRepository.php
│   │   │   ├── ProductService.php
│   │   │   └── ProductLockManager.php   # 🔒 قفل المنتجات
│   │   │
│   │   ├── Source/
│   │   │   ├── Source.php
│   │   │   ├── SourceRepository.php
│   │   │   └── Adapters/
│   │   │       ├── SourceAdapterInterface.php
│   │   │       ├── ShopifyAdapter.php
│   │   │       ├── WooCommerceAdapter.php
│   │   │       ├── SallaAdapter.php
│   │   │       ├── AliExpressAdapter.php
│   │   │       ├── CsvAdapter.php
│   │   │       └── CustomApiAdapter.php
│   │   │
│   │   └── Target/
│   │       ├── Target.php
│   │       ├── TargetRepository.php
│   │       └── Publishers/
│   │           ├── TargetPublisherInterface.php
│   │           ├── SallaPublisher.php   # ← الأهم
│   │           ├── ShopifyPublisher.php
│   │           └── WooCommercePublisher.php
│   │
│   ├── Application/
│   │   ├── Bridge/
│   │   │   ├── SyncOrchestrator.php     # يدير عملية السحب
│   │   │   ├── PublishOrchestrator.php  # يدير عملية الدفع
│   │   │   └── LockOrchestrator.php     # 🔒 يدير القفل
│   │   │
│   │   ├── AI/
│   │   │   ├── AIGateway.php
│   │   │   ├── Providers/
│   │   │   │   ├── OpenAIProvider.php
│   │   │   │   ├── AnthropicProvider.php
│   │   │   │   └── LocalProvider.php
│   │   │   ├── Features/
│   │   │   │   ├── ProductEnricher.php
│   │   │   │   ├── TutorAgent.php
│   │   │   │   ├── Translator.php
│   │   │   │   └── DescriptionGenerator.php
│   │   │   └── MeteringService.php
│   │   │
│   │   └── Jobs/
│   │       ├── JobInterface.php
│   │       ├── JobQueue.php
│   │       ├── Worker.php
│   │       └── Handlers/
│   │           ├── SyncSourceJob.php
│   │           ├── PublishProductJob.php
│   │           ├── BulkLockJob.php
│   │           └── RetryPaymentJob.php
│   │
│   ├── Integrations/
│   │   ├── Salla/
│   │   │   ├── SallaClient.php          # HTTP Client
│   │   │   ├── SallaOAuth.php
│   │   │   ├── SallaWebhooks.php
│   │   │   └── SallaMapper.php          # Product → Salla format
│   │   │
│   │   ├── Shopify/
│   │   │   ├── ShopifyClient.php
│   │   │   └── ShopifyMapper.php
│   │   │
│   │   └── Payments/
│   │       ├── StripeGateway.php
│   │       ├── MoyasarGateway.php
│   │       ├── TapGateway.php
│   │       └── PayPalGateway.php
│   │
│   ├── Http/
│   │   ├── Router.php
│   │   ├── Middleware/
│   │   │   ├── AuthMiddleware.php
│   │   │   ├── TenantMiddleware.php     # ← يحدد الـtenant الحالي
│   │   │   ├── EntitlementMiddleware.php# ← يمنع الوصول بدون صلاحية
│   │   │   └── RateLimitMiddleware.php
│   │   └── Controllers/
│   │       ├── AuthController.php
│   │       ├── TenantController.php
│   │       ├── SubscriptionController.php
│   │       ├── SourceController.php
│   │       ├── TargetController.php
│   │       ├── ProductController.php
│   │       ├── AiController.php
│   │       └── WebhookController.php
│   │
│   ├── Admin/
│   │   ├── Menu.php
│   │   ├── Dashboard.php
│   │   ├── Pages/
│   │   │   ├── TenantsPage.php
│   │   │   ├── PlansPage.php
│   │   │   ├── SourcesPage.php
│   │   │   ├── TargetsPage.php
│   │   │   ├── ProductsPage.php
│   │   │   └── SettingsPage.php
│   │   └── Views/
│   │       ├── dashboard.php
│   │       ├── sources-list.php
│   │       ├── products-grid.php
│   │       └── lock-status.php
│   │
│   ├── Frontend/
│   │   ├── Shortcodes/
│   │   │   ├── PricingShortcode.php
│   │   │   ├── DashboardShortcode.php
│   │   │   └── TutorShortcode.php
│   │   ├── Blocks/
│   │   │   ├── PricingBlock.php
│   │   │   └── ProductsBlock.php
│   │   └── Assets/
│   │       ├── css/
│   │       └── js/
│   │
│   ├── Support/
│   │   ├── Logger.php
│   │   ├── Encrypter.php               # AES-256 for credentials
│   │   ├── Validator.php
│   │   ├── Str.php
│   │   ├── Arr.php
│   │   └── Http.php
│   │
│   └── Exceptions/
│       ├── EntitlementException.php
│       ├── SubscriptionExpiredException.php
│       ├── SourceException.php
│       └── TargetException.php
│
├── config/
│   ├── plans.php                        # تعريف الباقات
│   ├── features.php                     # قائمة الميزات
│   └── ai-models.php
│
├── database/
│   └── seeds/
│       ├── PlansSeeder.php
│       └── FeaturesSeeder.php
│
├── tests/
│   ├── Unit/
│   ├── Integration/
│   └── E2E/
│
├── assets/
│   ├── admin/
│   └── public/
│
└── languages/
    ├── kosmos-ar.po
    └── kosmos-en_US.po

💻 الجزء 4: PHP Namespaces & Classes

Convention:

text

KOSMOS\Studio\<Layer>\<Domain>\<Class>

الملف الرئيسي:

php

<?php
/**
 * Plugin Name:  KOSMOS Studio
 * Description:  Subscription-as-a-Service Knowledge & Commerce Bridge
 * Version:      1.0.0
 * Author:       KOSMOS Team
 * Text Domain:  kosmos
 * Requires PHP: 8.2
 * Requires at least: 6.4
 */

declare(strict_types=1);

namespace KOSMOS\Studio;

if (!defined('ABSPATH')) exit;

// Autoload
require_once __DIR__ . '/vendor/autoload.php';

// Constants
define('KOSMOS_VERSION', '1.0.0');
define('KOSMOS_FILE', __FILE__);
define('KOSMOS_PATH', plugin_dir_path(__FILE__));
define('KOSMOS_URL', plugin_dir_url(__FILE__));
define('KOSMOS_DB_VERSION', '1.0.0');

// Boot
Core\Plugin::instance()->boot();

Core\Plugin — نقطة الدخول:

php

<?php
declare(strict_types=1);

namespace KOSMOS\Studio\Core;

use KOSMOS\Studio\Database\Migrator;
use KOSMOS\Studio\Admin\Menu;
use KOSMOS\Studio\Http\Router;
use KOSMOS\Studio\Application\Jobs\Worker;

final class Plugin {
    private static ?self $instance = null;
    private Container $container;
    
    public static function instance(): self {
        return self::$instance ??= new self();
    }
    
    private function __construct() {
        $this->container = new Container();
    }
    
    public function boot(): void {
        // 1. Container bindings
        $this->registerBindings();
        
        // 2. Activation/Deactivation
        register_activation_hook(KOSMOS_FILE, [$this, 'onActivate']);
        register_deactivation_hook(KOSMOS_FILE, [$this, 'onDeactivate']);
        
        // 3. Hooks
        add_action('plugins_loaded', [$this, 'onPluginsLoaded']);
        add_action('init', [$this, 'onInit']);
        add_action('rest_api_init', [$this, 'registerRestRoutes']);
        
        // 4. Workers (background)
        if (defined('KOSMOS_ENABLE_WORKER') && KOSMOS_ENABLE_WORKER) {
            add_action('kosmos_worker_tick', [Worker::class, 'tick']);
        }
    }
    
    private function registerBindings(): void {
        // Core services
        $this->container->singleton(Config::class);
        $this->container->singleton(Hooks::class);
        
        // Domain services
        $this->container->singleton(\KOSMOS\Studio\Domain\Tenant\TenantService::class);
        $this->container->singleton(\KOSMOS\Studio\Domain\Subscription\SubscriptionService::class);
        $this->container->singleton(\KOSMOS\Studio\Domain\Entitlement\EntitlementService::class);
        $this->container->singleton(\KOSMOS\Studio\Domain\Product\ProductLockManager::class);
        
        // Application services
        $this->container->singleton(\KOSMOS\Studio\Application\Bridge\SyncOrchestrator::class);
        $this->container->singleton(\KOSMOS\Studio\Application\Bridge\PublishOrchestrator::class);
        $this->container->singleton(\KOSMOS\Studio\Application\Bridge\LockOrchestrator::class);
        $this->container->singleton(\KOSMOS\Studio\Application\AI\AIGateway::class);
    }
    
    public function onActivate(): void {
        // Run migrations
        (new Migrator())->run();
        
        // Seed plans
        (new \KOSMOS\Studio\Database\Seeds\PlansSeeder())->run();
        
        // Schedule cron
        if (!wp_next_scheduled('kosmos_worker_tick')) {
            wp_schedule_event(time(), 'every_minute', 'kosmos_worker_tick');
        }
        
        // Flush rewrite rules
        flush_rewrite_rules();
        
        // Set DB version
        update_option('kosmos_db_version', KOSMOS_DB_VERSION);
    }
    
    public function onDeactivate(): void {
        wp_clear_scheduled_hook('kosmos_worker_tick');
        flush_rewrite_rules();
    }
    
    public function onPluginsLoaded(): void {
        // Check if WooCommerce is active
        if (!class_exists('WooCommerce')) {
            add_action('admin_notices', function () {
                echo '<div class="error"><p>';
                echo 'KOSMOS Studio requires WooCommerce to be installed.';
                echo '</p></div>';
            });
            return;
        }
        
        // Load translations
        load_plugin_textdomain('kosmos', false, dirname(plugin_basename(KOSMOS_FILE)) . '/languages');
    }
    
    public function onInit(): void {
        // Register post types, taxonomies if needed
        // Register shortcodes
        add_shortcode('kosmos_pricing', [\KOSMOS\Studio\Frontend\Shortcodes\PricingShortcode::class, 'render']);
        add_shortcode('kosmos_dashboard', [\KOSMOS\Studio\Frontend\Shortcodes\DashboardShortcode::class, 'render']);
        add_shortcode('kosmos_tutor', [\KOSMOS\Studio\Frontend\Shortcodes\TutorShortcode::class, 'render']);
    }
    
    public function registerRestRoutes(): void {
        (new Router())->register();
    }
    
    public function container(): Container {
        return $this->container;
    }
}

Domain\Entitlement\EntitlementService — أهم class:

php

<?php
declare(strict_types=1);

namespace KOSMOS\Studio\Domain\Entitlement;

use KOSMOS\Studio\Domain\Tenant\Tenant;
use KOSMOS\Studio\Exceptions\EntitlementException;

/**
 * نقطة القرار المركزية — كل شيء يمر من هنا
 */
final class EntitlementService {
    
    public function __construct(
        private EntitlementRepository $repo
    ) {}
    
    /**
     * هل يمكن للـtenant استخدام الميزة؟
     */
    public function can(int $tenantId, string $featureKey, ?int $scopeId = null): bool {
        $entitlement = $this->repo->find($tenantId, $featureKey, $scopeId);
        
        if (!$entitlement) return false;
        if (!$entitlement->isEnabled()) return false;
        if ($entitlement->isExpired()) return false;
        if ($entitlement->isExhausted()) return false;
        
        return true;
    }
    
    /**
     * استهلك من الحصة
     */
    public function consume(int $tenantId, string $featureKey, int $amount = 1): bool {
        if (!$this->can($tenantId, $featureKey)) {
            throw new EntitlementException(
                "Entitlement exhausted: {$featureKey}"
            );
        }
        
        return $this->repo->increment($tenantId, $featureKey, $amount);
    }
    
    /**
     * امنح/جدّد
     */
    public function grant(int $tenantId, string $featureKey, int $limit, ?int $scopeId = null): void {
        $this->repo->upsert($tenantId, $featureKey, [
            'limit_value' => $limit,
            'used_value'  => 0,
            'is_enabled'  => 1,
            'last_reset_at' => current_time('mysql'),
        ], $scopeId);
    }
    
    /**
     * عزّل كل entitlements عند إلغاء الاشتراك
     */
    public function revokeAll(int $tenantId): void {
        $this->repo->disableAll($tenantId);
    }
    
    /**
     * بطّل الميزات المرتبطة بمصدر معين
     */
    public function revokeForSource(int $tenantId, int $sourceId): void {
        $this->repo->disableByScope($tenantId, 'source', $sourceId);
    }
}

Domain\Product\ProductLockManager — 🔒 قفل المنتجات:

php

<?php
declare(strict_types=1);

namespace KOSMOS\Studio\Domain\Product;

/**
 * المسؤول عن قفل/فتح المنتجات عند الاشتراك/الإلغاء
 */
final class ProductLockManager {
    
    public function __construct(
        private ProductRepository $products,
        private \KOSMOS\Studio\Integrations\Salla\SallaClient $salla,
        private \KOSMOS\Studio\Support\Logger $logger
    ) {}
    
    /**
     * اقفل كل منتجات الـtenant
     */
    public function lockAll(int $tenantId, string $reason = 'subscription_expired'): int {
        $this->logger->warning("Locking all products for tenant {$tenantId}: {$reason}");
        
        // 1. علّم في DB
        $locked = $this->products->lockAll($tenantId);
        
        // 2. أضف job لإخفاء المنتجات من سلة
        foreach ($this->products->getTargetsByTenant($tenantId) as $target) {
            \KOSMOS\Studio\Application\Jobs\JobQueue::push(
                $tenantId,
                'bulk_lock',
                [
                    'target_id' => $target['id'],
                    'action'    => 'hide',
                    'reason'    => $reason,
                ],
                priority: 1
            );
        }
        
        // 3. سجّل الحدث
        do_action('kosmos/products_locked', $tenantId, $locked, $reason);
        
        return $locked;
    }
    
    /**
     * افتح المنتجات عند تجديد الاشتراك
     */
    public function unlockAll(int $tenantId): int {
        $this->logger->info("Unlocking all products for tenant {$tenantId}");
        
        $unlocked = $this->products->unlockAll($tenantId);
        
        foreach ($this->products->getTargetsByTenant($tenantId) as $target) {
            \KOSMOS\Studio\Application\Jobs\JobQueue::push(
                $tenantId,
                'bulk_lock',
                [
                    'target_id' => $target['id'],
                    'action'    => 'show',
                ],
                priority: 1
            );
        }
        
        do_action('kosmos/products_unlocked', $tenantId, $unlocked);
        
        return $unlocked;
    }
    
    /**
     * اقفل مصدراً معيناً (عند حذف/تعطيل مصدر)
     */
    public function lockSource(int $tenantId, int $sourceId): int {
        return $this->products->lockBySource($tenantId, $sourceId);
    }
}

Application\Bridge\LockOrchestrator — المنسق:

php

<?php
declare(strict_types=1);

namespace KOSMOS\Studio\Application\Bridge;

use KOSMOS\Studio\Domain\Product\ProductLockManager;
use KOSMOS\Studio\Domain\Entitlement\EntitlementService;
use KOSMOS\Studio\Domain\Target\TargetRepository;

/**
 * ينسّق عملية القفل الكاملة عند انتهاء الاشتراك
 */
final class LockOrchestrator {
    
    public function __construct(
        private ProductLockManager $lockManager,
        private EntitlementService $entitlements,
        private TargetRepository $targets
    ) {}
    
    /**
     * يُستدعى من cron أو webhook عند انتهاء الاشتراك
     */
    public function handleSubscriptionExpired(int $tenantId): void {
        // 1. عزّل كل الـentitlements
        $this->entitlements->revokeAll($tenantId);
        
        // 2. اقفل كل المنتجات
        $count = $this->lockManager->lockAll($tenantId, 'subscription_expired');
        
        // 3. اقفل كل الـtargets
        $this->targets->lockAll($tenantId, 'subscription_expired');
        
        // 4. سجّل
        do_action('kosmos/subscription_expired_handled', $tenantId, $count);
    }
    
    /**
     * عند تجديد الاشتراك — افتح كل شيء
     */
    public function handleSubscriptionRenewed(int $tenantId): void {
        // 1. جدّد الـentitlements بناءً على الباقة
        $this->entitlements->grantFromPlan($tenantId);
        
        // 2. افتح المنتجات
        $this->lockManager->unlockAll($tenantId);
        
        // 3. افتح الـtargets
        $this->targets->unlockAll($tenantId);
        
        do_action('kosmos/subscription_renewed_handled', $tenantId);
    }
}

Integrations\Salla\SallaPublisher — النشر في سلة:

php

<?php
declare(strict_types=1);

namespace KOSMOS\Studio\Integrations\Salla;

use KOSMOS\Studio\Domain\Product\Product;
use KOSMOS\Studio\Domain\Target\Target;

/**
 * مسؤول عن نشر/إخفاء/تحديث المنتجات في متجر سلة
 */
final class SallaPublisher {
    
    public function __construct(
        private SallaClient $client,
        private SallaMapper $mapper
    ) {}
    
    /**
     * انشر منتجاً جديداً في سلة
     */
    public function publish(Target $target, Product $product): array {
        $payload = $this->mapper->toSalla($product);
        
        $response = $this->client
            ->forTarget($target)
            ->post('/products', $payload);
        
        if ($response['success'] ?? false) {
            return [
                'success'     => true,
                'external_id' => $response['data']['id'] ?? null,
            ];
        }
        
        return ['success' => false, 'error' => $response['message'] ?? 'unknown'];
    }
    
    /**
     * حدّث منتجاً موجوداً
     */
    public function update(Target $target, Product $product, string $externalId): array {
        $payload = $this->mapper->toSalla($product);
        
        $response = $this->client
            ->forTarget($target)
            ->put("/products/{$externalId}", $payload);
        
        return [
            'success' => $response['success'] ?? false,
            'error'   => $response['message'] ?? null,
        ];
    }
    
    /**
     * 🔒 أخفِ منتجاً (عند انتهاء الاشتراك)
     */
    public function hide(Target $target, string $externalId): bool {
        $response = $this->client
            ->forTarget($target)
            ->put("/products/{$externalId}", [
                'status'     => 'hidden',
                'visibility' => 'hidden',
            ]);
        
        return $response['success'] ?? false;
    }
    
    /**
     * أظهر منتجاً (عند التجديد)
     */
    public function show(Target $target, string $externalId): bool {
        $response = $this->client
            ->forTarget($target)
            ->put("/products/{$externalId}", [
                'status'     => 'sale',
                'visibility' => 'visible',
            ]);
        
        return $response['success'] ?? false;
    }
    
    /**
     * احذف منتجاً
     */
    public function delete(Target $target, string $externalId): bool {
        $response = $this->client
            ->forTarget($target)
            ->delete("/products/{$externalId}");
        
        return $response['success'] ?? false;
    }
    
    /**
     * 🔒 اقفل تصنيفاً كاملاً (categories hidden)
     */
    public function hideCategory(Target $target, string $categoryId): bool {
        $response = $this->client
            ->forTarget($target)
            ->put("/categories/{$categoryId}", [
                'status' => 'hidden',
            ]);
        
        return $response['success'] ?? false;
    }
    
    /**
     * اجلب المنتجات من سلة (للـsync العكسي)
     */
    public function listProducts(Target $target, int $page = 1): array {
        return $this->client
            ->forTarget($target)
            ->get('/products', ['page' => $page, 'per_page' => 50]);
    }
}

Integrations\Salla\SallaClient:

php

<?php
declare(strict_types=1);

namespace KOSMOS\Studio\Integrations\Salla;

use KOSMOS\Studio\Domain\Target\Target;
use KOSMOS\Studio\Support\Http;

final class SallaClient {
    
    private const BASE_URL = 'https://api.salla.dev/admin/v2';
    
    private ?Target $target = null;
    
    public function forTarget(Target $target): self {
        $clone = clone $this;
        $clone->target = $target;
        return $clone;
    }
    
    public function get(string $path, array $query = []): array {
        return $this->request('GET', $path, $query);
    }
    
    public function post(string $path, array $body = []): array {
        return $this->request('POST', $path, [], $body);
    }
    
    public function put(string $path, array $body = []): array {
        return $this->request('PUT', $path, [], $body);
    }
    
    public function delete(string $path): array {
        return $this->request('DELETE', $path);
    }
    
    private function request(string $method, string $path, array $query = [], array $body = []): array {
        if (!$this->target) {
            throw new \RuntimeException('No target set. Use forTarget() first.');
        }
        
        $creds = json_decode(
            \KOSMOS\Studio\Support\Encrypter::decrypt($this->target->credentials),
            true
        );
        
        $token = $creds['access_token'] ?? '';
        
        // Handle token refresh if needed
        if ($this->isTokenExpired($creds)) {
            $token = $this->refreshToken($this->target, $creds);
        }
        
        $url = self::BASE_URL . $path;
        if ($query) $url .= '?' . http_build_query($query);
        
        $response = Http::request($method, $url, [
            'headers' => [
                'Authorization' => "Bearer {$token}",
                'Content-Type'  => 'application/json',
                'Accept'        => 'application/json',
            ],
            'body' => $body ? wp_json_encode($body) : null,
            'timeout' => 30,
        ]);
        
        // Log for audit
        \KOSMOS\Studio\Support\Logger::debug("Salla API {$method} {$path}", [
            'status' => $response['status'] ?? null,
        ]);
        
        return $response;
    }
    
    private function isTokenExpired(array $creds): bool {
        return isset($creds['expires_at']) 
            && strtotime($creds['expires_at']) < time() + 300;
    }
    
    private function refreshToken(Target $target, array $creds): string {
        $response = Http::post('https://accounts.salla.sa/oauth2/token', [
            'grant_type'    => 'refresh_token',
            'refresh_token' => $creds['refresh_token'],
            'client_id'     => get_option('kosmos_salla_client_id'),
            'client_secret' => get_option('kosmos_salla_client_secret'),
        ]);
        
        $newCreds = array_merge($creds, [
            'access_token'  => $response['access_token'],
            'refresh_token' => $response['refresh_token'] ?? $creds['refresh_token'],
            'expires_at'    => date('c', time() + ($response['expires_in'] ?? 3600)),
        ]);
        
        $target->updateCredentials(\KOSMOS\Studio\Support\Encrypter::encrypt(
            wp_json_encode($newCreds)
        ));
        
        return $newCreds['access_token'];
    }
}

🌐 الجزء 5: REST API Endpoints الكاملة

Base URL: `/wp-json/kosmos/v1/`

Convention:

Auth: Authorization: Bearer <jwt> أو WP Nonce
Tenant: يُحدد تلقائياً من الـuser
Rate limit: 100 req/min/tenant
Response: JSON موحد

Response Envelope:

json

{
  "success": true,
  "data": { ... },
  "meta": { "page": 1, "total": 100 }
}

json

{
  "success": false,
  "error": {
    "code": "entitlement_exhausted",
    "message": "Your plan has reached the limit for products",
    "details": { "feature": "products.sync", "limit": 500, "used": 500 }
  }
}

📋 جدول Endpoints الكامل:

Method	Endpoint	Description	Auth	Entitlement
Auth
POST	`/auth/register`	تسجيل tenant جديد	❌	—
POST	`/auth/login`	تسجيل دخول	❌	—
POST	`/auth/refresh`	تحديث JWT	✅	—
GET	`/auth/me`	معلومات المستخدم	✅	—
Tenants
GET	`/tenant`	بيانات الـtenant الحالي	✅	—
PATCH	`/tenant`	تحديث البيانات	✅	—
GET	`/tenant/usage`	استهلاك الحصص	✅	—
GET	`/tenant/limits`	الحدود الحالية	✅	—
Subscriptions
GET	`/plans`	قائمة الباقات	❌	—
GET	`/subscription`	اشتراكي الحالي	✅	—
POST	`/subscription/checkout`	إنشاء جلسة دفع	✅	—
POST	`/subscription/cancel`	إلغاء	✅	—
POST	`/subscription/resume`	استئناف	✅	—
POST	`/subscription/upgrade`	ترقية	✅	—
Sources
GET	`/sources`	قائمة المصادر	✅	`sources.list`
POST	`/sources`	إضافة مصدر	✅	`sources.create`
GET	`/sources/{id}`	تفاصيل مصدر	✅	`sources.view`
PATCH	`/sources/{id}`	تحديث	✅	`sources.update`
DELETE	`/sources/{id}`	حذف	✅	`sources.delete`
POST	`/sources/{id}/test`	اختبار الاتصال	✅	`sources.test`
POST	`/sources/{id}/sync`	بدء sync يدوي	✅	`sources.sync`
GET	`/sources/{id}/status`	حالة الـsync	✅	`sources.view`
Targets
GET	`/targets`	قائمة الأهداف	✅	`targets.list`
POST	`/targets`	إضافة هدف (سلة)	✅	`targets.create`
POST	`/targets/salla/oauth`	OAuth مع سلة	✅	`targets.create`
GET	`/targets/{id}`	تفاصيل	✅	`targets.view`
DELETE	`/targets/{id}`	حذف	✅	`targets.delete`
POST	`/targets/{id}/test`	اختبار	✅	`targets.test`
POST	`/targets/{id}/publish-all`	نشر الكل	✅	`targets.publish`
Products
GET	`/products`	قائمة المنتجات	✅	`products.list`
GET	`/products/{id}`	تفاصيل	✅	`products.view`
POST	`/products`	إنشاء يدوي	✅	`products.create`
PATCH	`/products/{id}`	تحديث	✅	`products.update`
DELETE	`/products/{id}`	حذف	✅	`products.delete`
POST	`/products/{id}/publish`	نشر لمنصة	✅	`products.publish`
POST	`/products/bulk-publish`	نشر جماعي	✅	`products.bulk_publish`
GET	`/products/{id}/lock-status`	🔒 حالة القفل	✅	`products.view`
AI
POST	`/ai/tutor`	محادثة AI	✅	`ai.tutor`
POST	`/ai/enrich`	تحسين منتج	✅	`ai.enrich`
POST	`/ai/translate`	ترجمة	✅	`ai.translate`
POST	`/ai/generate-description`	توليد وصف	✅	`ai.generate`
GET	`/ai/usage`	استهلاك AI	✅	—
Webhooks
POST	`/webhooks/salla`	webhooks من سلة	signature	—
POST	`/webhooks/stripe`	webhooks من Stripe	signature	—
POST	`/webhooks/moyasar`	webhooks من Moyasar	signature	—
Admin (requires admin)
GET	`/admin/tenants`	كل الـtenants	✅ admin	—
GET	`/admin/jobs`	حالة الطوابير	✅ admin	—
POST	`/admin/jobs/{id}/retry`	إعادة محاولة	✅ admin	—
GET	`/admin/audit`	سجل التدقيق	✅ admin	—
Health
GET	`/health`	صحة الخدمة	❌	—
GET	`/metrics`	مقاييس Prometheus	❌	—

مثال تطبيقي — Sync Endpoint:

php

<?php
declare(strict_types=1);

namespace KOSMOS\Studio\Http\Controllers;

use KOSMOS\Studio\Application\Jobs\JobQueue;
use KOSMOS\Studio\Domain\Entitlement\EntitlementService;

final class SourceController {
    
    public function __construct(
        private \KOSMOS\Studio\Domain\Source\SourceService $sources,
        private EntitlementService $entitlements
    ) {}
    
    /**
     * POST /sources/{id}/sync
     */
    public function sync(\WP_REST_Request $req): \WP_REST_Response {
        $tenantId = get_current_user_id(); // simplified
        $sourceId = (int) $req->get_param('id');
        
        // 1. تحقق من الاشتراك
        if (!$this->entitlements->can($tenantId, 'sources.sync')) {
            return new \WP_REST_Response([
                'success' => false,
                'error' => [
                    'code'    => 'entitlement_exhausted',
                    'message' => 'Sync limit reached. Upgrade your plan.',
                ],
            ], 402);
        }
        
        // 2. تحقق من حد المصادر
        $source = $this->sources->find($sourceId, $tenantId);
        if (!$source) {
            return new \WP_REST_Response([
                'success' => false,
                'error'   => ['code' => 'not_found'],
            ], 404);
        }
        
        // 3. ادفع job
        $jobId = JobQueue::push($tenantId, 'sync_source', [
            'source_id' => $sourceId,
            'mode'      => $req->get_param('mode') ?? 'full',
        ]);
        
        // 4. استهلك من الحصة
        $this->entitlements->consume($tenantId, 'sources.sync');
        
        return new \WP_REST_Response([
            'success' => true,
            'data' => [
                'job_id'  => $jobId,
                'status'  => 'queued',
                'poll_url' => "/wp-json/kosmos/v1/jobs/{$jobId}",
            ],
        ], 202);
    }
}

🔐 الجزء 6: Roles & Capabilities

Custom Roles:

php

<?php
// يُنفّذ عند activation
function kosmos_register_roles(): void {
    
    // 1. Platform Owner — مالك المنصة
    add_role('kosmos_owner', 'KOSMOS Owner', [
        'read'                    => true,
        'kosmos_manage_platform'  => true,
        'kosmos_manage_tenants'   => true,
        'kosmos_manage_plans'     => true,
        'kosmos_view_audit'       => true,
        'kosmos_manage_workers'   => true,
    ]);
    
    // 2. Tenant Admin — مدير حساب
    add_role('kosmos_tenant_admin', 'Tenant Admin', [
        'read'                    => true,
        'kosmos_manage_tenant'    => true,
        'kosmos_manage_sources'   => true,
        'kosmos_manage_targets'   => true,
        'kosmos_manage_products'  => true,
        'kosmos_manage_billing'   => true,
        'kosmos_use_ai'           => true,
        'kosmos_invite_users'     => true,
    ]);
    
    // 3. Tenant Editor — محرر
    add_role('kosmos_tenant_editor', 'Tenant Editor', [
        'read'                    => true,
        'kosmos_manage_sources'   => true,
        'kosmos_manage_products'  => true,
        'kosmos_use_ai'           => true,
    ]);
    
    // 4. Tenant Viewer — مشاهد فقط
    add_role('kosmos_tenant_viewer', 'Tenant Viewer', [
        'read'                    => true,
        'kosmos_view_products'    => true,
    ]);
    
    // 5. API Consumer — وصول API فقط
    add_role('kosmos_api', 'API Consumer', [
        'read'                    => true,
        'kosmos_api_access'       => true,
    ]);
}

Capabilities المخصصة:

php

<?php
// يُنفّذ عند activation
function kosmos_register_capabilities(): void {
    $caps = [
        // Platform-level
        'kosmos_manage_platform',
        'kosmos_manage_tenants',
        'kosmos_manage_plans',
        'kosmos_view_audit',
        'kosmos_manage_workers',
        
        // Tenant-level
        'kosmos_manage_tenant',
        'kosmos_manage_billing',
        'kosmos_invite_users',
        
        // Sources
        'kosmos_manage_sources',
        'kosmos_sync_sources',
        
        // Targets
        'kosmos_manage_targets',
        'kosmos_publish_products',
        
        // Products
        'kosmos_manage_products',
        'kosmos_view_products',
        'kosmos_bulk_publish',
        
        // AI
        'kosmos_use_ai',
        'kosmos_manage_ai_settings',
        
        // API
        'kosmos_api_access',
    ];
    
    // امنح كل الصلاحيات للمدير العام
    $admin = get_role('administrator');
    foreach ($caps as $cap) {
        $admin->add_cap($cap);
    }
}

مصفوفة الصلاحيات:

Capability	Owner	Tenant Admin	Editor	Viewer	API
`kosmos_manage_platform`	✅	❌	❌	❌	❌
`kosmos_manage_tenants`	✅	❌	❌	❌	❌
`kosmos_manage_tenant`	✅	✅	❌	❌	❌
`kosmos_manage_billing`	✅	✅	❌	❌	❌
`kosmos_manage_sources`	✅	✅	✅	❌	❌
`kosmos_manage_targets`	✅	✅	❌	❌	❌
`kosmos_publish_products`	✅	✅	❌	❌	❌
`kosmos_manage_products`	✅	✅	✅	❌	❌
`kosmos_view_products`	✅	✅	✅	✅	✅
`kosmos_use_ai`	✅	✅	✅	❌	❌
`kosmos_api_access`	✅	❌	❌	❌	✅

💳 الجزء 7: نظام الباقات والـEntitlements

الباقات (Plans):

php

<?php
// config/plans.php
return [
    'trial' => [
        'name'          => 'تجريبي',
        'description'   => '14 يوماً لتجربة كل الميزات',
        'price_monthly' => 0,
        'price_yearly'  => 0,
        'trial_days'    => 14,
        'limits' => [
            'products'   => 50,
            'sources'    => 1,
            'targets'    => 1,
            'users'      => 1,
            'ai_credits' => 100,
            'storage_mb' => 256,
        ],
        'features' => [
            'salla_integration'   => true,
            'shopify_integration' => false,
            'ai_tutor'            => true,
            'knowledge_graph'     => true,
            'white_label'         => false,
            'api_access'          => false,
            'priority_support'    => false,
            'custom_domain'       => false,
        ],
    ],
    
    'starter' => [
        'name'          => 'المبتدئ',
        'description'   => 'للتجار الأفراد',
        'price_monthly' => 99,
        'price_yearly'  => 990,
        'trial_days'    => 7,
        'limits' => [
            'products'   => 500,
            'sources'    => 2,
            'targets'    => 1,
            'users'      => 1,
            'ai_credits' => 1000,
            'storage_mb' => 1024,
        ],
        'features' => [
            'salla_integration'   => true,
            'shopify_integration' => true,
            'ai_tutor'            => true,
            'knowledge_graph'     => true,
            'white_label'         => false,
            'api_access'          => false,
            'priority_support'    => false,
            'custom_domain'       => false,
        ],
    ],
    
    'professional' => [
        'name'          => 'الاحترافي',
        'description'   => 'للوكالات الصغيرة',
        'price_monthly' => 299,
        'price_yearly'  => 2990,
        'trial_days'    => 7,
        'limits' => [
            'products'   => 5000,
            'sources'    => 5,
            'targets'    => 3,
            'users'      => 5,
            'ai_credits' => 5000,
            'storage_mb' => 10240,
        ],
        'features' => [
            'salla_integration'   => true,
            'shopify_integration' => true,
            'ai_tutor'            => true,
            'knowledge_graph'     => true,
            'white_label'         => false,
            'api_access'          => true,
            'priority_support'    => true,
            'custom_domain'       => true,
        ],
    ],
    
    'enterprise' => [
        'name'          => 'المؤسسي',
        'description'   => 'للشركات الكبيرة',
        'price_monthly' => 999,
        'price_yearly'  => 9990,
        'trial_days'    => 14,
        'limits' => [
            'products'   => -1, // unlimited
            'sources'    => -1,
            'targets'    => -1,
            'users'      => -1,
            'ai_credits' => 50000,
            'storage_mb' => -1,
        ],
        'features' => [
            'salla_integration'   => true,
            'shopify_integration' => true,
            'ai_tutor'            => true,
            'knowledge_graph'     => true,
            'white_label'         => true,
            'api_access'          => true,
            'priority_support'    => true,
            'custom_domain'       => true,
            'sla'                 => true,
            'dedicated_support'   => true,
        ],
    ],
];

Feature Keys:

php

<?php
// config/features.php
return [
    // Quantifiable
    'products.sync'       => ['type' => 'quota', 'unit' => 'product'],
    'products.publish'    => ['type' => 'quota', 'unit' => 'product'],
    'sources.create'      => ['type' => 'quota', 'unit' => 'source'],
    'sources.sync'        => ['type' => 'quota', 'unit' => 'sync'],
    'targets.create'      => ['type' => 'quota', 'unit' => 'target'],
    'users.invite'        => ['type' => 'quota', 'unit' => 'user'],
    'ai.credits'          => ['type' => 'metered', 'unit' => 'credit'],
    'storage.bytes'       => ['type' => 'quota', 'unit' => 'mb'],
    
    // Boolean
    'salla_integration'   => ['type' => 'boolean'],
    'shopify_integration' => ['type' => 'boolean'],
    'ai_tutor'            => ['type' => 'boolean'],
    'knowledge_graph'     => ['type' => 'boolean'],
    'white_label'         => ['type' => 'boolean'],
    'api_access'          => ['type' => 'boolean'],
    'custom_domain'       => ['type' => 'boolean'],
    'priority_support'    => ['type' => 'boolean'],
];

Entitlement Middleware:

php

<?php
declare(strict_types=1);

namespace KOSMOS\Studio\Http\Middleware;

use KOSMOS\Studio\Domain\Entitlement\EntitlementService;

/**
 * يمنع الوصول للـendpoints بدون صلاحية
 * يُستخدم عبر: ->middleware('entitlement:sources.sync')
 */
final class EntitlementMiddleware {
    
    public function __construct(
        private EntitlementService $entitlements
    ) {}
    
    public function handle(\WP_REST_Request $req, string $featureKey): bool|\WP_Error {
        $tenantId = get_current_user_id();
        
        if (!$this->entitlements->can($tenantId, $featureKey)) {
            return new \WP_Error(
                'entitlement_exhausted',
                'Your subscription does not allow this action',
                [
                    'status'  => 402,
                    'feature' => $featureKey,
                    'limits'  => $this->entitlements->getLimits($tenantId),
                    'upgrade' => '/pricing',
                ]
            );
        }
        
        return true;
    }
}

🔗 الجزء 8: WooCommerce Hooks Integration

Hooks المستمع إليها:

php

<?php
// src/Integrations/WooCommerce/Hooks.php
declare(strict_types=1);

namespace KOSMOS\Studio\Integrations\WooCommerce;

use KOSMOS\Studio\Application\Bridge\LockOrchestrator;
use KOSMOS\Studio\Domain\Subscription\SubscriptionService;

final class Hooks {
    
    public function __construct(
        private SubscriptionService $subscriptions,
        private LockOrchestrator $locker
    ) {}
    
    public function register(): void {
        // ===== Subscription lifecycle =====
        add_action('woocommerce_subscription_status_active',
            [$this, 'onActive'], 10, 1);
        add_action('woocommerce_subscription_status_pending-cancel',
            [$this, 'onPendingCancel'], 10, 1);
        add_action('woocommerce_subscription_status_cancelled',
            [$this, 'onCancelled'], 10, 1);
        add_action('woocommerce_subscription_status_expired',
            [$this, 'onExpired'], 10, 1);
        add_action('woocommerce_subscription_status_on-hold',
            [$this, 'onHold'], 10, 1);
        
        // ===== Renewal =====
        add_action('woocommerce_subscription_renewal_payment_complete',
            [$this, 'onRenewalComplete'], 10, 2);
        add_action('woocommerce_subscription_renewal_payment_failed',
            [$this, 'onRenewalFailed'], 10, 2);
        
        // ===== Order =====
        add_action('woocommerce_order_status_completed',
            [$this, 'onOrderCompleted'], 10, 1);
        add_action('woocommerce_order_refunded',
            [$this, 'onRefunded'], 10, 2);
        
        // ===== Product =====
        add_action('woocommerce_product_set_stock',
            [$this, 'onStockChange'], 10, 1);
        
        // ===== Cron =====
        add_action('kosmos/check_expirations', [$this, 'checkExpirations']);
    }
    
    public function onActive($subscription): void {
        $tenantId = $this->resolveTenantId($subscription);
        $this->subscriptions->markActive($subscription->get_id());
        $this->locker->handleSubscriptionRenewed($tenantId);
    }
    
    public function onExpired($subscription): void {
        $tenantId = $this->resolveTenantId($subscription);
        $this->subscriptions->markExpired($subscription->get_id());
        $this->locker->handleSubscriptionExpired($tenantId);
    }
    
    public function onCancelled($subscription): void {
        // لا نقفل فوراً — ننتظر انتهاء الفترة المدفوعة
        $tenantId = $this->resolveTenantId($subscription);
        $this->subscriptions->markCancelled($subscription->get_id());
        
        // جدول فحص بعد انتهاء الفترة
        wp_schedule_single_event(
            $subscription->get_date('end')->getTimestamp() + 3600,
            'kosmos/check_expirations',
            [$tenantId]
        );
    }
    
    public function onHold($subscription): void {
        $tenantId = $this->resolveTenantId($subscription);
        // امنح 3 أيام grace period
        $graceEnds = time() + (3 * DAY_IN_SECONDS);
        $this->subscriptions->setGracePeriod($subscription->get_id(), $graceEnds);
    }
    
    public function onRenewalFailed($subscription, $lastOrder): void {
        $tenantId = $this->resolveTenantId($subscription);
        $this->subscriptions->incrementFailedPayments($subscription->get_id());
        
        $fails = $this->subscriptions->getFailedCount($subscription->get_id());
        
        // 3 محاولات → ثم القفل
        if ($fails >= 3) {
            $this->locker->handleSubscriptionExpired($tenantId);
        }
    }
    
    public function checkExpirations(?int $tenantId = null): void {
        if ($tenantId) {
            $sub = $this->subscriptions->getActiveByTenant($tenantId);
            if ($sub && $sub->current_period_end < time()) {
                $this->locker->handleSubscriptionExpired($tenantId);
            }
            return;
        }
        
        // فحص جماعي
        foreach ($this->subscriptions->getAllExpiring() as $sub) {
            $this->locker->handleSubscriptionExpired($sub->tenant_id);
        }
    }
    
    private function resolveTenantId($subscription): int {
        $userId = $subscription->get_user_id();
        return (int) get_user_meta($userId, '_kosmos_tenant_id', true);
    }
}

Cron Schedule مخصص:

php

<?php
// إضافة فترات cron مخصصة
add_filter('cron_schedules', function ($schedules) {
    $schedules['every_minute'] = [
        'interval' => 60,
        'display'  => 'Every Minute',
    ];
    $schedules['every_five_minutes'] = [
        'interval' => 300,
        'display'  => 'Every 5 Minutes',
    ];
    return $schedules;
});

// تسجيل أحداث cron
add_action('init', function () {
    if (!wp_next_scheduled('kosmos/check_expirations')) {
        wp_schedule_event(time(), 'hourly', 'kosmos/check_expirations');
    }
    if (!wp_next_scheduled('kosmos/worker_tick')) {
        wp_schedule_event(time(), 'every_minute', 'kosmos/worker_tick');
    }
});

🤖 الجزء 9: AI Gateway الكامل

php

<?php
declare(strict_types=1);

namespace KOSMOS\Studio\Application\AI;

use KOSMOS\Studio\Application\AI\Providers\ProviderInterface;
use KOSMOS\Studio\Domain\Entitlement\EntitlementService;
use KOSMOS\Studio\Support\Logger;

/**
 * نقطة دخول واحدة لكل استدعاءات AI
 */
final class AIGateway {
    
    /** @var array<string,ProviderInterface> */
    private array $providers = [];
    
    public function __construct(
        private EntitlementService $entitlements,
        private Logger $logger
    ) {}
    
    public function registerProvider(string $name, ProviderInterface $provider): void {
        $this->providers[$name] = $provider;
    }
    
    /**
     * @param string $feature tutor|enrich|translate|generate
     */
    public function call(
        int $tenantId,
        string $feature,
        array $payload,
        ?string $preferredProvider = null
    ): array {
        // 1. تحقق من الصلاحية
        $featureKey = "ai.{$feature}";
        if (!$this->entitlements->can($tenantId, $featureKey)) {
            return [
                'success' => false,
                'error'   => [
                    'code'    => 'entitlement_exhausted',
                    'message' => 'AI credits exhausted. Please upgrade.',
                ],
            ];
        }
        
        // 2. اختر المزود
        $providerName = $preferredProvider ?? $this->selectProvider($feature);
        $provider = $this->providers[$providerName] ?? null;
        
        if (!$provider) {
            return [
                'success' => false,
                'error'   => ['code' => 'provider_unavailable'],
            ];
        }
        
        // 3. نفّذ
        $start = microtime(true);
        try {
            $result = $provider->execute($feature, $payload);
            $duration = (int) ((microtime(true) - $start) * 1000);
            
            // 4. استهلك
            $credits = $this->calculateCredits($result['tokens'] ?? 0);
            $this->entitlements->consume($tenantId, $featureKey, $credits);
            
            // 5. سجّل
            $this->logUsage($tenantId, $feature, $providerName, $result, $duration);
            
            return [
                'success' => true,
                'data'    => $result['data'] ?? $result,
                'meta' => [
                    'provider'     => $providerName,
                    'tokens'       => $result['tokens'] ?? 0,
                    'credits_used' => $credits,
                    'duration_ms'  => $duration,
                ],
            ];
        } catch (\Throwable $e) {
            $this->logger->error('AI call failed', [
                'feature'  => $feature,
                'provider' => $providerName,
                'error'    => $e->getMessage(),
            ]);
            
            return [
                'success' => false,
                'error'   => [
                    'code'    => 'ai_provider_error',
                    'message' => $e->getMessage(),
                ],
            ];
        }
    }
    
    private function selectProvider(string $feature): string {
        // يمكن أن يكون ذكياً: حسب التكلفة/السرعة/الجودة
        $map = [
            'tutor'      => 'openai',
            'enrich'     => 'openai',
            'translate'  => 'google',
            'generate'   => 'openai',
        ];
        return $map[$feature] ?? 'openai';
    }
    
    private function calculateCredits(int $tokens): float {
        // 1000 tokens = 1 credit
        return round($tokens / 1000, 4);
    }
    
    private function logUsage(int $tenantId, string $feature, string $provider, array $result, int $duration): void {
        global $wpdb;
        $wpdb->insert("{$wpdb->prefix}kosmos_ai_usage", [
            'tenant_id'    => $tenantId,
            'feature'      => $feature,
            'model'        => $result['model'] ?? 'unknown',
            'provider'     => $provider,
            'tokens_in'    => $result['tokens_in'] ?? 0,
            'tokens_out'   => $result['tokens_out'] ?? 0,
            'credits_used' => $this->calculateCredits($result['tokens'] ?? 0),
            'cost_usd'     => $result['cost'] ?? 0,
            'duration_ms'  => $duration,
            'success'      => 1,
        ]);
    }
}

Provider Interface + OpenAI:

php

<?php
declare(strict_types=1);

namespace KOSMOS\Studio\Application\AI\Providers;

interface ProviderInterface {
    public function execute(string $feature, array $payload): array;
    public function name(): string;
}

php

<?php
declare(strict_types=1);

namespace KOSMOS\Studio\Application\AI\Providers;

use OpenAI\Client;

final class OpenAIProvider implements ProviderInterface {
    
    private Client $client;
    
    public function __construct() {
        $apiKey = get_option('kosmos_openai_key') ?: getenv('OPENAI_API_KEY');
        $this->client = \OpenAI::client($apiKey);
    }
    
    public function name(): string {
        return 'openai';
    }
    
    public function execute(string $feature, array $payload): array {
        return match($feature) {
            'tutor'    => $this->tutor($payload),
            'enrich'   => $this->enrich($payload),
            'generate' => $this->generate($payload),
            default    => throw new \InvalidArgumentException("Unknown feature: {$feature}"),
        };
    }
    
    private function tutor(array $payload): array {
        $messages = [
            ['role' => 'system', 'content' => 'أنت KOSMOS Tutor...'],
        ];
        
        if (!empty($payload['context'])) {
            $messages[] = ['role' => 'system', 'content' => "السياق:\n{$payload['context']}"];
        }
        
        foreach ($payload['history'] ?? [] as $msg) {
            $messages[] = $msg;
        }
        
        $messages[] = ['role' => 'user', 'content' => $payload['query']];
        
        $response = $this->client->chat()->create([
            'model'       => 'gpt-4o-mini',
            'messages'    => $messages,
            'temperature' => 0.3,
            'max_tokens'  => 900,
        ]);
        
        return [
            'data'       => $response->choices[0]->message->content,
            'tokens'     => $response->usage->totalTokens,
            'tokens_in'  => $response->usage->promptTokens,
            'tokens_out' => $response->usage->completionTokens,
            'model'      => 'gpt-4o-mini',
            'cost'       => $this->calculateCost($response->usage),
        ];
    }
    
    private function enrich(array $payload): array {
        $product = $payload['product'] ?? [];
        
        $response = $this->client->chat()->create([
            'model'    => 'gpt-4o-mini',
            'messages' => [
                ['role' => 'system', 'content' => 'أنت خبير تجارة إلكترونية. حسّن بيانات المنتج.'],
                ['role' => 'user', 'content' => wp_json_encode($product)],
            ],
            'response_format' => ['type' => 'json_object'],
        ]);
        
        return [
            'data'   => json_decode($response->choices[0]->message->content, true),
            'tokens' => $response->usage->totalTokens,
            'model'  => 'gpt-4o-mini',
        ];
    }
    
    private function generate(array $payload): array {
        $response = $this->client->chat()->create([
            'model'    => 'gpt-4o-mini',
            'messages' => [
                ['role' => 'user', 'content' => $payload['prompt'] ?? ''],
            ],
        ]);
        
        return [
            'data'   => $response->choices[0]->message->content,
            'tokens' => $response->usage->totalTokens,
            'model'  => 'gpt-4o-mini',
        ];
    }
    
    private function calculateCost(object $usage): float {
        // $0.15/1M input, $0.60/1M output (gpt-4o-mini)
        return ($usage->promptTokens * 0.15 + $usage->completionTokens * 0.60) / 1_000_000;
    }
}

📊 الجزء 10: الـDashboards

1️⃣ Tenant Dashboard (Frontend):

php

<?php
// src/Frontend/Shortcodes/DashboardShortcode.php
declare(strict_types=1);

namespace KOSMOS\Studio\Frontend\Shortcodes;

final class DashboardShortcode {
    
    public static function render(): string {
        if (!is_user_logged_in()) {
            return '<p>يجب تسجيل الدخول.</p>';
        }
        
        $tenantId = (int) get_user_meta(get_current_user_id(), '_kosmos_tenant_id', true);
        $tenant = \KOSMOS\Studio\Domain\Tenant\TenantRepository::find($tenantId);
        
        if (!$tenant) {
            return '<p>لا يوجد حساب مرتبط.</p>';
        }
        
        ob_start();
        ?>
        <div class="kosmos-dashboard" data-tenant="<?= esc_attr($tenantId) ?>">
          <header class="kosmos-header">
            <h1><?= esc_html($tenant->name) ?></h1>
            <div class="kosmos-sub-status <?= esc_attr($tenant->status) ?>">
              <?php if ($tenant->status === 'active'): ?>
                ✅ اشتراك نشط — يتجدد في <?= esc_html($tenant->current_period_end) ?>
              <?php else: ?>
                ⚠️ <?= esc_html($tenant->status) ?> — <a href="/pricing">جدّد الآن</a>
              <?php endif; ?>
            </div>
          </header>
          
          <div class="kosmos-grid">
            <?php
            $stats = [
              ['📦', 'المنتجات', \KOSMOS\Studio\Domain\Product\ProductRepository::countByTenant($tenantId)],
              ['🔌', 'المصادر', \KOSMOS\Studio\Domain\Source\SourceRepository::countByTenant($tenantId)],
              ['🎯', 'قنوات البيع', \KOSMOS\Studio\Domain\Target\TargetRepository::countByTenant($tenantId)],
              ['🧠', 'استهلاك AI', self::getAiUsage($tenantId)],
            ];
            foreach ($stats as [$icon, $label, $value]): ?>
              <div class="kosmos-card">
                <div class="icon"><?= $icon ?></div>
                <div class="value"><?= esc_html((string) $value) ?></div>
                <div class="label"><?= esc_html($label) ?></div>
              </div>
            <?php endforeach; ?>
          </div>
          
          <div class="kosmos-actions">
            <a href="/dashboard/sources" class="btn">إدارة المصادر</a>
            <a href="/dashboard/targets" class="btn">قنوات البيع</a>
            <a href="/dashboard/products" class="btn">المنتجات</a>
            <a href="/dashboard/tutor" class="btn">اسأل AI</a>
          </div>
        </div>
        <?php
        return ob_get_clean();
    }
    
    private static function getAiUsage(int $tenantId): string {
        global $wpdb;
        $sum = $wpdb->get_var($wpdb->prepare(
            "SELECT SUM(credits_used) FROM {$wpdb->prefix}kosmos_ai_usage 
             WHERE tenant_id = %d AND created_at >= %s",
            $tenantId,
            date('Y-m-01')
        ));
        return number_format((float) $sum, 1);
    }
}

2️⃣ Admin Dashboard (WP Admin):

php

<?php
// src/Admin/Pages/Dashboard.php
declare(strict_types=1);

namespace KOSMOS\Studio\Admin\Pages;

final class Dashboard {
    
    public function render(): void {
        global $wpdb;
        
        $stats = [
            'tenants'       => (int) $wpdb->get_var("SELECT COUNT(*) FROM {$wpdb->prefix}kosmos_tenants WHERE status='active'"),
            'mrr'           => (float) $wpdb->get_var("SELECT SUM(amount) FROM {$wpdb->prefix}kosmos_subscriptions WHERE status='active' AND billing_cycle='monthly'"),
            'products'      => (int) $wpdb->get_var("SELECT COUNT(*) FROM {$wpdb->prefix}kosmos_products"),
            'locked'        => (int) $wpdb->get_var("SELECT COUNT(*) FROM {$wpdb->prefix}kosmos_products WHERE locked_by_subscription=1"),
            'ai_calls_24h'  => (int) $wpdb->get_var("SELECT COUNT(*) FROM {$wpdb->prefix}kosmos_ai_usage WHERE created_at >= DATE_SUB(NOW(), INTERVAL 24 HOUR)"),
            'jobs_queued'   => (int) $wpdb->get_var("SELECT COUNT(*) FROM {$wpdb->prefix}kosmos_jobs WHERE status='queued'"),
        ];
        ?>
        <div class="wrap kosmos-admin-dashboard">
          <h1>🌌 KOSMOS Control Center</h1>
          
          <div class="kosmos-kpi-grid">
            <?php foreach ($stats as $key => $value): ?>
              <div class="kpi-card">
                <div class="kpi-value"><?= esc_html((string) $value) ?></div>
                <div class="kpi-label"><?= esc_html($key) ?></div>
              </div>
            <?php endforeach; ?>
          </div>
          
          <div class="kosmos-panels">
            <div class="panel">
              <h2>اشتراكات تنتهي قريباً</h2>
              <?php $this->renderExpiringSubscriptions(); ?>
            </div>
            
            <div class="panel">
              <h2>مهام قيد التنفيذ</h2>
              <?php $this->renderRunningJobs(); ?>
            </div>
            
            <div class="panel">
              <h2>أخطاء حديثة</h2>
              <?php $this->renderRecentErrors(); ?>
            </div>
          </div>
        </div>
        <?php
    }
    
    private function renderExpiringSubscriptions(): void {
        global $wpdb;
        $rows = $wpdb->get_results("
            SELECT s.id, t.name, s.current_period_end
            FROM {$wpdb->prefix}kosmos_subscriptions s
            JOIN {$wpdb->prefix}kosmos_tenants t ON t.id = s.tenant_id
            WHERE s.status = 'active'
              AND s.current_period_end <= DATE_ADD(NOW(), INTERVAL 7 DAY)
            ORDER BY s.current_period_end ASC
            LIMIT 20
        ");
        
        if (!$rows) {
            echo '<p>لا يوجد.</p>';
            return;
        }
        
        echo '<table class="widefat"><thead><tr>';
        echo '<th>Tenant</th><th>ينتهي في</th><th>الحالة</th>';
        echo '</tr></thead><tbody>';
        foreach ($rows as $r) {
            $days = (strtotime($r->current_period_end) - time()) / 86400;
            echo '<tr>';
            echo '<td>' . esc_html($r->name) . '</td>';
            echo '<td>' . esc_html($r->current_period_end) . '</td>';
            echo '<td>' . ($days < 0 ? '⚠️ منتهي' : sprintf('خلال %.1f يوم', $days)) . '</td>';
            echo '</tr>';
        }
        echo '</tbody></table>';
    }
    
    private function renderRunningJobs(): void {
        global $wpdb;
        $rows = $wpdb->get_results("
            SELECT id, job_type, tenant_id, status, attempts, started_at
            FROM {$wpdb->prefix}kosmos_jobs
            WHERE status IN ('queued','running')
            ORDER BY priority ASC, scheduled_at ASC
            LIMIT 20
        ");
        
        if (!$rows) {
            echo '<p>لا يوجد مهام قيد التنفيذ.</p>';
            return;
        }
        
        echo '<table class="widefat"><thead><tr>';
        echo '<th>#</th><th>النوع</th><th>Tenant</th><th>الحالة</th><th>المحاولات</th>';
        echo '</tr></thead><tbody>';
        foreach ($rows as $r) {
            echo '<tr>';
            echo '<td>' . (int) $r->id . '</td>';
            echo '<td>' . esc_html($r->job_type) . '</td>';
            echo '<td>' . (int) $r->tenant_id . '</td>';
            echo '<td>' . esc_html($r->status) . '</td>';
            echo '<td>' . (int) $r->attempts . '</td>';
            echo '</tr>';
        }
        echo '</tbody></table>';
    }
    
    private function renderRecentErrors(): void {
        global $wpdb;
        $rows = $wpdb->get_results("
            SELECT id, source, event_type, error_message, created_at
            FROM {$wpdb->prefix}kosmos_webhook_events
            WHERE error_message IS NOT NULL
            ORDER BY created_at DESC
            LIMIT 10
        ");
        
        if (!$rows) {
            echo '<p>لا يوجد أخطاء.</p>';
            return;
        }
        
        echo '<ul>';
        foreach ($rows as $r) {
            echo '<li>';
            echo '<strong>' . esc_html($r->source) . '/' . esc_html($r->event_type) . '</strong>: ';
            echo esc_html(substr($r->error_message, 0, 100));
            echo ' <em>(' . esc_html($r->created_at) . ')</em>';
            echo '</li>';
        }
        echo '</ul>';
    }
}

⚡ الجزء 11: Job Queue & Workers

php

<?php
declare(strict_types=1);

namespace KOSMOS\Studio\Application\Jobs;

final class JobQueue {
    
    public static function push(
        int $tenantId,
        string $jobType,
        array $payload,
        int $priority = 5,
        ?int $delaySeconds = null
    ): int {
        global $wpdb;
        
        $wpdb->insert("{$wpdb->prefix}kosmos_jobs", [
            'tenant_id'     => $tenantId,
            'job_type'      => $jobType,
            'payload'       => wp_json_encode($payload),
            'status'        => 'queued',
            'priority'      => $priority,
            'scheduled_at'  => $delaySeconds 
                ? date('Y-m-d H:i:s', time() + $delaySeconds)
                : current_time('mysql'),
            'created_at'    => current_time('mysql'),
        ]);
        
        return (int) $wpdb->insert_id;
    }
    
    public static function claim(string $workerId): ?array {
        global $wpdb;
        
        // قفل ذري — يمنع تنفيذ نفس المهمة مرتين
        $wpdb->query('START TRANSACTION');
        
        $job = $wpdb->get_row($wpdb->prepare("
            SELECT * FROM {$wpdb->prefix}kosmos_jobs
            WHERE status = 'queued'
              AND scheduled_at <= NOW()
            ORDER BY priority ASC, scheduled_at ASC
            LIMIT 1
            FOR UPDATE SKIP LOCKED
        "));
        
        if (!$job) {
            $wpdb->query('COMMIT');
            return null;
        }
        
        $wpdb->update(
            "{$wpdb->prefix}kosmos_jobs",
            [
                'status'     => 'running',
                'started_at' => current_time('mysql'),
                'worker_id'  => $workerId,
                'attempts'   => $job->attempts + 1,
            ],
            ['id' => $job->id]
        );
        
        $wpdb->query('COMMIT');
        
        return (array) $job;
    }
    
    public static function complete(int $jobId, array $result = []): void {
        global $wpdb;
        $wpdb->update(
            "{$wpdb->prefix}kosmos_jobs",
            [
                'status'       => 'completed',
                'completed_at' => current_time('mysql'),
                'result'       => wp_json_encode($result),
            ],
            ['id' => $jobId]
        );
    }
    
    public static function fail(int $jobId, string $error): void {
        global $wpdb;
        
        $job = $wpdb->get_row($wpdb->prepare(
            "SELECT attempts, max_attempts FROM {$wpdb->prefix}kosmos_jobs WHERE id = %d",
            $jobId
        ));
        
        $status = ($job && $job->attempts >= $job->max_attempts) ? 'failed' : 'queued';
        
        // Exponential backoff
        $delay = min(3600, pow(2, $job->attempts ?? 1) * 30);
        
        $wpdb->update(
            "{$wpdb->prefix}kosmos_jobs",
            [
                'status'        => $status,
                'error_message' => $error,
                'scheduled_at'  => date('Y-m-d H:i:s', time() + $delay),
            ],
            ['id' => $jobId]
        );
    }
}

php

<?php
declare(strict_types=1);

namespace KOSMOS\Studio\Application\Jobs;

use KOSMOS\Studio\Application\Bridge\SyncOrchestrator;
use KOSMOS\Studio\Application\Bridge\PublishOrchestrator;
use KOSMOS\Studio\Domain\Product\ProductLockManager;

final class Worker {
    
    private const WORKER_ID_PREFIX = 'kosmos-worker-';
    private const MAX_JOBS_PER_TICK = 5;
    private const TIME_BUDGET_SECONDS = 50;
    
    public static function tick(): void {
        $workerId = self::WORKER_ID_PREFIX . gethostname() . '-' . getmypid();
        $start = time();
        
        for ($i = 0; $i < self::MAX_JOBS_PER_TICK; $i++) {
            if ((time() - $start) > self::TIME_BUDGET_SECONDS) break;
            
            $job = JobQueue::claim($workerId);
            if (!$job) break;
            
            try {
                $result = self::execute($job);
                JobQueue::complete($job['id'], $result);
            } catch (\Throwable $e) {
                JobQueue::fail($job['id'], $e->getMessage());
            }
        }
    }
    
    private static function execute(array $job): array {
        $payload = json_decode($job['payload'], true) ?: [];
        $tenantId = (int) $job['tenant_id'];
        
        return match ($job['job_type']) {
            'sync_source'      => self::handleSyncSource($tenantId, $payload),
            'publish_product'  => self::handlePublishProduct($tenantId, $payload),
            'bulk_lock'        => self::handleBulkLock($tenantId, $payload),
            default            => throw new \RuntimeException("Unknown job: {$job['job_type']}"),
        };
    }
    
    private static function handleSyncSource(int $tenantId, array $payload): array {
        $orchestrator = \KOSMOS\Studio\Core\Plugin::instance()
            ->container()
            ->get(SyncOrchestrator::class);
        
        return $orchestrator->syncSource(
            $tenantId,
            (int) $payload['source_id'],
            $payload['mode'] ?? 'full'
        );
    }
    
    private static function handlePublishProduct(int $tenantId, array $payload): array {
        $orchestrator = \KOSMOS\Studio\Core\Plugin::instance()
            ->container()
            ->get(PublishOrchestrator::class);
        
        return $orchestrator->publish(
            $tenantId,
            (int) $payload['product_id'],
            (int) $payload['target_id']
        );
    }
    
    private static function handleBulkLock(int $tenantId, array $payload): array {
        $targets = \KOSMOS\Studio\Domain\Target\TargetRepository::find(
            (int) $payload['target_id'],
            $tenantId
        );
        
        if (!$targets) return ['skipped' => true];
        
        $publisher = new \KOSMOS\Studio\Integrations\Salla\SallaPublisher(
            new \KOSMOS\Studio\Integrations\Salla\SallaClient(),
            new \KOSMOS\Studio\Integrations\Salla\SallaMapper()
        );
        
        $action = $payload['action'] ?? 'hide';
        $products = \KOSMOS\Studio\Domain\Product\ProductRepository::findByTarget($tenantId, (int) $payload['target_id']);
        
        $done = 0;
        foreach ($products as $p) {
            if (!$p['external_id']) continue;
            
            $ok = $action === 'hide'
                ? $publisher->hide($targets, $p['external_id'])
                : $publisher->show($targets, $p['external_id']);
            
            if ($ok) $done++;
        }
        
        return ['action' => $action, 'affected' => $done];
    }
}

🚀 الجزء 12: خطة التنفيذ — أول 60 دقيقة ملفًا بملف

🕐 الدقيقة 0-5 | Bootstrap

bash

# 1. أنشئ المشروع
mkdir -p kosmos-studio && cd kosmos-studio
composer init --name=kosmos/studio --type=wordpress-plugin

json

// composer.json
{
  "name": "kosmos/studio",
  "type": "wordpress-plugin",
  "require": {
    "php": ">=8.2",
    "openai-php/client": "^0.10",
    "guzzlehttp/guzzle": "^7.8",
    "monolog/monolog": "^3.6",
    "ramsey/uuid": "^4.7",
    "defuse/php-encryption": "^2.4"
  },
  "require-dev": {
    "phpunit/phpunit": "^11.0",
    "mockery/mockery": "^1.6",
    "squizlabs/php_codesniffer": "^3.10",
    "phpstan/phpstan": "^1.11"
  },
  "autoload": {
    "psr-4": {
      "KOSMOS\\Studio\\": "src/"
    }
  },
  "autoload-dev": {
    "psr-4": {
      "KOSMOS\\Studio\\Tests\\": "tests/"
    }
  },
  "config": {
    "optimize-autoloader": true
  },
  "scripts": {
    "test": "phpunit",
    "lint": "phpcs --standard=PSR12 src/",
    "analyze": "phpstan analyse src/ --level=8"
  }
}

bash

composer install

🕐 الدقيقة 5-10 | Plugin Main File

bash

cat > kosmos-studio.php << 'EOF'
<?php
/**
 * Plugin Name:  KOSMOS Studio
 * Description:  Subscription-as-a-Service Knowledge & Commerce Bridge
 * Version:      1.0.0
 * Requires PHP: 8.2
 */
declare(strict_types=1);

namespace KOSMOS\Studio;

if (!defined('ABSPATH')) exit;
require_once __DIR__ . '/vendor/autoload.php';

define('KOSMOS_VERSION', '1.0.0');
define('KOSMOS_FILE', __FILE__);
define('KOSMOS_PATH', plugin_dir_path(__FILE__));
define('KOSMOS_URL', plugin_dir_url(__FILE__));

Core\Plugin::instance()->boot();
EOF

🕐 الدقيقة 10-20 | Core Classes

bash

mkdir -p src/{Core,Database/{Migrations,Seeds},Domain/{Tenant,Subscription,Entitlement,Product,Source,Target},Application/{Bridge,AI/Providers,Jobs/Handlers},Integrations/{Salla,Shopify,Payments},Http/{Middleware,Controllers},Admin/Pages,Frontend/Shortcodes,Support,Exceptions}

bash

# Core/Plugin.php
cat > src/Core/Plugin.php << 'EOF'
<?php
declare(strict_types=1);
namespace KOSMOS\Studio\Core;

use KOSMOS\Studio\Database\Migrator;
use KOSMOS\Studio\Http\Router;

final class Plugin {
    private static ?self $instance = null;
    private Container $container;
    
    public static function instance(): self {
        return self::$instance ??= new self();
    }
    
    private function __construct() {
        $this->container = new Container();
    }
    
    public function boot(): void {
        register_activation_hook(KOSMOS_FILE, [$this, 'onActivate']);
        add_action('plugins_loaded', [$this, 'onPluginsLoaded']);
        add_action('init', [$this, 'onInit']);
        add_action('rest_api_init', [$this, 'registerRestRoutes']);
    }
    
    public function onActivate(): void {
        (new Migrator())->run();
        (new \KOSMOS\Studio\Database\Seeds\PlansSeeder())->run();
    }
    
    public function onPluginsLoaded(): void {
        if (!class_exists('WooCommerce')) return;
        load_plugin_textdomain('kosmos', false, dirname(plugin_basename(KOSMOS_FILE)) . '/languages');
    }
    
    public function onInit(): void {
        add_shortcode('kosmos_pricing', [\KOSMOS\Studio\Frontend\Shortcodes\PricingShortcode::class, 'render']);
    }
    
    public function registerRestRoutes(): void {
        (new Router())->register();
    }
    
    public function container(): Container { return $this->container; }
}
EOF

bash

# Core/Container.php
cat > src/Core/Container.php << 'EOF'
<?php
declare(strict_types=1);
namespace KOSMOS\Studio\Core;

final class Container {
    private array $bindings = [];
    private array $instances = [];
    
    public function bind(string $abstract, callable $factory): void {
        $this->bindings[$abstract] = $factory;
    }
    
    public function singleton(string $abstract, ?callable $factory = null): void {
        $factory ??= fn() => new $abstract();
        $this->bindings[$abstract] = function () use ($factory, $abstract) {
            return $this->instances[$abstract] ??= $factory($this);
        };
    }
    
    public function get(string $abstract): mixed {
        if (isset($this->instances[$abstract])) return $this->instances[$abstract];
        
        $factory = $this->bindings[$abstract] ?? null;
        if (!$factory) {
            if (!class_exists($abstract)) throw new \RuntimeException("Not bound: {$abstract}");
            return $this->instances[$abstract] = new $abstract();
        }
        
        return $factory($this);
    }
}
EOF

🕐 الدقيقة 20-30 | Database Schema

bash

# Database/Migrator.php
cat > src/Database/Migrator.php << 'EOF'
<?php
declare(strict_types=1);
namespace KOSMOS\Studio\Database;

final class Migrator {
    public function run(): void {
        $migrations = glob(KOSMOS_PATH . 'src/Database/Migrations/*.php');
        sort($migrations);
        
        $ran = get_option('kosmos_migrations', []);
        
        foreach ($migrations as $file) {
            $name = basename($file, '.php');
            if (in_array($name, $ran, true)) continue;
            
            require_once $file;
            $class = 'KOSMOS\\Studio\\Database\\Migrations\\' . $name;
            
            if (class_exists($class)) {
                (new $class())->up();
                $ran[] = $name;
            }
        }
        
        update_option('kosmos_migrations', $ran);
    }
}
EOF

bash

# Migration 001 - Tenants
cat > src/Database/Migrations/Migration_001_CreateTenants.php << 'EOF'
<?php
declare(strict_types=1);
namespace KOSMOS\Studio\Database\Migrations;

final class Migration_001_CreateTenants {
    public function up(): void {
        global $wpdb;
        $charset = $wpdb->get_charset_collate();
        
        $wpdb->query("CREATE TABLE IF NOT EXISTS {$wpdb->prefix}kosmos_tenants (
            id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
            uuid CHAR(36) NOT NULL UNIQUE,
            slug VARCHAR(64) NOT NULL UNIQUE,
            name VARCHAR(191) NOT NULL,
            owner_user_id BIGINT UNSIGNED NOT NULL,
            plan_slug VARCHAR(32) NOT NULL DEFAULT 'trial',
            status ENUM('active','suspended','cancelled','trial') DEFAULT 'trial',
            subdomain VARCHAR(64) NOT NULL UNIQUE,
            custom_domain VARCHAR(191) NULL UNIQUE,
            salla_store_id VARCHAR(64) NULL,
            salla_access_token TEXT NULL,
            salla_refresh_token TEXT NULL,
            salla_token_expires DATETIME NULL,
            max_products INT DEFAULT 100,
            max_users INT DEFAULT 3,
            max_sources INT DEFAULT 2,
            ai_credits INT DEFAULT 500,
            trial_ends_at DATETIME NULL,
            current_period_start DATETIME NULL,
            current_period_end DATETIME NULL,
            metadata JSON NULL,
            created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
            updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
            deleted_at DATETIME NULL,
            INDEX idx_status (status),
            INDEX idx_plan (plan_slug),
            INDEX idx_owner (owner_user_id),
            INDEX idx_period_end (current_period_end)
        ) $charset;");
    }
}
EOF

(يكرر نفس النمط لـ 11 migration متبقية حسب الجداول المُعرّفة في الجزء 2)

🕐 الدقيقة 30-45 | Core Domain Services

bash

# Domain/Entitlement/EntitlementService.php
cat > src/Domain/Entitlement/EntitlementService.php << 'EOF'
<?php
declare(strict_types=1);
namespace KOSMOS\Studio\Domain\Entitlement;

final class EntitlementService {
    private const CACHE_TTL = 300;
    
    public function can(int $tenantId, string $featureKey, ?int $scopeId = null): bool {
        $cacheKey = "entitlement:{$tenantId}:{$featureKey}:{$scopeId}";
        $cached = wp_cache_get($cacheKey, 'kosmos');
        if ($cached !== false) return (bool) $cached;
        
        global $wpdb;
        $row = $wpdb->get_row($wpdb->prepare("
            SELECT * FROM {$wpdb->prefix}kosmos_entitlements
            WHERE tenant_id = %d AND feature_key = %s
              AND (scope_id = %d OR scope_id IS NULL)
              AND is_enabled = 1
              AND (expires_at IS NULL OR expires_at > NOW())
            LIMIT 1
        ", $tenantId, $featureKey, $scopeId ?? 0));
        
        $allowed = $row && ($row->limit_value === null || $row->used_value < $row->limit_value);
        
        wp_cache_set($cacheKey, $allowed ? 1 : 0, 'kosmos', self::CACHE_TTL);
        return (bool) $allowed;
    }
    
    public function consume(int $tenantId, string $featureKey, float $amount = 1): bool {
        global $wpdb;
        
        $affected = $wpdb->query($wpdb->prepare("
            UPDATE {$wpdb->prefix}kosmos_entitlements
            SET used_value = used_value + %f, updated_at = NOW()
            WHERE tenant_id = %d 
              AND feature_key = %s
              AND is_enabled = 1
              AND (limit_value IS NULL OR used_value + %f <= limit_value)
        ", $amount, $tenantId, $featureKey, $amount));
        
        if ($affected) {
            wp_cache_delete("entitlement:{$tenantId}:{$featureKey}:0", 'kosmos');
        }
        
        return $affected > 0;
    }
    
    public function grant(int $tenantId, string $featureKey, int $limit, ?int $scopeId = null): void {
        global $wpdb;
        
        $wpdb->replace("{$wpdb->prefix}kosmos_entitlements", [
            'tenant_id'     => $tenantId,
            'feature_key'   => $featureKey,
            'scope_type'    => 'global',
            'scope_id'      => $scopeId,
            'limit_value'   => $limit,
            'used_value'    => 0,
            'reset_period'  => 'monthly',
            'last_reset_at' => current_time('mysql'),
            'is_enabled'    => 1,
            'created_at'    => current_time('mysql'),
            'updated_at'    => current_time('mysql'),
        ]);
        
        wp_cache_delete("entitlement:{$tenantId}:{$featureKey}:{$scopeId}", 'kosmos');
    }
    
    public function revokeAll(int $tenantId): void {
        global $wpdb;
        $wpdb->update(
            "{$wpdb->prefix}kosmos_entitlements",
            ['is_enabled' => 0],
            ['tenant_id' => $tenantId]
        );
        wp_cache_flush_group('kosmos');
    }
    
    public function grantFromPlan(int $tenantId): void {
        global $wpdb;
        $plan = $wpdb->get_row($wpdb->prepare("
            SELECT p.* FROM {$wpdb->prefix}kosmos_plans p
            JOIN {$wpdb->prefix}kosmos_tenants t ON t.plan_slug = p.slug
            WHERE t.id = %d
        ", $tenantId));
        
        if (!$plan) return;
        
        $limits = json_decode($plan->limits, true) ?: [];
        foreach ($limits as $feature => $value) {
            $this->grant($tenantId, $feature, (int) $value);
        }
    }
}
EOF

bash

# Domain/Product/ProductLockManager.php
cat > src/Domain/Product/ProductLockManager.php << 'EOF'
<?php
declare(strict_types=1);
namespace KOSMOS\Studio\Domain\Product;

use KOSMOS\Studio\Application\Jobs\JobQueue;

final class ProductLockManager {
    
    public function lockAll(int $tenantId, string $reason = 'subscription_expired'): int {
        global $wpdb;
        
        $count = $wpdb->query($wpdb->prepare("
            UPDATE {$wpdb->prefix}kosmos_products
            SET locked_by_subscription = 1, sync_status = 'locked', updated_at = NOW()
            WHERE tenant_id = %d AND deleted_at IS NULL
        ", $tenantId));
        
        // أضف job لإخفاء المنتجات من سلة
        $targets = $wpdb->get_results($wpdb->prepare("
            SELECT id FROM {$wpdb->prefix}kosmos_targets
            WHERE tenant_id = %d AND deleted_at IS NULL
        ", $tenantId));
        
        foreach ($targets as $t) {
            JobQueue::push($tenantId, 'bulk_lock', [
                'target_id' => (int) $t->id,
                'action'    => 'hide',
                'reason'    => $reason,
            ], priority: 1);
        }
        
        do_action('kosmos/products_locked', $tenantId, $count, $reason);
        
        return (int) $count;
    }
    
    public function unlockAll(int $tenantId): int {
        global $wpdb;
        
        $count = $wpdb->query($wpdb->prepare("
            UPDATE {$wpdb->prefix}kosmos_products
            SET locked_by_subscription = 0, sync_status = 'outdated', updated_at = NOW()
            WHERE tenant_id = %d AND locked_by_subscription = 1
        ", $tenantId));
        
        $targets = $wpdb->get_results($wpdb->prepare("
            SELECT id FROM {$wpdb->prefix}kosmos_targets
            WHERE tenant_id = %d AND is_locked = 1
        ", $tenantId));
        
        foreach ($targets as $t) {
            JobQueue::push($tenantId, 'bulk_lock', [
                'target_id' => (int) $t->id,
                'action'    => 'show',
            ], priority: 1);
        }
        
        do_action('kosmos/products_unlocked', $tenantId, $count);
        
        return (int) $count;
    }
}
EOF

🕐 الدقيقة 45-55 | Salla Integration

bash

# Integrations/Salla/SallaPublisher.php
cat > src/Integrations/Salla/SallaPublisher.php << 'EOF'
<?php
declare(strict_types=1);
namespace KOSMOS\Studio\Integrations\Salla;

final class SallaPublisher {
    public function __construct(
        private SallaClient $client,
        private SallaMapper $mapper
    ) {}
    
    public function publish(object $target, array $product): array {
        $payload = $this->mapper->toSalla($product);
        return $this->client->forTarget($target)->post('/products', $payload);
    }
    
    public function hide(object $target, string $externalId): bool {
        $r = $this->client->forTarget($target)->put("/products/{$externalId}", [
            'status' => 'hidden',
        ]);
        return $r['success'] ?? false;
    }
    
    public function show(object $target, string $externalId): bool {
        $r = $this->client->forTarget($target)->put("/products/{$externalId}", [
            'status' => 'sale',
        ]);
        return $r['success'] ?? false;
    }
}
EOF

bash

# Integrations/Salla/SallaClient.php
cat > src/Integrations/Salla/SallaClient.php << 'EOF'
<?php
declare(strict_types=1);
namespace KOSMOS\Studio\Integrations\Salla;

use KOSMOS\Studio\Support\Encrypter;

final class SallaClient {
    private const BASE_URL = 'https://api.salla.dev/admin/v2';
    private ?object $target = null;
    
    public function forTarget(object $target): self {
        $clone = clone $this;
        $clone->target = $target;
        return $clone;
    }
    
    public function get(string $path, array $q = []): array {
        return $this->request('GET', $path, $q);
    }
    
    public function post(string $path, array $body = []): array {
        return $this->request('POST', $path, [], $body);
    }
    
    public function put(string $path, array $body = []): array {
        return $this->request('PUT', $path, [], $body);
    }
    
    private function request(string $method, string $path, array $q = [], array $b = []): array {
        if (!$this->target) throw new \RuntimeException('Target not set');
        
        $creds = json_decode(Encrypter::decrypt($this->target->credentials), true);
        $token = $creds['access_token'] ?? '';
        
        $url = self::BASE_URL . $path;
        if ($q) $url .= '?' . http_build_query($q);
        
        $response = wp_remote_request($url, [
            'method'  => $method,
            'timeout' => 30,
            'headers' => [
                'Authorization' => "Bearer {$token}",
                'Content-Type'  => 'application/json',
                'Accept'        => 'application/json',
            ],
            'body' => $b ? wp_json_encode($b) : null,
        ]);
        
        if (is_wp_error($response)) {
            return ['success' => false, 'message' => $response->get_error_message()];
        }
        
        return json_decode(wp_remote_retrieve_body($response), true) ?: ['success' => false];
    }
}
EOF

🕐 الدقيقة 55-60 | REST Router + Test

bash

# Http/Router.php
cat > src/Http/Router.php << 'EOF'
<?php
declare(strict_types=1);
namespace KOSMOS\Studio\Http;

final class Router {
    public function register(): void {
        register_rest_route('kosmos/v1', '/health', [
            'methods'             => 'GET',
            'callback'            => fn() => [
                'status'  => 'alive',
                'version' => KOSMOS_VERSION,
                'time'    => current_time('c'),
            ],
            'permission_callback' => '__return_true',
        ]);
        
        register_rest_route('kosmos/v1', '/sources/(?P<id>\d+)/sync', [
            'methods'             => 'POST',
            'callback'            => [new \KOSMOS\Studio\Http\Controllers\SourceController(), 'sync'],
            'permission_callback' => fn() => current_user_can('kosmos_sync_sources'),
        ]);
        
        register_rest_route('kosmos/v1', '/ai/tutor', [
            'methods'             => 'POST',
            'callback'            => [new \KOSMOS\Studio\Http\Controllers\AiController(), 'tutor'],
            'permission_callback' => fn() => current_user_can('kosmos_use_ai'),
        ]);
    }
}
EOF

bash

# اختبر الآن
echo "✅ KOSMOS Studio — Skeleton Ready"
docker compose up -d
sleep 30
curl -s http://localhost:8080/wp-json/kosmos/v1/health | jq

النتيجة المتوقعة:

json

{
  "status": "alive",
  "version": "1.0.0",
  "time": "2025-01-15T10:30:00+00:00"
}

📋 الجزء 13: خلاصة المواصفة

ما تم توثيقه كاملاً:

المكوّن	الحالة
✅ قاعدة البيانات	12 جدول + علاقات + فهارس
✅ هيكل Plugin	~80 ملف + namespaces
✅ Domain Classes	كود كامل لـ: Tenant, Subscription, Entitlement, Product, Source, Target
✅ REST API	45+ endpoint موثّق
✅ نظام الباقات	4 باقات + Entitlements
✅ WooCommerce Hooks	15+ hook مرتبط
✅ AI Gateway	Provider-based + Metering
✅ Roles & Capabilities	5 roles + 20 capability
✅ Dashboards	Tenant + Admin كاملين
✅ Job Queue	Atomic claim + Retry + Backoff
✅ Salla Integration	Client + Publisher + Hide/Show
✅ Product Lock System	القفل التلقائي عند انتهاء الاشتراك
✅ خطة 60 دقيقة	12 مرحلة ملفًا بملف

🎯 الخطوة التالية — اختر

#	الخيار	المحتوى
A	🔌 Source Adapters كاملة	Shopify + WooCommerce + AliExpress + CSV + Custom API
B	💳 Payment Gateways كاملة	Stripe + Moyasar + Tap + PayPal + Webhooks
C	🎨 Frontend كامل	React/Next.js Dashboard + Pricing + Tutor UI
D	🧪 Test Suite كاملة	PHPUnit + Integration + E2E + Load (k6)
E	🚀 CI/CD + Deployment	GitHub Actions + K8s + Monitoring
F	📚 كل ما سبق	المواصفة تُصبح منصة كاملة

قل الحرف وسأكمل. 🔥

KOSMOS v1.0 — المواصفة الهندسية الكاملة

من التصور إلى التنفيذ — Blueprint تنفيذي كامل

🎯 الجزء 0: إعادة تعريف المنصة — النسخة النهائية

الاسم النهائي: KOSMOS Studio

النوع: Subscription-as-a-Service Knowledge & Commerce Bridge

الرؤية (جملة واحدة):

القيمة الفريدة (3 محاور):

الشعار التسويقي:

الجمهور المستهدف:

📐 الجزء 1: المعمارية العامة (System Architecture)

المكونات الأساسية (Bounded Contexts):

البرومبت الهندسي الشامل — منصة “سلة بريدج” (Salla Bridge Platform)

🎯 الهدف العام (Master Prompt)

📐 القسم 1: تعريف المنصة (Platform Definition)

🗄️ القسم 2: بنية قاعدة البيانات (Database Schema v1.0)

2.1 الجداول الأساسية

2.2 الفهارس (Indexes)

🧩 القسم 3: هيكل الـPlugin (Folder & Namespace Structure)

🔌 القسم 4: REST Endpoints (v1)

🛒 القسم 5: تكامل سلة (Salla Integration)

💳 القسم 6: نظام الباقات والاشتراكات (Plans & Entitlements)

6.1 الباقات المقترحة

6.2 Entitlements Logic

6.3 WooCommerce Hooks (لأن المنصة نفسها تُبنى على Woo)

6.4 دورة حياة الاشتراك

🔒 القسم 7: نظام القفل التلقائي (Auto-Lock System) — القلب النابض

7.1 Cron: sb_check_subscriptions (كل ساعة)

7.2 LockManager::lock()

7.3 LockManager::release()

7.4 Cron Guard

🤖 القسم 8: AI Gateway

👥 القسم 9: Roles & Capabilities

📊 القسم 10: Dashboards

10.1 Tenant Dashboard (React SPA)

10.2 Admin Dashboard

10.3 Billing Dashboard

⏱️ القسم 11: خطة تنفيذ أول 60 دقيقة (Minute-by-Minute)

🧪 القسم 12: معايير القبول (Acceptance Criteria)

📦 القسم 13: مخرجات مطلوبة منك (Deliverables)

🚫 قيود صارمة

📚 الملحق الهندسي الموسّع — SallaBridge v1.1

🔐 القسم 14: طبقة التشفير والأمان (Crypto & Security)

14.1 src/Support/Crypto.php

14.2 قواعد الأمان الإلزامية

14.3 HMAC Webhook Verification

⚙️ القسم 15: نظام الطوابير (Job Queue)

15.1 لماذا لا نعتمد على wp_cron فقط؟

15.2 بنية Queue

15.3 أنواع الـJobs

15.4 Dead Letter Queue (DLQ)

🏗️ القسم 16: Multi-Tenancy العميق

16.1 Row-Level Isolation

16.2 Tenant Context Resolution

16.3 Tenant Lifecycle

🔌 القسم 17: محوّلات المصادر (Source Adapters) بالتفصيل

17.1 الواجهة الموحدة

17.2 ProductDTO الموحّد

17.3 جدول المصادر المدعومة

17.4 خوارزمية اختيار المصدر

🤖 القسم 18: AI Gateway المتقدم

18.1 Routing Strategy (Cost-Aware)

18.2 AI Caching Layer

18.3 Prompt Templates

18.4 حدود AI حسب الباقة

💰 القسم 19: الفوترة والاشتراكات (Billing Deep Dive)

19.1 دورة حياة الاشتراك (State Machine)

19.2 SubscriptionManager::renew()

19.3 Webhook Handlers لكل Gateway

19.4 الفواتير (Invoices)

🔒 القسم 20: نظام القفل — التنفيذ الكامل

20.1 LockManager.php (كامل)

20.2 SallaLocker.php

20.3 Cron: CheckSubscriptions

🌐 القسم 21: تكامل سلة (Salla) — الطبقة الكاملة

21.1 Salla\Client.php

21.2 Rate Limiter لسلة

21.3 Webhooks من سلة

📊 القسم 22: قاعدة البيانات — SQL الكامل

🧪 القسم 23: الاختبارات (Testing Strategy)

23.1 الهرم

7.1 Cron: `sb_check_subscriptions` (كل ساعة)

14.1 `src/Support/Crypto.php`

15.1 لماذا لا نعتمد على `wp_cron` فقط؟

17.2 `ProductDTO` الموحّد

19.2 `SubscriptionManager::renew()`

20.1 `LockManager.php` (كامل)

20.2 `SallaLocker.php`

20.3 Cron: `CheckSubscriptions`

21.1 `Salla\Client.php`

📋 جدول 1: `kosmos_tenants` — الحسابات الرئيسية

📋 جدول 2: `kosmos_subscriptions` — الاشتراكات

📋 جدول 3: `kosmos_entitlements` — صلاحيات الوصول (القلب)

📋 جدول 4: `kosmos_plans` — تعريف الباقات

📋 جدول 5: `kosmos_sources` — مصادر المحتوى

📋 جدول 6: `kosmos_targets` — قنوات الإخراج (سلة، شوبيفاي…)

📋 جدول 7: `kosmos_products` — كتالوج موحّد

📋 جدول 8: `kosmos_publish_log` — سجل النشر

📋 جدول 9: `kosmos_ai_usage` — استهلاك AI

📋 جدول 10: `kosmos_audit_log` — الأمان والامتثال

📋 جدول 11: `kosmos_jobs` — طابور المهام

📋 جدول 12: `kosmos_webhook_events` — الأحداث الواردة

Base URL: `/wp-json/kosmos/v1/`