From 405cab38284a2691fae4384fc5b0576e0209ee59 Mon Sep 17 00:00:00 2001 From: Amirhossein Khalili Date: Sat, 5 Sep 2026 22:10:43 +0800 Subject: [PATCH] feat: add chapter 06-frontend-prototype specs --- .../00-lesson-chapter-goals/spec.md | 81 ++++++++++++ .../01-lesson-frontend-frameworks/spec.md | 115 +++++++++++++++++ .../spec.md | 114 +++++++++++++++++ .../03-lesson-ui-with-mock-data/spec.md | 116 ++++++++++++++++++ .../04-lesson-ui-state-management/spec.md | 101 +++++++++++++++ .../spec.md | 106 ++++++++++++++++ .../spec.md | 105 ++++++++++++++++ 7 files changed, 738 insertions(+) create mode 100644 chapters/06-frontend-prototype/00-lesson-chapter-goals/spec.md create mode 100644 chapters/06-frontend-prototype/01-lesson-frontend-frameworks/spec.md create mode 100644 chapters/06-frontend-prototype/02-lesson-frontend-component-libraries/spec.md create mode 100644 chapters/06-frontend-prototype/03-lesson-ui-with-mock-data/spec.md create mode 100644 chapters/06-frontend-prototype/04-lesson-ui-state-management/spec.md create mode 100644 chapters/06-frontend-prototype/05-lesson-practical-responsive-implementation/spec.md create mode 100644 chapters/06-frontend-prototype/06-lesson-agentic-frontend-iteration/spec.md diff --git a/chapters/06-frontend-prototype/00-lesson-chapter-goals/spec.md b/chapters/06-frontend-prototype/00-lesson-chapter-goals/spec.md new file mode 100644 index 0000000..cf962ed --- /dev/null +++ b/chapters/06-frontend-prototype/00-lesson-chapter-goals/spec.md @@ -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. **کال‌اوت نکته کوئرا (`
`):** دست به ابزار شدن و اجرای واقعی دستورات هم‌گام با مطالعه دروس. + +### آنچه نباید وارد آن شویم (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 (`
`):** ثبت دکمه «خواندم» و آغاز هیجان‌انگیز ساخت پروتوتایپ. + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] گذار به فاز ساخت و لمس نتایج زنده در مرورگر با لحن انگیزاننده تبیین شده باشد. +- [ ] سرفصل‌های ۷ درس این فصل به همراه خروجی ملموس پورتفولیو مشخص گردند. +- [ ] الزام ارائه دستورات چندسکویی با زبانه‌های کشویی یادآوری شود. diff --git a/chapters/06-frontend-prototype/01-lesson-frontend-frameworks/spec.md b/chapters/06-frontend-prototype/01-lesson-frontend-frameworks/spec.md new file mode 100644 index 0000000..27d188b --- /dev/null +++ b/chapters/06-frontend-prototype/01-lesson-frontend-frameworks/spec.md @@ -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 "@/*" + ``` + * ارائه دستور در منوهای کشویی: + * `
راهنمای اجرا در ویندوز (Windows PowerShell) ...
` + * `
راهنمای اجرا در مک‌اواس (macOS Terminal) ...
` + * `
راهنمای اجرا در لینوکس (Linux Bash) ...
` +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:** + * `
`: تفاوت Server Component با Client Component در دو جمله ساده و ملموس. + * `
`: رفع خطای متداول «پورت ۳۰۰۰ اشغال است» (`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 (`
`):** تمایز ساده سرور و کلاینت در قالب دو تعریف روشن. +7. **تایپ‌اسکریپت: کمربند ایمنی وایب کدرها در برابر باگ‌ها:** چرا ادیتورهای هوشمند با تایپ‌اسکریپت بهتر کار می‌کنند؟ +8. **ساخت گام‌به‌گام اسکلت پروژه با خط فرمان:** + * دستور استاندارد `create-next-app`. + * منوی کشویی ویندوز (Windows). + * منوی کشویی مک‌اواس (macOS). + * منوی کشویی لینوکس (Linux). +9. **نقشه معماری مسیرهای پورتفولیوی پویا:** تفکیک ویترین عمومی از پیشخوان ادمین و پنل سئو. +10. **اجرای سرور محلی (`npm run dev`) و مشاهده اولین خروجی:** بازرسی صفحه در `localhost:3000`. +11. **باکس رفع خطای Quera (`
`):** حل مشکل پر بودن پورت ۳۰۰۰. +12. **جمع‌بندی درس‌نامه:** بالا آمدن اسکلت زنده پروژه و آماده شدن برای تجهیز کامپوننت‌های شادسی‌ان در درس بعد. + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] مزایای معماری Next.js App Router و نقش آن در سئو و ساختار پنل‌ها تبیین شده باشد. +- [ ] تفاوت سرور کامپوننت و کلاینت کامپوننت به شکلی قابل درک برای نوآموزان آموزش داده شود. +- [ ] دستور راه‌اندازی پروژه برای سه سیستم‌عامل در منوهای کشویی مجزا درج گردد. +- [ ] نقشه مسیرهای پروژه محوری (صفحه اصلی و زیرشاخه‌های ادمین) به دقت تصویرسازی شود. diff --git a/chapters/06-frontend-prototype/02-lesson-frontend-component-libraries/spec.md b/chapters/06-frontend-prototype/02-lesson-frontend-component-libraries/spec.md new file mode 100644 index 0000000..5c44ba8 --- /dev/null +++ b/chapters/06-frontend-prototype/02-lesson-frontend-component-libraries/spec.md @@ -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:** + * `
`: راز پوشه `components/ui/`؛ کدهایی که به شما تعلق دارند و هوش مصنوعی هر زمان بخواهد می‌تواند آن‌ها را ارتقا دهد. + * `
`: میانبر طلایی ترمینال؛ اضافه کردن همزمان چندین کامپوننت شادسی‌ان با یک دستور واحد. + +### آنچه نباید وارد آن شویم (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 (`
`):** چرا ایجنت‌های کدنویسی عاشق پوشه `components/ui/` هستند؟ +9. **مقایسه با کتابخانه‌های کلاسیک (Material UI و Ant Design):** چرا سبک جدید سریع‌تر و مدرن‌تر است؟ +10. **باکس میانبر Quera (`
`):** مدیریت و اضافه کردن آسان کامپوننت‌های آینده. +11. **جمع‌بندی درس‌نامه:** مجهز شدن پروژه به تمام قطعات ظاهری و ورود به مرحله تزریق داده‌های تستی (Mock Data). + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] معماری نوین shadcn/ui و مزیت حضور فایل‌ها در پوشه محلی به دقت تحلیل شده باشد. +- [ ] دستورات نصب init و add برای سه سیستم‌عامل در منوهای کشویی جداگانه قرار گیرد. +- [ ] نقش هریک از کامپوننت‌های نصب‌شده در پورتفولیوی پویا تشریح شده باشد. +- [ ] نصب و نحوه کار با Lucide Icons همراه با مثال عملی در متن گنجانده شود. diff --git a/chapters/06-frontend-prototype/03-lesson-ui-with-mock-data/spec.md b/chapters/06-frontend-prototype/03-lesson-ui-with-mock-data/spec.md new file mode 100644 index 0000000..e10d3e7 --- /dev/null +++ b/chapters/06-frontend-prototype/03-lesson-ui-with-mock-data/spec.md @@ -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:** + * `
`: چرا تفکیک رابط کاربری از دیتابیس سرعت پیشرفت پروژه را در متدولوژی وایب کدینگ ۵ برابر می‌کند؟ + * `
`: تله «داده‌های بیش از حد ایده‌آل»؛ در داده‌های تستی حتماً یک عنوان بسیار طولانی بگذارید تا مطمئن شوید کادرها در صورت طولانی شدن متن نمی‌شکنند. + +### آنچه نباید وارد آن شویم (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 (`
`):** سرعت و استقلال توسعه با داده‌های شبیه‌سازی‌شده. +7. **ساخت کامپوننت کارت پروژه (`ProjectCard.tsx`):** + * ترکیب کامپوننت Card شادسی‌ان با بج‌ها و آیکون‌های Lucide. +8. **ساخت گرید ریسپانسیو و مودال جزئیات:** + * چیدمان ۳ ستونه با CSS Grid. + * تعامل باز شدن پنجره دیالوگ شادسی‌ان. +9. **هدر اصلی سایت و پیاده‌سازی فیلتر تعاملی دسته‌بندی:** آزمایش تعاملات بدون نیاز به سرور. +10. **باکس هشدار Quera (`
`):** آزمون لبه‌ها؛ تست کارت‌ها با عنوان‌های بسیار طولانی. +11. **جمع‌بندی درس‌نامه:** مشاهده اولین نسخه زنده و تماشایی پورتفولیو و آمادگی برای مدیریت وضعیت‌های UI در درس بعد. + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] فلسفه Mock Data و مزیت استقلال فرانت‌اند از بک‌اند به درستی تبیین شده باشد. +- [ ] ساختار اینترفیس‌های تایپ‌اسکریپت برای پروژه محوری مستند گردد. +- [ ] نحوه پیاده‌سازی کامپوننت‌های کارت، گرید و مودال جزئیات شرح داده شود. +- [ ] نمونه‌های داده تستی ملموس و متنوع در ساختار درس لحاظ شده باشند. diff --git a/chapters/06-frontend-prototype/04-lesson-ui-state-management/spec.md b/chapters/06-frontend-prototype/04-lesson-ui-state-management/spec.md new file mode 100644 index 0000000..6cfafc3 --- /dev/null +++ b/chapters/06-frontend-prototype/04-lesson-ui-state-management/spec.md @@ -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:** + * `
`: چرا اسکلتون لودرها در غول‌های فناوری نظیر یوتیوب، فیس‌بوک و لینکدین جایگزین تمام اسپینرهای چرخان شده‌اند؟ + * `
`: تله رها کردن صفحه در وضعیت خنثی؛ هرگز کاربر را در حین لودینگ یا خطا بدون هیچ پیام و بازخوردی در برزخ رها نکنید. + +### آنچه نباید وارد آن شویم (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 (`
`):** کاهش بار روانی انتظار در کاربر با اسکلتون لودر. +7. **وضعیت دوم: هنر طراحی داده‌های خالی (Empty State):** + * تبدیل یک صفحه خالی غم‌انگیز به فرصتی برای راهنمایی کاربر. + * پیاده‌سازی باکس خالی با دکمه بازنشانی فیلتر. +8. **وضعیت سوم: مدیریت آبرومندانه خطاها (Error State):** + * جلوگیری از سفید شدن صفحه و دکمه نجات‌بخش «تلاش مجدد». +9. **قراردادهای بومی Next.js: فایل‌های `loading.tsx` و `error.tsx`:** اتوماسیون کامل وضعیت‌ها در مسیرهای پروژه. +10. **باکس هشدار Quera (`
`):** هرگز کاربر را در حین خطا بدون توضیح تنها نگذارید! +11. **جمع‌بندی درس‌نامه:** تسلط بر تاب‌آوری رابط کاربری و آماده‌سازی برای پیاده‌سازی و آزمون واکنش‌گرایی در دنیای واقعی. + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] نقد تفکر Happy Path و ضرورت پوشش وضعیت‌های لودینگ، خالی و خطا به روشنی تبیین شده باشد. +- [ ] مزایای اسکلتون لودر و نحوه پیاده‌سازی آن در کامپوننت‌های پورتفولیو شرح داده شود. +- [ ] طراحی وضعیت‌های خالی و خطا همراه با دکمه‌های اکشن متناظر به طور کامل مستند گردد. +- [ ] سازوکار فایل‌های قراردادی `loading.tsx` و `error.tsx` فریم‌ورک Next.js آموزش داده شود. diff --git a/chapters/06-frontend-prototype/05-lesson-practical-responsive-implementation/spec.md b/chapters/06-frontend-prototype/05-lesson-practical-responsive-implementation/spec.md new file mode 100644 index 0000000..446aa60 --- /dev/null +++ b/chapters/06-frontend-prototype/05-lesson-practical-responsive-implementation/spec.md @@ -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:** + * `
`: آزمون شکنجه ۳۲۰ پیکسلی؛ راز تضمین کیفیت نرم‌افزارهای بین‌المللی. + * `
`: کابوس اسکرول افقی؛ فاجعه‌ای که بیش از ۴۰ درصد کاربران موبایل را بلافاصله فراری می‌دهد. + +### آنچه نباید وارد آن شویم (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 (`
`):** آزمون شکنجه ۳۲۰ پیکسلی و شیوه اجرای آن در مرورگر. +7. **کالبدشکافی کابوس اسکرول افقی (Horizontal Overflow):** ریشه‌ها و راه‌های پیشگیری. +8. **روش دیباگ خطاهای ریسپانسیو با پرامپت تصویری در Cursor:** چگونه اسکرین‌شات را به کامپوزر تحویل دهیم؟ +9. **باکس هشدار Quera (`
`):** پرهیز از عرض‌های ثابت پیکسلی در طراحی المان‌ها. +10. **جمع‌بندی درس‌نامه:** ضدضربه شدن پروتوتایپ در برابر تمام دستگاه‌ها و ورود به درس نهایی فصل: توسعه چرخشی با ایجنت‌ها. + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] حل سه چالش اساسی ریسپانسیو در پروژه پورتفولیو با کدهای عینی تبیین شده باشد. +- [ ] نحوه پیاده‌سازی کلاس‌های واکنش‌گرای Tailwind آموزش داده شود. +- [ ] مفهوم آزمون ۳۲۰ پیکسلی و راهکار حل باگ اسکرول افقی به صورت تصویری مستند گردد. +- [ ] تکنیک ارسال اسکرین‌شات خطای موبایل به ایجنت هوش مصنوعی برای اصلاح کدها در متن باشد. diff --git a/chapters/06-frontend-prototype/06-lesson-agentic-frontend-iteration/spec.md b/chapters/06-frontend-prototype/06-lesson-agentic-frontend-iteration/spec.md new file mode 100644 index 0000000..ab0b57d --- /dev/null +++ b/chapters/06-frontend-prototype/06-lesson-agentic-frontend-iteration/spec.md @@ -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:** + * `
`: هنر خواندن دیف‌ها در Cursor؛ چگونه در کمتر از ۱۰ ثانیه تغییرات پیشنهادی هوش مصنوعی را داوری کنیم؟ + * `
`: خطای هایدریشن (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 (`
`):** انضباط طلایی بازبینی دیف‌ها (Diff Review) در کامپوزر Cursor. +7. **باکس رفع خطای Quera (`
`):** حل خطای هایدریشن در دو دقیقه با کدهای کلاینت. +8. **پولیش نهایی پروژه پورتفولیوی پویا:** + * بررسی نرمی انیمیشن‌ها. + * تست تعاملات مودال و کارت‌ها. + * تایید کامل استانداردهای ریسپانسیو. +9. **جشن پایان فاز فرانت‌اند (The Prototype Milestone):** مرور دستاوردهای شگفت‌انگیز فصل ۶. +10. **جمع‌بندی فصل ششم و پیش‌درآمد فصل ۷:** آماده‌سازی پروتوتایپ زنده برای دریافت مغز متفکر و پایگاه داده واقعی. + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] مفهوم توسعه چرخشی و چرخه بازخورد به عنوان مهارت محوری وایب کدینگ تبیین شده باشد. +- [ ] سه نوع خطای شایع فرانت‌اند (کنسول، بصری، هایدریشن) با نحوه گزارش به ایجنت پوشش داده شوند. +- [ ] فرهنگ بازبینی دیف‌ها (Diff Review) پیش از زدن دکمه تایید در ادیتور آموزش داده شود. +- [ ] ایستگاه موفقیت‌آمیز پایان فصل ۶ با تست کامل پروتوتایپ پورتفولیو روی `localhost:3000` مستند گردد.