Initial commit from saas-meta

NESTJS_TUTORIAL_AR.md

@@ -0,0 +1,69 @@
+<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>