موجّه استكشاف قاعدة الكود والتأهيل التقني

**السياق:**  
أنا مطوّر انضممت للتو إلى المشروع، وأستعين بك كمساعد برمجي مدعوم بالذكاء الاصطناعي حتى أفهم قاعدة الكود الحالية بعمق. هدفي أن أصل للإنتاجية بأسرع وقت ممكن، وأن أتخذ قرارات تقنية واعية مبنية على فهم راسخ للنظام الحالي.

**الهدف الأساسي:**  
حلّل الكود المصدري الموجود في هذا المشروع/مساحة العمل، وأنشئ **مستند Markdown مفصّل، واضح، ومنظّم بشكل ممتاز** يشرح معمارية النظام، وميزاته، والمسارات الرئيسية، والمكوّنات الأساسية، والتقنيات المستخدمة.  
يجب أن يكون هذا المستند **دليل تأهيل تقني للمطوّرين**.  
كلما أمكن، حسّن سهولة التنقّل عبر توفير **روابط مباشرة للملفات، والفئات (classes)، والدوال ذات العلاقة**، مع أمثلة كود تساعد في توضيح المفاهيم.

---

## **تعليمات تفصيلية — يرجى تغطية النقاط التالية:**

### 1. **ملخص ملفات README / ملفات التعليمات**
- ابحث عن ملفات مثل `README.md` و`LEIAME.md` و`CONTRIBUTING.md` أو أي ملفات توثيق مشابهة.
- قدّم ملخصًا موضوعيًا ومفصّلًا لأهم الأقسام التي تهم المطوّر الجديد، ويشمل:
  - نظرة عامة على المشروع
  - طريقة إعداد النظام وتشغيله محليًا
  - المعايير والاتفاقيات المعتمدة
  - إرشادات المساهمة، إن وجدت

---

### 2. **التقنيات المستخدمة بالتفصيل**
- حدّد واعرض كامل التقنيات المستخدمة في المشروع:
  - لغة أو لغات البرمجة، مع الإصدارات إذا أمكن اكتشافها، مثلًا من `package.json` أو `pom.xml` أو `.tool-versions` أو `requirements.txt` أو `build.gradle` وغيرها.
  - أطر العمل الرئيسية، سواء للواجهة الخلفية أو الأمامية أو غيرها، مثل Spring Boot أو .NET أو React أو Angular أو Vue أو Django أو Rails.
  - قواعد البيانات:
    - النوع، مثل SQL / NoSQL
    - الاسم، مثل PostgreSQL أو MongoDB أو غيرها
  - نمط المعمارية الأساسي، مثل Monolith أو Microservices أو Serverless أو MVC أو MVVM أو Clean Architecture.
  - منصة السحابة، إذا كانت واضحة من خلال حِزم SDK أو ملفات الإعداد، مثل AWS أو Azure أو GCP.
  - أدوات البناء ومديري الحزم، مثل Maven أو Gradle أو npm أو yarn أو pip.
  - أي تقنيات أخرى ذات علاقة، مثل التخزين المؤقت، ووسطاء الرسائل، والحاويات مثل Docker أو Kubernetes.
- **اذكر واربط ملفات الإعداد التي تثبت كل عنصر.**

---

### 3. **نظرة عامة على النظام والغرض منه**
- اشرح بوضوح ماذا يفعل النظام ولمن هو موجّه.
- ما المشكلات التي يعالجها؟
- اذكر الوظائف الأساسية.
- إذا أمكن، اربط النظام بمجالات الأعمال أو المجالات التشغيلية التي يخدمها.
- قدّم وصفًا عالي المستوى لأهم الميزات.

---

### 4. **هيكلة المشروع وتوصيات القراءة**
- **نقطة البداية:**  
  من أين يُفضّل أن أبدأ استكشاف الكود؟ حدّد نقاط الدخول الرئيسية، مثل `main.go` أو `index.js` أو `Program.cs` أو `app.py` أو `Application.java`.  
  **وفّر روابط مباشرة لهذه الملفات.**
- **التنظيم العام:**  
  اشرح هيكلة المجلدات والملفات بشكل عام. أبرز الاتفاقيات المهمة.  
  **استخدم أمثلة حقيقية لأسماء المجلدات والملفات.**
- **الإعدادات:**  
  هل توجد ملفات إعداد رئيسية؟ مثل `config.yaml` أو `.env` أو `appsettings.json`  
  ما الإعدادات الحرجة؟  
  **وفّر روابط لها.**
- **توصية القراءة:**  
  اقترح ترتيبًا أو مجموعة ملفات/وحدات أساسية يُفضّل قراءتها أولًا لفهم المفاهيم الجوهرية للمشروع بسرعة.

---

### 5. **المكوّنات الأساسية**
- حدّد واشرح أهم الوحدات أو الفئات أو الدوال أو الخدمات المركزية.
- وضّح مسؤوليات كل مكوّن.
- اشرح العلاقات والاعتماديات المتبادلة بينها.
- لكل مكوّن:
  - أضف مقتطف كود تمثيلي
  - أضف رابطًا لمكان تنفيذه
- **وفّر روابط مباشرة وأمثلة كود كلما أمكن.**

---

### 6. **مسارات التنفيذ وتدفّق البيانات**
- صف أكثر مسارات العمل أو عمليات الأعمال شيوعًا أو أهمية، مثل معالجة الطلبات أو مصادقة المستخدم.
- اشرح كيف تتحرك البيانات داخل النظام:
  - أين يتم حفظ البيانات
  - كيف تتم قراءتها وتعديلها وتمريرها إلى بقية المكوّنات
- **كلما أمكن، وضّح بأمثلة واربط الدوال أو الفئات ذات العلاقة.**

#### 6.1 **نظرة عامة على مخطط قاعدة البيانات، إن وجد**
- للتطبيقات المعتمدة بكثافة على البيانات:
  - حدّد أهم الكيانات/الجداول/المجموعات
  - اشرح العلاقات الأساسية بينها
  - ابنِ ذلك على نماذج ORM أو ملفات الترحيل أو ملفات المخطط إن توفرت

---

### 7. **الاعتماديات والتكاملات**
- **الاعتماديات:**  
  اعرض أهم المكتبات الخارجية، وأطر العمل، وحِزم SDK المستخدمة.  
  اشرح باختصار دور كل واحدة.  
  **وفّر روابط للأماكن التي يتم إعدادها فيها أو أكثر المواضع استخدامًا لها.**
- **التكاملات:**  
  حدّد واشرح التكاملات مع الخدمات الخارجية، وقواعد البيانات الإضافية، وواجهات API التابعة لأطراف ثالثة، ووسطاء الرسائل، وغيرها.  
  كيف يتم التواصل معها؟  
  **أشر إلى الوحدات/الفئات المسؤولة وأضف روابط لها.**

#### 7.1 **توثيق واجهات API، إن وجد**
- إذا كان المشروع يوفّر واجهات API:
  - هل توجد مؤشرات على أدوات أو معايير لتوثيق API، مثل Swagger/OpenAPI أو Javadoc أو docstrings خاصة بنقاط النهاية؟
  - أين يوجد هذا التوثيق أو كيف يمكن توليده؟

---

### 8. **المخططات**
- أنشئ مخططات عالية المستوى لتوضيح معمارية النظام وسلوكه:
  - مخطط المكوّنات، مع إبراز الوحدات الرئيسية وتفاعلها
  - مخطط تدفّق البيانات، يوضح كيف تنتقل المعلومات داخل النظام
  - مخطط الفئات، يوضح الفئات الأساسية والعلاقات بينها إن كان مناسبًا
  - مخطط نشر مبسّط، يوضح أين تعمل المكوّنات إن أمكن اكتشاف ذلك
  - مخطط بنية تحتية/نشر مبسّط، إذا كانت تفاصيل البنية التحتية واضحة
- **أنشئ هذه المخططات باستخدام صيغة Mermaid داخل ملف Markdown.**
- يجب أن تكون المخططات **عالية المستوى**؛ لا حاجة لتفصيل مفرط.

---

### 9. **الاختبارات**
- هل توجد اختبارات آلية؟
  - اختبارات وحدة
  - اختبارات تكامل
  - اختبارات شاملة End-to-End (E2E)
- أين توجد داخل المشروع؟
- ما أطر الاختبار المستخدمة؟
- كيف يتم تشغيل الاختبارات عادة؟
- كيف يمكن تشغيل الاختبارات محليًا؟
- هل توجد استراتيجية CI/CD تشمل الاختبارات؟

---

### 10. **معالجة الأخطاء والتسجيل (Logging)**
- كيف يتعامل التطبيق بشكل عام مع الأخطاء؟
  - هل يوجد نمط موحّد، مثل وسيط عام (middleware) أو استثناءات مخصصة؟
- ما مكتبة التسجيل المستخدمة؟
- هل يوجد تنسيق موحّد للسجلات؟
- هل يظهر أي تكامل مع أدوات مراقبة مثل Datadog أو Sentry؟

---

### 11. **اعتبارات الأمان**
- هل توجد آليات أمان واضحة في الكود؟
  - المصادقة
  - التفويض/الصلاحيات، مثل middleware أو filters
  - التحقق من المدخلات
- هل توجد مكتبات أمان بارزة مستخدمة، مثل Spring Security أو Passport.js أو مكتبات JWT؟
- هل توجد ممارسات أمان ملحوظة؟
  - إدارة الأسرار
  - الحماية من الهجمات الشائعة

---

### 12. **ملاحظات أخرى مهمة، بما في ذلك البناء والنشر**
- هل توجد ملفات متعلقة بـ **البناء أو النشر**؟
  - `Dockerfile`
  - `docker-compose.yml`
  - سكربتات البناء/النشر
  - ملفات إعداد CI/CD مثل `.github/workflows/` أو `.gitlab-ci.yml`
- ماذا توضّح هذه الملفات عن طريقة بناء التطبيق ونشره؟
- هل يوجد أي شيء آخر مهم أو مفيد جدًا للمطوّر الجديد؟
  - ديون تقنية مذكورة في التعليقات
  - أنماط تصميم غير معتادة
  - اتفاقيات برمجية مهمة
  - ملاحظات أداء

---

## **صيغة المخرجات النهائية**
- أنشئ الرد الكامل على شكل **مستند Markdown منسّق جيدًا (`.md`)**.
- استخدم **لغة واضحة ومباشرة**.
- نظّم المحتوى باستخدام **عناوين وعناوين فرعية** حسب الأقسام المرقمة أعلاه.
- **أضف مقتطفات كود ذات علاقة**، على أن تكون قصيرة وتمثيلية.
- **أضف روابط قابلة للنقر** للملفات، والدوال، والفئات، والتعريفات كلما تم ذكر عنصر محدد من الكود.
- رتّب المستند باستخدام الأقسام المرقمة أعلاه لتسهيل القراءة.

**كلما أمكن:**
- أضف **روابط قابلة للنقر** للملفات، والدوال، والفئات.
- اعرض **مقتطفات كود قصيرة وتمثيلية**.
- استخدم **نقاط أو جداول** للقوائم.

---

### **مهم جدًا**
يجب أن يأخذ التحليل في الاعتبار **كل ملفات المشروع**.  
اقرأ وافهم **كل الملفات اللازمة** لتنفيذ هذه المهمة بالكامل والوصول إلى فهم شامل للنظام.

---

### **الإجراء المطلوب**
حلّل الكود المصدري المتاح حاليًا في بيئتي/مساحة العمل، وأنشئ مستند Markdown حسب المطلوب.

يجب أن يتبع اسم ملف المخرجات هذه الصيغة:  
`<yyyy-mm-dd-project-name-app-dev-discovery_cursor.md>`