<div dir="rtl">

# دليل تعلم NestJS: المفاهيم الأساسية والعملية
# NestJS Learning Guide: Core Concepts and Implementation

مرحباً بك في هذا الدليل التعليمي المخصص لمشروع **Ads Analytics Platform**. سنقوم هنا بشرح بنية البرنامج وكيفية تداخل مكوناته بأسلوب مبسط وموجه للمطورين.

---

## 🏗️ 1. البنية العامة (General Architecture)

تعتمد NestJS على بنية **النماذج (Modules)**. كل ميزة في التطبيق (مثل الإعلانات أو التحليلات) يتم فصلها في "موديول" مستقل.

- **AppModule**: هو الجذر (Root) الذي يربط كل الموديولات ببعضها.
- **Controller**: هو المسؤول عن استقبال الطلبات (HTTP Requests) وإرجاع الردود.
- **Service (Provider)**: هنا يكمن "المنطق" (Logic)، مثل حساب الأرباح أو جلب البيانات من Meta API.

---

## 💉 2. حقن التبعيات (Dependency Injection)

يعتبر "حقن التبعيات" من أهم ميزات NestJS. بدلاً من أن يقوم الكائن بإنشاء تبعياته بنفسه (مثل استخدام `new AnalyticsService()`)، يقوم المحرك (Nest IoC Container) بتمريرها له.

**لماذا نستخدمه؟**
1. **سهولة الاختبار (Testing)**: يمكننا بسهولة استبدال الخدمة الحقيقية بواحدة وهمية (Mock) أثناء الاختبار.
2. **برمجة نظيفة**: فصل المهام وجعل الكود أقل تشابكاً.

**مثال من المشروع:**
في `MetaAdsController` نقوم بحقن الـ `MetaAdsService` عبر الـ `constructor`:
```typescript
constructor(private readonly metaAdsService: MetaAdsService) {}
```

---

## 📦 3. الكبسلة (Encapsulation)

في NestJS، كل موديول هو "صندوق مغلق" افتراضياً. إذا أردت استخدام خدمة من موديول في موديول آخر، يجب عليك:
1. **تصديرها (Export)** من الموديول الأصلي.
2. **استيرادها (Import)** في الموديول الجديد.

هذا يضمن أن المكونات لا تتداخل بشكل عشوائي، مما يسهل صيانة النظام الكبير.

---

## 🧬 4. الوراثة (Inheritance)

نستخدم الوراثة لتقليل تكرار الكود. على سبيل المثال، قد يكون لدينا "خطأ مخصص" يرث من `HttpException` الأساسي في NestJS.

**مثال:**
مراقب الاستثناءات (Exception Filter) قد يرث ميزات معينة أو نستخدم الوراثة في DTOs (Data Transfer Objects) لمشاركة الحقول بين طلبات الإضافة والتعديل.

---

## 🔍 5. كيف يعمل المشروع الحالي؟

عندما تطلب المسار `/api/meta/insights`:
1. الطلب يمر عبر **Middlewares** (إن وجدت).
2. يصل إلى **MetaAdsController**.
3. الـ Controller ينادي الوظيفة المطلوبة في **MetaAdsService**.
4. الـ Service تقوم بالتواصل مع Meta API وتجري الحسابات.
5. النتيجة تعود كـ JSON للمستخدم.

---

> [!TIP]
> **نصيحة**: دائماً ابدأ بتصميم موديول مستقل لكل ميزة جديدة لضمان قابلية التوسع (Scalability).

</div>