arc42 §8 — المفاهيم الشاملة
الحالة: مسودة v0.1 · التاريخ: 2026-07-20 الغرض: أنماط تسري عبر الـ modules. تُحسم هنا مرة واحدة بدل أن تُحسم بتضارب في اثني عشر موضعًا.
8.1 المحتوى ثنائي اللغة (عربي / إنجليزي)#
OQ-12 · QAS-LOC-01, QAS-PERF-02 · CON-12
Qwizin منصة سعودية بوثيقة متطلبات أعمال (BRD) عربية. والعربية ليست فكرة لاحقة في التوطين — بل هي اللغة الأساسية للسوق.
التخزين: الفصل حسب نوع المحتوى، لا حسب طول الحقل#
| المحتوى | الآلية | لماذا |
|---|---|---|
| السمات القصيرة — أسماء الإدراجات، تسميات الفئات، الوسوم، الأوصاف القصيرة | عمود JSON ({"ar": "...", "en": "..."}) |
صفّ واحد، بلا joins، وكتابة بسيطة. وهو غالبية المحتوى القابل للترجمة. |
| المحتوى المطوّل — وحدات التدريب، القوالب، أسئلة التقييم | جدول ترجمة منفصل | هذه تحتاج دورات حياة مستقلة: قد تُنشر النسخة العربية بينما الإنجليزية قيد المراجعة، ولكل منها مؤلفها وحالة مراجعتها وتاريخ إصداراتها |
التمييز ليس في طول الحقل — بل في ما إذا كانت للترجمة دورة حياة مستقلة. لا تستطيع كتلة JSON أن تعبّر عن "النسخة العربية معتمدة والإنجليزية ليست كذلك"، وتركيب ذلك لاحقًا يعني ترحيل أثمن محتوى لديك.
التطبيع العربي (normalisation) — إلزامي لا اختياري#
يكتب المستخدمون أ / إ / آ / ا بالتبادل، و ى و ي بالتبادل، ولا يكتبون التشكيل تقريبًا أبدًا. وبدون الطيّ (folding) ينهار استرجاع البحث بصمت وبالكامل — يبحث المستخدم بالعربية، فلا يحصل على شيء، فيستنتج أن الدليل فارغ.
مسار معالجة التطبيع (pipeline) (يُطبَّق بالطريقة نفسها عند الفهرسة وعلى الاستعلامات):
strip tatweel (ـ) → strip diacritics/harakat → fold أإآٱ → ا
→ fold ة → ه → fold ى → ي → normalise Arabic-Indic digits ٠-٩ → 0-9
امتلك هذا في طبقة التطبيق. فهو نحو 150 سطرًا من معالجة النصوص جيدة الاختبار، ويقدّم النصف الأعلى أثرًا من جودة البحث العربي على أي محرك، ويجعل اختيار المحرك قابلًا للتراجع بدل أن يكون قرارًا غير قابل للتراجع (
R-11). وهو أكثر استثمار قابل للنقل متاح.
اهتمامات عربية إضافية#
| الاهتمام | المعالجة |
|---|---|
| الجموع المكسّرة (كتاب → كتب, بيت → بيوت) | لا يتعامل معها أي مُجذِّر خفيف (light stemmer) — وهي شائعة في أسماء المنتجات والفئات. خطّط لقاموس مرادفات/جذور بغضّ النظر عن المحرك؛ فهو الاستثمار الأعلى رافعة في الملاءمة. |
| الترتيب اللغوي (Collation) | الـ collation الافتراضي يعطي ترتيب النقاط الرمزية (codepoints)، لا الترتيب الأبجدي العربي. حدّد collation عربيًا لأي قائمة مرتّبة يراها المستخدم. |
| محارف التحكم بالاتجاه (RLM/LRM) | جرّدها عند الإدخال — فهي تكسر المطابقة التامة بشكل غير مرئي |
| الخلط بين LTR وRTL ("iPhone 15 برو") | اقتطاع واعٍ بالحروف الرسومية (grapheme-aware) في المعاينات؛ ولا تشطر عنقودًا ولا تترك علامة اتجاه معلّقة |
| الـ Slugs | الـ slugs العربية تحتاج نقحرة (transliteration) أو ترميزًا بالنسبة المئوية — احسم ذلك صراحةً |
شكل استجابة الـ API#
احسم اللغة على الخادم افتراضيًا؛ وأرجِع النص المحسوم مع بياناته الوصفية.
{ "id": 42, "name": "مطعم الرياض", "locale": "ar", "locale_fallback": false }
| القاعدة | المبرر |
|---|---|
استخدم معاملًا صريحًا ?locale= بوصفه مفتاح الذاكرة المؤقتة (cache key)، لا Accept-Language |
Accept-Language عالي التعدّد في الواقع (ar, ar-SA, ar-SA,ar;q=0.9,en;q=0.8…) ويمزّق معدلات إصابة الـ CDN. قيمتان مدعومتان = مدخلتان في الذاكرة المؤقتة. |
Accept-Language يُطبَّع إلى المجموعة المدعومة، ويُستخدم بوصفه قيمة افتراضية فقط |
— |
أرجِع كل الـ locales في نقاط النهاية التفصيلية والإدارية (?locales=all) |
المحرّرون يحرّرون الترجمات حرفيًا؛ والعروض التفصيلية تستفيد من التبديل الفوري |
أرجِع locale_fallback دائمًا |
الرجوع الصامت يجعل الترجمات المفقودة غير مرئية لفريق المحتوى. وفجوات المحتوى مشكلة منتج لا مشكلة عرض. |
أرجِع تلميح direction ضمن بيانات الـ locale الوصفية |
كي لا يكتب كل عميل خريطة locale ← direction بشكل صلب |
8.2 معالجة الأخطاء وعقد الـ API#
شكل استجابة الخطأ#
متسق عبر كل نقطة نهاية. يجب أن يكون بمقدور عملاء الجوال التصرّف بناءً على الأخطاء برمجيًا.
{
"error": {
"code": "account.not_approved",
"message": "Your account is under review.",
"message_ar": "حسابك قيد المراجعة.",
"details": { "state": "under_review", "submitted_at": "..." },
"correlation_id": "01J..."
}
}
| العنصر | الغرض |
|---|---|
code مقروء آليًا |
يتفرّع العملاء بناءً عليه، لا بناءً على نص الرسالة أبدًا |
| رسالة مترجَمة | قابلة للعرض مباشرةً |
details |
سياق مُهيكل — مثل حالة الحساب، ليعرض التطبيق شاشة onboarding الصحيحة |
correlation_id |
يستطيع المستخدم اقتباسه للدعم، وهو يرتبط مباشرةً بالسجلات (QAS-OPS-01) |
انضباط رموز الحالة#
| الرمز | الاستخدام |
|---|---|
400 |
طلب مشوَّه |
401 |
مصادقة مفقودة/غير صالحة |
403 |
مُصادَق عليه، لكن غير مسموح — وشرط ذلك ألّا يكون وجود المورد سرًّا |
404 |
غير موجود أو محاولة استكشاف عابرة للمستأجرين — فالرمز 403 يؤكد الوجود ويتيح هجوم التعداد |
409 |
تعارض في الحالة (مثل حجز موعد محجوز) |
422 |
فشل تحقق مع تفصيل على مستوى الحقل |
429 |
تجاوز حد المعدل، مع Retry-After |
فلسفة الفشل#
| المبدأ | المعنى |
|---|---|
| الرفض عند الشك (fail closed) في التخويل وتعدّد المستأجرين | الغموض يعني الرفض |
| السماح عند الشك (fail open) في الإثراء غير الحرج | البحث غير متاح ← عرض إدراجات متدهور من قاعدة البيانات، لا صفحة خطأ (QAS-AVL-04) |
| لا تفقد عملًا أُودع (committed) أبدًا | نتيجة التقييم تنجو من فشل توليد PDF؛ والحجز ينجو من فشل الإشعار |
| الأخطاء أحداث | حالات رفض التخويل هي إشارة الهجوم — سجّلها (§8.5) |
8.3 الخاصية التكرارية الآمنة (idempotency) والتزامن#
الـ idempotency#
| السطح | الآلية |
|---|---|
| تغييرات الدفع التي يبدأها العميل | idempotency key يوفّره العميل، مخزَّن مع النتيجة |
| كل الـ webhooks الواردة | إزالة التكرار بناءً على معرّف الحدث لدى المزوّد — فالمزوّدون سيعيدون المحاولة |
| المهام في الطوابير | المعالِجات idempotent؛ وحدوث SIGKILL بعد انتهاء مهلة السماح سيقع |
| تسليم التقييم | التسليم الثاني لمحاولة مُنهاة يُرفض، لا يُعاد تصحيحه |
المعالجة المكرّرة لعملية capture تعني خصمًا مزدوجًا. وهذه ليست لطافة في المتانة.
التزامن#
| نقطة التنافس | الآلية |
|---|---|
| موعد الحجز | قفل تشاؤمي (pessimistic lock) طوال نافذة الحجز — فالحجز المزدوج مرئي للمستخدم وغير قابل للتعافي |
| تجديد الاشتراك | قفل موزّع لكل اشتراك |
تسلسل فواتير ZATCA (إن انطبق OQ-11) |
نقطة تسلسل واحدة — فالتسلسل بالتجزئة (hash chaining) مرتَّب بصرامة ولا يمكن إنتاجه بالتوازي من عدة pods (R-02) |
| إصدار الشهادات | مرتبط معامليًا بمحاولة مصحَّحة؛ وقيد فريد يمنع التكرار |
| العدّادات / التجميعات | زيادات ذرّية (atomic)، لا قراءة-تعديل-كتابة أبدًا |
8.4 الوقت والمال والمعرّفات#
الوقت#
| القاعدة | المبرر |
|---|---|
| خزّن بتوقيت UTC، دائمًا | — |
| اعرض بتوقيت Asia/Riyadh افتراضيًا | سوق سعودي أولًا |
| منطق ساعات العمل يستخدم الأحد إلى الخميس | أسبوع العمل السعودي — وافتراض الإثنين إلى الجمعة خاطئ هنا |
| لا تثق بساعة العميل أبدًا | حدود وقت التقييم تُفرض مقابل وقت البدء المسجَّل على الخادم |
| مواعيد الحجز تحمل منطقة زمنية صريحة | مطلوب قبل التوسّع الخليجي (CON-12) |
| التواريخ الهجرية حيث تواجه المستخدم | فكّر فيها للشهادات والوثائق الرسمية |
المال#
| القاعدة | المبرر |
|---|---|
| وحدات فرعية صحيحة (هللات) — لا أعداد عشرية عائمة أبدًا | المال بالفاصلة العائمة خطأ صحّة ينتظر حالة تقريب |
| العملة صريحة على كل مبلغ | CON-12 — التوسّع الخليجي يعني أن الريال لن يبقى العملة الوحيدة إلى الأبد |
كائن قيمة Money في النواة المشتركة |
يمنع خلط العملات عن غير قصد |
| خزّن المبلغ كما حُصِّل، لا مجرد مرجع إلى خطة | أسعار الخطط تتغير؛ والسجلات التاريخية يجب ألا تتغير |
| ضريبة القيمة المضافة تُعالَج صراحةً | لا تُدمج في إجمالي مبهم (OQ-11) |
المعرّفات#
| النوع | الاستخدام |
|---|---|
| ULID/UUID لأي شيء يُشار إليه خارجيًا | الإدراجات، الحجوزات، الوثائق، الشهادات — يزيل التعداد التافه |
| أعداد صحيحة متسلسلة داخليًا حيثما كان مفيدًا | — |
| لا تسلسل للشهادات أبدًا | المعرّفات المتسلسلة تتيح لأي شخص تعداد مجموعة الشهادات بأكملها |
كائنات قيمة للمعرّفات المنمَّطة (UserId, CompanyId) |
تمنع تمرير معرّف شركة في موضع معرّف مستخدم — وهو مصدر حقيقي لأخطاء عبور المستأجرين |
8.5 قابلية المراقبة (observability)#
QAS-OPS-01 — يجب أن يشخّص مهندس مناوب واحد حادثة في الساعة 02:00 دون معرفة ضمنية متوارثة.
flowchart LR
REQ["Request"] -->|"generate<br/>correlation_id"| API["API"]
API -->|"propagate"| JOB["Queue job"]
API -->|"propagate"| SIDE["Sidecar"]
API -->|"propagate"| EXT["External call"]
API & JOB & SIDE --> LOGS["Structured logs<br/><i>correlation_id on every line</i>"]
API & JOB & SIDE --> TRACE["Traces"]
API & JOB & SIDE --> METRIC["Metrics"]
LOGS & TRACE & METRIC --> ALERT["Alerts on<br/><b>user-facing SLOs</b>"]
| الإشارة | النهج |
|---|---|
| معرّف الارتباط (correlation ID) | يُولَّد عند بوابة الدخول، ويُمرَّر عبر كل قفزة غير متزامنة، وحاضر في كل سطر سجل ومُعاد في استجابات الخطأ |
| التتبعات (Traces) | مُعايَنة؛ تدفقات الدفع والفيديو بنسبة 100 % |
| المقاييس | RED للـ API؛ وعمق الطابور وعمر أقدم مهمة للـ workers؛ وعدد الجلسات للوسائط |
| السجلات | JSON مُهيكل إلى stdout، تُشحن خارج العنقود، مع حجب البيانات الشخصية (PII) في طبقة التسجيل |
| التنبيهات | على أهداف مستوى الخدمة (SLOs) التي تواجه المستخدم — لا على رسوم استهلاك المعالج |
مقاييس الأعمال من الدرجة الأولى، لا فكرة لاحقة: مؤشرات الأداء الأربعة في SRC-MOM §13 تتطلب التقاط أحداث مصمّمًا منذ البداية. وإعادة بناء "عدد القوالب المُنزَّلة" من سجلات الوصول بعد عام مكلفة وغير دقيقة.
8.6 التهيئة وإدارة الميزات#
هرمية التهيئة#
| الطبقة | تحتوي | التغيير يتطلب |
|---|---|---|
| وقت البناء | تهيئة إطار العمل، مُخزَّنة مؤقتًا | نشرًا |
| البيئة | نقاط النهاية، بيانات الاعتماد (من مخزن الأسرار) | إعادة تشغيل |
| وقت التشغيل / قاعدة البيانات | تهيئة الأعمال | لا شيء — واجهة المسؤول |
ما يجب أن يكون تهيئة في قاعدة البيانات، لا كودًا#
CON-07 وCON-08 قيدان صريحان، وكلاهما يُستوفى ببساطة تامة إذا صُمّم بشكل صحيح من البداية:
- خطط الاشتراك وتسعيرها (
CON-07) - درجات النجاح في التقييمات (
CON-08) - باقات الإدراج المميّز (featured)
- مجموعات الوثائق المطلوبة لكل نوع حساب (بانتظار
OQ-02) - قوالب الإشعارات
- SLA استجابة المستشار، ونوافذ انتهاء صلاحية الحجز (بانتظار
OQ-05)
تغيير درجة النجاح يجب ألا يستلزم إصدارًا إطلاقًا. كل ما قد يرغب صاحب مصلحة في الأعمال بتعديله على نحو معقول ينتمي إلى لوحة المسؤول — وكتابته بشكل صلب تحوّل قرار عمل مدته خمس دقائق إلى عملية نشر.
مفاتيح الميزات (Feature flags)#
لميزات التدريب المعتمدة على CONF-01، وللطرح التدريجي للتغييرات عالية المخاطر (فرض RLS، تبديل محرك البحث). أبقِ مجموعة المفاتيح صغيرة وأزل المفتاح بمجرد حسم القرار — فالمفتاح الدائم تفرّع غير مُختبَر.
8.7 استراتيجية الاختبار#
مرتّبة حسب قيمتها في منع العيوب في هذا النظام تحديدًا، لا حسب العُرف.
| الطبقة | التركيز | غير قابل للتفاوض |
|---|---|---|
| حزمة اختبارات خصومية عابرة للمستأجرين | كل نقطة نهاية، في الاتجاهين | ⭐ QAS-SEC-01 — الضابط الذي ينجو من دوران الموظفين |
| اختبارات معمارية | حدود الـ modules، وعزل User، وسمات المستأجر، ولا env() خارج ملفات التهيئة |
⭐ R-08 |
| اختبارات العقد (Contract tests) | لا حقول صحّة الإجابات في استجابات تسليم التقييم | ⭐ QAS-INT-01 |
| اختبارات الصورة الذهبية (Golden-image) | تصيير PDF العربي على مجموعة أسماء ثابتة | ⭐ QAS-LOC-01 |
| التكامل | آلات الحالة: الحجز، الاعتماد، الاشتراك | قيمة عالية |
| الوحدة | منطق المجال، التصحيح، حسابات المال | قياسي |
| الحمل | ذروة التزامن، التوليد الدفعي للشهادات | قبل الإطلاق |
الطبقات الأربع المُنجَّمة غير معتادة وخاصة بمخاطر هذا النظام. هرم اختبارات تقليدي كان سيفوّت الأربع جميعًا، وكل واحدة منها تحرس نمط فشل صامت في الإنتاج.
8.8 الاحتفاظ بالبيانات وحذفها#
QAS-CMP-01 · ⚠️ مدد الاحتفاظ تتطلب تأكيدًا قانونيًا (R-03)
| البيانات | محرّك الاحتفاظ | التعارض |
|---|---|---|
| السجلات المالية، الفواتير | نظامي (7 سنوات فأكثر على الأرجح) | يتجاوز طلبات المحو |
| سجل التدقيق | دليل الامتثال | ⚠️ توتر مباشر مع مبدأ التقليل في PDPL — يجب توثيقه والدفاع عنه، لا ارتجاله |
| الشهادات الصادرة | قيمة التحقق لدى أطراف ثالثة | الإبطال بدل الحذف؟ → OQ-07 |
| محاولات التقييم | إثبات منشأ الشهادة | إخفاء الهوية بدل الحذف |
الاستشارات المسجّلة (إن انطبق OQ-08) |
نافذة النزاع فقط | الحذف الحازم هو الافتراض الصحيح |
| سجلات الجلسات، القياسات عن بُعد | تشغيلي | قصير، وآلي |
| أحداث التسويق/التحليلات | مرهون بالموافقة | — |
مشكلة التعداد#
الجزء الصعب في طلب صاحب البيانات ليس الحذف — بل العثور على كل شيء. فبمجرد انتشار البيانات الشخصية في فهرس بحث، وprojection للتقارير، وpipeline للسجلات، والنسخ الاحتياطية، يصبح سؤال "حدّد كل البيانات المتعلقة بهذا الشخص" بلا إجابة دون جرد للبيانات الشخصية يُصان كمُنتَج من الدرجة الأولى.
ابنِ الجرد بينما النظام صغير. فتركيبه لاحقًا يعني تدقيق كل مخزن بعد وقوع الأمر.
8.9 ملخّص المفاهيم#
| المفهوم | ما تقرّر | أين |
|---|---|---|
| التخزين ثنائي اللغة | الفصل حسب دورة الحياة، لا الطول | §8.1 |
| التطبيع العربي | pipeline مملوك للتطبيق | §8.1 |
| عقد الخطأ | code مقروء آليًا + correlation ID | §8.2 |
| محاولات الاستكشاف عبر المستأجرين | 404، لا 403 أبدًا | §8.2 |
| Idempotency | مفاتيح العميل + إزالة تكرار الـ webhooks | §8.3 |
| تزامن الحجز | قفل تشاؤمي | §8.3 |
| المال | وحدات فرعية صحيحة + عملة صريحة | §8.4 |
| الوقت | يُخزَّن UTC، ويُعرض بتوقيت الرياض، أسبوع الأحد إلى الخميس | §8.4 |
| المعرّفات الخارجية | ULID — لا تسلسل للشهادات أبدًا | §8.4 |
| قابلية المراقبة | correlation ID عبر كل قفزة غير متزامنة | §8.5 |
| تهيئة الأعمال | قاعدة البيانات، لا الكود (CON-07, CON-08) |
§8.6 |
| الاختبار | أربع طبقات خاصة بالنظام فوق الهرم | §8.7 |
| الاحتفاظ | الجرد أولًا؛ وتوثيق التعارض بين التدقيق والمحو | §8.8 |