📦 microsoft / Web-Dev-For-Beginners

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
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
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415<!--
CO_OP_TRANSLATOR_METADATA:
{
  "original_hash": "a362efd06d64d4134a0cfe8515a86d34",
  "translation_date": "2025-10-03T11:32:49+00:00",
  "source_file": "AGENTS.md",
  "language_code": "he"
}
-->
# AGENTS.md

## סקירת הפרויקט

זהו מאגר תכנית לימודים חינוכית להוראת יסודות פיתוח אתרים למתחילים. התכנית היא קורס מקיף של 12 שבועות שפותח על ידי Microsoft Cloud Advocates, וכוללת 24 שיעורים מעשיים המכסים JavaScript, CSS ו-HTML.

### רכיבים מרכזיים

- **תוכן חינוכי**: 24 שיעורים מובנים המאורגנים במודולים מבוססי פרויקטים
- **פרויקטים מעשיים**: טרריום, משחק הקלדה, הרחבת דפדפן, משחק חלל, אפליקציית בנקאות, עורך קוד ועוזר צ'אט מבוסס AI
- **חידונים אינטראקטיביים**: 48 חידונים עם 3 שאלות כל אחד (הערכות לפני/אחרי שיעור)
- **תמיכה רב-לשונית**: תרגומים אוטומטיים ל-50+ שפות באמצעות GitHub Actions
- **טכנולוגיות**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (לפרויקטי AI)

### ארכיטקטורה

- מאגר חינוכי עם מבנה מבוסס שיעורים
- כל תיקיית שיעור מכילה 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        # Start development server
npm run build      # Build for production
npm run lint       # Run ESLint
```

### API של פרויקט הבנק (Node.js + Express)

```bash
cd 7-bank-project/api
npm install
npm start          # Start API server
npm run lint       # Run ESLint
npm run format     # Format with Prettier
```

### פרויקטים של הרחבות דפדפן

```bash
cd 5-browser-extension/solution
npm install
# Follow browser-specific extension loading instructions
```

### פרויקטים של משחק החלל

```bash
cd 6-space-game/solution
npm install
# Open index.html in browser or use Live Server
```

### פרויקט הצ'אט (Python Backend)

```bash
cd 9-chat-project/solution/backend/python
pip install openai
# Set GITHUB_TOKEN environment variable
python api.py
```

## זרימת עבודה לפיתוח

### עבור תורמי תוכן

1. **צרו Fork למאגר** לחשבון GitHub שלכם
2. **שכפלו את ה-Fork** באופן מקומי
3. **צרו ענף חדש** לשינויים שלכם
4. בצעו שינויים בתוכן השיעורים או בדוגמאות הקוד
5. בדקו שינויים בקוד בתיקיות הפרויקטים הרלוונטיות
6. שלחו Pull Requests בהתאם להנחיות התרומה

### עבור לומדים

1. צרו Fork או שכפלו את המאגר
2. נווטו לתיקיות השיעורים לפי הסדר
3. קראו את קבצי README לכל שיעור
4. השלימו חידונים לפני השיעור בכתובת https://ff-quizzes.netlify.app/web/
5. עבדו על דוגמאות הקוד בתיקיות השיעורים
6. השלימו משימות ואתגרים
7. בצעו חידונים לאחר השיעור

### פיתוח חי

- **תיעוד**: הריצו `docsify serve` בתיקיית השורש (פורט 3000)
- **אפליקציית חידונים**: הריצו `npm run dev` בתיקיית quiz-app
- **פרויקטים**: השתמשו בתוסף Live Server של VS Code לפרויקטי HTML
- **פרויקטי API**: הריצו `npm start` בתיקיות ה-API הרלוונטיות

## הוראות בדיקה

### בדיקת אפליקציית החידונים

```bash
cd quiz-app
npm run lint       # Check for code style issues
npm run build      # Verify build succeeds
```

### בדיקת API של הבנק

```bash
cd 7-bank-project/api
npm run lint       # Check for code style issues
node server.js     # Verify server starts without errors
```

### גישת בדיקה כללית

- זהו מאגר חינוכי ללא בדיקות אוטומטיות מקיפות
- בדיקות ידניות מתמקדות ב:
  - דוגמאות קוד רצות ללא שגיאות
  - קישורים בתיעוד עובדים כראוי
  - בניית פרויקטים מסתיימת בהצלחה
  - דוגמאות עוקבות אחר שיטות עבודה מומלצות

### בדיקות לפני שליחה

- הריצו `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)

אפליקציית החידונים מוגדרת לפריסה ב-Azure Static Web Apps:

```bash
cd quiz-app
npm run build      # Creates dist/ folder
# Deploys via GitHub Actions workflow on push to main
```

תצורת Azure Static Web Apps:
- **מיקום האפליקציה**: `/quiz-app`
- **מיקום הפלט**: `dist`
- **Workflow**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`

### יצירת PDF לתיעוד

```bash
npm install                    # Install docsify-to-pdf
npm run convert               # Generate PDF from docs
```

### תיעוד Docsify

```bash
npm install -g docsify-cli    # Install Docsify globally
docsify serve                 # Serve on localhost:3000
```

### בניות ספציפיות לפרויקטים

לכל תיקיית פרויקט עשוי להיות תהליך בנייה משלה:
- פרויקטי Vue: `npm run build` יוצר חבילות ייצור
- פרויקטים סטטיים: אין שלב בנייה, הגישו קבצים ישירות

## הנחיות Pull Request

### פורמט כותרת

השתמשו בכותרות ברורות ותיאוריות המצביעות על תחום השינוי:
- `[Quiz-app] Add new quiz for lesson X`
- `[Lesson-3] Fix typo in terrarium project`
- `[Translation] Add Spanish translation for lesson 5`
- `[Docs] Update setup instructions`

### בדיקות נדרשות

לפני שליחת PR:

1. **איכות קוד**:
   - הריצו `npm run lint` בתיקיות הפרויקטים המושפעות
   - תקנו את כל שגיאות ואזהרות הלינטר

2. **אימות בנייה**:
   - הריצו `npm run build` אם רלוונטי
   - ודאו שאין שגיאות בנייה

3. **אימות קישורים**:
   - בדקו את כל קישורי Markdown
   - ודאו שהפניות לתמונות עובדות

4. **סקירת תוכן**:
   - בדקו שגיאות כתיב ודקדוק
   - ודאו שדוגמאות הקוד נכונות וחינוכיות
   - בדקו שהתרגומים שומרים על המשמעות המקורית

### דרישות תרומה

- הסכימו ל-Microsoft CLA (בדיקה אוטומטית ב-PR הראשון)
- עקבו אחר [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)
- ראו [CONTRIBUTING.md](./CONTRIBUTING.md) להנחיות מפורטות
- התייחסו למספרי בעיות בתיאור ה-PR אם רלוונטי

### תהליך סקירה

- PRs נסקרים על ידי מתחזקים והקהילה
- בהירות חינוכית היא בעדיפות
- דוגמאות קוד צריכות לעקוב אחר שיטות עבודה עדכניות
- תרגומים נסקרים לצורך דיוק והתאמה תרבותית

## מערכת תרגום

### תרגום אוטומטי

- משתמשת ב-GitHub Actions עם workflow של 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 Models

**Docsify לא מגיש תיעוד**:
- התקינו docsify-cli באופן גלובלי: `npm install -g docsify-cli`
- הריצו מתיקיית השורש של המאגר
- בדקו ש-`docs/_sidebar.md` קיים

### טיפים לסביבת פיתוח

- השתמשו ב-VS Code עם תוסף Live Server לפרויקטי HTML
- התקינו תוספי ESLint ו-Prettier לעיצוב עקבי
- השתמשו בכלי DevTools של הדפדפן לאיתור באגים ב-JavaScript
- לפרויקטי Vue, התקינו את תוסף Vue DevTools לדפדפן

### שיקולי ביצועים

- מספר גדול של קבצים מתורגמים (50+ שפות) גורם לכך ששכפולים מלאים גדולים
- השתמשו בשכפול רדוד אם עובדים רק על תוכן: `git clone --depth 1`
- החריגו תרגומים מחיפושים בעת עבודה על תוכן באנגלית
- תהליכי בנייה עשויים להיות איטיים בהרצה הראשונה (npm install, Vite build)

## שיקולי אבטחה

### משתני סביבה

- מפתחות API לעולם לא צריכים להיות מחויבים למאגר
- השתמשו בקבצי `.env` (כבר ב-.gitignore)
- תעדו משתני סביבה נדרשים בקבצי README של הפרויקטים

### פרויקטי Python

- השתמשו בסביבות וירטואליות: `python -m venv venv`
- שמרו על תלויות מעודכנות
- אסימוני GitHub צריכים להיות בעלי הרשאות מינימליות נדרשות

### גישה ל-GitHub Models

- נדרשים Personal Access Tokens (PAT) ל-GitHub Models
- אסימונים צריכים להיות מאוחסנים כמשתני סביבה
- לעולם אל תתחייבו אסימונים או אישורים

## הערות נוספות

### קהל יעד

- מתחילים מוחלטים בפיתוח אתרים
- סטודנטים ולומדים עצמאיים
- מורים המשתמשים בתכנית הלימודים בכיתות
- התוכן מיועד לנגישות ולבניית מיומנויות הדרגתית

### פילוסופיה חינוכית

- גישה מבוססת פרויקטים ללמידה
- בדיקות ידע תכופות (חידונים)
- תרגילי קוד מעשיים
- דוגמאות יישום בעולם האמיתי
- התמקדות ביסודות לפני מסגרות עבודה

### תחזוקת המאגר

- קהילה פעילה של לומדים ותורמים
- עדכונים שוטפים לתלויות ולתוכן
- בעיות ודיונים מנוטרים על ידי מתחזקים
- עדכוני תרגום אוטומטיים באמצעות 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) מומלץ ללומדים
- קורסים נוספים: Generative AI, Data Science, ML, IoT זמינים

### עבודה עם פרויקטים ספציפיים

להוראות מפורטות על פרויקטים בודדים, עיינו בקבצי 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](https://github.com/Azure/co-op-translator). למרות שאנו שואפים לדיוק, יש לקחת בחשבון שתרגומים אוטומטיים עשויים להכיל שגיאות או אי דיוקים. המסמך המקורי בשפתו המקורית צריך להיחשב כמקור סמכותי. עבור מידע קריטי, מומלץ להשתמש בתרגום מקצועי על ידי אדם. איננו נושאים באחריות לאי הבנות או לפרשנויות שגויות הנובעות משימוש בתרגום זה.