AGENTS.md

1# AGENTS.md
2 
3## نظرة عامة على المشروع
4 
5هذا مستودع منهج تعليمي لتعليم أساسيات تطوير الويب للمبتدئين. المنهج هو دورة شاملة مدتها 12 أسبوعًا تم تطويرها بواسطة Microsoft Cloud Advocates، ويضم 24 درسًا عمليًا يغطي JavaScript و CSS و HTML.
6 
7### المكونات الرئيسية
8 
9- **المحتوى التعليمي**: 24 درسًا منظّمة ضمن وحدات قائمة على المشاريع
10- **المشاريع العملية**: Terrarium، لعبة الطباعة، إضافة المتصفح، لعبة الفضاء، تطبيق البنك، محرر الأكواد، ومساعد دردشة AI
11- **اختبارات تفاعلية**: 48 اختبارًا كل منها يحتوي على 3 أسئلة (تقييمات قبل وبعد الدرس)
12- **دعم متعدد اللغات**: ترجمات آلية لأكثر من 50 لغة عبر GitHub Actions
13- **التقنيات**: HTML، CSS، JavaScript، Vue.js 3، Vite، Node.js، Express، Python (لمشاريع الذكاء الاصطناعي)
14 
15### الهيكلية
16 
17- مستودع تعليمي به هيكلية قائمة على الدروس
18- يحتوي كل مجلد درس على README، وأمثلة على الشفرة، والحلول
19- مشاريع قائمة بذاتها في مجلدات منفصلة (quiz-app، مشاريع دروس مختلفة)
20- نظام ترجمة يستخدم GitHub Actions (co-op-translator)
21- الوثائق مقدمة عبر Docsify ومتاحة كملفات PDF
22 
23## أوامر الإعداد
24 
25هذا المستودع مخصص بشكل أساسي لاستهلاك المحتوى التعليمي. للعمل على مشاريع محددة:
26 
27### إعداد المستودع الرئيسي
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### إعداد تطبيق الاختبارات (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # ابدأ خادم التطوير
40npm run build      # إنشاء للإنتاج
41npm run lint       # تشغيل ESLint
42```
43 
44### API مشروع البنك (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # بدء خادم API
50npm run lint       # تشغيل ESLint
51npm run format     # التنسيق باستخدام Prettier
52```
53 
54### مشاريع إضافة المتصفح
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# اتبع تعليمات تحميل الإضافات الخاصة بالمتصفح
60```
61 
62### مشاريع لعبة الفضاء
63 
64```bash
65cd 6-space-game/solution
66npm install
67# افتح index.html في المتصفح أو استخدم Live Server
68```
69 
70### مشروع الدردشة (خلفية Python)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# تعيين متغير البيئة GITHUB_TOKEN
76python api.py
77```
78 
79## سير العمل التطويري
80 
81### للمساهمين في المحتوى
82 
831. **افتح فورك للمستودع** على حساب GitHub الخاص بك
842. **انسخ الفورك محليًا**
853. **أنشئ فرعًا جديدًا** لتغييراتك
864. قم بإجراء تغييرات على محتوى الدرس أو أمثلة الشفرة
875. اختبر أي تغييرات في الشفرة في مجلدات المشروع المعنية
886. قدم طلبات سحب باتباع إرشادات المساهمة
89 
90### للمتعلمين
91 
921. افتح فورك أو انسخ المستودع
932. انتقل إلى مجلدات الدروس بترتيب متسلسل
943. اقرأ ملفات README لكل درس
954. أكمل اختبارات ما قبل الدرس على https://ff-quizzes.netlify.app/web/
965. اعمل على أمثلة الشفرة في مجلدات الدرس
976. أكمل المهام والتحديات
987. قم بأداء اختبارات ما بعد الدرس
99 
100### التطوير الحي
101 
102- **الوثائق**: شغّل `docsify serve` في جذر المستودع (المنفذ 3000)
103- **تطبيق الاختبارات**: شغّل `npm run dev` في دليل quiz-app
104- **المشاريع**: استخدم ملحق VS Code Live Server لمشاريع HTML
105- **مشاريع API**: شغّل `npm start` في مجلدات API المعنية
106 
107## تعليمات الاختبار
108 
109### اختبار تطبيق الاختبارات
110 
111```bash
112cd quiz-app
113npm run lint       # التحقق من وجود مشكلات في نمط الكود
114npm run build      # التأكد من نجاح البناء
115```
116 
117### اختبار Bank API
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # التحقق من مشاكل تنسيق الكود
122node server.js     # التأكد من أن الخادم يبدأ بدون أخطاء
123```
124 
125### النهج العام للاختبار
126 
127- هذا مستودع تعليمي بدون اختبارات آلية شاملة
128- يركز الاختبار اليدوي على:
129  - تشغيل أمثلة الشفرة بدون أخطاء
130  - عمل الروابط في الوثائق بشكل صحيح
131  - إتمام بناء المشاريع بنجاح
132  - اتباع أفضل الممارسات في الأمثلة
133 
134### الفحوصات قبل الإرسال
135 
136- شغّل `npm run lint` في المجلدات التي تحتوي على package.json
137- تحقق من صلاحية روابط markdown
138- اختبر أمثلة الشفرة في المتصفح أو Node.js
139- تأكد من أن الترجمات تحافظ على الهيكلية الصحيحة
140 
141## إرشادات نمط الترميز
142 
143### JavaScript
144 
145- استخدم صِيَغ ES6+ الحديثة
146- اتبع تكوينات ESLint القياسية المقدمة في المشاريع
147- استخدم أسماء متغيرات ودوال ذات معنى لتوضيح التعلم
148- أضف تعليقات تشرح المفاهيم للمتعلمين
149- نسق باستخدام Prettier حيثما تم تهيئته
150 
151### HTML/CSS
152 
153- عناصر HTML5 دلالية
154- مبادئ التصميم المتجاوب
155- تسميات واضحة للفئات
156- تعليقات تشرح تقنيات CSS للمتعلمين
157 
158### Python
159 
160- إرشادات نمط PEP 8
161- أمثلة شفرة واضحة وتعليمية
162- استخدام تلميحات النوع حيثما كان ذلك مفيدًا للتعلم
163 
164### توثيق Markdown
165 
166- هيكلية عناوين واضحة
167- كتل شفرة مع تحديد اللغة
168- روابط لمصادر إضافية
169- لقطات شاشة وصور في مجلدات `images/`
170- نص بديل للصور لتوفير إمكانية الوصول
171 
172### تنظيم الملفات
173 
174- ترقيم الدروس بتسلسل (1-getting-started-lessons، 2-js-basics، إلخ)
175- لكل مشروع مجلدات `solution/` وغالبًا `start/` أو `your-work/`
176- تخزين الصور في مجلدات `images/` الخاصة بكل درس
177- الترجمات ضمن هيكل `translations/{language-code}/`
178 
179## البناء والنشر
180 
181### نشر تطبيق الاختبارات (Azure Static Web Apps)
182 
183تم تكوين تطبيق quiz-app للنشر عبر Azure Static Web Apps:
184 
185```bash
186cd quiz-app
187npm run build      # ينشئ مجلد dist/
188# ينشر من خلال سير عمل GitHub Actions عند الدفع إلى الفرع الرئيسي
189```
190 
191تكوين Azure Static Web Apps:
192- **موقع التطبيق**: `/quiz-app`
193- **موقع الإخراج**: `dist`
194- **سير العمل**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### توليد ملفات PDF للوثائق
197 
198```bash
199npm install                    # تثبيت docsify-to-pdf
200npm run convert               # توليد PDF من المستندات
201```
202 
203### توثيق Docsify
204 
205```bash
206npm install -g docsify-cli    # تثبيت Docsify على مستوى النظام
207docsify serve                 # الخادم على localhost:3000
208```
209 
210### عمليات البناء الخاصة بكل مشروع
211 
212قد يكون لكل مجلد مشروع عملية بناء خاصة به:
213- مشاريع Vue: `npm run build` لإنشاء حزم الإنتاج
214- المشاريع الثابتة: لا توجد خطوة بناء، تقدم الملفات مباشرة
215 
216## إرشادات طلبات السحب
217 
218### صيغة العنوان
219 
220استخدم عناوين واضحة ووصفية تشير إلى مجال التغيير:
221- `[Quiz-app] إضافة اختبار جديد للدرس X`
222- `[Lesson-3] إصلاح خطأ مطبعي في مشروع terrarium`
223- `[Translation] إضافة ترجمة إسبانية للدرس 5`
224- `[Docs] تحديث تعليمات الإعداد`
225 
226### الفحوصات المطلوبة
227 
228قبل تقديم طلب السحب:
229 
2301. **جودة الشفرة**:
231   - شغّل `npm run lint` في مجلدات المشاريع المتأثرة
232   - أصلح جميع أخطاء وتحذيرات اللينتر
233 
2342. **التحقق من البناء**:
235   - شغّل `npm run build` إذا كان ذلك مناسبًا
236   - تأكد من عدم وجود أخطاء في البناء
237 
2383. **التحقق من الروابط**:
239   - اختبر جميع روابط markdown
240   - تحقق من عمل مراجع الصور
241 
2424. **مراجعة المحتوى**:
243   - تدقيق إملائي ونحوي
244   - تأكد من صحة وأسلوب أمثلة الشفرة التعليمية
245   - تحقق من دقة الترجمات والمحافظة على المعنى الأصلي
246 
247### متطلبات المساهمة
248 
249- الموافقة على اتفاقية Microsoft CLA (فحص تلقائي عند أول PR)
250- الالتزام بـ [ميثاق السلوك المصدر المفتوح من Microsoft](https://opensource.microsoft.com/codeofconduct/)
251- انظر [CONTRIBUTING.md](./CONTRIBUTING.md) للإرشادات التفصيلية
252- أدرج أرقام القضايا في وصف طلب السحب إذا وجد
253 
254### عملية المراجعة
255 
256- يتم مراجعة طلبات السحب من قبل الصيانة والمجتمع
257- تُعطى أولوية لوضوح المحتوى التعليمي
258- يجب أن تتبع أمثلة الشفرة أفضل الممارسات الحالية
259- تُراجع الترجمات للدقة والملائمة الثقافية
260 
261## نظام الترجمة
262 
263### الترجمة الآلية
264 
265- يستخدم GitHub Actions مع سير العمل co-op-translator
266- يترجم تلقائيًا لأكثر من 50 لغة
267- ملفات المصدر في الأدلة الرئيسية
268- ملفات الترجمة في مجلدات `translations/{language-code}/`
269 
270### إضافة تحسينات يدوية للترجمة
271 
2721. حدد موقع الملف في `translations/{language-code}/`
2732. قم بإجراء التحسينات مع الحفاظ على الهيكلية
2743. تأكد من استمرارية عمل أمثلة الشفرة
2754. اختبر أي محتوى اختبار محلي
276 
277### بيانات وصفية للترجمة
278 
279تتضمن الملفات المترجمة رأس بيانات وصفية:
280```markdown
281<!--
282CO_OP_TRANSLATOR_METADATA:
283{
284  "original_hash": "...",
285  "translation_date": "...",
286  "source_file": "...",
287  "language_code": "..."
288}
289-->
290```
291 
292## تصحيح الأخطاء واستكشاف المشكلات
293 
294### المشكلات الشائعة
295 
296**فشل تطبيق الاختبارات في البدء**:
297- تحقق من إصدار Node.js (يفضل v14+)
298- حذف `node_modules` و `package-lock.json`، ثم إعادة تشغيل `npm install`
299- تحقق من تعارضات المنافذ (افتراضيًا: Vite يستخدم المنفذ 5173)
300 
301**عدم بدء تشغيل خادم API**:
302- تحقق من توافق إصدار Node.js (node >=10)
303- تحقق إذا كان المنفذ مستخدمًا بالفعل
304- تأكد من تثبيت جميع التبعيات ب`npm install`
305 
306**إضافة المتصفح لا تعمل**:
307- تحقق من صحة تنسيق ملف manifest.json
308- راجع وحدة تحكم المتصفح للأخطاء
309- اتبع تعليمات التثبيت الخاصة بالمتصفح
310 
311**مشكلات مشروع دردشة Python**:
312- تأكد من تثبيت حزمة OpenAI: `pip install openai`
313- تحقق من تعيين متغير البيئة GITHUB_TOKEN
314- تحقق من أذونات وصول نماذج GitHub
315 
316**عدم تقديم Docsify للوثائق**:
317- ثبت docsify-cli عالميًا: `npm install -g docsify-cli`
318- شغل من دليل جذر المستودع
319- تحقق من وجود `docs/_sidebar.md`
320 
321### نصائح بيئة التطوير
322 
323- استخدم VS Code مع امتداد Live Server لمشاريع HTML
324- ثبت امتدادات ESLint و Prettier لتنسيق موحد
325- استخدم أدوات المطور في المتصفح لتصحيح JavaScript
326- لمشاريع Vue، ثبت إضافة Vue DevTools لمتصفحك
327 
328### اعتبارات الأداء
329 
330- العدد الكبير من ملفات الترجمة (أكثر من 50 لغة) يجعل النسخ الكامل كبير الحجم
331- استخدم نسخة ضحلة إذا كنت تعمل على المحتوى فقط: `git clone --depth 1`
332- استبعد الترجمات من عمليات البحث عند العمل على المحتوى الإنجليزي
333- عمليات البناء قد تكون بطيئة في التشغيل الأول (npm install، Vite build)
334 
335## اعتبارات الأمان
336 
337### متغيرات البيئة
338 
339- يجب ألا تُخزّن مفاتيح API في المستودع
340- استخدم ملفات `.env` (مودّجة بالفعل في `.gitignore`)
341- وثّق متغيرات البيئة المطلوبة في ملفات README الخاصة بالمشاريع
342 
343### مشاريع Python
344 
345- استخدم بيئات افتراضية: `python -m venv venv`
346- حافظ على تحديث التبعيات
347- يجب أن يمتلك رموز GitHub الحد الأدنى من الأذونات المطلوبة
348 
349### وصول نماذج GitHub
350 
351- تتطلب رموز وصول شخصية (PAT) لنماذج GitHub
352- يجب تخزين الرموز كمتغيرات بيئية
353- لا تلتزم الرموز أو بيانات الاعتماد في المستودع
354 
355## ملاحظات إضافية
356 
357### الجمهور المستهدف
358 
359- مبتدئون تمامًا في تطوير الويب
360- الطلاب والمتعلمون الذاتيّون
361- المعلمون الذين يستخدمون المنهج في الفصول الدراسية
362- المحتوى مصمم ليكون سهل الوصول ويُبنى المهارات تدريجيًا
363 
364### الفلسفة التعليمية
365 
366- نهج التعلم بالمشاريع
367- اختبارات متكررة للمعرفة (الاختبارات)
368- تمارين ترميز عملية
369- أمثلة تطبيق من الواقع
370- التركيز على الأساسيات قبل الأُطُر
371 
372### صيانة المستودع
373 
374- مجتمع نشط من المتعلمين والمساهمين
375- تحديثات منتظمة للتبعيات والمحتوى
376- متابعة القضايا والمناقشات من قبل الصيانة
377- تحديثات الترجمة آلية عبر GitHub Actions
378 
379### الموارد ذات الصلة
380 
381- [وحدات Microsoft Learn](https://docs.microsoft.com/learn/)
382- [موارد Student Hub](https://docs.microsoft.com/learn/student-hub/)
383- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) يُوصى به للمتعلمين
384- دورات إضافية: الذكاء الاصطناعي التوليدي، علوم البيانات، تعلم الآلة، مناهج إنترنت الأشياء متاحة
385 
386### العمل مع مشاريع محددة
387 
388للحصول على تعليمات مفصلة حول المشاريع الفردية، راجع ملفات README في:
389- `quiz-app/README.md` - تطبيق اختبار Vue 3
390- `7-bank-project/README.md` - تطبيق البنك مع المصادقة
391- `5-browser-extension/README.md` - تطوير إضافة المتصفح
392- `6-space-game/README.md` - تطوير لعبة على Canvas
393- `9-chat-project/README.md` - مشروع مساعد دردشة AI
394 
395### هيكلية Monorepo
396 
397على الرغم من أنه ليس monorepo تقليدي، يحتوي هذا المستودع على مشاريع مستقلة متعددة:
398- كل درس قائم بذاته
399- المشاريع لا تشترك في التبعيات
400- يمكنك العمل على مشاريع فردية بدون التأثير على الآخرين
401- انسخ المستودع بالكامل للحصول على تجربة المنهج الكامل
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**تنويه**:  
407تمت ترجمة هذا المستند باستخدام خدمة الترجمة الآلية [Co-op Translator](https://github.com/Azure/co-op-translator). بينما نسعى لتحقيق الدقة، يرجى العلم أن الترجمات الآلية قد تحتوي على أخطاء أو عدم دقة. يجب اعتبار المستند الأصلي بلغته الأصلية المصدر الموثوق والمعتمد. للمعلومات الحساسة أو الحيوية، يُنصح بالاعتماد على ترجمة بشرية محترفة. نحن غير مسؤولين عن أي سوء فهم أو تفسير ناتج عن استخدام هذه الترجمة.
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->