قواعد المعمارية

تحدد هذه القواعد ما الذي يعد سطحًا عامًا مستقرًا، وما الذي يعد داخليًا، ومتى ينبغي توسيع مساحة العمل بحزمة أو مجلد جديد.

السطح العام

prelude هو قصة الاستيراد المستقرة الموصى بها
الوحدات المسماة مثل layout وrender وinteraction وwidget عامة لكنها موجهة للتكاملات المتقدمة
الأنواع العامة التي يكتبها المستخدم يجب أن تبقى موثقة عند موضع تعريفها
طبقات التوافق تبقى على مسارات صريحة ولا تدخل في الـ preludes الموصى بها

internal وinternal_prelude أدوات تنفيذ داخلية لمساحة العمل وليستا عقدًا عامًا مع التطبيقات
الوحدات المخفية مثل layout::core وlayout::algorithms وlayout::components وlayout::pipeline يمكن أن تتغير لدعم إعادة هيكلة المحرك
علامات runtime والكاشات وتتبع الأبناء المولدين يجب أن تبقى خاصة بالحزمة أو pub(super) ما لم تحتجها حزمة أخرى فعلًا
سياسة الحدود الفورية داخل مساحة العمل موثقة في الملف الجذري ENGINE_BOUNDARY_RULES.md
يمنع ./scripts/check_engine_boundary_guardrails.sh ظهور imports جديدة من engine internals خارج المحرك أثناء تنظيف الاستثناءات الحالية

أضف حزمة جديدة فقط إذا تحقق واحد على الأقل مما يلي:

لا تضف حزمة فقط لتقسيم الملفات. ابدأ بالمجلدات والوحدات أولًا.

أضف مجلدًا عندما تصبح مسؤولية واحدة مكوّنة من عدة ملفات متعاونة بأدوار واضحة
أضف وحدة عندما تجعل الملكية أو الاكتشاف أوضح من ملف طويل واحد
فضّل أسماء المسؤوليات مثل roots أو state أو runtime أو events أو placement
تجنب الأسماء العامة عندما يتوفر اسم domain أدق

الوحدات الجاهزة تعتمد على المحرك والتفاعل والستايل، لكن المحرك لا يعتمد على الوحدات الجاهزة
التفاعل يعتمد على حالة المحرك للجذور والهندسة، لكن المحرك لا يعتمد على التفاعل
حزم الواجهة الجامعة تعيد تصدير سطوح عامة منتقاة، ويجب ألا تسرّب المساعدات الداخلية بالخطأ