# المعمارية

## الاختيارات

- Laravel 13 وPHP 8.3+ مع Livewire 4 وBlade. اختير Livewire لتقليل اعتماد الواجهة على خادم Node في الإنتاج؛ يُستخدم Node أثناء البناء فقط.
- MySQL/MariaDB قاعدة واحدة مع `tenant_id` في بيانات العملاء، والتحقق من المستأجر والصلاحية في سياسات الخادم واستعلاماته.
- طابور Laravel Database كافتراضي. يعمل عامل محدود عبر Scheduler/Cron، فلا يحتاج الخادم إلى Supervisor أو Redis.
- Polling كل 7 ثوانٍ من Livewire؛ يتوقف عندما تصبح الصفحة مخفية. WebSockets وRedis غير مطلوبين لمسار الإنتاج الأساسي.
- الملفات الصوتية والتصديرات والنسخ الاحتياطية على قرص خاص. S3-compatible خيار تخزين للنسخ؛ لا تُنشأ روابط عامة للملفات الصوتية.

## حدود التطبيق

```mermaid
flowchart TD
  A["SMS Forwarder"] -->|"HTTPS + device secret"| B["Webhook endpoint"]
  B --> C["Encrypted webhook receipt"]
  C --> D["Database queue"]
  D --> E["Parser + sender access + redaction"]
  E --> F["Tenant conversation and message"]
  F --> G["Policies + Livewire inbox"]
  F --> H["Telegram / exports / backup"]
```

## استقبال الرسائل

1. يقبل `POST /api/webhooks/sms/{device_uuid}/{secret}` JSON أو form-encoded أو نصًا خامًا.
2. يقارن النظام السر بـHash الجهاز النشط، ويفرض حد 100KB وRate Limit.
3. يكتب إيصالًا إلى `webhook_receipts` مشفرًا بـLaravel `Crypt`، ثم يعيد 202 دون انتظار التحليل.
4. يقوم العامل بفك الإيصال، والتحقق من صيغة `SMSFW_V1` أو حقل `text`, ثم يحل المرسل.
5. إذا كان المرسل غير معروف أو غير مسموح، تُشفّر الرسالة في `unknown_sender_inbox` المتاح لـSuper Admin فقط.
6. إذا كان مسموحًا، تُنشأ محادثة واحدة لكل `(tenant_id, sender_id)` ورسالة مرتبطة بها. يُخزّن الأصل مشفرًا، ويُستخدم النص المنقح في الواجهة والتصدير وTelegram.

## الوصول وعزل العميل

السياسة `MessagePolicy` تتحقق من الدور والعميل والسجلات في `sender_tenant_access` و`employee_sender_permissions`. كل Controller وLivewire query يقيّد الرسائل قبل عرضها. لا يعتمد النظام على `tenant_id` المرسل من المتصفح. مسارات Super Admin منفصلة ويُسجّل الوصول الحساس في `super_admin_security_logs`.

## الحجز وتحديث الحالة

تستخدم خدمة `MessageWorkflow` معاملة وقفل `SELECT ... FOR UPDATE` على الرسالة. يحفظ كل حجز في `message_assignments` وكل انتقال في `message_status_events`. حالات الفشل والتخلّي تحتاج سببًا نصيًا أو تسجيلًا صوتيًا. كل تعديل لحالة سابقة يحتاج سببًا. أحداث Super Admin الخاصة تُحفظ مع علامة داخلية ويُخفى سجلها عن عميل الرسالة.

## التزامن

يستخدم الصندوق `wire:poll.visible.7s` مع بحث مؤجل ثانية واحدة وترقيم صفحات. لا تُحمّل جميع الرسائل دفعة واحدة، وتُوقف استعلامات polling عندما تكون الصفحة مخفية. تُحسب التواريخ من المنطقة الزمنية للعميل وتحفظ في قاعدة البيانات بتوقيت UTC.

## الطوابير والجدولة

- Webhook processing, Telegram, exports, and manual backups dispatch Laravel Jobs.
- `routes/console.php` يسجل مهمة عامل `queue:work database --stop-when-empty --max-time=50 --tries=3` كل دقيقة.
- Scheduler يشغّل تنظيف التصديرات المنتهية يوميًا وفحص النسخ الاحتياطي كل ساعة؛ ينشئ نسخة فقط عندما يكون الإعداد مفعلًا وتجاوزت الفترة 12 أو 24 ساعة.
- أمر Cron الوحيد هو `php artisan schedule:run` كل دقيقة.

## الترقيات الاختيارية

توجد إعدادات Redis في `config/database.php` لكن المسار المشترك لا يحتاجها. تشغيل Reverb/WebSockets ليس ضمن تشغيل هذه النسخة؛ polling هو مسار الإنتاج المدعوم. يمكن استبدال قناة الإشعار لاحقًا مع بقاء سياسات الرسائل والخدمات كما هي.