🌐 العربية · ← English · الفهرس ثنائي اللغة
Qwizin — وثائق المعمارية
الحالة: مسودة v0.1 · التاريخ: 2026-07-20 · القائد التقني: أمير هارون النطاق: وثائق بحث وتصميم فقط. لم يبدأ أي تنفيذ.
🧭 افتح الدليل الملاحي (NAVIGATOR) ←#
خريطة الوثائق · فهرس البحث بالسؤال · فهرس الميزات ← تدفقات البيانات · سجل المعرّفات · جميع الأسئلة المفتوحة الـ 25 · مرجع سريع للمخاطر · لوحة الحالة.
⛔ اقرأ أولًا — أربعة عوائق حاسمة#
يجب حسم هذه قبل بدء العمل الهندسي. ثلاثة منها تتطلب استشارة قانونية سعودية، لا مزيدًا من البحث.
| # | العائق الحاسم | لماذا يعيق | المسؤول |
|---|---|---|---|
| 1 | ترخيص SAMA — هل يتطلب تحصيل أموال المشترين وصرفها للمستشارين تصريح مؤسسة مدفوعات؟ | قد يُبطل تصميم المدفوعات بأكمله. مُدخل قرار المضي/عدم المضي، لا تفصيلة تصميمية. | مستشار خدمات مالية |
| 2 | الفوترة الإلكترونية ZATCA — مدى الانطباق، إضافة إلى قيد معماري صارم | تسلسل تجزئة الفواتير (hash-chaining) ذو حالة ومرتّب بصرامة — وهو يتعارض مع التوسّع الأفقي. غير مذكور في أي وثيقة مصدرية. | مستشار ضريبي + المعماري |
| 3 | مصفوفة الأدوار والصلاحيات المصحّحة | SRC-BRD §11 غير متسق داخليًا (CONF-03). لا يمكن تصميم التخويل انطلاقًا منه بصيغته الحالية. |
الراعي / محلل الأعمال |
| 4 | OQ-08 — هل تُسجَّل الاستشارات؟ |
تغيّر تكلفة البنية التحتية للفيديو بنحو 80%، وتغيّر تصنيف البيانات وفق PDPL. | الراعي |
لا تنفق جهدًا هندسيًا على المدفوعات أو الفوترة قبل الإجابة على 1 و2. فهما يحدّدان ما الذي سيُبنى، لا مجرد كيفية بنائه.
ترتيب القراءة#
ابدأ من هنا#
| الوثيقة | ماذا تعطيك |
|---|---|
00-requirements-baseline.md |
متطلبات مستخلصة من جميع الوثائق المصدرية الـ 12. الجهات الفاعلة، الوحدات (modules)، القيود، والتناقضات الخمسة المكتشفة في المصادر. جذر التتبّع — كل وثيقة أخرى تشير إلى معرّفاتها. |
01-quality-attribute-scenarios.md |
21 سيناريو قابلًا للقياس تحل محل الصفات ("آمن"، "قابل للتوسّع") في الوثائق المصدرية. تُثبت أن سمات الجودة المهيمنة على النظام ليست تلك التي تركّز عليها الوثائق. |
arc42/11-risks-and-technical-debt.md |
16 مخاطرة مرتّبة. اقرأ هذه قبل وثائق التصميم — عدد منها يغيّر ما يستحق التصميم أصلًا. |
المعمارية#
| الوثيقة | ماذا تعطيك |
|---|---|
arc42/03-context-and-containers.md |
C4 المستوى 1 (سياق النظام) والمستوى 2 (الـ containers). سجل التبعيات الخارجية. لماذا ليست microservices، وما الذي أُجّل عن قصد. |
arc42/05-building-block-view.md |
C4 المستوى 3. اثنتا عشرة وحدة (module)، عقودها العامة، كتالوج الأحداث بين الوحدات، قواعد التبعية — وآلية CI التي تفرضها. تحرس R-08، المخاطرة الوحيدة الموسومة بأنها غير قابلة للعكس عمليًا. |
arc42/06-runtime-view.md |
التدفقات الستة الحرجة معماريًا. المصادقة ودورة حياة الـ token، مسار رفع المستندات (pipeline)، الحجز←الدفع←الاستشارة، التقييم←الشهادة، بحث السوق الإلكتروني، الوصول المحصور بالمستأجر. |
arc42/06b-feature-flows-core.md |
خريطة تدفق بيانات النظام على المستوى 0 (4 pipelines) + التدفقات F-01…F-09: التسجيل حسب النوع، الملفات الشخصية، تزويد حسابات الموظفين، آلة حالات التفعيل، دليل المستشارين، الاستشارة الميدانية، كتالوج القوالب، طلبات القوالب المخصّصة، إسناد التدريب ومتابعة التقدّم. |
arc42/06c-feature-flows-commerce-admin.md |
التدفقات C-00…C-09: طوبولوجيا تدفق الأموال، آلة حالات دفع الاستشارة، الاشتراكات ومتابعة التحصيل (dunning)، الإدراج المميّز (featured) والترتيب، التحويلات للمزوّدين (payouts)، أدوار الإدارة وطوابيرها، إدارة المحتوى، التقارير ومؤشرات الأداء، توزيع الإشعارات (fan-out). |
| arc42/07-deployment-view.md | المناطق، البيئات، node pools، طبقة البيانات، طوبولوجيا الشبكة، التعافي من الكوارث (DR) (داخل المملكة، دون نقل عبر الحدود)، تحجيم السعة عند الإطلاق. |
| arc42/08-crosscutting-concepts.md | التعامل مع ثنائية اللغة/العربية، عقد الأخطاء، الخاصية التكرارية الآمنة (idempotency) والتزامن، اتفاقيات المال/الوقت/المعرّفات، قابلية المراقبة (observability)، التهيئة، استراتيجية الاختبار، الاحتفاظ والحذف. |
تعمّقات#
| الوثيقة | ماذا تعطيك |
|---|---|
deep-dives/devops-containerization-orchestration.md |
استراتيجية الـ containers، طوبولوجيا K8s، ثلاثة مسارات مستقلة لموازنة الأحمال، إشارات التوسّع التلقائي (autoscaling) لكل نوع حِمل، CI/CD، خارطة طريق تحصين متدرّجة مرتّبة بحسب خفض المخاطر لكل ساعة عمل. |
deep-dives/security-architecture.md |
سبع حدود ثقة (trust boundaries)، آلية عزل المستأجرين (tenant isolation)، مسار الرفع، الهوية والتخويل، نزاهة التقييمات/الشهادات، سجل التدقيق، نموذج التهديدات STRIDE، ترتيب التنفيذ حسب الأولوية. |
سجلات القرارات#
| ADR | القرار | الحالة |
|---|---|---|
ADR-0001 |
Oracle Cloud الرياض + جدة للتعافي من الكوارث (DR)، داخل المملكة | مقترح — مشروط بـ 4 بنود تحقق |
ADR-0002 |
نمط أحادي معياري (modular monolith) بدلًا من microservices | معتمد |
ADR-0003 |
Kubernetes، بمستوى تحكّم مُدار | معتمد — مع تحفّظ مُوثَّق |
ADR-0005 |
منفذ فيديو (port) محايد تجاه المزوّد؛ المزوّد مؤجَّل | مقترح — مشروط بـ OQ-08 + حسم قانوني |
ADR-0007 |
قاعدة بيانات مشتركة + PostgreSQL RLS، فرض من خمس طبقات | معتمد |
ADR-0004 (منفذ الدفع)، وADR-0006 (محرك البحث)، ونموذج السعة/التكلفة لم تُكتب عن قصد. كلٌّ منها يعتمد على دليل غير موجود بعد — حسم قانوني، وتجربة مقارنة مقيسة للبحث العربي، وعروض أسعار من المزوّدين على التوالي. كتابتها الآن ستنتج قرارات لا شيء خلفها.
القرارات الأساسية (Baseline)#
| القرار | الاختيار | المسوّغ |
|---|---|---|
| الاستضافة | داخل منطقة المملكة — Oracle OCI الرياض، وجدة للـ DR | المزوّد الوحيد الذي لديه منطقتان متاحتان عمومًا (GA) داخل المملكة (تعافٍ من الكوارث حقيقي داخل البلد)؛ وتسعير عالمي موحّد مقابل علاوة Google الدمام البالغة نحو +88% |
| النمط المعماري | Laravel modular monolith + sidecars مستخرَجة | المكوّنات ذات ملامح توسّع مختلفة فعليًا (إخراج PDF، فحص البرمجيات الخبيثة، البحث، الوسائط) تُستخرج بالفعل — وهو الفائدة الحقيقية من microservices، دون تكلفة الأنظمة الموزّعة |
| التنسيق (orchestration) | Kubernetes (OKE مُدار) | قرار معماري؛ العبء التشغيلي مُوثَّق كـ R-09 |
| العملاء (Clients) | الجوال أولًا، والويب لاحقًا | Backend يعتمد نهج API-first؛ لا BFF — وجود نوع عميل واحد يجعل الـ BFF وسيطًا لنفسه |
| Backend | Laravel 13 + PHP 8.4، PHP-FPM (لا Octane في البداية) | عمّال Octane الدائمون يرفعون فعليًا مخاطر التسرّب بين المستأجرين (R-05) مقابل أداء لا يحتاجه حجم الإطلاق |
| قاعدة البيانات | PostgreSQL مع أمان مستوى الصفوف (RLS) | طبقة عزل المستأجرين الوحيدة التي ترفض عند الشك (fail closed) بغض النظر عن أخطاء التطبيق |
| الفيديو | مؤجَّل خلف منفذ (port) | انظر ADR-0005 |
| المدفوعات | مؤجَّلة خلف منفذ (port) | معلّقة على OQ-01 وسؤال SAMA |
نتائج قلبت افتراضات سابقة#
مُوثَّقة لأن العمل بالافتراضات الأصلية كان سينتج نظامًا أسوأ.
- PDPL لا يفرض التخزين داخل المملكة للبيانات الشخصية في القطاع الخاص. تسمح المادة 29 بالنقل عبر الحدود ضمن شروط (SCCs أو BCRs أو الاعتماد، إضافة إلى تقييم مخاطر). تبقى الاستضافة داخل المملكة هي الخيار الصحيح — لكن لأنها تُلغي مسار عمل الامتثال للنقل وتفي مسبقًا بقاعدة البيانات الحكومية لدى CST، لا لأنها مفروضة قانونًا. المصادر متعارضة؛ والاستشارة القانونية مطلوبة.
- لا تملك AWS منطقة GA يمكن التحقق منها في السعودية. توثيق AWS نفسه لا يذكر في الشرق الأوسط سوى البحرين والإمارات، بما يناقض عدة مصادر ثانوية تزعم إطلاقًا في يناير 2026.
- LiveKit لا يتجاوز قيد hostNetwork في Kubernetes. توثيقه الخاص يشترط شبكة المضيف وpod واحد لكل node — وهو مطابق معماريًا لـ JVB في Jitsi. القول الشائع بأن "LiveKit هو الحل السحابي الأصيل" غير صحيح بالصيغة المتداولة.
- التسجيل يقضي على أفضلية Jitsi في التكلفة. ينضم Jibri كمشارك ثالث، مما يُخرج المكالمات الثنائية من وضع P2P ويعيدها عبر الجسر (bridge) — فيقتل التوفير البالغ نحو 80% ويضيف أغلى شريحة أيضًا. كلا الأثرين ينبعان من قرار منتجي واحد (
OQ-08). - Meilisearch بلا اشتقاق جذور (stemming) وبلا تعزيز عند الاستعلام، ونسخته مفتوحة المصدر بلا توفّر عالٍ (HA) (النسخ المتماثل والتجزئة ضمن نسخة Enterprise المرخّصة بـ BSL). كلا الأمرين يؤثر مباشرة في استرجاع النتائج العربية وفي تحقيق الدخل من الإدراج المميّز.
- Laravel بلا إصدار LTS. آخر إصدار LTS كان النسخة 6 (2019). نافذة إصلاح العلل في Laravel 12 تُغلق في 2026-08-13. يجب رصد ميزانية لترقية رئيسية سنوية كعمل روتيني.
- إرجاع
Gate::beforeللقيمةfalseيُعطّل كل policy في التطبيق — الطريقة البديهية لتطبيق شرط "يجب أن يكون الحساب معتمدًا" هي فخ مُوثَّق يُعطّل أيضًا مراجعة المسؤول الأعلى (super-admin).
الوثائق المصدرية#
الملفات الاثنا عشر في المجلد الأعلى. لاحظ أن ستة منها — دفاتر عمل SOP وHACCP وسلامة الغذاء والتدقيق — هي عيّنات محتوى لمكتبة القوالب، لا مواصفات نظام. بنيتها مهمة لسبب واحد: دفاتر التدقيق عبارة عن قوائم تحقق بصف لكل ضابط، وهو ما يشير إلى أن "القالب القابل للتحميل" شكل انتقالي لما سيصبح أداة تدقيق رقمية تفاعلية (SEAM-03).
مصادر البحث وحدوده#
تستند هذه الوثائق إلى بحث متوازٍ شمل المشهد السحابي والتنظيمي في السعودية، والبنية التحتية للفيديو، وأنماط معمارية Laravel، والأمن والامتثال.
قيدان يُذكران بصراحة:
- استُنفدت ميزانية البحث على الويب في هذه الجلسة، وتوقفت عدة مسارات بحثية مبكرًا. البنود التي تعذّر التحقق منها مقابل مصادر أولية موسومة صراحةً بـ UNVERIFIED في كل الوثائق بدلًا من ملئها من الذاكرة. أرقام التكلفة والادعاءات التنظيمية هي بالضبط المواضع التي يُحدث فيها رقم خاطئ يبدو معقولًا ضررًا — ولا يظهر أي منها هنا إلا إذا كان مسترجَعًا أو موسومًا بأنه استنتاج بنيوي.
- لا شيء هنا فتوى قانونية. أقسام SAMA وZATCA وPDPL هي أطر تحديد نطاق وقوائم أسئلة للمستشار القانوني، لا إجابات.
بنود التحقق المفتوحة الرئيسية مدرجة في arc42/11-risks-and-technical-debt.md تحت R-16.
الخطوات التالية الموصى بها#
قبل أي كود:
- الاستعانة بمستشار قانوني سعودي بشأن SAMA وZATCA والواجبات التشغيلية لـ PDPL
- الحصول على مصفوفة الأدوار والصلاحيات المصحّحة (
CONF-03) - الحسم في
OQ-08(التسجيل) وCONF-01(نطاق التدريب)
تجارب استكشافية (spikes) رخيصة تُزيل مخاطر غير متناسبة: 4. تجربة مقارنة للبحث العربي — 2–3 أيام، نحو 500 إدراج حقيقي، المحركات الأربعة جميعها مع pipeline تطبيع أمامها. قرار غير قابل للتراجع. 5. إخراج PDF عربي — يوم واحد. أنتج شهادة ثنائية اللغة حقيقية واحدة واعرضها على متحدث بالعربية. 6. التحقق من مصفوفة خدمات منطقة OCI وفئة التسجيل لدى CST — ساعات، وتحكم بوابة ADR-0001
ابْنِ هذا قبل وجود الوحدة الثانية:
7. منظومة الفرض (enforcement harness) — Deptrac (ملاحظة: deptrac/deptrac، أما qossmic/deptrac القديم فمهجور) + اختبارات المعمارية + مجموعة الاختبار العدائية بمستأجرَين. إعادة تركيب الحدود على ست وحدات لاحقًا تكلّف نحو 20 ضعفًا.
8. صندوق الصادر المعاملاتي (outbox) + واجهة EventBus — نحو يوم واحد، وهو أرخص تأمين متاح لعملية الفصل المستقبلي
9. سياسات RLS بالتزامن مع أول migration مرتبط بالمستأجر — إضافة RLS إلى جدول ممتلئ بالبيانات تتطلب نافذة صيانة
لم تُكتب عن قصد بعد — كلٌّ منها معلّق على دليل لا على جهد:
| المُخرَج | معلّق على |
|---|---|
| ADR-0004 — منفذ الدفع | حسم SAMA في OQ-10. الإجابة القانونية تغيّر طوبولوجيا الدفع، لا مجرد معاملاتها. |
| ADR-0006 — محرك البحث | تجربة المقارنة للبحث العربي. هذا قرار غير قابل للتراجع يحتاج استرجاعًا مقيسًا على إدراجات حقيقية، لا رأيًا. |
| نموذج السعة والتكلفة | قرار التسجيل في OQ-08 + عروض أسعار المزوّدين. الفيديو هو التكلفة المتغيرة المهيمنة ويتأرجح بنحو 80% تبعًا لتلك الإجابة الواحدة. |