Web-Dev-For-Beginners/translations/fa/AGENTS.md

# AGENTS.md

## مروری بر پروژه

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

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

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

### پروژه چت (بک‌اند پایتون)

```bash
cd 9-chat-project/solution/backend/python
pip install openai
# متغیر محیطی GITHUB_TOKEN را تنظیم کنید
python api.py
```

## روند توسعه

### برای همکاران محتوا

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

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

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

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

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

## راهنمای سبک کد

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

- استفاده از سینتکس مدرن ES6+  
- پیروی از پیکربندی ESLint استاندارد پروژه‌ها  
- استفاده از نام‌های متغیر و توابع معنی‌دار برای درک بهتر آموزشی  
- افزودن کامنت برای توضیح مفاهیم  
- فرمت کردن کد با Prettier در صورت تنظیم شدن  

### HTML/CSS

- استفاده از عناصر معنایی HTML5  
- اصول طراحی واکنشگرا  
- نام‌گذاری واضح برای کلاس‌ها  
- کامنت‌های آموزشی در مورد تکنیک‌های CSS برای یادگیرندگان  

### پایتون

- پیروی از دستورالعمل‌های سبک PEP ۸  
- مثال‌های کد آموزشی و خوانا  
- استفاده از تایپ هینت‌ها در صورت مفید بودن برای آموزش  

### مستندسازی مارک‌داون

- ساختار واضح عنوان‌ها  
- بلاک‌های کد با مشخص کردن زبان  
- لینک به منابع اضافه  
- اسکرین‌شات‌ها و تصاویر در دایرکتوری‌های `images/`  
- متن جایگزین برای تصاویر جهت دسترسی‌پذیری  

### سازماندهی فایل‌ها

- دروس به صورت مرتب شماره‌گذاری شده (۱-getting-started-lessons، ۲-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 در هنگام push به 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 از داکس
```

### مستندات Docsify

```bash
npm install -g docsify-cli    # نصب Docsify به صورت سراسری
docsify serve                 # ارائه در localhost:3000
```

### ساخت‌های اختصاصی پروژه

هر دایرکتوری پروژه ممکن است فرایند ساخت خاص خود را داشته باشد:  
- پروژه‌های Vue: اجرای `npm run build` بسته‌های تولید را ایجاد می‌کند  
- پروژه‌های استاتیک: هیچ قدم ساختی ندارند، مستقیماً فایل‌ها سرو می‌شوند  

## راهنمای درخواست‌های پول (PR)

### فرمت عنوان

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

### چک‌های مورد نیاز

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

1. **کیفیت کد**:  
   - اجرای `npm run lint` در دایرکتوری‌های پروژه مرتبط  
   - رفع تمام خطاها و هشدارهای lint  

2. **تأیید ساخت**:  
   - اجرای `npm run build` در صورت نیاز  
   - اطمینان از عدم وجود خطا در ساخت  

3. **اعتبارسنجی لینک**:  
   - تست تمام لینک‌های مارک‌داون  
   - بررسی صحت ارجاعات به تصاویر  

4. **بازبینی محتوا**:  
   - بازخوانی برای املاء و دستور زبان  
   - اطمینان از صحیح و آموزشی بودن نمونه‌های کد  
   - تأیید صحت مفهوم ترجمه‌ها  

### الزامات مشارکت

- پذیرش 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  
- نگاه به کنسول مرورگر برای خطاها  
- پیروی از دستورالعمل نصب افزونه مرورگر خاص  

**مشکلات پروژه چت پایتون**:  
- اطمینان از نصب پکیج 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 مرورگر برای اشکال‌زدایی جاوااسکریپت  
- برای پروژه‌های Vue، نصب افزونه Vue DevTools در مرورگر  

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

- تعداد زیاد فایل‌های ترجمه شده (بیش از ۵۰ زبان) به معنی کلون‌های حجیم است  
- استفاده از کلون کم‌عمق در صورت کار صرفاً روی محتوا: `git clone --depth 1`  
- هنگام کار روی محتوای انگلیسی، ترجمه‌ها را از جستجوها مستثنی کنید  
- فرایندهای ساخت ممکن است در اجرای اول کند باشند (npm install، ساخت Vite)  

## ملاحظات امنیتی

### متغیرهای محیطی

- کلیدهای API هرگز نباید در مخزن کامیت شوند  
- استفاده از فایل‌های `.env` (که در `.gitignore` موجود است)  
- متغیرهای محیطی مورد نیاز را در README پروژه‌ها مستند کنید  

### پروژه‌های پایتون

- استفاده از محیط‌های مجازی: `python -m venv venv`  
- به‌روزرسانی مرتب وابستگی‌ها  
- توکن‌های GitHub باید حداقل مجوزهای لازم را داشته باشند  

### دسترسی GitHub Models

- توکن‌های دسترسی شخصی (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) پیشنهاد شده برای یادگیرندگان  
- دوره‌های اضافی: AI مولد، علوم داده، یادگیری ماشین، دوره‌های 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  

### ساختار مونو-ریپو

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

---

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