# AGENTS.md

## نظرة عامة على المشروع

هذا مستودع منهج تعليمي لتعليم أساسيات تطوير الويب للمبتدئين. المنهج هو دورة شاملة مدتها 12 أسبوعًا تم تطويرها بواسطة Microsoft Cloud Advocates، ويضم 24 درسًا عمليًا يغطي JavaScript و CSS و HTML.

### المكونات الرئيسية

- **المحتوى التعليمي**: 24 درسًا منظّمة ضمن وحدات قائمة على المشاريع
- **المشاريع العملية**: Terrarium، لعبة الطباعة، إضافة المتصفح، لعبة الفضاء، تطبيق البنك، محرر الأكواد، ومساعد دردشة AI
- **اختبارات تفاعلية**: 48 اختبارًا كل منها يحتوي على 3 أسئلة (تقييمات قبل وبعد الدرس)
- **دعم متعدد اللغات**: ترجمات آلية لأكثر من 50 لغة عبر GitHub Actions
- **التقنيات**: HTML، CSS، JavaScript، Vue.js 3، Vite، Node.js، Express، Python (لمشاريع الذكاء الاصطناعي)

### الهيكلية

- مستودع تعليمي به هيكلية قائمة على الدروس
- يحتوي كل مجلد درس على README، وأمثلة على الشفرة، والحلول
- مشاريع قائمة بذاتها في مجلدات منفصلة (quiz-app، مشاريع دروس مختلفة)
- نظام ترجمة يستخدم GitHub Actions (co-op-translator)
- الوثائق مقدمة عبر Docsify ومتاحة كملفات PDF

## أوامر الإعداد

هذا المستودع مخصص بشكل أساسي لاستهلاك المحتوى التعليمي. للعمل على مشاريع محددة:

### إعداد المستودع الرئيسي

```bash
git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
cd Web-Dev-For-Beginners
```

### إعداد تطبيق الاختبارات (Vue 3 + Vite)

```bash
cd quiz-app
npm install
npm run dev        # ابدأ خادم التطوير
npm run build      # إنشاء للإنتاج
npm run lint       # تشغيل ESLint
```

### API مشروع البنك (Node.js + Express)

```bash
cd 7-bank-project/api
npm install
npm start          # بدء خادم API
npm run lint       # تشغيل ESLint
npm run format     # التنسيق باستخدام Prettier
```

### مشاريع إضافة المتصفح

```bash
cd 5-browser-extension/solution
npm install
# اتبع تعليمات تحميل الإضافات الخاصة بالمتصفح
```

### مشاريع لعبة الفضاء

```bash
cd 6-space-game/solution
npm install
# افتح index.html في المتصفح أو استخدم Live Server
```

### مشروع الدردشة (خلفية Python)

```bash
cd 9-chat-project/solution/backend/python
pip install openai
# تعيين متغير البيئة GITHUB_TOKEN
python api.py
```

## سير العمل التطويري

### للمساهمين في المحتوى

1. **افتح فورك للمستودع** على حساب GitHub الخاص بك
2. **انسخ الفورك محليًا**
3. **أنشئ فرعًا جديدًا** لتغييراتك
4. قم بإجراء تغييرات على محتوى الدرس أو أمثلة الشفرة
5. اختبر أي تغييرات في الشفرة في مجلدات المشروع المعنية
6. قدم طلبات سحب باتباع إرشادات المساهمة

### للمتعلمين

1. افتح فورك أو انسخ المستودع
2. انتقل إلى مجلدات الدروس بترتيب متسلسل
3. اقرأ ملفات README لكل درس
4. أكمل اختبارات ما قبل الدرس على https://ff-quizzes.netlify.app/web/
5. اعمل على أمثلة الشفرة في مجلدات الدرس
6. أكمل المهام والتحديات
7. قم بأداء اختبارات ما بعد الدرس

### التطوير الحي

- **الوثائق**: شغّل `docsify serve` في جذر المستودع (المنفذ 3000)
- **تطبيق الاختبارات**: شغّل `npm run dev` في دليل quiz-app
- **المشاريع**: استخدم ملحق VS Code Live Server لمشاريع HTML
- **مشاريع API**: شغّل `npm start` في مجلدات API المعنية

## تعليمات الاختبار

### اختبار تطبيق الاختبارات

```bash
cd quiz-app
npm run lint       # التحقق من وجود مشكلات في نمط الكود
npm run build      # التأكد من نجاح البناء
```

### اختبار Bank API

```bash
cd 7-bank-project/api
npm run lint       # التحقق من مشاكل تنسيق الكود
node server.js     # التأكد من أن الخادم يبدأ بدون أخطاء
```

### النهج العام للاختبار

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

### الفحوصات قبل الإرسال

- شغّل `npm run lint` في المجلدات التي تحتوي على package.json
- تحقق من صلاحية روابط markdown
- اختبر أمثلة الشفرة في المتصفح أو Node.js
- تأكد من أن الترجمات تحافظ على الهيكلية الصحيحة

## إرشادات نمط الترميز

### JavaScript

- استخدم صِيَغ ES6+ الحديثة
- اتبع تكوينات ESLint القياسية المقدمة في المشاريع
- استخدم أسماء متغيرات ودوال ذات معنى لتوضيح التعلم
- أضف تعليقات تشرح المفاهيم للمتعلمين
- نسق باستخدام Prettier حيثما تم تهيئته

### HTML/CSS

- عناصر HTML5 دلالية
- مبادئ التصميم المتجاوب
- تسميات واضحة للفئات
- تعليقات تشرح تقنيات CSS للمتعلمين

### Python

- إرشادات نمط PEP 8
- أمثلة شفرة واضحة وتعليمية
- استخدام تلميحات النوع حيثما كان ذلك مفيدًا للتعلم

### توثيق Markdown

- هيكلية عناوين واضحة
- كتل شفرة مع تحديد اللغة
- روابط لمصادر إضافية
- لقطات شاشة وصور في مجلدات `images/`
- نص بديل للصور لتوفير إمكانية الوصول

### تنظيم الملفات

- ترقيم الدروس بتسلسل (1-getting-started-lessons، 2-js-basics، إلخ)
- لكل مشروع مجلدات `solution/` وغالبًا `start/` أو `your-work/`
- تخزين الصور في مجلدات `images/` الخاصة بكل درس
- الترجمات ضمن هيكل `translations/{language-code}/`

## البناء والنشر

### نشر تطبيق الاختبارات (Azure Static Web Apps)

تم تكوين تطبيق quiz-app للنشر عبر Azure Static Web Apps:

```bash
cd quiz-app
npm run build      # ينشئ مجلد dist/
# ينشر من خلال سير عمل GitHub Actions عند الدفع إلى الفرع الرئيسي
```

تكوين Azure Static Web Apps:
- **موقع التطبيق**: `/quiz-app`
- **موقع الإخراج**: `dist`
- **سير العمل**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`

### توليد ملفات PDF للوثائق

```bash
npm install                    # تثبيت docsify-to-pdf
npm run convert               # توليد PDF من المستندات
```

### توثيق Docsify

```bash
npm install -g docsify-cli    # تثبيت Docsify على مستوى النظام
docsify serve                 # الخادم على localhost:3000
```

### عمليات البناء الخاصة بكل مشروع

قد يكون لكل مجلد مشروع عملية بناء خاصة به:
- مشاريع Vue: `npm run build` لإنشاء حزم الإنتاج
- المشاريع الثابتة: لا توجد خطوة بناء، تقدم الملفات مباشرة

## إرشادات طلبات السحب

### صيغة العنوان

استخدم عناوين واضحة ووصفية تشير إلى مجال التغيير:
- `[Quiz-app] إضافة اختبار جديد للدرس X`
- `[Lesson-3] إصلاح خطأ مطبعي في مشروع terrarium`
- `[Translation] إضافة ترجمة إسبانية للدرس 5`
- `[Docs] تحديث تعليمات الإعداد`

### الفحوصات المطلوبة

قبل تقديم طلب السحب:

1. **جودة الشفرة**:
   - شغّل `npm run lint` في مجلدات المشاريع المتأثرة
   - أصلح جميع أخطاء وتحذيرات اللينتر

2. **التحقق من البناء**:
   - شغّل `npm run build` إذا كان ذلك مناسبًا
   - تأكد من عدم وجود أخطاء في البناء

3. **التحقق من الروابط**:
   - اختبر جميع روابط markdown
   - تحقق من عمل مراجع الصور

4. **مراجعة المحتوى**:
   - تدقيق إملائي ونحوي
   - تأكد من صحة وأسلوب أمثلة الشفرة التعليمية
   - تحقق من دقة الترجمات والمحافظة على المعنى الأصلي

### متطلبات المساهمة

- الموافقة على اتفاقية Microsoft CLA (فحص تلقائي عند أول PR)
- الالتزام بـ [ميثاق السلوك المصدر المفتوح من Microsoft](https://opensource.microsoft.com/codeofconduct/)
- انظر [CONTRIBUTING.md](./CONTRIBUTING.md) للإرشادات التفصيلية
- أدرج أرقام القضايا في وصف طلب السحب إذا وجد

### عملية المراجعة

- يتم مراجعة طلبات السحب من قبل الصيانة والمجتمع
- تُعطى أولوية لوضوح المحتوى التعليمي
- يجب أن تتبع أمثلة الشفرة أفضل الممارسات الحالية
- تُراجع الترجمات للدقة والملائمة الثقافية

## نظام الترجمة

### الترجمة الآلية

- يستخدم GitHub Actions مع سير العمل co-op-translator
- يترجم تلقائيًا لأكثر من 50 لغة
- ملفات المصدر في الأدلة الرئيسية
- ملفات الترجمة في مجلدات `translations/{language-code}/`

### إضافة تحسينات يدوية للترجمة

1. حدد موقع الملف في `translations/{language-code}/`
2. قم بإجراء التحسينات مع الحفاظ على الهيكلية
3. تأكد من استمرارية عمل أمثلة الشفرة
4. اختبر أي محتوى اختبار محلي

### بيانات وصفية للترجمة

تتضمن الملفات المترجمة رأس بيانات وصفية:
```markdown
<!--
CO_OP_TRANSLATOR_METADATA:
{
  "original_hash": "...",
  "translation_date": "...",
  "source_file": "...",
  "language_code": "..."
}
-->
```

## تصحيح الأخطاء واستكشاف المشكلات

### المشكلات الشائعة

**فشل تطبيق الاختبارات في البدء**:
- تحقق من إصدار Node.js (يفضل v14+)
- حذف `node_modules` و `package-lock.json`، ثم إعادة تشغيل `npm install`
- تحقق من تعارضات المنافذ (افتراضيًا: Vite يستخدم المنفذ 5173)

**عدم بدء تشغيل خادم API**:
- تحقق من توافق إصدار Node.js (node >=10)
- تحقق إذا كان المنفذ مستخدمًا بالفعل
- تأكد من تثبيت جميع التبعيات ب`npm install`

**إضافة المتصفح لا تعمل**:
- تحقق من صحة تنسيق ملف manifest.json
- راجع وحدة تحكم المتصفح للأخطاء
- اتبع تعليمات التثبيت الخاصة بالمتصفح

**مشكلات مشروع دردشة Python**:
- تأكد من تثبيت حزمة OpenAI: `pip install openai`
- تحقق من تعيين متغير البيئة GITHUB_TOKEN
- تحقق من أذونات وصول نماذج GitHub

**عدم تقديم Docsify للوثائق**:
- ثبت docsify-cli عالميًا: `npm install -g docsify-cli`
- شغل من دليل جذر المستودع
- تحقق من وجود `docs/_sidebar.md`

### نصائح بيئة التطوير

- استخدم VS Code مع امتداد Live Server لمشاريع HTML
- ثبت امتدادات ESLint و Prettier لتنسيق موحد
- استخدم أدوات المطور في المتصفح لتصحيح JavaScript
- لمشاريع Vue، ثبت إضافة Vue DevTools لمتصفحك

### اعتبارات الأداء

- العدد الكبير من ملفات الترجمة (أكثر من 50 لغة) يجعل النسخ الكامل كبير الحجم
- استخدم نسخة ضحلة إذا كنت تعمل على المحتوى فقط: `git clone --depth 1`
- استبعد الترجمات من عمليات البحث عند العمل على المحتوى الإنجليزي
- عمليات البناء قد تكون بطيئة في التشغيل الأول (npm install، Vite build)

## اعتبارات الأمان

### متغيرات البيئة

- يجب ألا تُخزّن مفاتيح API في المستودع
- استخدم ملفات `.env` (مودّجة بالفعل في `.gitignore`)
- وثّق متغيرات البيئة المطلوبة في ملفات README الخاصة بالمشاريع

### مشاريع Python

- استخدم بيئات افتراضية: `python -m venv venv`
- حافظ على تحديث التبعيات
- يجب أن يمتلك رموز GitHub الحد الأدنى من الأذونات المطلوبة

### وصول نماذج GitHub

- تتطلب رموز وصول شخصية (PAT) لنماذج GitHub
- يجب تخزين الرموز كمتغيرات بيئية
- لا تلتزم الرموز أو بيانات الاعتماد في المستودع

## ملاحظات إضافية

### الجمهور المستهدف

- مبتدئون تمامًا في تطوير الويب
- الطلاب والمتعلمون الذاتيّون
- المعلمون الذين يستخدمون المنهج في الفصول الدراسية
- المحتوى مصمم ليكون سهل الوصول ويُبنى المهارات تدريجيًا

### الفلسفة التعليمية

- نهج التعلم بالمشاريع
- اختبارات متكررة للمعرفة (الاختبارات)
- تمارين ترميز عملية
- أمثلة تطبيق من الواقع
- التركيز على الأساسيات قبل الأُطُر

### صيانة المستودع

- مجتمع نشط من المتعلمين والمساهمين
- تحديثات منتظمة للتبعيات والمحتوى
- متابعة القضايا والمناقشات من قبل الصيانة
- تحديثات الترجمة آلية عبر GitHub Actions

### الموارد ذات الصلة

- [وحدات Microsoft Learn](https://docs.microsoft.com/learn/)
- [موارد Student Hub](https://docs.microsoft.com/learn/student-hub/)
- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) يُوصى به للمتعلمين
- دورات إضافية: الذكاء الاصطناعي التوليدي، علوم البيانات، تعلم الآلة، مناهج إنترنت الأشياء متاحة

### العمل مع مشاريع محددة

للحصول على تعليمات مفصلة حول المشاريع الفردية، راجع ملفات README في:
- `quiz-app/README.md` - تطبيق اختبار Vue 3
- `7-bank-project/README.md` - تطبيق البنك مع المصادقة
- `5-browser-extension/README.md` - تطوير إضافة المتصفح
- `6-space-game/README.md` - تطوير لعبة على Canvas
- `9-chat-project/README.md` - مشروع مساعد دردشة AI

### هيكلية Monorepo

على الرغم من أنه ليس monorepo تقليدي، يحتوي هذا المستودع على مشاريع مستقلة متعددة:
- كل درس قائم بذاته
- المشاريع لا تشترك في التبعيات
- يمكنك العمل على مشاريع فردية بدون التأثير على الآخرين
- انسخ المستودع بالكامل للحصول على تجربة المنهج الكامل

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**تنويه**:  
تمت ترجمة هذا المستند باستخدام خدمة الترجمة الآلية [Co-op Translator](https://github.com/Azure/co-op-translator). بينما نسعى لتحقيق الدقة، يرجى العلم أن الترجمات الآلية قد تحتوي على أخطاء أو عدم دقة. يجب اعتبار المستند الأصلي بلغته الأصلية المصدر الموثوق والمعتمد. للمعلومات الحساسة أو الحيوية، يُنصح بالاعتماد على ترجمة بشرية محترفة. نحن غير مسؤولين عن أي سوء فهم أو تفسير ناتج عن استخدام هذه الترجمة.
<!-- CO-OP TRANSLATOR DISCLAIMER END -->