AGENTS.md

1# AGENTS.md
2 
3## مروری بر پروژه
4 
5این مخزن یک برنامه آموزشی برای آموزش مفاهیم پایه توسعه وب به مبتدیان است. این برنامه آموزشی یک دوره جامع ۱۲ هفته‌ای است که توسط مدافعان ابری مایکروسافت توسعه یافته و شامل ۲۴ درس عملی در زمینه JavaScript، CSS و HTML می‌باشد.
6 
7### اجزای کلیدی
8 
9- **محتوای آموزشی**: ۲۴ درس ساختاربندی شده در ماژول‌های مبتنی بر پروژه  
10- **پروژه‌های عملی**: تریاریوم، بازی تایپینگ، افزونه مرورگر، بازی فضا، اپلیکیشن بانکی، ویرایشگر کد و دستیار چت AI  
11- **آزمون‌های تعاملی**: ۴۸ آزمون با ۳ سوال هر کدام (ارزیابی‌های پیش و پس از درس)  
12- **پشتیبانی چندزبانه**: ترجمه‌های خودکار برای بیش از ۵۰ زبان از طریق GitHub Actions  
13- **فناوری‌ها**: HTML، CSS، JavaScript، Vue.js 3، Vite، Node.js، Express، پایتون (برای پروژه‌های 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### پروژه چت (بک‌اند پایتون)
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. **مخزن را فورک کنید** به حساب گیت‌هاب خود  
842. **فورک خود را کلون کنید** به صورت محلی  
853. **یک شاخه جدید بسازید** برای تغییرات خود  
864. تغییرات در محتوای درس یا نمونه‌های کد بدهید  
875. تغییرات کد را در دایرکتوری‌های مرتبط پروژه آزمایش کنید  
886. درخواست‌های پول (Pull Requests) را مطابق با دستورالعمل‌ها ارسال کنید  
89 
90### برای یادگیرندگان
91 
921. مخزن را فورک یا کلون کنید  
932. به ترتیب به دایرکتوری‌های درس بروید  
943. فایل README هر درس را بخوانید  
954. آزمون‌های پیش‌درس را در https://ff-quizzes.netlify.app/web/ کامل کنید  
965. نمونه‌های کد در پوشه‌های درس را اجرا کنید  
976. تمرینات و چالش‌ها را انجام دهید  
987. آزمون‌های پس‌درس را بگیرید  
99 
100### توسعه زنده
101 
102- **مستندات**: دستور `docsify serve` را در ریشه اجرا کنید (پورت ۳۰۰۰)  
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- اعتبارسنجی لینک‌های مارک‌داون  
138- تست نمونه‌های کد در مرورگر یا Node.js  
139- اطمینان از حفظ ساختار صحیح ترجمه‌ها  
140 
141## راهنمای سبک کد
142 
143### جاوااسکریپت
144 
145- استفاده از سینتکس مدرن ES6+  
146- پیروی از پیکربندی ESLint استاندارد پروژه‌ها  
147- استفاده از نام‌های متغیر و توابع معنی‌دار برای درک بهتر آموزشی  
148- افزودن کامنت برای توضیح مفاهیم  
149- فرمت کردن کد با Prettier در صورت تنظیم شدن  
150 
151### HTML/CSS
152 
153- استفاده از عناصر معنایی HTML5  
154- اصول طراحی واکنشگرا  
155- نام‌گذاری واضح برای کلاس‌ها  
156- کامنت‌های آموزشی در مورد تکنیک‌های CSS برای یادگیرندگان  
157 
158### پایتون
159 
160- پیروی از دستورالعمل‌های سبک PEP ۸  
161- مثال‌های کد آموزشی و خوانا  
162- استفاده از تایپ هینت‌ها در صورت مفید بودن برای آموزش  
163 
164### مستندسازی مارک‌داون
165 
166- ساختار واضح عنوان‌ها  
167- بلاک‌های کد با مشخص کردن زبان  
168- لینک به منابع اضافه  
169- اسکرین‌شات‌ها و تصاویر در دایرکتوری‌های `images/`  
170- متن جایگزین برای تصاویر جهت دسترسی‌پذیری  
171 
172### سازماندهی فایل‌ها
173 
174- دروس به صورت مرتب شماره‌گذاری شده (۱-getting-started-lessons، ۲-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 در هنگام push به 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 از داکس
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## راهنمای درخواست‌های پول (PR)
217 
218### فرمت عنوان
219 
220از عناوین واضح و توصیفی استفاده کنید که بخش تغییر را نمایش دهد:  
221- `[Quiz-app] افزودن آزمون جدید برای درس X`  
222- `[Lesson-3] رفع غلط املایی در پروژه تریاریوم`  
223- `[Translation] افزودن ترجمه اسپانیایی برای درس ۵`  
224- `[Docs] به‌روزرسانی دستورالعمل‌های راه‌اندازی`  
225 
226### چک‌های مورد نیاز
227 
228قبل از ارسال PR:  
229 
2301. **کیفیت کد**:  
231   - اجرای `npm run lint` در دایرکتوری‌های پروژه مرتبط  
232   - رفع تمام خطاها و هشدارهای lint  
233 
2342. **تأیید ساخت**:  
235   - اجرای `npm run build` در صورت نیاز  
236   - اطمینان از عدم وجود خطا در ساخت  
237 
2383. **اعتبارسنجی لینک**:  
239   - تست تمام لینک‌های مارک‌داون  
240   - بررسی صحت ارجاعات به تصاویر  
241 
2424. **بازبینی محتوا**:  
243   - بازخوانی برای املاء و دستور زبان  
244   - اطمینان از صحیح و آموزشی بودن نمونه‌های کد  
245   - تأیید صحت مفهوم ترجمه‌ها  
246 
247### الزامات مشارکت
248 
249- پذیرش CLA مایکروسافت (چک خودکار در اولین PR)  
250- پیروی از [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)  
251- مشاهده [CONTRIBUTING.md](./CONTRIBUTING.md) برای دستورالعمل‌های دقیق  
252- ارجاع شماره مسائل در توضیحات PR در صورت کاربرد  
253 
254### روند بازبینی
255 
256- PRها توسط نگهدارندگان و جامعه بررسی می‌شوند  
257- شفافیت آموزشی در اولویت است  
258- نمونه‌های کد باید بهترین روش‌های فعلی را دنبال کنند  
259- ترجمه‌ها برای دقت و سازگاری فرهنگی بررسی می‌شوند  
260 
261## سیستم ترجمه
262 
263### ترجمه خودکار
264 
265- استفاده از GitHub Actions با روند کاری co-op-translator  
266- ترجمه خودکار به بیش از ۵۰ زبان  
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 Models  
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- استفاده از DevTools مرورگر برای اشکال‌زدایی جاوااسکریپت  
326- برای پروژه‌های Vue، نصب افزونه Vue DevTools در مرورگر  
327 
328### ملاحظات عملکرد
329 
330- تعداد زیاد فایل‌های ترجمه شده (بیش از ۵۰ زبان) به معنی کلون‌های حجیم است  
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 Models
350 
351- توکن‌های دسترسی شخصی (PAT) برای GitHub Models مورد نیاز است  
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` - توسعه بازی مبتنی بر Canvas  
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 -->