feat: add chapter 06-frontend-prototype specs
This commit is contained in:
@@ -0,0 +1,81 @@
|
|||||||
|
# مشخصات درس‌نامه: اهداف فصل ششم (Chapter Goals)
|
||||||
|
- **شناسه در سیلابس:** `L6.1`
|
||||||
|
- **فصل:** فصل ۶: آماده‌سازی Prototype (Ch 6)
|
||||||
|
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||||
|
- **زمان تقریبی مطالعه:** ۵ دقیقه
|
||||||
|
- **پیش‌نیازهای مستقیم:** `L5.9` (ایده‌پردازی با AI و پرهیز از AI Slop)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||||
|
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||||
|
- [ ] **درک کند (Understand):** جایگاه محوری فصل ۶ به عنوان نقطه عطف ورود به پیاده‌سازی واقعی و دیدن اولین خروجی زنده و تعاملی در مرورگر چیست.
|
||||||
|
- [ ] **درک کند (Understand):** نقشه راه ۷ درس‌نامه این فصل (از فریم‌ورک Next.js App Router و شادسی‌ان تا کار با داده‌های ماک، مدیریت وضعیت‌ها، واکنش‌گرایی عملی و توسعه چرخشی با ایجنت‌ها) چگونه چیده شده است.
|
||||||
|
- [ ] **تحلیل/ارزیابی کند (Evaluate):** ارزش ساخت یک پروتوتایپ کاربردی بر پایه داده‌های شبیه‌سازی‌شده (Mock Data) پیش از درگیر شدن با پیچیدگی‌های دیتابیس را تحلیل کند.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** محیط پروژه را برای ساخت ساختار فرانت‌اند پروژه محوری (پورتفولیوی پویا با ویترین و داشبورد ادمین) آماده سازد.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||||
|
|
||||||
|
### آنچه باید پوشش داده شود (In-Scope):
|
||||||
|
1. **ورود به فاز سوم نقشه راه دوره: ساخت پروتوتایپ زنده:**
|
||||||
|
* تا این لحظه ایده شفاف شد، PRD و تسک‌ها نوشته شدند، و هویت بصری شکل گرفت؛ اکنون نوبت دست به کد شدن با ایجنت‌های هوش مصنوعی است.
|
||||||
|
2. **مرور سرفصل‌های فصل ۶:**
|
||||||
|
* درس ۶.۲: انتخاب فریم‌ورک مدرن، ساختار معماری Next.js App Router و تایپ‌اسکریپت به زبان ساده.
|
||||||
|
* درس ۶.۳: ورود کامپوننت‌های shadcn/ui به پروژه و ترکیب آن با Tailwind CSS.
|
||||||
|
* درس ۶.۴: پیاده‌سازی ویترین پورتفولیو و کارت‌های پروژه‌ها با داده‌های نمونه (Mock Data).
|
||||||
|
* درس ۶.۵: مدیریت وضعیت‌های چهارگانه UI (اسکلتون لودینگ، خطای بارگذاری، وضعیت خالی بودن پروژه‌ها و پیام‌های موفقیت).
|
||||||
|
* درس ۶.۶: پیاده‌سازی و تست عملی واکنش‌گرایی در اندازه‌های واقعی موبایل و دسکتاپ.
|
||||||
|
* درس ۶.۷: هنر دیباگ و تعامل پیشرفته با ایجنت‌های کدنویسی (Cursor Composer) برای پولیش مرحله‌به‌مرحله فرانت‌اند.
|
||||||
|
3. **پروژه محوری (پورتفولیوی پویا):**
|
||||||
|
* بالا آوردن سرور محلی روی پورت ۳۰۰۰ و مشاهده زنده اولین کارت‌های پروژه در مرورگر.
|
||||||
|
4. **دستورات چندسکویی:**
|
||||||
|
* یادآوری منوهای کشویی جداگانه برای Windows، macOS و Linux در اجرای کامندهای npm و npx.
|
||||||
|
5. **کال‌اوت نکته کوئرا (`<details class="green">`):** دست به ابزار شدن و اجرای واقعی دستورات هم‌گام با مطالعه دروس.
|
||||||
|
|
||||||
|
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||||
|
- اتصال به پایگاه داده واقعی Supabase یا نوشتن کوئری‌های SQL (فصل ۷).
|
||||||
|
- پیاده‌سازی سیستم احراز هویت با بک‌اند واقعی (درس‌های فصل ۷ و ۸).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||||
|
|
||||||
|
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| Interactive Prototype | پروتوتایپ تعاملی | نسخه اولیه و قابل کلیک از نرم‌افزار که ظاهر و رفتار واقعی را شبیه‌سازی می‌کند |
|
||||||
|
| Mock Data | داده‌های شبیه‌سازی‌شده / ماک | اطلاعات تستی ساختگی برای آزمایش رابط کاربری پیش از اتصال به پایگاه داده واقعی |
|
||||||
|
| App Router | اپ روتر | سیستم مسیریابی فایل‌محور نوین در فریم‌ورک Next.js بر پایه پوشه `app/` |
|
||||||
|
| Local Dev Server | سرور توسعه محلی | سرور تستی در کامپیوتر کاربر (معمولاً روی `localhost:3000`) برای مشاهده آنی تغییرات کد |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||||
|
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` قرار گرفته و در قالب جدول تک‌خانه‌ای وسط‌چین با کپشن تفصیلی درج شوند:
|
||||||
|
|
||||||
|
1. **تصویر کاور درس:** `images/cover.png`
|
||||||
|
* **موضوع:** کاور مدرن با تم تیره که کدهای درخشان تایپ‌اسکریپت و لوگوی Next.js را در حال تبدیل شدن به یک وب‌سایت زنده در مرورگر نشان می‌دهد.
|
||||||
|
2. **نقشه راه فصل ۶:** `images/chapter-6-roadmap.png`
|
||||||
|
* **موضوع:** اینفوگرافیک گام‌به‌گام از معماری Next.js $\rightarrow$ کامپوننت‌های shadcn $\rightarrow$ داده‌های ماک $\rightarrow$ وضعیت‌های UI $\rightarrow$ ریسپانسیو عملی $\rightarrow$ توسعه چرخشی با ایجنت.
|
||||||
|
3. **خروجی هدف در پایان فصل ۶:** `images/chapter-6-outcome-preview.png`
|
||||||
|
* **موضوع:** اسکرین‌شات ماکت پورتفولیوی شخصی پویا در حال اجرا روی `localhost:3000` با کارت‌های تعاملی و مودال جزئیات.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||||
|
|
||||||
|
1. **تیتر اصلی:** `# اهداف فصل ششم: آماده‌سازی Prototype زنده و کاربردی`
|
||||||
|
2. **مقدمه کوتاه:** گذر از تئوری‌های دیزاین به لمس اولین دکمه‌ها و کدهای واقعی در مرورگر.
|
||||||
|
3. **جدول کاور درس**
|
||||||
|
4. **سرفصل‌های کلیدی فصل در یک نگاه:** مرور ۷ ایستگاه ساخت فرانت‌اند مدرن.
|
||||||
|
5. **جدول نقشه راه یادگیری فصل**
|
||||||
|
6. **دستورات چندسکویی در خدمت همه:** یادآوری زبانه‌های کشویی ویندوز، مک و لینوکس.
|
||||||
|
7. **کال‌اوت آرامش‌بخش Quera (`<details class="green">`):** ثبت دکمه «خواندم» و آغاز هیجان‌انگیز ساخت پروتوتایپ.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||||
|
- [ ] گذار به فاز ساخت و لمس نتایج زنده در مرورگر با لحن انگیزاننده تبیین شده باشد.
|
||||||
|
- [ ] سرفصل‌های ۷ درس این فصل به همراه خروجی ملموس پورتفولیو مشخص گردند.
|
||||||
|
- [ ] الزام ارائه دستورات چندسکویی با زبانه‌های کشویی یادآوری شود.
|
||||||
@@ -0,0 +1,115 @@
|
|||||||
|
# مشخصات درس‌نامه: معرفی مسیر فرانت‌اند و فریم‌ورک‌ها (Next.js App Router & TypeScript)
|
||||||
|
- **شناسه در سیلابس:** `L6.2`
|
||||||
|
- **فصل:** فصل ۶: آماده‌سازی Prototype (Ch 6)
|
||||||
|
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||||
|
- **زمان تقریبی مطالعه:** ۱۵ دقیقه
|
||||||
|
- **پیش‌نیازهای مستقیم:** `L6.1` (اهداف فصل ششم)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||||
|
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||||
|
- [ ] **درک کند (Understand):** چرا فریم‌ورک Next.js (معماری App Router) به استاندارد بی‌رقیب وب مدرن، به ویژه برای محصولاتی که به سئوی قوی و پنل ادمین تفکیک‌شده نیاز دارند، تبدیل شده است.
|
||||||
|
- [ ] **درک کند (Understand):** تفاوت بنیادین میان کامپوننت‌های سمت سرور (Server Components: پیش‌فرض، پرسرعت، ایده‌آل برای سئو) و کامپوننت‌های سمت کلاینت (Client Components با دستور `'use client'`: تعاملی و دارای وضعیت) چیست.
|
||||||
|
- [ ] **تحلیل/ارزیابی کند (Evaluate):** چرا استفاده از تایپ‌اسکریپت (TypeScript) بهترین دوست و شبکه ایمنی ایجنت‌های هوش مصنوعی برای جلوگیری از باگ‌های نحوی است.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** پروژه Next.js مجهز به TypeScript و Tailwind CSS را با استفاده از دستورات خط فرمان در منوهای کشویی سیستم‌عامل خود (ویندوز، مک، لینوکس) راه‌اندازی کند.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** سرور توسعه محلی (`npm run dev`) را اجرا کرده و صفحه اولیه را در آدرس `http://localhost:3000` در مرورگر بازرسی کند.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||||
|
|
||||||
|
### آنچه باید پوشش داده شود (In-Scope):
|
||||||
|
1. **گذار از صفحات ساده HTML به فریم‌ورک قدرتمند Next.js:**
|
||||||
|
* چرا React به تنهایی برای سئو ضعیف بود و Next.js چگونه با رندرینگ هوشمند مشکل سئو را برای همیشه حل کرد.
|
||||||
|
* سیستم روتینگ فایل‌محور: ساخت هر پوشه مساوی است با ساخت یک صفحه در وب‌سایت!
|
||||||
|
2. **کالبدشکافی دوگانه سرور و کلاینت در App Router:**
|
||||||
|
* **کامپوننت‌های سرور (Server Components):** به طور پیش‌فرض تمام فایل‌ها روی سرور رندر می‌شوند، حجم کد جاوااسکریپت کاربر صفر است و خروجی برای گوگل آماده است.
|
||||||
|
* **کامپوننت‌های کلاینت (`'use client'`):** هر جا کاربر نیاز به کلیک، تایپ در فرم یا باز کردن مودال دارد، عبارت `'use client'` در خط اول فایل قرار می‌گیرد.
|
||||||
|
3. **چرا تایپ‌اسکریپت سوپرپاور هوش مصنوعی است؟**
|
||||||
|
* رفع ترس نوآموزان: تایپ‌اسکریپت زبان جدیدی نیست؛ همان کدهای برنامه با برچسب شفاف نوع داده‌هاست (مثلاً «عنوان باید متن باشد، نه عدد»).
|
||||||
|
* وقتی ایجنت کدی می‌نویسد، کامپایلر تایپ‌اسکریپت با خط قرمز بلافاصله خطاهای پنهان را نشان می‌دهد و به ایجنت دستور اصلاح فوری می‌دهد.
|
||||||
|
4. **ساخت پروژه با خط فرمان (دستورات چندسکویی در ۳ منوی کشویی):**
|
||||||
|
* ساختار پروژه با دستور رسمی:
|
||||||
|
```bash
|
||||||
|
npx create-next-app@latest my-portfolio --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"
|
||||||
|
```
|
||||||
|
* ارائه دستور در منوهای کشویی:
|
||||||
|
* `<details><summary>راهنمای اجرا در ویندوز (Windows PowerShell)</summary> ... </details>`
|
||||||
|
* `<details><summary>راهنمای اجرا در مک‌اواس (macOS Terminal)</summary> ... </details>`
|
||||||
|
* `<details><summary>راهنمای اجرا در لینوکس (Linux Bash)</summary> ... </details>`
|
||||||
|
5. **معماری مسیرهای پروژه محوری (پورتفولیوی پویا):**
|
||||||
|
* `src/app/layout.tsx`: پوسته اصلی کل سایت، تزریق فونت‌های وزیرمتن و اینتر.
|
||||||
|
* `src/app/page.tsx`: صفحه اصلی ویترین پروژه‌ها.
|
||||||
|
* `src/app/admin/layout.tsx`: پوسته اختصاصی پنل مدیریت همراه با سایدبار.
|
||||||
|
* `src/app/admin/page.tsx`: داشبورد مدیریت پروژه‌ها.
|
||||||
|
* `src/app/admin/seo/page.tsx`: صفحه اختصاصی تنظیمات متادیتا و سئو.
|
||||||
|
6. **اجرای سرور محلی و خطایابی پورت:**
|
||||||
|
* اجرای دستور `npm run dev` در ترمینال.
|
||||||
|
* مشاهده صفحه خوش‌آمدگویی روی `http://localhost:3000`.
|
||||||
|
7. **کال‌اوت‌های Quera:**
|
||||||
|
* `<details class="violet">`: تفاوت Server Component با Client Component در دو جمله ساده و ملموس.
|
||||||
|
* `<details class="red">`: رفع خطای متداول «پورت ۳۰۰۰ اشغال است» (`Port 3000 is already in use`)؛ نحوه متوقف کردن ترمینال قبلی با `Ctrl+C`.
|
||||||
|
|
||||||
|
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||||
|
- نصب کامپوننت‌های shadcn/ui (در درس بعدی ۶.۳).
|
||||||
|
- نوشتن کدهای منطقی خواندن داده از دیتابیس (فصل ۷).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||||
|
|
||||||
|
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| Next.js App Router | اپ روتر نکست‌جی‌اس | ساختار مسیریابی فایل‌محور نوین بر پایه پوشه `app/` در نسخه ۱۳ به بالای Next.js |
|
||||||
|
| Server Component | کامپوننت سمت سرور | قطعه‌کدی که در سرور پردازش و به صورت HTML آماده به مرورگر کاربر ارسال می‌شود |
|
||||||
|
| Client Component ('use client') | کامپوننت سمت کلاینت | کامپوننتی که در مرورگر کاربر اجرا می‌شود و امکان تعامل، کلیک و مدیریت وضعیت را دارد |
|
||||||
|
| TypeScript | تایپ‌اسکریپت | لایه اعتبارسنجی روی کدهای جاوااسکریپت برای تعیین نوع داده‌ها و پیشگیری از خطاهای متنی |
|
||||||
|
| File-Based Routing | مسیریابی فایل‌محور | روشی که در آن ساختار پوشه‌ها و فایل‌های دایرکتوری، آدرس‌های وب‌سایت را تعیین می‌کند |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||||
|
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` قرار گرفته و در قالب جدول تک‌خانه‌ای وسط‌چین با کپشن تفصیلی درج شوند:
|
||||||
|
|
||||||
|
1. **تصویر کاور درس:** `images/cover.png`
|
||||||
|
* **موضوع:** کاور مدرن با تم تیره که نشان Next.js و لوگوی تایپ‌اسکریپت را در حال سازماندهی پوشه‌ها و مسیرهای وب‌سایت نشان می‌دهد.
|
||||||
|
2. **درخت پوشه‌بندی و مسیرهای پروژه پورتفولیو:** `images/portfolio-route-architecture.png`
|
||||||
|
* **موضوع:** دیاگرام ساختار درختی: `src/app/` شامل `page.tsx` (عمومی)، `layout.tsx` (اصلی)، و شاخه `admin/` شامل `layout.tsx`، `page.tsx` و `seo/page.tsx`.
|
||||||
|
3. **تفاوت کامپوننت سرور و کلاینت در یک نگاه:** `images/server-vs-client-diagram.png`
|
||||||
|
* **موضوع:** اینفوگرافیک مقایسه‌ای: ستون آبی سرور (سئو عالی، سریع، بدون JS کلاینت) در برابر ستون سبز کلاینت (`'use client'` برای کلیک، فرم و انیمیشن).
|
||||||
|
4. **خط قرمز تایپ‌اسکریپت به عنوان شبکه ایمنی:** `images/typescript-error-safety.png`
|
||||||
|
* **موضوع:** اسکرین‌شات از ادیتور Cursor که خط قرمز زیر یک متغیر تایپ‌اسکریپت را نشان داده و هوش مصنوعی بلافاصله آن را تصحیح می‌کند.
|
||||||
|
5. **خروجی نخستین اجرای سرور روی localhost:** `images/localhost-initial-screen.png`
|
||||||
|
* **موضوع:** اسکرین‌شات تمیز از ترمینال موفق `Ready in 1500ms` و تب مرورگر بازشده روی پورت ۳۰۰۰.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||||
|
|
||||||
|
1. **تیتر اصلی:** `# معرفی مسیر فرانت‌اند و فریم‌ورک‌ها: چرا Next.js انتخاب نهایی ماست؟`
|
||||||
|
2. **مقدمه:** چرا غول‌های وب جهان و استارتاپ‌های پیشرو به جای وب‌سایت‌های قدیمی به فریم‌ورک Next.js کوچ کرده‌اند؟
|
||||||
|
3. **جدول کاور درس**
|
||||||
|
4. **انقلاب App Router و مسیریابی فایل‌محور:** هر پوشه یک آدرس در اینترنت.
|
||||||
|
5. **دوگانگی سرور و کلاینت: هنر ترکیب سرعت با تعامل:**
|
||||||
|
* قدرت Server Components در سئو و لودینگ برق‌آسا.
|
||||||
|
* کلیدواژه طلایی `'use client'` برای فرم‌ها و دکمه‌ها.
|
||||||
|
6. **باکس نکته Quera (`<details class="violet">`):** تمایز ساده سرور و کلاینت در قالب دو تعریف روشن.
|
||||||
|
7. **تایپ‌اسکریپت: کمربند ایمنی وایب کدرها در برابر باگ‌ها:** چرا ادیتورهای هوشمند با تایپ‌اسکریپت بهتر کار می‌کنند؟
|
||||||
|
8. **ساخت گام‌به‌گام اسکلت پروژه با خط فرمان:**
|
||||||
|
* دستور استاندارد `create-next-app`.
|
||||||
|
* منوی کشویی ویندوز (Windows).
|
||||||
|
* منوی کشویی مک‌اواس (macOS).
|
||||||
|
* منوی کشویی لینوکس (Linux).
|
||||||
|
9. **نقشه معماری مسیرهای پورتفولیوی پویا:** تفکیک ویترین عمومی از پیشخوان ادمین و پنل سئو.
|
||||||
|
10. **اجرای سرور محلی (`npm run dev`) و مشاهده اولین خروجی:** بازرسی صفحه در `localhost:3000`.
|
||||||
|
11. **باکس رفع خطای Quera (`<details class="red">`):** حل مشکل پر بودن پورت ۳۰۰۰.
|
||||||
|
12. **جمع‌بندی درس‌نامه:** بالا آمدن اسکلت زنده پروژه و آماده شدن برای تجهیز کامپوننت‌های شادسی‌ان در درس بعد.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||||
|
- [ ] مزایای معماری Next.js App Router و نقش آن در سئو و ساختار پنل‌ها تبیین شده باشد.
|
||||||
|
- [ ] تفاوت سرور کامپوننت و کلاینت کامپوننت به شکلی قابل درک برای نوآموزان آموزش داده شود.
|
||||||
|
- [ ] دستور راه‌اندازی پروژه برای سه سیستم‌عامل در منوهای کشویی مجزا درج گردد.
|
||||||
|
- [ ] نقشه مسیرهای پروژه محوری (صفحه اصلی و زیرشاخه‌های ادمین) به دقت تصویرسازی شود.
|
||||||
@@ -0,0 +1,114 @@
|
|||||||
|
# مشخصات درس‌نامه: کامپوننت‌ها و کتابخانه‌های فرانت‌اند (shadcn/ui & Modern UI Libraries)
|
||||||
|
- **شناسه در سیلابس:** `L6.3`
|
||||||
|
- **فصل:** فصل ۶: آماده‌سازی Prototype (Ch 6)
|
||||||
|
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||||
|
- **زمان تقریبی مطالعه:** ۱۵ دقیقه
|
||||||
|
- **پیش‌نیازهای مستقیم:** `L6.2` (معرفی مسیر فرانت‌اند و فریم‌ورک‌ها)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||||
|
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||||
|
- [ ] **درک کند (Understand):** چرا مجموعه کامپوننت‌های **shadcn/ui** به محبوب‌ترین استاندارد توسعه وب در عصر ایجنت‌های هوش مصنوعی تبدیل شده است و چه تفاوتی با کتابخانه‌های سنتی مانند Material UI دارد.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** دستور اولیه `npx shadcn@latest init` را با منوهای کشویی سیستم‌عامل‌های ویندوز، مک و لینوکس با موفقیت اجرا کند.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** بسته کامپوننت‌های ضروری پروژه محوری (دکمه `button`، کارت `card`، دیالوگ/مودال `dialog`، برچسب `badge`، اینپوت‌ها `input`, `textarea`، تب‌ها `tabs` و اعلان‌ها `toast`) را در پوشه `src/components/ui/` نصب و فعال سازد.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** پکیج آیکون‌های رسمی **Lucide React** را نصب کرده و آن را در داخل کامپوننت‌های نصب‌شده شادسی‌ان به کار گیرد.
|
||||||
|
- [ ] **تحلیل/ارزیابی کند (Evaluate):** چرا داشتن سورس‌کد خام کامپوننت‌ها در داخل پروژه (برخلاف پکیج‌های سربسته npm) به ایجنت هوش مصنوعی اجازه می‌دهد بدون محدودیت کدهای استایل را سفارشی‌سازی کند.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||||
|
|
||||||
|
### آنچه باید پوشش داده شود (In-Scope):
|
||||||
|
1. **انقلاب shadcn/ui در ساختار کتابخانه‌های فرانت‌اند:**
|
||||||
|
* در کتابخانه‌های قدیمی (مثل Material UI یا Ant Design)، شما یک پکیج حجیم نصب می‌کردید و اگر می‌خواستید رنگ یا انیمیشن یک دکمه را عوض کنید با صدها خط کد اورراید کلافه می‌شدید.
|
||||||
|
* در معماری shadcn/ui، زیرساخت دسترسی‌پذیر Radix UI با استایل‌های شیک Tailwind ترکیب شده و فایل خام کامپوننت مستقیماً در پوشه `components/ui/` پروژه شما قرار می‌گیرد.
|
||||||
|
2. **پیکربندی اولیه shadcn/ui با خط فرمان (منوهای کشویی سیستم‌عامل‌ها):**
|
||||||
|
* دستور رسمی آغازین:
|
||||||
|
```bash
|
||||||
|
npx shadcn@latest init
|
||||||
|
```
|
||||||
|
* انتخاب تنظیمات بهینه (تم رنگی Zinc یا Slate، فعال بودن CSS Variables، استایل New York).
|
||||||
|
* منوهای کشویی جداگانه برای Windows، macOS و Linux.
|
||||||
|
3. **نصب جعبه‌ابزار کامپوننت‌های پروژه محوری (پورتفولیوی پویا):**
|
||||||
|
* نصب کامپوننت‌ها در یک خط دستور:
|
||||||
|
```bash
|
||||||
|
npx shadcn@latest add button card dialog input textarea badge tabs toast
|
||||||
|
```
|
||||||
|
* تشریح نقش هر جزء در محصول:
|
||||||
|
* `button`: برای دکمه‌های CTA، فیلترها و دکمه‌های اکشن ادمین.
|
||||||
|
* `card`: برای نمایش پروژه‌های ویترین عمومی با استایل کادر شیشه‌ای.
|
||||||
|
* `dialog`: برای باز کردن پنجره مودال نمایش جزئیات پروژه و تایید حذف.
|
||||||
|
* `badge`: برای نمایش چیپ‌های تگ‌های مهارت (Next.js, Tailwind, Supabase).
|
||||||
|
* `input` و `textarea`: فیلدهای ورود اطلاعات پروژه و تنظیمات عنوان و دیسکریپشن سئو.
|
||||||
|
* `tabs`: تفکیک تب‌های مدیریت پروژه‌ها و پنل اختصاصی سئو در داشبورد ادمین.
|
||||||
|
4. **نصب پکیج آیکون‌های Lucide React:**
|
||||||
|
* دستور `npm install lucide-react` و نحوه فراخوانی آیکون‌ها درون دکمه‌ها و کارت‌ها.
|
||||||
|
5. **مقایسه تحلیلی با Material UI:**
|
||||||
|
* متریال یو‌آی کجاست که هنوز استفاده می‌شود؟ (پنل‌های شرکتی قدیمی).
|
||||||
|
* چرا shadcn/ui انتخاب اول وایب کدرهاست؟ (سازگاری کامل با مدل‌های زبانی به دلیل خوانا بودن فایل‌های باز کامپوننت).
|
||||||
|
6. **کال‌اوت‌های Quera:**
|
||||||
|
* `<details class="violet">`: راز پوشه `components/ui/`؛ کدهایی که به شما تعلق دارند و هوش مصنوعی هر زمان بخواهد می‌تواند آن‌ها را ارتقا دهد.
|
||||||
|
* `<details class="green">`: میانبر طلایی ترمینال؛ اضافه کردن همزمان چندین کامپوننت شادسی‌ان با یک دستور واحد.
|
||||||
|
|
||||||
|
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||||
|
- پر کردن کامپوننت‌ها با دیتابیس آنلاین (در درس بعدی ۶.۴ ابتدا با Mock Data کار می‌کنیم).
|
||||||
|
- کدنویسی اعتبارسنجی پیشرفته فرم‌ها با کتابخانه‌های فرم سنگین (درس‌های بعدی).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||||
|
|
||||||
|
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| shadcn/ui | شادسی‌ان یو‌آی | الگوی نوین کامپوننت‌های فرانت‌اند که کدهای قابل ویرایش را در پروژه کپی می‌کند |
|
||||||
|
| Radix UI Primitives | قطعات اولیه رادیکس | ساختار بنیادی بدون استایل اما ۱۰۰٪ استاندارد از نظر دسترسی‌پذیری و کار با کیبورد |
|
||||||
|
| Headless Components | کامپوننت‌های بدون استایل | اجزایی که فقط منطق عملکرد را دارند و طراحی ظاهری را به کلاس‌های Tailwind می‌سپارند |
|
||||||
|
| CLI Component Add | افزودن کامپوننت با ترمینال | دانلود و قرارگیری خودکار فایل تایپ‌اسکریپت هر کامپوننت در پوشه محلی پروژه |
|
||||||
|
| Lucide React | کتابخانه آیکون‌های لوسید | بسته رسمی ری‌اکت برای رندر آیکون‌های سبک برداری SVG در اجزای وب |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||||
|
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` قرار گرفته و در قالب جدول تک‌خانه‌ای وسط‌چین با کپشن تفصیلی درج شوند:
|
||||||
|
|
||||||
|
1. **تصویر کاور درس:** `images/cover.png`
|
||||||
|
* **موضوع:** کاور مدرن با تم تیره و لوگوی شیک shadcn/ui که جعبه‌ابزار کامپوننت‌های دکمه، مودال، تگ و کارت را به صورت شناور سه‌بعدی نمایش می‌دهد.
|
||||||
|
2. **معماری سه‌لایه کامپوننت‌های shadcn/ui:** `images/shadcn-architecture-layers.png`
|
||||||
|
* **موضوع:** دیاگرام ساختار: لایه اول منطق رادیکس (Radix) $\rightarrow$ لایه دوم استایل تیلویند (Tailwind) $\rightarrow$ لایه سوم پوشه محلی `src/components/ui/`.
|
||||||
|
3. **ترمینال نصب موفق کامپوننت‌ها:** `images/shadcn-terminal-add-success.png`
|
||||||
|
* **موضوع:** اسکرین‌شات تمیز از اجرای دستور `npx shadcn add` در ترمینال با تیک‌های سبز ایجاد فایل‌ها.
|
||||||
|
4. **ویترین کامپوننت‌های نصب‌شده پورتفولیو:** `images/portfolio-installed-components.png`
|
||||||
|
* **موضوع:** تصویر کادر مرتب المان‌های نصب‌شده (دکمه‌های تیره، چیپ‌های مهارت، کارت پروژه و پنجره دیالوگ) با تم شیک و نئونی.
|
||||||
|
5. **مقایسه shadcn/ui در برابر Material UI:** `images/shadcn-vs-material-ui.png`
|
||||||
|
* **موضوع:** جدول مقایسه‌ای: سرعت بارگذاری، حجم باندل، سهولت دستکاری با هوش مصنوعی و انعطاف‌پذیری طراحی.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||||
|
|
||||||
|
1. **تیتر اصلی:** `# کامپوننت‌ها و کتابخانه‌های فرانت‌اند: تجهیز سلاح‌های مدرن با shadcn/ui`
|
||||||
|
2. **مقدمه:** چرا کپی کردن کدهای خام کامپوننت در پروژه، انقلابی‌ترین ایده طراحی در سال‌های اخیر بود؟
|
||||||
|
3. **جدول کاور درس**
|
||||||
|
4. **فلسفه بنیادین shadcn/ui: مالکیت کامل بر کدهای رابط کاربری:**
|
||||||
|
* خداحافظی با پکیج‌های سربسته و قفل‌شده.
|
||||||
|
* ترکیب جادویی منطق Radix با آزادی عمل Tailwind.
|
||||||
|
5. **راه‌اندازی گام‌به‌گام با دستور `npx shadcn@latest init`:**
|
||||||
|
* انتخاب پالت Zinc و استایل مدرن New York.
|
||||||
|
* منوهای کشویی سیستم‌عامل‌ها (Windows, macOS, Linux).
|
||||||
|
6. **دانلود و نصب جعبه‌ابزار اختصاصی پورتفولیوی پویا:**
|
||||||
|
* دکمه، کارت، مودال، اینپوت، تکست‌اریا، بج و تب‌ها.
|
||||||
|
* دستور چندسکویی یک‌خطی نصب تمام اجزا.
|
||||||
|
7. **نصب و تزریق آیکون‌های Lucide React:** افزودن آیکون‌های تعاملی به کامپوننت‌ها.
|
||||||
|
8. **باکس نکته Quera (`<details class="violet">`):** چرا ایجنت‌های کدنویسی عاشق پوشه `components/ui/` هستند؟
|
||||||
|
9. **مقایسه با کتابخانه‌های کلاسیک (Material UI و Ant Design):** چرا سبک جدید سریع‌تر و مدرن‌تر است؟
|
||||||
|
10. **باکس میانبر Quera (`<details class="green">`):** مدیریت و اضافه کردن آسان کامپوننت‌های آینده.
|
||||||
|
11. **جمع‌بندی درس‌نامه:** مجهز شدن پروژه به تمام قطعات ظاهری و ورود به مرحله تزریق داده‌های تستی (Mock Data).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||||
|
- [ ] معماری نوین shadcn/ui و مزیت حضور فایل‌ها در پوشه محلی به دقت تحلیل شده باشد.
|
||||||
|
- [ ] دستورات نصب init و add برای سه سیستم‌عامل در منوهای کشویی جداگانه قرار گیرد.
|
||||||
|
- [ ] نقش هریک از کامپوننت‌های نصب‌شده در پورتفولیوی پویا تشریح شده باشد.
|
||||||
|
- [ ] نصب و نحوه کار با Lucide Icons همراه با مثال عملی در متن گنجانده شود.
|
||||||
@@ -0,0 +1,116 @@
|
|||||||
|
# مشخصات درس‌نامه: طراحی رابط کاربری با Mock Data (UI Prototyping with Mock Data)
|
||||||
|
- **شناسه در سیلابس:** `L6.4`
|
||||||
|
- **فصل:** فصل ۶: آماده‌سازی Prototype (Ch 6)
|
||||||
|
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||||
|
- **زمان تقریبی مطالعه:** ۱۵ دقیقه
|
||||||
|
- **پیش‌نیازهای مستقیم:** `L6.3` (کامپوننت‌ها و کتابخانه‌های فرانت‌اند)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||||
|
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||||
|
- [ ] **درک کند (Understand):** چرا توسعه فرانت‌اند با داده‌های شبیه‌سازی‌شده (Mock Data) پیش از اتصال به دیتابیس، سرعت چرخه بازخورد را چند برابر کرده و وابستگی‌ها را به صفر می‌رساند.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** تایپ‌ها و اینترفیس‌های مدل داده تایپ‌اسکریپت (`Project` و `SiteSettings`) را به عنوان قرارداد ساختار داده‌ها در پوشه `types/` تعریف کند.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** فایل داده‌های تستی واقع‌بینانه (`mock-portfolio.ts`) را با ۴ تا ۶ نمونه‌کار جذاب و متنوع ایجاد کند.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** کامپوننت‌های رندرکننده ویترین عمومی شامل: **کارت پروژه (`ProjectCard`)، گرید ریسپانسیو (`ProjectsGrid`)، پنجره مودال جزئیات (`ProjectDetailModal`)، و بخش هدر (`HeroSection`)** را با کامپوننت‌های شادسی‌ان پیاده‌سازی کند.
|
||||||
|
- [ ] **تحلیل/ارزیابی کند (Evaluate):** اهمیت قرار دادن داده‌های با طول نامتقارن (یک عنوان بسیار طولانی در برابر عنوان کوتاه) را برای سنجش استحکام چیدمان ارزیابی کند.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||||
|
|
||||||
|
### آنچه باید پوشش داده شود (In-Scope):
|
||||||
|
1. **فلسفه کار با داده‌های شبیه‌سازی‌شده (Mock Data):**
|
||||||
|
* چرا نباید ساخت ظاهر سایت را به تکمیل پایگاه داده و بک‌اند گره زد؟
|
||||||
|
* با داده‌های ماک، می‌توانید در چند دقیقه کل ظاهر و رفتار کلیک‌ها را در مرورگر تست کنید و اگر نیازی به تغییر چیدمان بود، بدون درگیر شدن با تغییر جداول دیتابیس آن را اصلاح نمایید.
|
||||||
|
2. **تعریف ساختار داده‌ها با TypeScript Interfaces:**
|
||||||
|
* ساخت اینترفیس `Project`:
|
||||||
|
* `id`: شناسه یکتا
|
||||||
|
* `title`: عنوان پروژه
|
||||||
|
* `description`: توضیح کوتاه کارت
|
||||||
|
* `longDescription`: توضیحات کامل برای مودال
|
||||||
|
* `imageUrl`: آدرس تصویر کاور پروژه
|
||||||
|
* `tags`: آرایه‌ای از رشته‌ها برای تکنولوژی‌ها (مانند `['Next.js', 'Tailwind', 'AI']`)
|
||||||
|
* `liveUrl`: آدرس دموی اینترنتی
|
||||||
|
* `githubUrl`: آدرس مخزن کد
|
||||||
|
* `featured`: بولین اولویت نمایش
|
||||||
|
* ساخت اینترفیس `SiteSettings` (برای هدر و متادیتای سئو).
|
||||||
|
3. **تولید فایل داده‌های نمونه (`src/data/mock-portfolio.ts`):**
|
||||||
|
* ایجاد ۶ پروژه واقعی و جذاب:
|
||||||
|
۱. دستیار هوشمند مدیریت عادات روزانه (AI Habit Tracker)
|
||||||
|
۲. پلتفرم داشبورد تحلیل داده‌های تجارت الکترونیک
|
||||||
|
۳. سیستم بوک‌مارک و خلاصه‌ساز مقالات با هوش مصنوعی
|
||||||
|
۴. اپلیکیشن موبایل ثبت هزینه‌ها
|
||||||
|
۵. کیت رابط کاربری وب‌سایت‌های ساس (SaaS Kit)
|
||||||
|
۶. ربات خودکار پردازش اسناد پی‌دی‌اف
|
||||||
|
4. **ساخت کامپوننت‌های ویترین عمومی پورتفولیو:**
|
||||||
|
* کامپوننت `HeroSection.tsx`: نمایش آواتار، نام، بیوگرافی و دکمه‌های اقدام.
|
||||||
|
* کامپوننت `ProjectCard.tsx`: استفاده از کارت شادسی‌ان، نمایش تصویر، بج‌های مهارت و دکمه باز کردن جزئیات.
|
||||||
|
* کامپوننت `ProjectsGrid.tsx`: چیدمان کارت‌ها در گرید مدرن ۳ ستونه با کلاس‌های واکنش‌گرا.
|
||||||
|
* کامپوننت `ProjectDetailModal.tsx`: باز شدن پنجره دیالوگ با کلیک روی کارت و نمایش تصویر بزرگ و دکمه‌های دمو.
|
||||||
|
5. **شبیه‌سازی تعاملی فیلتر دسته‌بندی با `useState`:**
|
||||||
|
* ایجاد یک ردیف دکمه برای فیلتر کردن کارت‌ها بر اساس تگ انتخابی (همه، هوش مصنوعی، فرانت‌اند، ابزارها) به صورت کامپوننت کلاینت.
|
||||||
|
6. **کال‌اوت‌های Quera:**
|
||||||
|
* `<details class="violet">`: چرا تفکیک رابط کاربری از دیتابیس سرعت پیشرفت پروژه را در متدولوژی وایب کدینگ ۵ برابر می‌کند؟
|
||||||
|
* `<details class="red">`: تله «داده‌های بیش از حد ایده‌آل»؛ در داده‌های تستی حتماً یک عنوان بسیار طولانی بگذارید تا مطمئن شوید کادرها در صورت طولانی شدن متن نمی‌شکنند.
|
||||||
|
|
||||||
|
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||||
|
- فراخوانی API از سرور با `fetch` یا اتصال به جدول دیتابیس واقعی (فصل ۷).
|
||||||
|
- پیاده‌سازی صفحه لاگین با منطق رمزنگاری (فصل ۷ و ۸).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||||
|
|
||||||
|
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| Mock Data | داده‌های ماک / نمونه | اطلاعات مصنوعی واقع‌گرایانه برای شبیه‌سازی محتوای دیتابیس در فرانت‌اند |
|
||||||
|
| TypeScript Interface | اینترفیس تایپ‌اسکریپت | ساختار و قراردادی که شکل، اسامی و نوع فیلدهای یک شیء داده را معین می‌کند |
|
||||||
|
| Props Drilling / Passing | پاس دادن ورودی‌ها | فرستادن اطلاعات از کامپوننت والد (مانند گرید) به کامپوننت فرزند (مانند کارت) |
|
||||||
|
| Dialog / Modal | دیالوگ / پنجره مودال | کادر شناوری که روی صفحه باز می‌شود و تمرکز کاربر را به محتوای خاصی جلب می‌کند |
|
||||||
|
| Client-Side Filtering | فیلتر سمت کلاینت | پردازش و فیلتر کردن فوری لیست داده‌ها در مرورگر بدون ارسال درخواست به سرور |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||||
|
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` قرار گرفته و در قالب جدول تک‌خانه‌ای وسط‌چین با کپشن تفصیلی درج شوند:
|
||||||
|
|
||||||
|
1. **تصویر کاور درس:** `images/cover.png`
|
||||||
|
* **موضوع:** کاور مدرن با تم تیره که فایل داده‌های متنی `mock-portfolio.ts` را در حال تزریق نورانی به کارت‌های سه‌بعدی شیک پورتفولیو در صفحه نشان می‌دهد.
|
||||||
|
2. **جریان حرکت داده‌های ماک در کامپوننت‌ها:** `images/mock-data-flow-diagram.png`
|
||||||
|
* **موضوع:** اینفوگرافیک معماری: اینترفیس TypeScript $\rightarrow$ آرایه داده‌های ماک $\rightarrow$ کامپوننت والد ProjectsGrid $\rightarrow$ کارت‌های فرزند ProjectCard.
|
||||||
|
3. **خروجی زنده گرید پروژه‌ها در مرورگر:** `images/rendered-projects-grid.png`
|
||||||
|
* **موضوع:** اسکرین‌شات تمیز از اجرای پروژه روی `localhost:3000` با نمایش ۶ کارت شیک، بج‌های رنگی و تصاویر جذاب.
|
||||||
|
4. **پنجره مودال جزئیات پروژه در حالت باز:** `images/project-detail-dialog.png`
|
||||||
|
* **موضوع:** اسکرین‌شات از دیالوگ شادسی‌ان بازشده روی صفحه با پس‌زمینه تیره محوشده و دکمه‌های دمو و گیت‌هاب.
|
||||||
|
5. **تست فیلتر کارت‌ها در عمل:** `images/category-filter-demo.png`
|
||||||
|
* **موضوع:** نمایش فیلتر شدن سریع کارت‌ها با کلیک روی تب مهارت Next.js در ویترین.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||||
|
|
||||||
|
1. **تیتر اصلی:** `# طراحی رابط کاربری با Mock Data: دمیدن زندگی اولیه بدون دیتابیس`
|
||||||
|
2. **مقدمه:** چرا مهندسان ارشد پیش از ساخت دیتابیس، ظاهر نرم‌افزار را با داده‌های تستی کامل می‌کنند؟
|
||||||
|
3. **جدول کاور درس**
|
||||||
|
4. **قرارداد داده‌ها: تعریف اینترفیس‌های TypeScript:**
|
||||||
|
* اینترفیس پروژه (`Project`).
|
||||||
|
* اینترفیس تنظیمات پورتفولیو (`SiteSettings`).
|
||||||
|
5. **ساخت فایل داده‌های نمونه (`mock-portfolio.ts`):** ایجاد ۶ نمونه‌کار الهام‌بخش با تصاویر استاندارد.
|
||||||
|
6. **باکس نکته Quera (`<details class="violet">`):** سرعت و استقلال توسعه با داده‌های شبیه‌سازی‌شده.
|
||||||
|
7. **ساخت کامپوننت کارت پروژه (`ProjectCard.tsx`):**
|
||||||
|
* ترکیب کامپوننت Card شادسی‌ان با بج‌ها و آیکون‌های Lucide.
|
||||||
|
8. **ساخت گرید ریسپانسیو و مودال جزئیات:**
|
||||||
|
* چیدمان ۳ ستونه با CSS Grid.
|
||||||
|
* تعامل باز شدن پنجره دیالوگ شادسی‌ان.
|
||||||
|
9. **هدر اصلی سایت و پیاده‌سازی فیلتر تعاملی دسته‌بندی:** آزمایش تعاملات بدون نیاز به سرور.
|
||||||
|
10. **باکس هشدار Quera (`<details class="red">`):** آزمون لبه‌ها؛ تست کارت‌ها با عنوان‌های بسیار طولانی.
|
||||||
|
11. **جمع‌بندی درس‌نامه:** مشاهده اولین نسخه زنده و تماشایی پورتفولیو و آمادگی برای مدیریت وضعیت‌های UI در درس بعد.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||||
|
- [ ] فلسفه Mock Data و مزیت استقلال فرانت‌اند از بک‌اند به درستی تبیین شده باشد.
|
||||||
|
- [ ] ساختار اینترفیس‌های تایپ‌اسکریپت برای پروژه محوری مستند گردد.
|
||||||
|
- [ ] نحوه پیاده‌سازی کامپوننت‌های کارت، گرید و مودال جزئیات شرح داده شود.
|
||||||
|
- [ ] نمونه‌های داده تستی ملموس و متنوع در ساختار درس لحاظ شده باشند.
|
||||||
@@ -0,0 +1,101 @@
|
|||||||
|
# مشخصات درس‌نامه: مدیریت وضعیت‌های مختلف UI (UI State Management)
|
||||||
|
- **شناسه در سیلابس:** `L6.5` (`L6.6` در شیت)
|
||||||
|
- **فصل:** فصل ۶: آماده‌سازی Prototype (Ch 6)
|
||||||
|
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||||
|
- **زمان تقریبی مطالعه:** ۱۲ دقیقه
|
||||||
|
- **پیش‌نیازهای مستقیم:** `L6.4` (طراحی رابط کاربری با Mock Data)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||||
|
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||||
|
- [ ] **درک کند (Understand):** تله «مسیر ایده‌آل (Happy Path)» چیست و چرا طراحی نرم‌افزار حرفه‌ای بیش از هر چیز در مدیریت شرایط غیرمنتظره (لودینگ، خطای شبکه، و داده‌های خالی) نهفته است.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** کامپوننت‌های اسکلتون لودر (Skeleton Screen) با پویانمایی پالس نرم (`animate-pulse`) را برای کارت‌های پروژه پیاده کند تا مانع از پرش ناگهانی چیدمان (Layout Shift) شود.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** وضعیت داده‌های خالی (Empty State) را با پیام فارسی صمیمانه، آیکون مناسب و دکمه بازنشانی فیلتر طراحی کند.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** کامپوننت وضعیت خطا (Error State) همراه با دکمه تلاش مجدد (Retry) را به گونه‌ای بسازد که در صورت بروز هرگونه مشکل، مانع از کرش و سفیدی کل صفحه شود.
|
||||||
|
- [ ] **درک کند (Understand):** فایل‌های قراردادی و خودکار فریم‌ورک Next.js یعنی `loading.tsx` و `error.tsx` چگونه به صورت پیش‌فرض وضعیت‌های صفحه را مدیریت می‌کنند.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||||
|
|
||||||
|
### آنچه باید پوشش داده شود (In-Scope):
|
||||||
|
1. **تلهٔ مسیر ایده‌آل (The Happy Path Fallacy):**
|
||||||
|
* برنامه‌نویسان مبتدی و ایجنت‌های تنبل همیشه فرض می‌کنند اینترنت پرسرعت است، داده‌ها همیشه موجودند و هیچ خطایی رخ نمی‌دهد!
|
||||||
|
* در دنیای واقعی: اینترنت قطع‌ووصلی دارد، سرور ممکن است ۲ ثانیه معطل کند، و ممکن است فیلتر انتخابی هیچ نتیجه‌ای نداشته باشد.
|
||||||
|
2. **وضعیت اول: بارگذاری پیشرفته با اسکلتون (Skeleton Loading):**
|
||||||
|
* چرا لودرهای چرخشی قدیمی (Spinners) خسته‌کننده هستند و باعث پرش محتوا می‌شوند؟
|
||||||
|
* اسکلتون لودر: کشیدن ماکت خاکستری و ضربان‌دار با ابعاد دقیق کارت واقعی (`ProjectCardSkeleton.tsx`) که به کاربر نشان می‌دهد محتوا دقیقاً در کجای صفحه قرار خواهد گرفت.
|
||||||
|
3. **وضعیت دوم: داده‌های تهی و خالی (Empty State):**
|
||||||
|
* سناریو: کاربر روی فیلتر «هوش مصنوعی» کلیک می‌کند در حالی که هنوز پروژه‌ای با این تگ ثبت نشده است، یا صاحب پورتفولیو تازه ثبت‌نام کرده و هنوز پروژه‌ای نساخته است.
|
||||||
|
* طراحی باکس Empty State: آیکون پوشه خالی یا ذره‌بین، متن راهنما («هنوز پروژه‌ای در این دسته ثبت نشده است»)، و دکمه اکشن («پاک کردن فیلترها» یا «افزودن اولین پروژه»).
|
||||||
|
4. **وضعیت سوم: مدیریت متمدنانه خطاها (Error State):**
|
||||||
|
* پرهیز از صفحه سفید مرگ (White Screen of Death) یا نمایش متن‌های نامفهوم انگلیسی برنامه.
|
||||||
|
* باکس خطای کاربری: پیام شفاف فارسی («بارگذاری پروژه‌ها با خطا مواجه شد») همراه با دکمه «تلاش مجدد».
|
||||||
|
5. **قراردادهای جادویی Next.js (`loading.tsx` و `error.tsx`):**
|
||||||
|
* نحوه ساخت فایل `loading.tsx` در پوشه روت که Next.js به طور خودکار در زمان دریافت داده‌ها آن را نمایش می‌دهد.
|
||||||
|
* نحوه ساخت فایل `error.tsx` با قابلیت بازنشانی (`reset()`).
|
||||||
|
6. **کال‌اوت‌های Quera:**
|
||||||
|
* `<details class="violet">`: چرا اسکلتون لودرها در غول‌های فناوری نظیر یوتیوب، فیس‌بوک و لینکدین جایگزین تمام اسپینرهای چرخان شده‌اند؟
|
||||||
|
* `<details class="red">`: تله رها کردن صفحه در وضعیت خنثی؛ هرگز کاربر را در حین لودینگ یا خطا بدون هیچ پیام و بازخوردی در برزخ رها نکنید.
|
||||||
|
|
||||||
|
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||||
|
- کتابخانه‌های مدیریت وضعیت گلوبال سنگین مانند Redux یا Zustand (در فصل‌های آینده در صورت نیاز بررسی خواهد شد).
|
||||||
|
- راه‌اندازی مانیتورینگ خودکار خطاها نظیر Sentry (فصل ۱۳).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||||
|
|
||||||
|
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| Happy Path | مسیر ایده‌آل / خوش‌بینانه | سناریویی در اجرای نرم‌افزار که همه چیز بدون هیچ خطا و مانعی به طور کامل کار می‌کند |
|
||||||
|
| Skeleton Loader | لودر اسکلتی / اسکلتون | ماکت خاکستری محو و متحرک که اسکلت چیدمان صفحه را پیش از رسیدن داده‌ها نمایش می‌دهد |
|
||||||
|
| Layout Shift (CLS) | پرش ناگهانی چیدمان | حرکت ناگهانی عناصر صفحه حین لود شدن محتوا که باعث آسیب به تجربه کاربری می‌شود |
|
||||||
|
| Empty State | وضعیت تهی / بدون داده | صفحه یا بخشی از نرم‌افزار که در حال حاضر هیچ دیتایی برای نمایش به کاربر ندارد |
|
||||||
|
| Error Boundary | مرز مهار خطا | مکانیزمی در فرانت‌اند که مانع از پخش شدن خطای یک جزء به کل صفحه و سقوط برنامه می‌شود |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||||
|
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` قرار گرفته و در قالب جدول تک‌خانه‌ای وسط‌چین با کپشن تفصیلی درج شوند:
|
||||||
|
|
||||||
|
1. **تصویر کاور درس:** `images/cover.png`
|
||||||
|
* **موضوع:** کاور مدرن با تم تیره که ۴ وضعیت یک اپلیکیشن (اسکلتون در حال پالس، وضعیت پر، وضعیت خالی و خطای کنترل‌شده) را در قاب‌های دیجیتال کنار هم نشان می‌دهد.
|
||||||
|
2. **ماتریس چهارگانه وضعیت‌های رابط کاربری:** `images/four-ui-states-matrix.png`
|
||||||
|
* **موضوع:** اینفوگرافیک ۴ خانه‌ای: ۱. در حال لودینگ (اسکلتون) $\rightarrow$ ۲. موفق (کارت‌ها) $\rightarrow$ ۳. خالی (پیام صمیمانه) $\rightarrow$ ۴. خطا با دکمه تلاش مجدد.
|
||||||
|
3. **اسکلتون لودر کارت پورتفولیو در عمل:** `images/skeleton-card-pulse.png`
|
||||||
|
* **موضوع:** اسکرین‌شات از ۳ کارت اسکلتون خاکستری با کلاس `animate-pulse` که دقیقاً جایگاه تصویر و متن را شبیه‌سازی کرده‌اند.
|
||||||
|
4. **نمونه باکس Empty State در گرید پروژه‌ها:** `images/empty-state-showcase.png`
|
||||||
|
* **موضوع:** تصویر کادر شیک با آیکون سرچ، متن «پروژه‌ای یافت نشد» و دکمه شفاف «مشاهده همه پروژه‌ها».
|
||||||
|
5. **معماری فایل‌های `loading.tsx` و `error.tsx` در Next.js:** `images/nextjs-conventions-diagram.png`
|
||||||
|
* **موضوع:** دیاگرام عملکرد خودکار فریم‌ورک در جابجایی بین فایل صفحه، لودینگ و مرز خطا.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||||
|
|
||||||
|
1. **تیتر اصلی:** `# مدیریت وضعیت‌های مختلف UI: نجات از تله مسیر ایده‌آل`
|
||||||
|
2. **مقدمه:** چرا یک توسعه‌دهنده حرفه‌ای را نه با کدهای وضعیت عادی، بلکه با نحوه برخوردش با خطاها و لودینگ می‌شناسند؟
|
||||||
|
3. **جدول کاور درس**
|
||||||
|
4. **تلهٔ مسیر ایده‌آل (Happy Path) چیست؟:** ریشه‌های غفلت هوش مصنوعی از وضعیت‌های واقعی.
|
||||||
|
5. **وضعیت اول: جادوی اسکلتون لودرها (Skeleton Screens):**
|
||||||
|
* چرا اسپینرهای گردشی باعث سردرگمی و پرش چیدمان می‌شوند؟
|
||||||
|
* ساخت کامپوننت `ProjectCardSkeleton.tsx` با کلاس‌های پالس.
|
||||||
|
6. **باکس نکته Quera (`<details class="violet">`):** کاهش بار روانی انتظار در کاربر با اسکلتون لودر.
|
||||||
|
7. **وضعیت دوم: هنر طراحی داده‌های خالی (Empty State):**
|
||||||
|
* تبدیل یک صفحه خالی غم‌انگیز به فرصتی برای راهنمایی کاربر.
|
||||||
|
* پیاده‌سازی باکس خالی با دکمه بازنشانی فیلتر.
|
||||||
|
8. **وضعیت سوم: مدیریت آبرومندانه خطاها (Error State):**
|
||||||
|
* جلوگیری از سفید شدن صفحه و دکمه نجات‌بخش «تلاش مجدد».
|
||||||
|
9. **قراردادهای بومی Next.js: فایل‌های `loading.tsx` و `error.tsx`:** اتوماسیون کامل وضعیت‌ها در مسیرهای پروژه.
|
||||||
|
10. **باکس هشدار Quera (`<details class="red">`):** هرگز کاربر را در حین خطا بدون توضیح تنها نگذارید!
|
||||||
|
11. **جمع‌بندی درس‌نامه:** تسلط بر تاب‌آوری رابط کاربری و آماده‌سازی برای پیاده‌سازی و آزمون واکنش‌گرایی در دنیای واقعی.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||||
|
- [ ] نقد تفکر Happy Path و ضرورت پوشش وضعیت‌های لودینگ، خالی و خطا به روشنی تبیین شده باشد.
|
||||||
|
- [ ] مزایای اسکلتون لودر و نحوه پیاده‌سازی آن در کامپوننت‌های پورتفولیو شرح داده شود.
|
||||||
|
- [ ] طراحی وضعیت‌های خالی و خطا همراه با دکمه‌های اکشن متناظر به طور کامل مستند گردد.
|
||||||
|
- [ ] سازوکار فایل‌های قراردادی `loading.tsx` و `error.tsx` فریم‌ورک Next.js آموزش داده شود.
|
||||||
@@ -0,0 +1,106 @@
|
|||||||
|
# مشخصات درس‌نامه: پیاده‌سازی واکنش‌گرا و سازگاری در عمل (Practical Responsive Implementation)
|
||||||
|
- **شناسه در سیلابس:** `L6.6` (`L6.8` در شیت)
|
||||||
|
- **فصل:** فصل ۶: آماده‌سازی Prototype (Ch 6)
|
||||||
|
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||||
|
- **زمان تقریبی مطالعه:** ۱۲ دقیقه
|
||||||
|
- **پیش‌نیازهای مستقیم:** `L6.5` (مدیریت وضعیت‌های مختلف UI)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||||
|
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** کلاس‌های تطبیق‌پذیر Tailwind CSS (مانند `flex-col md:flex-row` و `grid-cols-1 md:grid-cols-2 lg:grid-cols-3`) را در کدهای پروژه پورتفولیو به کار گیرد.
|
||||||
|
- [ ] **تحلیل/ارزیابی کند (Evaluate):** چالش‌های سه‌گانه واکنش‌گرایی (تبدیل منوی ناوبری دسکتاپ به منوی همبرگری موبایل، چینش عمودی سکشن هدر، و تک‌ستونه شدن فرم‌های ادمین) را حل کند.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** «آزمون شکنجه ۳۲۰ پیکسلی (iPhone SE Torture Test)» را در ابزار DevTools مرورگر اجرا کرده و از سلامت چیدمان در کوچک‌ترین نمایشگرها مطمئن شود.
|
||||||
|
- [ ] **تحلیل/ارزیابی کند (Evaluate):** باگ ویرانگر اسکرول افقی ناخواسته (Horizontal Scroll Overflow) را شناسایی و با ابزارهای بازرسی دیباگ کند.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** با ارسال اسکرین‌شات از خطای نمایش موبایل به ایجنت هوش مصنوعی، کدهای ریسپانسیو را با پرامپت چندرسانه‌ای در چند ثانیه بازسازی کند.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||||
|
|
||||||
|
### آنچه باید پوشش داده شود (In-Scope):
|
||||||
|
1. **گذر از تئوری به کدهای واقعی ریسپانسیو:**
|
||||||
|
* در فصل ۵ مفاهیم واکنش‌گرایی را شناختیم؛ در این درس کلاس‌های مشخص و کالبدشکافی کدهای واقعی پورتفولیو را در عمل می‌سازیم.
|
||||||
|
2. **حل سه چالش بزرگ واکنش‌گرایی در پروژه محوری:**
|
||||||
|
* **چالش ۱: نوار ناوبری (Navbar):**
|
||||||
|
* در دسکتاپ: لینک‌ها افقی و باز با دکمه ارتباط (`hidden md:flex`).
|
||||||
|
* در موبایل: هدر چسبان فشرده با آیکون همبرگری مدرن (`flex md:hidden`) که با کلیک روی آن منوی کشویی باز می‌شود.
|
||||||
|
* **چالش ۲: بخش هدر معرفی (Hero Section):**
|
||||||
|
* در دسکتاپ: تصویر آواتار در کنار متن و دکمه‌ها به صورت ردیف افقی (`md:flex-row`).
|
||||||
|
* در موبایل: آواتار در مرکز بالای صفحه و بیوگرافی و دکمه‌ها به صورت ستونی زیر آن (`flex-col text-center md:text-right`).
|
||||||
|
* **چالش ۳: داشبورد ادمین و فرم‌های سئو:**
|
||||||
|
* تبدیل فرم‌های ۲ ستونه دسکتاپ به فیلدهای تمام‌عرض تک‌ستونه در موبایل (`grid-cols-1 md:grid-cols-2`) تا ادمین بتواند به راحتی با کیبورد گوشی اطلاعات را تایپ کند.
|
||||||
|
3. **فرمول کلاس‌های واکنش‌گرای پرکاربرد Tailwind:**
|
||||||
|
* `p-4 sm:p-6 lg:p-8`: پدینگ شناور متناسب با ابعاد صفحه.
|
||||||
|
* `text-2xl sm:text-3xl lg:text-4xl`: مقیاس تایپوگرافی زنده.
|
||||||
|
* `w-full max-w-md mx-auto`: مهار عرض فرم‌ها در وسط صفحه.
|
||||||
|
4. **آزمون شکنجه ۳۲۰ پیکسلی (The 320px Torture Test):**
|
||||||
|
* کوچک‌ترین ابعاد استاندارد گوشی‌های هوشمند (iPhone SE).
|
||||||
|
* اگر وب‌سایت در عرض ۳۲۰ پیکسل بدون بیرون‌زدگی کار کند، در تمام نمایشگرهای دنیا بی‌نقص خواهد بود.
|
||||||
|
5. **شکار و انهدام باگ اسکرول افقی (Horizontal Scroll):**
|
||||||
|
* چرا وقتی یک عکس عرض ثابت مثلاً `w-[450px]` دارد، کل صفحه گوشی به چپ و راست تکان می‌خورد؟
|
||||||
|
* راه‌حل فنی: استفاده از `max-w-full` و ردیابی عنصر متخلف با ابزار Inspect.
|
||||||
|
6. **کال‌اوت‌های Quera:**
|
||||||
|
* `<details class="violet">`: آزمون شکنجه ۳۲۰ پیکسلی؛ راز تضمین کیفیت نرم‌افزارهای بین‌المللی.
|
||||||
|
* `<details class="red">`: کابوس اسکرول افقی؛ فاجعه‌ای که بیش از ۴۰ درصد کاربران موبایل را بلافاصله فراری می‌دهد.
|
||||||
|
|
||||||
|
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||||
|
- نوشتن کوئری‌های CSS سنتی `@media` به شکل دستی (ما تماماً بر کلاس‌های مدرن Tailwind تکیه می‌کنیم).
|
||||||
|
- دیپلوی پروژه روی اینترنت و تست روی دستگاه‌های فیزیکی واقعی (مربوط به فصل ۱۲).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||||
|
|
||||||
|
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| Responsive Implementation | پیاده‌سازی واکنش‌گرا | نوشتن کدهایی که ساختار و استایل المان‌ها را بر اساس ابعاد نمایشگر تغییر می‌دهند |
|
||||||
|
| Hamburger Menu | منوی همبرگری | آیکون ۳ خطی در موبایل که با لمس آن، گزینه‌های ناوبری باز و بسته می‌شوند |
|
||||||
|
| Horizontal Scroll Bug | باگ اسکرول افقی | خطای آزاردهنده‌ای که در آن المان‌ها از عرض صفحه گوشی بیرون زده و صفحه لق می‌زند |
|
||||||
|
| Fluid Spacing | فاصله‌گذاری شناور | تغییر خودکار پدینگ‌ها و مارجین‌ها از مقادیر کم در موبایل به مقادیر باز در دسکتاپ |
|
||||||
|
| 320px Torture Test | آزمون شکنجه ۳۲۰ پیکسل | تست سنجش استحکام چیدمان نرم‌افزار در کمترین عرض استاندارد نمایشگرهای همراه |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||||
|
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` قرار گرفته و در قالب جدول تک‌خانه‌ای وسط‌چین با کپشن تفصیلی درج شوند:
|
||||||
|
|
||||||
|
1. **تصویر کاور درس:** `images/cover.png`
|
||||||
|
* **موضوع:** کاور مدرن با تم تیره که خط‌کش‌های تنظیم ابعاد را در حال کشیدن و فشرده کردن کادر سایت پورتفولیو بدون شکستگی نشان می‌دهد.
|
||||||
|
2. **نگاشت کدهای Tailwind به ابعاد نمایشگر:** `images/tailwind-responsive-classes-map.png`
|
||||||
|
* **موضوع:** اینفوگرافیک تطبیق کدهای `flex-col` روی موبایل با `md:flex-row` روی صفحه لپ‌تاپ به همراه فلش‌های تعاملی.
|
||||||
|
3. **آزمون ۳۲۰ پیکسلی در آیفون SE:** `images/iphone-se-layout-test.png`
|
||||||
|
* **موضوع:** اسکرین‌شات از ابزار DevTools کروم در عرض دقیق ۳۲۰ پیکسل که سلامت کارت‌ها و دکمه‌ها را اثبات می‌کند.
|
||||||
|
4. **داشبورد ادمین در دو نمای موبایل و دسکتاپ:** `images/admin-dashboard-responsive-comparison.png`
|
||||||
|
* **موضوع:** تصویر کنار هم: داشبورد تک‌ستونه ادمین روی گوشی در برابر چیدمان باز سایدباردار روی مانیتور.
|
||||||
|
5. **کالبدشکافی و حل خطای اسکرول افقی:** `images/horizontal-scroll-debug.png`
|
||||||
|
* **موضوع:** تصویر شماتیک خطای المان بیرون‌زده با کادر قرمز و رفع آن با کلاس `max-w-full`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||||
|
|
||||||
|
1. **تیتر اصلی:** `# پیاده‌سازی واکنش‌گرا در عمل: تسخیر نمایشگرها از موبایل تا دسکتاپ`
|
||||||
|
2. **مقدمه:** چرا نوشتن کدهای ریسپانسیو با هوش مصنوعی آسان‌ترین کار است، به شرطی که دستور درست را بدهید؟
|
||||||
|
3. **جدول کاور درس**
|
||||||
|
4. **معماری سه‌گانه واکنش‌گرایی در پورتفولیوی پویا:**
|
||||||
|
* ناوبری و منوی همبرگری موبایل.
|
||||||
|
* هدر معرفی منعطف (ستون به سطر).
|
||||||
|
* فرم‌های بهینه‌شده برای انگشت شست در داشبورد ادمین.
|
||||||
|
5. **کلاس‌های جادویی Tailwind در واکنش‌گرایی عملی:**
|
||||||
|
* ترکیب `hidden md:flex` و جابجایی ستون‌ها.
|
||||||
|
* فواصل و تایپوگرافی شناور.
|
||||||
|
6. **باکس نکته Quera (`<details class="violet">`):** آزمون شکنجه ۳۲۰ پیکسلی و شیوه اجرای آن در مرورگر.
|
||||||
|
7. **کالبدشکافی کابوس اسکرول افقی (Horizontal Overflow):** ریشه‌ها و راه‌های پیشگیری.
|
||||||
|
8. **روش دیباگ خطاهای ریسپانسیو با پرامپت تصویری در Cursor:** چگونه اسکرین‌شات را به کامپوزر تحویل دهیم؟
|
||||||
|
9. **باکس هشدار Quera (`<details class="red">`):** پرهیز از عرض‌های ثابت پیکسلی در طراحی المان‌ها.
|
||||||
|
10. **جمع‌بندی درس‌نامه:** ضدضربه شدن پروتوتایپ در برابر تمام دستگاه‌ها و ورود به درس نهایی فصل: توسعه چرخشی با ایجنت‌ها.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||||
|
- [ ] حل سه چالش اساسی ریسپانسیو در پروژه پورتفولیو با کدهای عینی تبیین شده باشد.
|
||||||
|
- [ ] نحوه پیاده‌سازی کلاس‌های واکنش‌گرای Tailwind آموزش داده شود.
|
||||||
|
- [ ] مفهوم آزمون ۳۲۰ پیکسلی و راهکار حل باگ اسکرول افقی به صورت تصویری مستند گردد.
|
||||||
|
- [ ] تکنیک ارسال اسکرین‌شات خطای موبایل به ایجنت هوش مصنوعی برای اصلاح کدها در متن باشد.
|
||||||
@@ -0,0 +1,105 @@
|
|||||||
|
# مشخصات درس‌نامه: تعامل با Agentها برای بهبود و توسعه تدریجی کد (Agentic Frontend Iteration)
|
||||||
|
- **شناسه در سیلابس:** `L6.7` (`L6.9` در شیت)
|
||||||
|
- **فصل:** فصل ۶: آماده‌سازی Prototype (Ch 6)
|
||||||
|
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||||
|
- **زمان تقریبی مطالعه:** ۱۵ دقیقه
|
||||||
|
- **پیش‌نیازهای مستقیم:** `L6.6` (پیاده‌سازی واکنش‌گرا و سازگاری در عمل)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||||
|
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||||
|
- [ ] **درک کند (Understand):** چرا هیچ هوش مصنوعی در اولین پرامپت یک رابط کاربری صددرصد بی‌نقص نمی‌سازد و هنر واقعی وایب کدر در **چرخه تکرار و توسعه تدریجی (Rapid Iteration Loop)** نهفته است.
|
||||||
|
- [ ] **تحلیل/ارزیابی کند (Evaluate):** سه دسته خطای متداول فرانت‌اند (خطاهای کنسول و ترمینال، خطاهای بصری چیدمان، و خطای ناهماهنگی هایدریشن Next.js) را تفکیک و به درستی به ایجنت گزارش کند.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** مهارت مرور تغییرات (Diff Review) را در پنجره کامپوزر ادیتور Cursor اجرا کند؛ خطوط سبز (اضافه‌شده) و قرمز (حذف‌شده) را بازرسی کرده و مانع از پذیرش کورکورانه تغییرات اشتباه شود.
|
||||||
|
- [ ] **تحلیل/ارزیابی کند (Evaluate):** خطای معروف هایدریشن (Hydration Mismatch Error) ناشی از ناهماهنگی کدهای رندر سرور با مرورگر کلاینت را ریشه‌یابی و برطرف نماید.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** نسخه نهایی پروتوتایپ پورتفولیوی پویا را با تمام تعاملات، فیلترها، مودال‌ها و چیدمان واکنش‌گرا به عنوان نقطه پایان موفقیت‌آمیز فاز فرانت‌اند تست و تحویل بگیرد.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||||
|
|
||||||
|
### آنچه باید پوشش داده شود (In-Scope):
|
||||||
|
1. **واقعیت ملموس وایب کدینگ: قدرت در اصلاح و صیقل دادن است:**
|
||||||
|
* پرامپت اول تنها ۶۰ تا ۷۰ درصد مسیر را می‌رود؛ ۳۰ درصد باقیمانده که محصول را به کمال می‌رساند، بازخوردهای دقیق و گام‌به‌گام شماست.
|
||||||
|
2. **چرخه شش‌مرحله‌ای توسعه چرخشی با ایجنت (The Agentic Loop):**
|
||||||
|
* ۱. ارسال پرامپت تسک $\rightarrow$ ۲. ایجاد کدها توسط ایجنت $\rightarrow$ ۳. مشاهده و تست زنده در مرورگر $\rightarrow$ ۴. شناسایی باگ یا ناهماهنگی $\rightarrow$ ۵. ارسال فیدبک دقیق به ایجنت $\rightarrow$ ۶. بازبینی دیف‌ها و تایید نهایی (Commit).
|
||||||
|
3. **دسته‌بندی و مهار ۳ خطای متداول در فرانت‌اند با هوش مصنوعی:**
|
||||||
|
* **دسته ۱: خطاهای ران‌تایم کنسول مرورگر و ترمینال:**
|
||||||
|
* نحوه فشردن `F12`، رفتن به تب Console، کپی کردن متن قرمز خطا و تحویل آن به ایجنت.
|
||||||
|
* **دسته ۲: باگ‌های بصری و استایل (Visual Glitches):**
|
||||||
|
* عکس گرفتن از کادر کج یا فاصله نامناسب، پیوست کردن عکس در کامپوزر Cursor با توضیح: «این فاصله را به ۱۶ پیکسل تغییر بده و متن را راست‌چین کن».
|
||||||
|
* **دسته ۳: خطای هایدریشن در Next.js (Hydration Mismatch):**
|
||||||
|
* چرا این خطا رخ می‌دهد؟ وقتی سرور یک چیز می‌سازد ولی مرورگر در کلاینت چیز دیگری رندر می‌کند (مثلاً استفاده از تاریخ پویا یا دسترسی به `window` بدون `'use client'`).
|
||||||
|
4. **انضباط حیاتی بازبینی دیف‌ها (Diff Review Discipline):**
|
||||||
|
* هرگز دکمه Accept All را با چشمان بسته نزنید!
|
||||||
|
* بررسی تغییرات: آیا ایجنت به اشتباه کدهای کارکردی قبلی را پاک نکرده است؟
|
||||||
|
* استفاده از دکمه Reject برای رد کردن تغییرات نامطلوب و هدایت مجدد مدل.
|
||||||
|
5. **پولیش نهایی پروتوتایپ پورتفولیوی پویا:**
|
||||||
|
* هماهنگ‌سازی انیمیشن باز و بسته شدن مودال.
|
||||||
|
* تنظیم دقیق فاصله‌های کارت‌ها در هاور.
|
||||||
|
* تایید کارکرد روان فیلتر دسته‌بندی پروژه‌ها.
|
||||||
|
6. **کال‌اوت‌های Quera:**
|
||||||
|
* `<details class="violet">`: هنر خواندن دیف‌ها در Cursor؛ چگونه در کمتر از ۱۰ ثانیه تغییرات پیشنهادی هوش مصنوعی را داوری کنیم؟
|
||||||
|
* `<details class="red">`: خطای هایدریشن (Hydration Error)؛ راز حل خطای قرمز ترسناک Next.js با افزودن `'use client'` یا `useEffect`.
|
||||||
|
|
||||||
|
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||||
|
- تست‌های خودکار اند-تو-اند با Playwright یا Cypress (در فصل ۹ بررسی می‌شود).
|
||||||
|
- شروع پیاده‌سازی بک‌اند و جداول دیتابیس (ورود رسمی از فصل ۷).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||||
|
|
||||||
|
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| Iterative Refinement | پالایش و توسعه چرخشی | بهبود مرحله‌به‌مرحله محصول از طریق ارزیابی مداوم و رفع تدریجی نواقص |
|
||||||
|
| Diff Review | بازبینی تفاوت کدها | بررسی خطوط اضافه و حذف‌شده در ادیتور پیش از پذیرش و ادغام کدهای هوش مصنوعی |
|
||||||
|
| Hydration Error | خطای ناهماهنگی هایدریشن | اختلاف میان خروجی اولیه سرور با رندرینگ نهایی جاوااسکریپت در مرورگر کاربر |
|
||||||
|
| Console Stack Trace | ردپای خطای کنسول | گزارش فنی دقیق مرورگر شامل نام فایل و شماره خطی که باعث ایجاد باگ شده است |
|
||||||
|
| Targeted Feedback | بازخورد هدفمند و موضعی | دستورالعمل صریح و مشخص به هوش مصنوعی برای اصلاح یک نقطه خاص بدون برهم زدن سایر بخش‌ها |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||||
|
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` قرار گرفته و در قالب جدول تک‌خانه‌ای وسط‌چین با کپشن تفصیلی درج شوند:
|
||||||
|
|
||||||
|
1. **تصویر کاور درس:** `images/cover.png`
|
||||||
|
* **موضوع:** کاور مدرن با تم تیره که ذره‌بین نئونی دیجیتال در حال بازرسی و پولیش خطوط کد و رندر نهایی یک کارت وب است.
|
||||||
|
2. **چرخه شش‌گانه توسعه چرخشی با ایجنت:** `images/agentic-iteration-cycle.png`
|
||||||
|
* **موضوع:** اینفوگرافیک چرخشی: ۱. پرامپت $\rightarrow$ ۲. کد ایجنت $\rightarrow$ ۳. تست مرورگر $\rightarrow$ ۴. کشف ایراد $\rightarrow$ ۵. فیدبک با عکس/لاگ $\rightarrow$ ۶. تایید دیف.
|
||||||
|
3. **نمای پنجره Diff Review در Cursor Composer:** `images/cursor-diff-review-demo.png`
|
||||||
|
* **موضوع:** اسکرین‌شات تمیز از خطوط قرمز حذفی و خطوط سبز اضافه‌شده در ادیتور همراه با دکمه‌های Accept و Reject.
|
||||||
|
4. **کالبدشکافی و رفع خطای هایدریشن:** `images/hydration-error-fix.png`
|
||||||
|
* **موضوع:** تصویر خطای هایدریشن در کنسول مرورگر و اصلاح سریع آن با اضافه شدن لایه کلاینت.
|
||||||
|
5. **رونمایی از شاهکار نهایی فصل ۶ (پروتوتایپ کامل پورتفولیو):** `images/final-prototype-milestone.png`
|
||||||
|
* **موضوع:** اسکرین‌شات باشکوه از پورتفولیوی شخصی پویا در حال اجرا روی پورت ۳۰۰۰ با تمام المان‌های تعاملی و آماده برای اتصال به دیتابیس.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||||
|
|
||||||
|
1. **تیتر اصلی:** `# تعامل با Agentها برای بهبود و توسعه تدریجی: هنر صیقل دادن خروجی‌ها`
|
||||||
|
2. **مقدمه:** چرا تفاوت وایب کدرهای برنده با بازنده‌ها، در نحوه واکنش آن‌ها به اولین خطاهای کد است؟
|
||||||
|
3. **جدول کاور درس**
|
||||||
|
4. **چرخه طلایی بازخورد (The Iteration Loop):** هنر گفتگوی مهندسی با ایجنت.
|
||||||
|
5. **شکار و انهدام سه دسته خطای رایج در فرانت‌اند:**
|
||||||
|
* خطاهای متنی کنسول و نحوه ارسال گزارش تمیز.
|
||||||
|
* خطاهای چیدمان بصری و قدرت بازخورد تصویری.
|
||||||
|
* خطای مرموز هایدریشن (Hydration Mismatch) در Next.js.
|
||||||
|
6. **باکس نکته Quera (`<details class="violet">`):** انضباط طلایی بازبینی دیف‌ها (Diff Review) در کامپوزر Cursor.
|
||||||
|
7. **باکس رفع خطای Quera (`<details class="red">`):** حل خطای هایدریشن در دو دقیقه با کدهای کلاینت.
|
||||||
|
8. **پولیش نهایی پروژه پورتفولیوی پویا:**
|
||||||
|
* بررسی نرمی انیمیشن‌ها.
|
||||||
|
* تست تعاملات مودال و کارت‌ها.
|
||||||
|
* تایید کامل استانداردهای ریسپانسیو.
|
||||||
|
9. **جشن پایان فاز فرانت‌اند (The Prototype Milestone):** مرور دستاوردهای شگفت‌انگیز فصل ۶.
|
||||||
|
10. **جمع‌بندی فصل ششم و پیش‌درآمد فصل ۷:** آماده‌سازی پروتوتایپ زنده برای دریافت مغز متفکر و پایگاه داده واقعی.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||||
|
- [ ] مفهوم توسعه چرخشی و چرخه بازخورد به عنوان مهارت محوری وایب کدینگ تبیین شده باشد.
|
||||||
|
- [ ] سه نوع خطای شایع فرانت‌اند (کنسول، بصری، هایدریشن) با نحوه گزارش به ایجنت پوشش داده شوند.
|
||||||
|
- [ ] فرهنگ بازبینی دیف‌ها (Diff Review) پیش از زدن دکمه تایید در ادیتور آموزش داده شود.
|
||||||
|
- [ ] ایستگاه موفقیت‌آمیز پایان فصل ۶ با تست کامل پروتوتایپ پورتفولیو روی `localhost:3000` مستند گردد.
|
||||||
Reference in New Issue
Block a user