# 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        # הפעל שרת פיתוח
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
```

### פרויקט צ׳אט (Backend בפייתון)

```bash
cd 9-chat-project/solution/backend/python
pip install openai
# הגדר את משתנה הסביבה GITHUB_TOKEN
python api.py
```

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

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

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

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

1. צור Fork או שכפל את המאגר
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      # אמת שהבניין מצליח
```

### בדיקת 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)

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

```bash
cd quiz-app
npm run build      # יוצרת את התיקיה dist/
# מבצעת פריסה דרך זרימת עבודה של GitHub Actions בעת דחיפה לענף main
```

הגדרות 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 מ-docs
```

### תיעוד Docsify

```bash
npm install -g docsify-cli    # התקן את Docsify באופן גלובלי
docsify serve                 # שרת על localhost:3000
```

### בניות ייחודיות לפרויקט

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

## קווי הנחיה לבקשות משיכה

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

השתמש בכותרות ברורות ומתארות עם אזור השינוי:
- `[Quiz-app] הוסף חידון חדש לשיעור X`
- `[Lesson-3] תיקון שגיאת הקלדה בפרויקט טראריום`
- `[Translation] הוסף תרגום ספרדי לשיעור 5`
- `[Docs] עדכן הוראות התקנה`

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

לפני הגשת PR:

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

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

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

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

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

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

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

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

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

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

- משתמש ב-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 מעוצב כראוי
- בדוק בלוג הדפדפן לשגיאות
- עקוב אחר הוראות ההתקנה הספציפיות לדפדפן

**בעיות בפרויקט צ׳אט בפייתון**:
- ודא שהחבילה 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)

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

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

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

### פרויקטים בפייתון

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

### גישה למודלים של GitHub

- דרושים Personal Access Tokens (PAT) לגישה למודלים
- יש לאחסן אסימונים במשתני סביבה
- לעולם לא לשמור אסימונים או אישורים בקוד

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

### קהל יעד

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

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

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

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

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

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

להוראות מפורטות על פרויקטים בודדים, עיין בקבצי README ב:
- `quiz-app/README.md` - אפליקציית חידונים ב-Vue 3
- `7-bank-project/README.md` - אפליקציית בנקאות עם אימות
- `5-browser-extension/README.md` - פיתוח תוסף דפדפן
- `6-space-game/README.md` - פיתוח משחק מבוסס קנבס
- `9-chat-project/README.md` - פרויקט עוזר צ׳אט מבוסס AI

### מבנה מונורפו

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

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**כתב ויתור**:  
מסמך זה תורגם באמצעות שירות תרגום מבוסס בינה מלאכותית [Co-op Translator](https://github.com/Azure/co-op-translator). למרות שאנו שואפים לדיוק, יש להיות מודעים לכך שתירגומים אוטומטיים עלולים להכיל שגיאות או אי-דיוקים. המסמך המקורי בשפת המקור שלו הוא המקור הסמכותי. למידע קריטי מומלץ להשתמש בתרגום מקצועי של אדם. אנו לא אחראים לכל אי-הבנה או פרשנות שגויה הנובעת משימוש בתרגום זה.
<!-- CO-OP TRANSLATOR DISCLAIMER END -->