هندسة Angular العملية للحياة الواقعية

تقوم معظم دورات الهندسة المعمارية الزاوية بتدريس النظرية. ليس هذا.

تتعلم هنا اكتشاف المشكلات الحقيقية واتخاذ القرارات وبناء أنظمة تصمد عندما ينمو الفريق ويتغير المنتج ويمر الوقت.

عشرين وحدة. الممارسة الموجهة. لا الحشو.

---

INDEX — هندسة زاوية عملية للحياة الواقعية

---

الوحدة 0 — قاعدة النظام

النقطة 0 ليست وحدة محتوى. إنها طريقة الرؤية التي ستستخدمها خلال خريطة الطريق.

قبل الحديث عن مشاكل محددة في Angular، عليك الإجابة على سؤال:

كيف تنظر إلى تطبيق لا تعرفه وتقرر إذا كان جيدًا أم سيئًا؟

هناك أربع مهارات أساسية لذلك.

---

1. تحليل التطبيق دون لمس الرمز

القراءة الأولى للتطبيق ليست في المحرر. انها في الهيكل. قبل فتح ملف واحد، يمكنك استخراج المعلومات:

• ما هي المجلدات تسمى؟ هل الأسماء تقول ماذا يفعلون؟
• هل هناك مجلد shared يزن أكثر من أي شيء آخر؟
• كم عدد مستويات التعشيش الموجودة في الهيكل؟
• هل تحتوي الوحدات أو الميزات على أسماء نطاقات أو أسماء تقنية؟
• أين الخدمات؟ فضفاضة أو ضمن الميزات؟

يخبرك هذا بالفعل كثيرًا عما إذا كان الشخص الذي صنع التطبيق يفكر من الناحية التجارية أو من حيث الطبقات التقنية.

---

2. مراجعة الهندسة المعمارية بطريقة عملية

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

• أين يعيش منطق الأعمال؟
• من يعرف ماذا في كل طبقة؟
• كم عدد المواقع التي يجب عليك تغييرها لإضافة ميزة جديدة؟
• هل هناك تبعيات تسير في الاتجاه الخاطئ؟

لا يبدأ المهندس المعماري الكبير بالمكون الأكثر تعقيدًا. ابدأ بالنقاط الأعلى خطورة: الخدمات المشتركة، والحالة العالمية، وطبقة الوصول إلى البيانات.

---

3. كشف المشاكل قبل البرمجة

تحدث معظم الأضرار المعمارية في القرارات المبكرة التي تبدو غير ذات صلة:

• "سأضع هذا في خدمة مشتركة في الوقت الحالي"
• "المكون الأصلي يتعامل مع هذه الحالة، ثم نقوم بنقلها"
• "نحن نستخدم NgRx في كل شيء، لذا فهو متسق"

هذه القرارات لها عواقب حقيقية بعد أشهر. المعيار المعماري هو معرفة ما يشتريه كل قرار وما هو الدين الذي يتكبده.

---

4. تحويل النظرية إلى قائمة مرجعية حقيقية

كل مفهوم سنراه في خريطة الطريق هذه - المكونات الذكية/الغبية، ووضع الحالة، والخدمات الإلهية، وما إلى ذلك - يجب أن ينتهي بسؤال يمكنك طرحه على نفسك أثناء مراجعة الكود الحقيقي:

• هل يعرف هذا المكون من أين تأتي البيانات؟
• هل هذه الخدمة لها أكثر من سبب للتغيير؟
• هل هذه الحالة موجودة في مكانين مختلفين؟

إذا لم تتمكن من تحويل المفهوم إلى سؤال مراجعة، فأنت لم تستوعبه بعد.

---

الوحدة الأولى — كيفية تحليل تطبيق Angular دون لمس الرمز

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

** لماذا يهم؟ **

• إذا استغرقت وقتًا طويلاً لاكتشاف المشكلات المعمارية، فإن تكلفة تصحيحها تنمو بشكل كبير.
• الهيكل السيئ التصميم منذ اليوم الأول يصبح دينًا فنيًا يعيق الفريق بعد أشهر.
• يتيح لك تطوير الحكم البصري السريع اتخاذ قرارات أفضل قبل كتابة سطر واحد من التعليمات البرمجية.

الخطوة 1 - اقرأ بنية المجلد كخريطة

بنية المجلد هي أول قرار معماري مرئي. يخبرك كيف نظم الفريق عالمهم العقلي: هل يفكرون فيما يتعلق بالتكنولوجيا أم فيما يتعلق بالأعمال؟

ما هي الميزة؟

الميزة هي وظيفة عمل كاملة. ليس نوع الملف. ليست طبقة فنية.

فكر في تطبيق للتجارة الإلكترونية. الميزات هي:

• كتالوج المنتجات
• عربة التسوق
• عملية الخروج
• الملف الشخصي للمستخدم
• إدارة الطلبات

كل واحد من هؤلاء هو عمل منطقي في حد ذاته. يقوم المستخدم بالدخول إلى الكتالوج، وتصفحه، والإضافة إلى سلة التسوق، والخروج. تلك هي الميزات.

النموذج 1 — التنظيم حسب الطبقات الفنية (يمثل إشكالية على نطاق واسع)

هذا ما يفعله الجميع تقريبًا عندما يبدأون لأنه يبدو أنيقًا:

src/app/
  components/
    product-card.component.ts
    product-list.component.ts
    cart-item.component.ts
    checkout-form.component.ts
    user-profile.component.ts
  services/
    product.service.ts
    cart.service.ts
    checkout.service.ts
    user.service.ts
  models/
    product.model.ts
    cart.model.ts
    user.model.ts

المشكلة الحقيقية: عليك تعديل تدفق الخروج. لفهم ما ينطوي عليه الأمر، يمكنك التنقل بين ثلاثة مجلدات مختلفة - تبحث عن المكون في components/، والخدمة في services/، والنموذج في models/. إذا كان هناك أنبوب دفع محدد، فسيتم دمجه في pipes/ مع أنابيب من ميزات أخرى.

لتغيير ميزة واحدة، يمكنك التنقل عبر التطبيق بأكمله. هذا اقتران بالهيكل. عندما يكبر الفريق، يقوم شخصان يعملان على ميزات مختلفة بلمس نفس المجلدات باستمرار → يتعارضان في git، ويصعب معرفة من يملك ماذا.

النموذج 2 — التنظيم حسب الميزات (ما المقاييس)

src/app/
  features/
    catalog/
      components/
        product-card.component.ts
        product-list.component.ts
      services/
        product.service.ts
      models/
        product.model.ts
      catalog.routes.ts
    cart/
      components/
        cart-item.component.ts
        cart-summary.component.ts
      services/
        cart.service.ts
      cart.routes.ts
    checkout/
      components/
        checkout-form.component.ts
        order-confirmation.component.ts
      services/
        checkout.service.ts
      checkout.routes.ts
  shared/
  core/

لماذا يعمل هذا: عندما تضغط على الخروج، يكون كل شيء في الخروج معًا. المطور الجديد يعرف بالضبط أين يبحث. يمكن لشخص واحد أن يمتلك الميزة بأكملها. يمكنك حذف ميزة بأكملها عن طريق حذف المجلد الخاص بها فقط. تختفي تعارضات Git بين الميزات المختلفة تمامًا تقريبًا.

القاعدة الأساسية: إذا قمت بحذف ميزة، فهل يمكنك حذف مجلدها بالكامل دون لمس أي شيء آخر؟ إذا كانت الإجابة بنعم، فهذه الميزة معزولة جيدًا. إذا كان عليك البحث عن القطع في جميع أنحاء التطبيق، فهذا ليس كذلك.

الخطوة الثانية — اقرأ الأسماء

الأسماء هي وثائق. يخفي الاسم السيئ النية ويضيف حملاً معرفيًا لكل شخص يقرأ الكود.

shared/ — ما ينبغي أن يحتوي عليه وما لا ينبغي أن

shared/ مخصص للأشياء التي تستخدمها ميزات متعددة والتي ليس لها منطق أعمال خاص بها.

صحيح في shared/:

shared/
  components/
    button/
    modal/
    spinner/
    avatar/
  pipes/
    date-format.pipe.ts
    truncate.pipe.ts
  directives/
    click-outside.directive.ts
  validators/
    email-validator.ts

إنها قطع واجهة مستخدم قابلة لإعادة الاستخدام أو أدوات مساعدة خالصة. إنهم لا يعرفون شيئًا عن العمل. لا يعرف ButtonComponent ما إذا كان هذا زر الخروج أم زر ملف تعريف المستخدم. إنه يعرف فقط كيف يكون زرًا.

غير صحيح في shared/:

shared/
  services/
    cart.service.ts           ← lógica de negocio aquí
    user-auth.service.ts      ← pertenece a auth/core
    product-filter.service.ts ← pertenece a catalog
    report-generator.service.ts ← pertenece a reporting

عندما ترى خدمات تحتوي على منطق أعمال داخل shared/، فهذا يعني أن شخصًا ما لا يعرف مكان وضعها ووضعها هناك. بمرور الوقت، يصبح shared/ هو التطبيق الشامل.

core/ — ما هو وما ليس كذلك

core/ مخصص للبنية الأساسية المفردة التي تحتاج إلى التطبيق بأكمله مرة واحدة.

صحيح في core/:

core/
  services/
    auth.service.ts
    logger.service.ts
    error-handler.service.ts
  interceptors/
    auth.interceptor.ts
    error.interceptor.ts
  guards/
    auth.guard.ts
  models/
    user-session.model.ts

غير صحيح في core/:

core/
  components/
    dashboard.component.ts  ← eso es una feature
    home.component.ts       ← igual
  services/
    product.service.ts      ← pertenece a catalog
    report-generator.service.ts ← pertenece a reporting

هذه هي الأشياء التي يتم إنشاء مثيل لها مرة واحدة وتؤثر على التطبيق بأكمله. يعترض معترض المصادقة جميع طلبات HTTP للتطبيق بأكمله، ولهذا السبب يوجد في core/.

أسماء غامضة - أعلام حمراء

الاسم الغامض هو قرار مؤجل. عندما يقوم شخص ما بإنشاء data.service.ts، فهو لم يقرر بعد ما هي البيانات التي تتحدث عنها هذه الخدمة.

ما تراه	ماذا يمكن أن يعني
shared/ كبيرة جدًا	كل ما لا يصلح في أي مكان آخر. تصبح حقيبة مختلطة.
common/	نفس shared/، ولكن اسمها أسوأ. دون معايير لما يدخل.
utils/ مع الخدمات	منطق الأعمال المقنعة في صورة فائدة. علم أحمر خطير.
helpers/	نفس utils/. الاسم لا يقول شيئا عن المسؤولية.
components/ في الجذر	لا توجد منظمة حسب المجال. جميع المكونات معا.
core/ مع 40 ملفًا	جوهر محدد بشكل سيء. تم استخدام shared/ كالثاني.
app.service.ts	خدمة إلهية تنتظر النمو. أقصى إشارة إنذار.
data.service.ts	بيانات عن ماذا؟ مسؤولية غير محددة من الاسم.
helper.service.ts	وينتهي الأمر بأن تكون خدمة بطرق غير ذات صلة.
main.component.ts	ما هو "الرئيسي"؟ اسم عام يخفي المسؤولية الحقيقية.

قاعدة الاسم: إذا لم يخبرك اسم الملف بما يفعله بالضبط، فمن المحتمل أن الملف يفعل الكثير أو أن موقعه ضعيف.

أمثلة ملموسة للأسماء الغامضة وما تخفيه:

• utils/format.ts يحتوي على 800 سطر: مزيج من تنسيق التاريخ + التحقق من صحة النموذج + تحويل واجهة برمجة التطبيقات.
• helper.service.ts: ينتهي به الأمر إلى أن يكون خدمة إلهية بطرق غير ذات صلة.
• app.service.ts: خدمة تسمى التطبيق بأكمله ولها مسؤوليات عن التطبيق بأكمله.

الخطوة 3 - العد والقياس دون فتح الملفات

قبل قراءة التعليمات البرمجية، يمكنك إجراء هذه الملاحظات مباشرة من البنية:

حجم المكون كعلامة

لافتة	ماذا تشير؟
+300-400 خط في مكون واحد	أنت تفعل الكثير دائمًا تقريبًا. إنها ليست قاعدة مطلقة ولكنها تستحق التحقيق.
+10 المدخلات والمخرجات	واجهة برمجة تطبيقات معقدة للغاية. سيتم تقسيم المرشح إلى عدة مكونات.
مكالمات HTTP المباشرة في المكون	امزج العرض التقديمي مع الوصول إلى البيانات. طبقة الخدمة مفقودة.
1-2 مكونات لكل ميزة	ربما يفعلون الكثير. عدم وجود انقسام داخلي.
+20 مزودًا عالميًا	الكثير من منطق الدولة والمركزية. ليس كل شيء يجب أن يكون عالميًا.

الخدمات العالمية — خطر providedIn: 'root'

تعني الخدمة العالمية أن أي مكون في أي ميزة يمكنه إدخالها واستخدامها. يؤدي ذلك إلى إنشاء تبعيات غير مرئية بين الميزات التي يجب أن تكون مستقلة.

// Servicio que DEBERÍA ser local a la feature de catalog:
@Injectable({ providedIn: 'root' })  // ← señal de problema
export class ProductFilterService { ... }

// Ahora cualquier componente de cualquier feature puede usarlo.
// Si catalog cambia su lógica de filtrado, puede romper
// algo en una feature aparentemente no relacionada.

الخطوة الرابعة — app.module.ts أو app.config.ts: ما الذي تبحث عنه

في التطبيقات التي تحتوي على وحدات (Angular < 17 أو قديمة)

@NgModule({
  imports: [
    BrowserModule,
    HttpClientModule,
    RouterModule,
    AuthModule,       // ← bien, infraestructura singleton

    ProductModule,    // ← señal de problema
    CartModule,       // ← señal de problema
    CheckoutModule,   // ← señal de problema
    UserModule,       // ← señal de problema
    DashboardModule,  // ← señal de problema
    // Si hay 15+ módulos de features aquí,
    // el lazy loading no está funcionando.
  ],
  providers: [
    ProductService,   // ← si hay 20+ providers aquí,
    CartService,      // hay demasiada centralización
    UserService,
    AuthService,
  ]
})

يجب تحميل وحدات الميزات بشكل بطيء (عند الطلب)، وليس استيرادها مباشرة إلى الوحدة الجذرية. إذا كانت جميعها هنا، فسيتم تحميلها جميعًا عند بدء التشغيل حتى لو لم يحتاجها المستخدم أبدًا.

** في التطبيقات المستقلة (Angular 17+)**

// app.config.ts
export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes, withLazyLoading()),   // ← correcto
    provideHttpClient(withInterceptors([authInterceptor])),
    provideAnimations(),

    ProductService,   // ← esto NO debería estar aquí
    CartService,      // ← pertenece a la feature de cart
  ]
}

قاعدة التكوين العامة: يجب أن يحتوي التكوين العام فقط على بنية أساسية تؤثر على التطبيق بأكمله: جهاز توجيه ذو تحميل بطيء، HttpClient مزود بمعترضات عمومية، ورسوم متحركة، وخدمات البنية التحتية الفردية (المصادقة، والمسجل، ومعالج الأخطاء). إذا رأيت خدمات الميزات في التكوين العام، فهذا يعني أن شخصًا ما يقوم بتسجيل الأشياء عالميًا من أجل الراحة، وليس الضرورة.

قائمة المراجعة الكاملة — القراءة الأولى لتطبيق Angular

بناء

• هل يتم تنظيم الهيكل حسب الميزات (مجال الأعمال) أم حسب الطبقات التقنية؟
• هل يمكنني حذف ميزة بأكملها عن طريق حذف مجلدها فقط دون لمس أي شيء آخر؟
• هل تحتوي الميزات على أسماء نطاقات تجارية (checkout، catalog) أو أسماء فنية (list، form، detail)؟
• هل هناك مجلدات بأسماء غامضة: utils، helpers، common، misc، data؟

shared/ وcore/

• هل يحتوي shared/ على مكونات وأدوات مساعدة لواجهة المستخدم فقط دون منطق الأعمال؟
• هل يحتوي core/ على بنية تحتية مفردة فقط (أجهزة الاعتراض والحراس وخدمة المصادقة)؟
• هل توجد خدمات ذات منطق أعمال ضمن shared/؟
• هل يحتوي core/ على مكونات مميزة أو خدمات مجال؟

الخدمات ومقدمي الخدمات

• هل خدمات الأعمال ضمن مميزاتك أم أنها فضفاضة عالميًا؟
• هل هناك أكثر من 20 مزودًا عالميًا؟
• هل تقوم الوحدة الجذرية أو app.config.ts باستيراد وحدات الميزات مباشرة (بدون كسل)؟
• هل هناك خدمات ذات providedIn: 'root' يجب أن تكون محلية لميزة ما؟

الأسماء

• هل توضح أسماء الملفات بالضبط ما تفعله؟
• هل هناك ملفات يمكن أن ينطبق اسمها على أي جزء من التطبيق؟
• هل يوجد ملف باسم app.service.ts أو data.service.ts أو helper.service.ts؟
• هل يزن shared/ أكثر من أي ميزة فردية؟

يمارس

ابحث عن أي مشروع Angular عام على GitHub — يمكن أن يكون مشروعًا خاصًا بك أو مشروعًا مفتوح المصدر. دون فتح أي ملفات، فقط انظر إلى بنية المجلد وأسمائه:

1. ما هو النموذج التنظيمي الذي تستخدمه: الميزات أم الطبقات التقنية؟
2. ما هي الأسماء التي تثير الشكوك أو الشكوك لديك؟
3. أين تشك في منطق العمل؟
4. ما هو المجلد الذي تعتقد أنه يحتوي على أكبر مزيج من المسؤوليات؟
5. هل يمكنك حذف ميزة دون لمس أي شيء آخر؟

شارك ما لاحظته في الجلسة وسنقوم بمراجعته معًا كما يفعل أحد كبار المهندسين المعماريين.

---

عاجل: قم بتحليل مشروعك بالنقاط الأربع

انسخ هذه المطالبة واستخدمها مع أي الذكاء الاصطناعي (ChatGPT، Claude، Copilot) لتمريرها إلى شجرة المجلدات الخاصة بمشروعك:

---

قم بتحليل بنية المشروع بتطبيق هذه النقاط الأربع في الركيزة الأولى وقم بإنشاء تقرير.

النقطة 1 — بنية المجلد

حلل apps/ وlibs/ وأجب:

• هل التنظيم حسب الميزات (المجال التجاري) أم حسب الطبقات التقنية؟
• هل يمكنك حذف ميزة بأكملها عن طريق حذف المجلد الخاص بها فقط؟
• هل تحتوي الميزات على أسماء نطاق (checkout، catalog) أو أسماء فنية (list، form، detail)؟
• هل هناك مجلدات بأسماء غامضة: utils، helpers، common، misc، data؟
• يعرض الشجرة الفعلية للمجلدات التي عثرت عليها.

النقطة 2 - أسماء الملفات والمجلدات

ابحث في المشروع بأكمله والقائمة:

• الملفات ذات الأسماء الغامضة: data.service.ts، helper.service.ts، app.service.ts، main.component.ts، utils مع الخدمات بداخلها.
• الخدمات ذات منطق الأعمال ضمن shared/.
• المكونات أو خدمات المجال ضمن core/.
• هل يزن shared/ أكثر من أي ميزة فردية؟ عدد الملفات.

النقطة 3 — الخدمات العالمية

البحث في المشروع بأكمله:

• جميع الخدمات التي تحتوي على providedIn: 'root' — تسرد ما هي عليه وما إذا كان يجب أن تكون محلية لميزة ما.
• حساب عدد مقدمي الخدمات العالميين الموجودين إجمالاً.
• يحدد خدمات الأعمال المسجلة عالميًا عندما يجب أن تكون ضمن الميزة الخاصة بك.
• ابحث عن الخدمات في libs/services/ التي تنتمي بشكل واضح إلى مجال معين.

النقطة 4 — التكوين العام (app.config.ts أو app.module.ts)

ابحث عن ملف التكوين الجذري لكل تطبيق وقم بتحليله:

• ما هو المسجل عالميا والذي لا ينبغي أن يكون؟
• هل تم تحميل وحدات الميزات بالتحميل البطيء أم يتم استيرادها مباشرة؟
• هل هناك خدمات الأعمال في التكوين العالمي؟
• كم عدد مقدمي الخدمات المسجلين عالميًا بشكل إجمالي؟

تنسيق التقرير

لكل نقطة استخدم هذا الهيكل الدقيق:

✅ ما هو جيد

(قائمة ملموسة مع أمثلة التعليمات البرمجية الحقيقية)

⚠️ علامات يجب فحصها

(قائمة محددة بمسار الملف وسبب اعتباره علامة)

❌مسح المشاكل

(قائمة محددة بمسار الملف والمشكلة والتأثير الفعلي)

وفي النهاية يشمل:

ملخص تنفيذي

جدول يحتوي على 4 نقاط ورمز تعبيري للحالة (✅ ⚠️ ❌) وخط ختامي لكل نقطة.

الخطوات التالية ذات الأولوية

قائمة بحد أقصى 5 إجراءات محددة مرتبة حسب التأثير، مع المسار الدقيق للملف أو المجلد المراد لمسه.

كن مباشرا. لا تشرح ما هي الميزة أو النظرية. ما عليك سوى تحليل هذا المشروع المحدد وتقديم نتائج حقيقية.