سياسة معمارية منصّة RaR-IT لأنظمة SaaS

المعايير الإلزامية للبنية والتقنيات لجميع المحركات المشتركة والقطاعات المنتجة

:::danger الحالة: مُقترَحة — قيد المراجعة والاعتماد والنشر الإصدار 1.0 · 25 أغسطس 2026. هذا المستند غير سارٍ بعد — راجع القسم 10. :::

1- الغرض والنطاق

تُحدّد هذه السياسة البنية المعمارية والحزمة التقنية الإلزامية لكل نظام SaaS يُبنى أو يُصان ضمن برنامج RaR-IT متعدد القطاعات لمنصات SaaS — بما يشمل النواة المنصّية المشتركة (@rarit-kernel) وجميع القطاعات المنتجة (حالياً: عَمَار، Clinivio، EduSuite، الشحن والنقل، والسياحة، بالإضافة إلى أي قطاع مستقبلي يُضاف للبرنامج). تحكم هذه السياسة خدمات الخلفية والمحركات المشتركة ونقاط تكاملها المباشرة.

الغرض من هذه السياسة هو الحفاظ على الاتساق البنيوي بين قطاعات المنصّة الخمسة الحالية — وأي قطاع مستقبلي — وتجنّب تكرار الجهد الهندسي بين القطاعات، وضمان ألا تُعاد فتح أو مخالفة القرارات المعمارية التي جرى تقييمها فعلياً قطاعاً بقطاع.

2- سريان السياسة وإلزاميتها

بعد النشر، تكون هذه السياسة إلزامية لجميع موظفي RaR-IT والمتعاقدين وأي طرف ثالث ينفّذ عملاً هندسياً على أي نظام SaaS تابع لـRaR-IT، دون استثناءات إلا عبر إجراء الانحراف الرسمي في القسم 8.

تنطبق هذه السياسة على: جميع خدمات الخلفية الجديدة؛ جميع المحركات المشتركة الجديدة؛ جميع عمليات إعادة الهيكلة الجوهرية للخدمات القائمة.

العمل غير المتوافق الذي يُدمَج دون استثناء معتمَد بموجب القسم 8 يكون عرضةً للتراجع عنه أو لخطة ترحيل على حساب الفريق المسؤول، بحسب تقدير لجنة مراجعة المعمارية (القسم 9).

3- بنية المنصّة — النواة المشتركة والقطاعات

3-1 النواة المشتركة (@rarit-kernel)

توفّر النواة المشتركة للمنصّة خمسة محركات، تُنشَر كل منها كحزمة npm ضمن النطاق @rarit-kernel، تُستهلَك — لا يُعاد بناؤها — من قِبل كل قطاع:

• @rarit-kernel/entitlements — خطط المستأجرين، بيانات باقات الميزات، تقييد الوحدات لكل مستأجر.
• @rarit-kernel/iam — المصادقة، إدارة الجلسات، التحكم بالوصول القائم على الأدوار (RBAC)، وهوية المستأجر (جدول tenants موجود هنا؛ وكل محرك آخر يُشير إليه).
• @rarit-kernel/payment — الفوترة، إصدار الفواتير، التسوية، وآليات الاسترداد والسداد.
• @rarit-kernel/notifications — الإرسال داخل التطبيق والبريد الإلكتروني والرسائل النصية عبر جميع أحداث دورة الحياة.
• @rarit-kernel/audit — سجل تدقيق واحد مشترك غير قابل للحذف عبر كل القطاعات.

3-2 القطاعات المنتجة

كل قطاع بيئة تشغيل وقاعدة بيانات معزولة، متعددة المستأجرين داخلياً عبر Row-Level Security في PostgreSQL، ومُلزَم بنيوياً باستهلاك المحركات المشتركة الخمسة كافة:

• عَمَار (AMAAR) — العقارات والمقاولات
• Clinivio — الطبي/الرعاية الصحية
• EduSuite — التعليم
• الشحن والنقل (Shipping & Transport)
• السياحة (Tourism)

أي قطاع يُضاف للبرنامج مستقبلاً يدخل تلقائياً ضمن نطاق هذه السياسة منذ أول التزام (commit) له.

4- المبادئ المعمارية الأساسية

ما يلي إلزامي وغير قابل للتفاوض دون استثناء بموجب القسم 8:

• المحركات إضافات مُدمَجة (plugins)، لا خدمات مصغّرة مستقلة — المحركات الخمسة هي إضافات Fastify مُدمَجة مباشرة داخل عملية الخلفية الخاصة بكل قطاع.
• تغليف Fastify للإضافات هو حد تركيب (Composition)، لا حد تفويض (Authorization) — التفويض دائماً مسؤولية محركَي Entitlements وIAM، ويُتحقَّق منه صراحةً.
• هوية المستأجر مملوكة لمحرك IAM، لا لأي محرك آخر — جدول tenants موجود داخل @rarit-kernel/iam.
• محركات قائمة على البيانات الوصفية (Manifest) مقابل محركات ذات عقد ثابت — Entitlements وIAM وNotifications قائمة على بيانات وصفية؛ أما Payment وAudit فذات عقد ثابت.
• نماذج تحصيل الإيرادات الخاصة بقطاع معيّن هي إعداد (Configuration) فوق Payment وEntitlements، لا محركات جديدة.
• المراقبة والقابلية للرصد (Observability) هي أدوات قياس على مستوى البنية التحتية، لا محرك سادس ذو حالة.

5- حزمة التقنيات الإلزامية

الطبقة	التقنية	الحالة	المبرر
اللغة وبيئة التشغيل	Node.js + TypeScript	إلزامية	لغة واحدة عبر الخلفية والأدوات؛ التصنيف الساكن لـTypeScript ضروري في هذا المقياس.
إطار الخلفية	Fastify	إلزامي	نموذج التغليف/الإضافات فيه يُطابِق مباشرة معمارية "المحركات كإضافات مُدمَجة".
قاعدة البيانات	PostgreSQL	إلزامية	Row-Level Security (RLS) هي الآلية الجوهرية لعزل المستأجرين في المنصّة.
الواجهة الأمامية (Web)	React	إلزامية	مُعتمَدة عبر تطبيق الويب الخاص بكل قطاع.
الجوال	Flutter	إلزامي	اختير مرة واحدة للمنصّة بأكملها بدلاً من اختيار لكل قطاع.

6- البدائل المُقيَّمة والمرفوضة (لتأليف المحركات المشتركة)

جرى تقييم التقنيات التالية رسمياً لاستخدامها في تأليف المحركات المشتركة ورُفضت صراحةً في هذا الدور. يتناول القسم 6-1 أدناه سؤالاً مختلفاً — استخدام Nest في منطق أعمال القطاع الخاص — وهو أمرٌ تُرِك مفتوحاً، لا مرفوضاً.

التقنية	الحالة	سبب الرفض
NestJS	مرفوض لتأليف المحركات المشتركة	يُكرّر ما يوفّره تغليف إضافات Fastify فعلاً لنموذج "المحركات كإضافات مُدمَجة". حكم على مدى الملاءمة للمحركات بالتحديد، لا حكم عام على NestJS.
Express	مرفوض لصالح Fastify	استُبدِل بتحقق Fastify القائم على المخطط أولاً وأداء أعلى.
MongoDB / أي مخزن NoSQL كمخزن أساسي للمستأجرين	مرفوض لبيانات المستأجرين الجوهرية	RLS آلية علائقية خاصة بـPostgreSQL يُبنى عليها نموذج عزل المستأجرين بأكمله.

6-1 السماح المحدود النطاق: NestJS لمنطق أعمال القطاع الخاص

بخلاف القسم 6 أعلاه، لا تُعتبَر NestJS مرفوضة كأداة عامة الاستخدام. يجوز لأي قطاع استخدام Nest لتنظيم منطق أعماله الخاص بتطبيقه عندما تستفيد تعقيدات ذلك القطاع فعلياً من بنية الوحدات/حقن التبعيات في Nest. هذا قرار محلي خاص بكل قطاع، مقيَّد بشرطين:

1. نمط التكامل: يجب استخدام Nest كسياق تطبيق لحقن التبعيات فقط (عبر NestFactory.createApplicationContext)، مع بقاء ملكية كل مسار HTTP وبيان ميزات الوحدة وخطّاف التحقق من الاستحقاقات بيد Fastify.
2. الالتزام بالبيان (Manifest): يجب أن تُصدِّر الوحدة نفس بيان الميزات المستقل عن الإطار الذي تقرؤه آلية اكتشاف Entitlements فعلاً لكل وحدة أخرى.

يوجد نمط ثانٍ — تشغيل Nest نسخة HTTP خاصة بها — وهو ممكن تقنياً لكنه ليس الافتراضي ويتطلب اعتماد لجنة مراجعة المعمارية قبل استخدامه. راجع الملحق أ لأمثلة برمجية كاملة لكلا النمطين.

7- المكوّنات المُوصى بها القابلة للاستبدال

المكوّن	الافتراضي الحالي	يمكن استبداله بـ
طبقة ORM/الاستعلام	Drizzle ORM	أي طبقة استعلام TypeScript آمنة الأنواع وقائمة على SQL أولاً (مثل Kysely).
طابور المهام الخلفية	pg-boss أو BullMQ	كلاهما مقبول افتراضياً.
التحقق من المخطط	Zod	أي مُدقِّق مخطط قائم على TypeScript أولاً.
توثيق API	OpenAPI/Swagger مُولَّد من مخططات Fastify	يجب أن يُولَّد من نفس المخططات المستخدَمة في التحقق وقت التشغيل.

8- إجراء الاستثناء والانحراف

أي انحراف عن القسم 5 (الإلزامي) أو القسم 6 (المرفوض) يتطلب:

1. مقترحاً مكتوباً يُبيّن القيد التقني المحدد.
2. مراجعة واعتماد لجنة مراجعة المعمارية (القسم 9).
3. توثيق الاستثناء المعتمَد في سجل تغييرات هذه السياسة، بما يشمل النطاق وتاريخ انتهاء/مراجعة.

9- الحوكمة والملكية

تخضع ملكية هذه السياسة لـ المدير التقني تتكوّن لجنة مراجعة المعمارية من المدير التقني + مهندس أول واحد لكل قطاع نشط . تُراجَع هذه السياسة كل ربعين على الأقل.

10- اعتماد السياسة

بالتوقيع أدناه، يقرّ الأطراف المعنيون باعتماد هذه السياسة كمعيار إلزامي، سارٍ من تاريخ النشر الرسمي.

الدور	الاسم	التوقيع	التاريخ
المدير التقني
قائد قطاع عَمَار (AMAAR)
قائد قطاع Clinivio
قائد قطاع EduSuite
قائد قطاع النقل (Transport)
قائد قطاع السياحة (Tourism)

:::info السجل المُعتمَد بعد التوقيع، تُحفَظ النسخة المعتمَدة (PDF/DOCX) لهذا الإصدار ضمن signed-records/saas-architecture/ في هذا المستودع كنسخة ضبط غير قابلة للتغيير. يستمر مصدر Markdown هذا في التطوّر نحو الإصدار التالي. :::