ARCHITECTURE.md

هذا الملف هو الخريطة العلوية للنظام. يجب أن يظل موجزًا ويُشير إلى وثائق أعمق عند الحاجة.

شكل النظام

• المنتج: [استبدل باسم المنتج]
• سير عمل المستخدم الرئيسي: [استبدل بسير العمل الرئيسي]
• أسطح التشغيل: [desktop / web / cli / services / workers]
• مصدر الحقيقة لسلوك المنتج: docs/product-specs/

خريطة المجالات

المجال	الغرض	نقاط الدخول الرئيسية	المواصفة ذات الصلة
[domain-a]	[ما يملكه]	[modules / routes / commands]	[مسار المواصفة]
[domain-b]	[ما يملكه]	[modules / routes / commands]	[مسار المواصفة]

نموذج الطبقات

استخدم نموذجًا اتجاهيًا ثابتًا حتى لا يخترع الوكلاء بنية عشوائية:

Types -> Config -> Repo -> Service -> Runtime -> UI

المخاوف المشتركة يجب أن تدخل من خلال حدود موفّر أو محوّل صريحة بدلاً من الوصول المباشر عبر الطبقات.

قواعد التبعيات الثابتة

• الطبقات السفلية يجب ألا تعتمد على الطبقات العليا.
• واجهة المستخدم يجب ألا تتجاوز عقود التشغيل أو الخدمات.
• الوصول إلى البيانات يجب أن يتم من خلال مستودعات أو محوّلات معادلة.
• الأدوات المساعدة المشتركة يجب أن تظل عامة وألا تتراكم فيها منطق المجال.
• التبعيات الجديدة يجب تبريرها في الخطة أو وثيقة التصميم المطابقة.

الواجهات المشتركة

المخاوف	الحد المعتمد	ملاحظات
التسجيل والتتبع	[مسار الموفر / الأداة المساعدة]	[منظم فقط، بدون استخدام console عشوائي]
المصادقة	[مسار الموفر]	[قواعد token/session]
واجهات برمجة التطبيقات الخارجية	[مسار العميل أو الموفر]	[إرشادات حد السرعة / إعادة المحاولة]
علامات الميزات	[حد العلم]	[الملكية]

النقاط الساخنة الحالية

• [المنطقة الأصعب على الوكلاء تغييرها بأمان]
• [منطقة بحدود ضعيفة أو اختبارات هشة]

قائمة فحص التغيير

عندما تلمس كودًا يتعلق بالبنية:

1. حدِّث هذا الملف إذا تغيرت خريطة المجالات أو الحدود المسموح بها.
2. حدِّث وثيقة التصميم ذات الصلة في docs/design-docs/ إذا تغير المنطق.
3. أضف أو حدِّث فحصًا قابلًا للتنفيذ إذا كانت القاعدة يجب تُفرض آليًا.