AGENTS.md

1# AGENTS.md
2 
3## סקירת הפרויקט
4 
5זהו מאגר תוכן חינוכי ללימוד יסודות פיתוח ווב למתחילים. תוכנית הלימודים היא קורס מקיף בן 12 שבועות שפותח על ידי Microsoft Cloud Advocates, הכולל 24 שיעורים מעשיים העוסקים ב-JavaScript, CSS ו-HTML.
6 
7### רכיבים מרכזיים
8 
9- **תוכן חינוכי**: 24 שיעורים מאורגנים במודולים מבוססי פרויקטים
10- **פרויקטים מעשיים**: טראריום, משחק הקלדה, תוסף דפדפן, משחק חלל, אפליקציית בנקאות, עורך קוד ועוזר צ׳אט מבוסס AI
11- **חידונים אינטראקטיביים**: 48 חידונים עם 3 שאלות כל אחד (הערכות לפני/אחרי השיעור)
12- **תמיכה רב-שפתית**: תרגומים אוטומטיים ל-50+ שפות דרך GitHub Actions
13- **טכנולוגיות**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (לפרויקטים מבוססי AI)
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### פרויקט צ׳אט (Backend בפייתון)
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. **צור Fork למאגר** לחשבון ה-GitHub שלך
842. **שכפל את ה-Fork** במחשב המקומי שלך
853. **צור סניף חדש** לשינויים שלך
864. בצע שינויים בתוכן השיעורים או בדוגמאות הקוד
875. בדוק כל שינויי קוד בתיקיות הפרויקט הרלוונטיות
886. הגש בקשות משיכה בהתאם להנחיות התרומה
89 
90### עבור הלומדים
91 
921. צור Fork או שכפל את המאגר
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### בדיקת 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אפליקציית החידונים מוגדרת לפריסה בשירות Azure Static Web Apps:
184 
185```bash
186cd quiz-app
187npm run build      # יוצרת את התיקיה dist/
188# מבצעת פריסה דרך זרימת עבודה של GitHub Actions בעת דחיפה לענף main
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 מ-docs
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] תיקון שגיאת הקלדה בפרויקט טראריום`
223- `[Translation] הוסף תרגום ספרדי לשיעור 5`
224- `[Docs] עדכן הוראות התקנה`
225 
226### בדיקות נדרשות
227 
228לפני הגשת PR:
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- אישור CLA של מיקרוסופט (בדיקה אוטומטית בעת PR ראשון)
250- עקוב אחר [קוד ההתנהגות של Microsoft Open Source](https://opensource.microsoft.com/codeofconduct/)
251- עיין בקובץ [CONTRIBUTING.md](./CONTRIBUTING.md) להנחיות מפורטות
252- התייחס למספרי נושאים בתיאור ה-PR אם רלוונטי
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**בעיות בפרויקט צ׳אט בפייתון**:
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)
334 
335## שיקולי אבטחה
336 
337### משתני סביבה
338 
339- אסור לשמור מפתחות API במאגר
340- השתמש בקבצי `.env` (כבר ב-.gitignore)
341- תעד משתני סביבה נדרשים בקבצי README של הפרויקטים
342 
343### פרויקטים בפייתון
344 
345- השתמש בסביבות וירטואליות: `python -m venv venv`
346- שמור על עדכון התלויות
347- אסימונים של GitHub צריכים להיות עם הרשאות מינימליות
348 
349### גישה למודלים של GitHub
350 
351- דרושים Personal Access Tokens (PAT) לגישה למודלים
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- קורסים נוספים: AI גנרטיבי, מדעי נתונים, למידת מכונה, IoT זמינים
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` - פיתוח משחק מבוסס קנבס
393- `9-chat-project/README.md` - פרויקט עוזר צ׳אט מבוסס AI
394 
395### מבנה מונורפו
396 
397למרות שאינו מונורפו מסורתי, מאגר זה מכיל מספר פרויקטים עצמאיים:
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 -->