<!--
CO_OP_TRANSLATOR_METADATA:
{
  "original_hash": "a362efd06d64d4134a0cfe8515a86d34",
  "translation_date": "2025-10-03T11:15:19+00:00",
  "source_file": "AGENTS.md",
  "language_code": "fa"
}
-->
# AGENTS.md

## نمای کلی پروژه

این مخزن یک برنامه آموزشی برای آموزش اصول توسعه وب به مبتدیان است. این برنامه آموزشی یک دوره جامع ۱۲ هفته‌ای است که توسط Microsoft Cloud Advocates توسعه داده شده و شامل ۲۴ درس عملی در زمینه جاوااسکریپت، CSS و HTML می‌باشد.

### اجزای کلیدی

- **محتوای آموزشی**: ۲۴ درس ساختارمند که به صورت ماژول‌های مبتنی بر پروژه سازماندهی شده‌اند
- **پروژه‌های عملی**: Terrarium، بازی تایپ، افزونه مرورگر، بازی فضایی، اپلیکیشن بانکی، ویرایشگر کد، و دستیار چت هوش مصنوعی
- **آزمون‌های تعاملی**: ۴۸ آزمون با ۳ سوال در هر آزمون (ارزیابی‌های قبل و بعد از درس)
- **پشتیبانی چندزبانه**: ترجمه‌های خودکار به بیش از ۵۰ زبان از طریق GitHub Actions
- **فناوری‌ها**: HTML، CSS، جاوااسکریپت، 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        # 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)

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

## جریان کاری توسعه

### برای مشارکت‌کنندگان محتوا

1. **مخزن را فورک کنید** به حساب GitHub خود
2. **فورک خود را به صورت محلی کلون کنید**
3. **یک شاخه جدید ایجاد کنید** برای تغییرات خود
4. تغییرات را در محتوای درس یا مثال‌های کد اعمال کنید
5. تغییرات کد را در دایرکتوری‌های پروژه مربوطه آزمایش کنید
6. درخواست‌های pull را مطابق با دستورالعمل‌های مشارکت ارسال کنید

### برای یادگیرندگان

1. مخزن را فورک یا کلون کنید
2. به ترتیب به دایرکتوری‌های درس بروید
3. فایل‌های README هر درس را بخوانید
4. آزمون‌های قبل از درس را در https://ff-quizzes.netlify.app/web/ تکمیل کنید
5. مثال‌های کد را در پوشه‌های درس انجام دهید
6. تکالیف و چالش‌ها را کامل کنید
7. آزمون‌های بعد از درس را انجام دهید

### توسعه زنده

- **مستندات**: دستور `docsify serve` را در ریشه اجرا کنید (پورت ۳۰۰۰)
- **اپلیکیشن آزمون**: دستور `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 آزمایش کنید
- اطمینان حاصل کنید که ترجمه‌ها ساختار مناسب را حفظ کرده‌اند

## دستورالعمل‌های سبک کدنویسی

### جاوااسکریپت

- استفاده از سینتکس مدرن 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`
- **جریان کاری**: `.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

### قالب عنوان

از عناوین واضح و توصیفی که ناحیه تغییر را نشان می‌دهند استفاده کنید:
- `[Quiz-app] افزودن آزمون جدید برای درس X`
- `[Lesson-3] اصلاح اشتباه تایپی در پروژه terrarium`
- `[Translation] افزودن ترجمه اسپانیایی برای درس ۵`
- `[Docs] به‌روزرسانی دستورالعمل‌های راه‌اندازی`

### بررسی‌های مورد نیاز

قبل از ارسال PR:

1. **کیفیت کد**:
   - دستور `npm run lint` را در دایرکتوری‌های پروژه‌های تحت تأثیر اجرا کنید
   - تمام خطاها و هشدارهای linting را اصلاح کنید

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 ذکر کنید

### فرآیند بررسی

- PR‌ها توسط نگهدارندگان و جامعه بررسی می‌شوند
- وضوح آموزشی در اولویت است
- مثال‌های کد باید از بهترین شیوه‌های فعلی پیروی کنند
- ترجمه‌ها از نظر دقت و مناسب بودن فرهنگی بررسی می‌شوند

## سیستم ترجمه

### ترجمه خودکار

- از GitHub Actions با جریان کاری co-op-translator استفاده می‌کند
- به طور خودکار به بیش از ۵۰ زبان ترجمه می‌شود
- فایل‌های منبع در دایرکتوری‌های اصلی
- فایل‌های ترجمه شده در دایرکتوری‌های `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 را برای قالب‌بندی سازگار نصب کنید
- از ابزارهای توسعه مرورگر برای اشکال‌زدایی جاوااسکریپت استفاده کنید
- برای پروژه‌های Vue، افزونه Vue DevTools مرورگر را نصب کنید

### ملاحظات عملکرد

- تعداد زیادی فایل ترجمه شده (بیش از ۵۰ زبان) به این معنی است که کلون‌های کامل بزرگ هستند
- اگر فقط روی محتوا کار می‌کنید از کلون سطحی استفاده کنید: `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) برای یادگیرندگان توصیه می‌شود
- دوره‌های اضافی: هوش مصنوعی مولد، علم داده، یادگیری ماشین، برنامه‌های 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` - پروژه دستیار چت هوش مصنوعی

### ساختار Monorepo

اگرچه یک Monorepo سنتی نیست، این مخزن شامل چندین پروژه مستقل است:
- هر درس به صورت خودکفا است
- پروژه‌ها وابستگی‌ها را به اشتراک نمی‌گذارند
- روی پروژه‌های فردی کار کنید بدون اینکه بر دیگران تأثیر بگذارید
- کل مخزن را برای تجربه کامل برنامه آموزشی کلون کنید

---

**سلب مسئولیت**:  
این سند با استفاده از سرویس ترجمه هوش مصنوعی [Co-op Translator](https://github.com/Azure/co-op-translator) ترجمه شده است. در حالی که ما برای دقت تلاش می‌کنیم، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است حاوی خطاها یا نادرستی‌هایی باشند. سند اصلی به زبان اصلی آن باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حیاتی، ترجمه حرفه‌ای انسانی توصیه می‌شود. ما مسئولیتی در قبال هرگونه سوءتفاهم یا تفسیر نادرست ناشی از استفاده از این ترجمه نداریم.