feat: add chapter 15-production-evolution specs
This commit is contained in:
@@ -0,0 +1,88 @@
|
|||||||
|
# مشخصات درس‌نامه: اهداف فصل پانزدهم (Chapter Goals)
|
||||||
|
- **شناسه در سیلابس:** `L15.1`
|
||||||
|
- **فصل:** فصل ۱۵: تکامل محصول با AI (Ch 15)
|
||||||
|
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||||
|
- **زمان تقریبی مطالعه:** ۵ دقیقه
|
||||||
|
- **پیش‌نیازهای مستقیم:** `L13.7` (مستندسازی فاخر و کتابچه راهنمای نگهداری)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||||
|
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||||
|
- [ ] **درک کند (Understand):** چرا محصولات نرم‌افزاری موفق هرگز متوقف نمی‌شوند و چگونه هوش مصنوعی به عنوان یک کاتالیزور قدرتمند، چرخه تکامل، بازنویسی کدها (Refactoring)، اتوماسیون فرآیندها و گسترش به چند پلتفرم (PWA, Mobile, Desktop) را ۱۰ برابر سریع‌تر می‌کند.
|
||||||
|
- [ ] **درک کند (Understand):** نقشه راه ۱۲ درس‌نامه جامع فصل پانزدهم شامل: تحلیل بازخورد کاربران، تعریف مشخصات فیچرهای جدید، کاوش عمیق Codebase، ریفکتورینگ امن، افزودن قابلیت‌های پیشرفته AI، گردش‌کارهای ایجنتیک خودکار (Agentic Workflows)، اتوماسیون نگهداری، تحلیل هوشمند داده‌های محصول، تبدیل سایت به وب‌اپلیکیشن پیش‌رونده (PWA)، خروجی اپلیکیشن موبایل با هر دو روش Capacitor و Expo، و ساخت نسخه دسکتاپ با Tauri و Electron را بشناسد.
|
||||||
|
- [ ] **تحلیل/ارزیابی کند (Evaluate):** ارزش تکامل مستمر مبتنی بر ایجنت (Agent-Driven Product Evolution) را در افزایش طول عمر محصول و حفظ رقابت‌پذیری بازار تحلیل نماید.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** پورتفولیوی شخصی را از یک وب‌سایت ایستا به یک اکوسیستم چندسکویی و هوشمند قابل نصب روی گوشی‌های همراه و رایانه‌های دسکتاپ ارتقا دهد.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||||
|
|
||||||
|
### آنچه باید پوشش داده شود (In-Scope):
|
||||||
|
1. **قانون بقا در دنیای مدرن: تکامل یا مرگ نرم‌افزار:**
|
||||||
|
* نرم‌افزار ایستا نرم‌افزاری مرده است؛ موفق‌ترین محصولات دنیا دائماً بر اساس فیدبک کاربران در حال دگرگونی و ارتقا هستند.
|
||||||
|
2. **مرور سرفصل‌های تخصصی فصل ۱۵:**
|
||||||
|
* درس ۱۵.۲: تحلیل بازخورد کاربران و اولویت‌بندی تغییرات با ماتریس ارزش در برابر سختی (Value vs Effort).
|
||||||
|
* درس ۱۵.۳: هنر تعریف ویژگی جدید و تدوین مشخصات دقیق (Feature Spec) برای ایجنت‌های توسعه‌دهنده.
|
||||||
|
* درس ۱۵.۴: کالبدشکافی و کاوش در کدهای موجود (Codebase Analysis) با مدل‌های هوش مصنوعی دارای کانتکست غول‌پیکر.
|
||||||
|
* درس ۱۵.۵: بازنویسی، پاک‌سازی و ریفکتورینگ امن (Safe Refactoring) بدون شکستن فیچرهای فعلی.
|
||||||
|
* درس ۱۵.۶: تزریق قابلیت‌های هوشمند عمیق‌تر (جستجوی معنایی معنایی Semantic Search یا تولید خلاصه‌ساز).
|
||||||
|
* درس ۱۵.۷: ساخت گردش‌کارهای خودکار ایجنتیک (Agentic Workflows) برای انجام خودکار وظایف چندمرحله‌ای.
|
||||||
|
* درس ۱۵.۸: اتوماسیون نگهداری و توسعه (خودکارسازی تست‌ها، تریاژ ایشیوها و اسکریپت‌های خودترمیم).
|
||||||
|
* درس ۱۵.۹: تحلیل هوشمند متریک‌های محصول و استخراج بینش (Product Insights) با ترکیب هوش مصنوعی و لاگ‌ها.
|
||||||
|
* درس ۱۵.۱۰: تبدیل وب‌سایت به Progressive Web App (PWA) با مانیفست، سرویس‌ورکر و قابلیت نصب.
|
||||||
|
* درس ۱۵.۱۱: ساخت اپلیکیشن موبایل اندروید و iOS با پوشش هر دو مسیر: مسیر مستقیم Capacitor و مسیر بومی Expo / React Native.
|
||||||
|
* درس ۱۵.۱۲: بسته‌بندی نسخه دسکتاپ کراس‌پلتفرم با استفاده از Tauri پرسرعت و سبک در کنار مقایسه با Electron.
|
||||||
|
3. **تمرکز بر پروژه پورتفولیو:**
|
||||||
|
* تبدیل پورتفولیو به یک اکوسیستم همه‌فن‌حریف و چندپلتفرمه که قابلیت نصب روی گوشی و لپ‌تاپ را داراست.
|
||||||
|
4. **کال‌اوت‌های کوئرا:**
|
||||||
|
* کال‌اوت سبز (`<details class="green">`): انگیزه ورود به مرحله خلق ارزش افزوده پیشرفته و تبدیل شدن به یک معمار همه‌جانبه.
|
||||||
|
|
||||||
|
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||||
|
- مباحث کلان تیم‌های بین‌المللی، ارکستراسیون سازمان‌های بزرگ و تحول نقش برنامه‌نویس (در فصل پایانی ۱۶ بررسی می‌شود).
|
||||||
|
- برنامه‌نویسی سطح پایین سیستم‌های عامل با کد اسمبلی یا C++.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||||
|
|
||||||
|
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| Product Evolution | تکامل پیوسته محصول | فرآیند بازطراحی و ارتقای مداوم نرم‌افزار بر پایه نیازهای نوظهور کاربران و بازار |
|
||||||
|
| Safe Refactoring | بازنویسی امن ساختار کد | اصلاح و تمیزکاری ساختار درونی نرم‌افزار بدون تغییر در رفتار بیرونی آن و بدون ایجاد باگ |
|
||||||
|
| Agentic Workflow | گردش‌کار ایجنتیک خودکار | زنجیره‌ای از تصمیمات و عملکردهای خودمختار هوش مصنوعی برای انجام تسک‌های پیچیده |
|
||||||
|
| PWA (Progressive Web App) | وب‌اپلیکیشن پیش‌رونده | فناوری مدرن وب که به سایت امکان ذخیره آفلاین، دریافت نوتیفیکیشن و نصب شبیه اپ نیتیو را می‌دهد |
|
||||||
|
| Capacitor | موتور رابط کپسیتور | ابزار مدرن تبدیل مستقیم وب‌سایت به اپلیکیشن‌های بومی موبایل اندروید و iOS بدون بازنویسی |
|
||||||
|
| Tauri | فریم‌ورک دسکتاپ تاوری | بسته‌بند فوق‌سبک و امن اپلیکیشن‌های وب به نرم‌افزارهای دسکتاپ ویندوز، مک و لینوکس با وب‌ویو نیتیو |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||||
|
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||||||
|
|
||||||
|
1. **تصویر کاور درس:** `images/cover.png`
|
||||||
|
* **موضوع:** تکامل یک بذر دیجیتال کوچک به یک درخت تنومند نئونی پر از شاخه‌های موبایل، دسکتاپ، PWA و ایجنت‌های هوشمند.
|
||||||
|
2. **نقشه راه جامع فصل ۱۵:** `images/chapter-15-roadmap.png`
|
||||||
|
* **موضوع:** اینفوگرافیک ۱۲ مرحله‌ای فصل ۱۵ با نمادهای فیدبک، ریفکتور، ایجنتیک ورک‌فلو، اتوماسیون، PWA، کپسیتور/اکسپو و تاوری.
|
||||||
|
3. **چرخه تکامل مستمر محصول با هوش مصنوعی:** `images/ai-continuous-evolution-loop.png`
|
||||||
|
* **موضوع:** دیاگرام حلقوی بی‌پایان: تحلیل فیدبک $\rightarrow$ تولید مشخصات $\rightarrow$ کدنویسی ایجنت $\rightarrow$ ریفکتور امن $\rightarrow$ گسترش پلتفرم‌ها.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||||
|
|
||||||
|
1. **تیتر اصلی:** `# اهداف فصل پانزدهم: تکامل محصول با AI؛ از وب‌سایت ساده تا اکوسیستم چندسکویی`
|
||||||
|
2. **مقدمه کوتاه:** چرا نسخه اول محصول فقط نقطه شروع است و هوش مصنوعی چگونه سوخت موشک رشد بعدی شما را تامین می‌کند؟
|
||||||
|
3. **جدول کاور درس**
|
||||||
|
4. **سرفصل‌های طلایی فصل در یک نگاه:** مرور ۱۲ ایستگاه تکامل محصول.
|
||||||
|
5. **جدول نقشه راه یادگیری فصل**
|
||||||
|
6. **معماری کراس‌پلتفرم مدرن:** یک بار بنویسید، در وب، PWA، موبایل و دسکتاپ اجرا کنید.
|
||||||
|
7. **پورتفولیوی شخصی در نقش نماد تسلط تمام‌عیار مهندسی:** شگفت‌زده کردن کارفرمایان با ارائه نسخه اندروید، iOS و دسکتاپ رزومه شخصی.
|
||||||
|
8. **کال‌اوت الهام‌بخش Quera (`<details class="green">`):** ورود به هیجان‌انگیزترین فاز مهندسی ایجنتیک؛ جایی که مرزهای میان مهندس نرم‌افزار، مدیر محصول و طراح محو می‌شود!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||||
|
- [ ] اهداف کلان فصل ۱۵ و مفهوم تکامل محصول به روشنی تبیین شود.
|
||||||
|
- [ ] سرفصل‌های ۱۲ درس‌نامه بعدی با ذکر ابزارهای مصوب (Capacitor, Expo, Tauri, PWA) معرفی گردند.
|
||||||
|
- [ ] رویکرد چندسکویی و گسترش محصول بر بسترهای مختلف تشریح شود.
|
||||||
@@ -0,0 +1,102 @@
|
|||||||
|
# مشخصات درس‌نامه: تحلیل هوشمند بازخوردها و اولویت‌بندی تغییرات (Feedback & Prioritization)
|
||||||
|
- **شناسه در سیلابس:** `L15.2`
|
||||||
|
- **فصل:** فصل ۱۵: تکامل محصول با AI (Ch 15)
|
||||||
|
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||||
|
- **زمان تقریبی مطالعه:** ۱۶ دقیقه
|
||||||
|
- **پیش‌نیازهای مستقیم:** `L15.1` (اهداف فصل پانزدهم)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||||
|
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||||
|
- [ ] **درک کند (Understand):** تفاوت میان بازخوردهای کمی (Quantitative: نرخ پرش، نقشه‌های حرارتی) با بازخوردهای کیفی (Qualitative: نظرات مستقیم کارفرمایان و پیام‌های فرم تماس) را شرح دهد.
|
||||||
|
- [ ] **تحلیل/ارزیابی کند (Evaluate):** درخواست‌های پراکنده و متناقض کاربران را با استفاده از ماتریس ارزش در برابر تلاش (Value vs Effort) و چارچوب RICE اولویت‌بندی کرده و از تله اضافه کردن بی‌رویه فیچرها (Feature Creep) بپرهیزد.
|
||||||
|
- [ ] **درک کند (Understand):** چگونه ضریب «تلاش» (Effort) در عصر وایب کدینگ به شدت کاهش یافته و فیچرهایی که قبلاً هفته‌ها زمان می‌بردند، به دستاوردهای سریع (Quick Wins) تبدیل شده‌اند.
|
||||||
|
- [ ] **ایجاد کند (Create):** یک پرامپت تحلیلی برای ایجنت بنویسد که با دریافت ده‌ها متن پیام، تیکت و لاگ کاربر، بازخوردها را خوشه‌بندی، دسته‌بندی احساسی (Sentiment Analysis) و ۳ فیچر طلایی نسخه بعدی را استخراج نماید.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||||
|
|
||||||
|
### آنچه باید پوشش داده شود (In-Scope):
|
||||||
|
1. **استعاره ساخت قایق موتوری از روی چوب‌پنبه:**
|
||||||
|
* بازخورد کاربر بادبان‌های شماست؛ بدون بادبان در جا می‌زنید، اما اگر باد از هر طرف بوزد و سکان نداشته باشید غرق می‌شوید.
|
||||||
|
2. **منابع جمع‌آوری بازخورد در پروژه پورتفولیو:**
|
||||||
|
* بازخورد رفتاری: ویدیوهای مایکروسافت کلاریتی (کجاها کاربر معطل شد یا دکمه را پیدا نکرد؟).
|
||||||
|
* بازخورد کلامی: پیام‌های دریافتی در فرم تماس، کامنت‌های شبکه‌های اجتماعی و فیدبک مستقیم همکاران.
|
||||||
|
3. **ماتریس ارزش در برابر تلاش (Value vs Effort Matrix):**
|
||||||
|
* دستاوردهای سریع (Quick Wins): ارزش بالا، تلاش کم (بهترین گزینه برای شروع فاز تکامل).
|
||||||
|
* پروژه‌های کلیدی (Major Projects): ارزش بالا، تلاش زیاد (نیازمند برنامه‌ریزی دقیق).
|
||||||
|
* کارهای پرزحمت بی‌فایده (Thankless Tasks): ارزش کم، تلاش زیاد (باید فوراً حذف یا نادیده گرفته شوند).
|
||||||
|
4. **تغییر بنیادین متغیر «تلاش» با هوش مصنوعی:**
|
||||||
|
* کارهایی که در برنامه‌نویسی سنتی «پروژه سنگین» بودند (مانند ساخت فیلتر چندگانه پروژه‌ها یا دارک‌مود پیشرفته)، در وایب کدینگ به دلیل تسلط ایجنت‌ها به «دستاوردهای سریع» تبدیل می‌شوند.
|
||||||
|
5. **استفاده از هوش مصنوعی برای تحلیل متون حجیم بازخورد:**
|
||||||
|
* خوشه‌بندی نظرات کاربران، تشخیص نقاط درد مشترک (Pain Points) و رتبه‌بندی نیازها.
|
||||||
|
6. **جعبه پرامپت طلایی برای تحلیل فیدبک‌ها:**
|
||||||
|
* پرامپت جامع سنتز بازخوردها و خروجی ساختاریافته در قالب فایل `feedback-summary.md`.
|
||||||
|
7. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
|
||||||
|
* کال‌اوت بنفش (`<details class="violet">`): خطر تله «اقلیت پر سر و صدا» (Vocal Minority)؛ یک کاربر پرسروصدا نباید نقشه راه محصول را به بیراهه ببرد.
|
||||||
|
* کال‌اوت سبز (`<details class="green">`): احساس رضایت وقتی یک بازخورد تکراری کارفرما را در کمتر از نیم ساعت با کمک ایجنت برطرف می‌کنید.
|
||||||
|
* کال‌اوت قرمز (`<details class="red">`): تله شلوغی رابط کاربری (Feature Creep)؛ افزودن ۵ دکمه جدید نباید تمیز بودن و سادگی پورتفولیو را نابود کند.
|
||||||
|
|
||||||
|
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||||
|
- نرم‌افزارهای پیچیده مدیریت محصول سازمانی نظیر Jira Align یا Aha.
|
||||||
|
- مطالعات عمیق روان‌سنجی در تحقیقات کاربری تجاری (UX Research آکادمیک).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||||
|
|
||||||
|
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| Feature Creep | تورم ویژگی‌ها | گسترش بی‌رویه و شلوغ شدن محصول با قابلیت‌های کم‌اهمیت که موجب افت کیفیت کلی می‌شود |
|
||||||
|
| Value vs Effort Matrix | ماتریس ارزش در برابر تلاش | ابزار ۲ بعدی اولویت‌بندی تسک‌ها بر اساس اثرگذاری روی کاربر در برابر زحمت پیاده‌سازی |
|
||||||
|
| Quick Wins | دستاوردهای سریع | قابلیت‌هایی با ارزش کاربری بسیار بالا و سختی پیاده‌سازی اندک که رضایت آنی ایجاد می‌کنند |
|
||||||
|
| RICE Framework | چارچوب اولویت‌بندی رایس | مدل فرمول‌محور سنجش ایده‌ها بر اساس ۴ فاکتور: دسترسی، اثر، اطمینان و تلاش |
|
||||||
|
| Vocal Minority | اقلیت پر سر و صدا | گروه کوچکی از کاربران با نظرات تند که بازتاب‌دهنده نیازهای قاطبه کاربران واقعی نیستند |
|
||||||
|
| Sentiment Analysis | تحلیل تمایلات و احساسات | پردازش هوشمند متون نظرات برای درک رضایت، خشم یا سرخوردگی کاربران از یک قابلیت |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||||
|
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||||||
|
|
||||||
|
1. **تصویر کاور درس:** `images/cover.png`
|
||||||
|
* **موضوع:** تابلوی نئونی قیف بازخورد کاربران با نمادهای ستاره، پیام‌های قلبی و تیک‌های سبز که به صورت خوشه‌های منظم مرتب شده‌اند.
|
||||||
|
2. **ماتریس ارزش در برابر تلاش در عصر وایب کدینگ:** `images/value-vs-effort-matrix.png`
|
||||||
|
* **موضوع:** نمودار ۴ خانه‌ای: Quick Wins (سبز پررنگ)، Major Projects (آبی)، Fill-ins (زرد)، و Money Pits (قرمز تیره) با مثال‌های مشخص پورتفولیو.
|
||||||
|
3. **فرآیند خوشه‌بندی بازخوردها توسط مدل هوش مصنوعی:** `images/ai-feedback-clustering-flow.png`
|
||||||
|
* **موضوع:** اینفوگرافیک ورودی نظرات خام کاربران $\rightarrow$ موتور پردازش هوش مصنوعی $\rightarrow$ تفکیک به سه دسته: باگ‌های ظاهری، درخواست امکانات نو، و بهبود سرعت.
|
||||||
|
4. **پیش‌نمایش سند نقشه راه جدید حاصل از فیدبک:** `images/feature-roadmap-card-preview.png`
|
||||||
|
* **موضوع:** کارت دیجیتال شیک با عنوان «آپدیت نسخه ۲.۰ پورتفولیو» و لیست اولویت‌های سه‌گانه منتخب.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||||
|
|
||||||
|
1. **تیتر اصلی:** `# تحلیل هوشمند بازخوردها و اولویت‌بندی تغییرات (Feedback & Prioritization)`
|
||||||
|
2. **مقدمه:** محصول شما منتشر شد و کاربران شروع به استفاده کردند؛ چگونه از میان صدها ایده، دقیقاً همان تغییری را بسازیم که بیشترین لبخند را خلق می‌کند؟
|
||||||
|
3. **جدول کاور درس**
|
||||||
|
4. **استعاره بازخورد به عنوان قطب‌نما، نه فرمان اتومبیل:**
|
||||||
|
* گوش کردن به صدای کاربران هنر است، اما راننده نهایی شما هستید.
|
||||||
|
5. **جمع‌آوری داده‌ها: ترکیب طلایی کلاریتی و پیام‌های دریافتی پورتفولیو:**
|
||||||
|
* بررسی چرایی رها شدن فرم تماس و درخواست کارفرمایان برای دیدن دموهای زنده پروژه‌ها.
|
||||||
|
6. **ماتریس طلایی ارزش در برابر تلاش (Value vs Effort):**
|
||||||
|
* چرا هوش مصنوعی موازنه قدرت را به نفع Quick Wins تغییر داده است؟
|
||||||
|
7. **دام بزرگ Feature Creep و هنر «نه» گفتن به ایده‌های وسوسه‌انگیز:**
|
||||||
|
* حفظ سادگی، مینیمالیسم و هویت اصلی محصول.
|
||||||
|
8. **جعبه پرامپت طلایی: تحلیل و خوشه‌بندی نظرات با ایجنت:**
|
||||||
|
* پرامپت دقیق:
|
||||||
|
> «من این فهرست شامل ۳۰ بازخورد و پیام مختلف از کارفرمایان و بازدیدکنندگان پورتفولیو دارم: [متن بازخوردها]. لطفاً ۱) نظرات را به ۳ دسته موضوعی خوشه‌بندی کن، ۲) بار احساسی و میزان فوریت هر دسته را مشخص نما، و ۳) بر اساس ماتریس Value vs Effort، ۳ ویژگی با بالاترین ارزش و کمترین زحمت پیاده‌سازی را برای نسخه بعدی پیشنهاد بده.»
|
||||||
|
9. **باکس نکته Quera (`<details class="violet">`):** استفاده از چارچوب RICE زمانی که بین دو ویژگی فوق‌العاده مردد هستید.
|
||||||
|
10. **باکس هشدار Quera (`<details class="red">`):** هرگز بر اساس نظر یک فرد منفرد (حتی اگر دوست صمیمی شما باشد) کل ظاهر سایت را تغییر ندهید؛ به الگوهای تکرارشونده نگاه کنید.
|
||||||
|
11. **باکس رضایت‌بخش Quera (`<details class="green">`):** تصمیم‌گیری روشن و تدوین فهرست طلایی ویژگی‌های نسخه بعدی با آرامش خیال کامل.
|
||||||
|
12. **جمع‌بندی درس‌نامه:** اولویت‌بندی شفاف نیازها؛ ورود به ایستگاه تبدیل این ایده‌ها به مشخصات دقیق (Specification) برای ایجنت در درس بعدی.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||||
|
- [ ] تمایز میان بازخوردهای کمی و کیفی به همراه منابع جمع‌آوری تبیین شود.
|
||||||
|
- [ ] ماتریس Value vs Effort با تاکید بر تحول مفهوم «تلاش» در عصر AI تشریح گردد.
|
||||||
|
- [ ] خطرات Feature Creep و شیوه مهار آن به صورت ملموس بیان شود.
|
||||||
|
- [ ] پرامپت تحلیل هوشمند نظرات و استخراج نقشه راه آینده ارائه گردد.
|
||||||
@@ -0,0 +1,101 @@
|
|||||||
|
# مشخصات درس‌نامه: تعریف ویژگی جدید و تدوین مشخصات دقیق (Feature Spec) برای ایجنت
|
||||||
|
- **شناسه در سیلابس:** `L15.3`
|
||||||
|
- **فصل:** فصل ۱۵: تکامل محصول با AI (Ch 15)
|
||||||
|
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||||
|
- **زمان تقریبی مطالعه:** ۱۶ دقیقه
|
||||||
|
- **پیش‌نیازهای مستقیم:** `L15.2` (تحلیل هوشمند بازخوردها و اولویت‌بندی)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||||
|
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||||
|
- [ ] **درک کند (Understand):** تفاوت بنیادین میان «مشخصات پروژه از صفر» (Greenfield Spec) با «مشخصات تغییر روی پروژه زنده» (Delta Spec / Feature Spec) را شرح دهد و بداند چرا اضافه کردن فیچر به کدبیس فعال، نیازمند قیود منفی سخت‌گیرانه است.
|
||||||
|
- [ ] **تحلیل/ارزیابی کند (Evaluate):** خطرات یک پرامپت مبهم یک‌خطی (مانند «تگ‌ها را به پروژه‌ها اضافه کن») را در مقایسه با یک سند مهندسی مشخصات فیچر (شامل داستان کاربر، مرزها، تغییرات دیتابیس و شروط پذیرش) ارزیابی نماید.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** ساختار استاندارد ۶ بخشی سند مشخصات فیچر (User Story, Boundaries, DB Migrations, UI States, Acceptance Criteria, Negative Constraints) را برای قابلیت «فیلتر پروژه‌ها بر اساس تگ‌های مهارتی» تدوین کند.
|
||||||
|
- [ ] **ایجاد کند (Create):** فایل مشخصات را در پوشه `.specs/` پروژه ذخیره کرده و با استفاده از دستورات ارجاع هوشمند (`@specs/...`) ایجنت را برای پیاده‌سازی گام‌به‌گام هدایت نماید.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||||
|
|
||||||
|
### آنچه باید پوشش داده شود (In-Scope):
|
||||||
|
1. **چرا اضافه کردن فیچر به محصول زنده خطرناک‌تر از ساخت اولیه است؟**
|
||||||
|
* خطر شکستن دیتابیس، پاک شدن تصادفی کدهای قبلی توسط ایجنت، یا ایجاد ناسازگاری در کامپوننت‌های سالم.
|
||||||
|
2. **کالبدشکافی سند مشخصات دلتا (The Delta Feature Spec):**
|
||||||
|
* بخش ۱: داستان کاربر (User Story): «به عنوان یک کارفرما، می‌خواهم پروژه‌ها را بر اساس تگ‌های مهارتی فیلتر کنم تا سریعاً نمونه‌کارهای مرتبط با نیاز شرکتم را ببینم».
|
||||||
|
* بخش ۲: محدوده دقیق ورود و خروج (In-Scope vs Out-of-Scope).
|
||||||
|
* بخش ۳: تغییرات پایگاه داده (Schema Migration): افزودن ستون آرایه‌ای `tags text[]` به جدول `projects` در Supabase بدون دست زدن به سایر ستون‌ها.
|
||||||
|
* بخش ۴: تغییرات رابط کاربری (UI Component Specs): طراحی چیپ‌های تگ فیلتر (Chips) با حالت‌های فعال و غیرفعال بالای گرید پروژه‌ها.
|
||||||
|
* بخش ۵: معیارهای پذیرش شفاف (Given-When-Then): «هنگامی که روی تگ Next.js کلیک شد، تنها پروژه‌های دارای این تگ نمایش داده شوند و دکمه ریست ظاهر شود».
|
||||||
|
* بخش ۶: قیود منفی نجات‌بخش (Negative Constraints): «به هیچ وجه چیدمان پنل ادمین را تغییر نده؛ هیچ تغییری در روت‌های داینامیک ایجاد نکن».
|
||||||
|
3. **سازماندهی پوشه `.specs/` در ریشه پروژه:**
|
||||||
|
* مستندسازی تمام تغییرات آینده برای اینکه تاریخچه تکامل محصول برای ایجنت شفاف بماند.
|
||||||
|
4. **جعبه پرامپت طلایی: تغذیه سند مشخصات به کامپوزر ادیتور:**
|
||||||
|
* نحوه فراخوانی `@specs/feature-tags-filter.md` و دستور اجرای مرحله‌ای.
|
||||||
|
5. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
|
||||||
|
* کال‌اوت بنفش (`<details class="violet">`): مفهوم قیود منفی (Negative Constraints)؛ قدرتمندترین سلاح شما برای جلوگیری از خرابکاری ایجنت در بخش‌های سالم کد.
|
||||||
|
* کال‌اوت سبز (`<details class="green">`): پیاده‌سازی بی‌نقص فیچر در اولین تلاش وقتی ایجنت یک سند مشخصات شفاف در دست دارد.
|
||||||
|
* کال‌اوت قرمز (`<details class="red">`): تله دستورات شفاهی کوتاه در چت؛ هرگز بدون نوشتن سند مشخصات وارد تغییرات ساختاری در دیتابیس نشوید.
|
||||||
|
|
||||||
|
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||||
|
- بازنویسی کامل ساختار معماری (در درس ۱۵.۵ ریفکتورینگ بررسی می‌شود).
|
||||||
|
- تعریف مستندات نیازمندی‌های پروژه‌های شرکتی صد صفحه‌ای (BRD سازمانی).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||||
|
|
||||||
|
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| Feature Specification | مشخصات فنی ویژگی | سند ساختاریافته تشریح‌کننده هدف، رفتار، تغییرات دیتابیس و شروط پذیرش یک قابلیت جدید |
|
||||||
|
| Delta Spec | مشخصات تغییرات دلتا | سندی که تنها تغییرات، تفاوت‌ها و افزونه‌ها را نسبت به کدبیس موجود توصیف می‌کند |
|
||||||
|
| Negative Constraints | قیود و شروط منفی | دستورات بازدارنده‌ای که به ایجنت صراحتاً دیکته می‌کنند به کدام بخش‌های کد نباید دست بزند |
|
||||||
|
| Greenfield vs Brownfield | پروژه نوساز در برابر بازسازی | تمایز میان توسعه از نقطه صفر با توسعه و افزودن فیچر به کدهای از پیش موجود و فعال |
|
||||||
|
| Schema Migration | مهاجرت اسکیمای داده | ایجاد تغییرات ایمن و برگشت‌پذیر در جداول دیتابیس بدون از دست رفتن داده‌های قبلی |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||||
|
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||||||
|
|
||||||
|
1. **تصویر کاور درس:** `images/cover.png`
|
||||||
|
* **موضوع:** نقشه مهندسی دیجیتال نئونی که پیوست شدن یک بال جدید و مدرن به یک ساختمان مستحکم موجود را بدون تخریب دیوارها نشان می‌دهد.
|
||||||
|
2. **آناتومی ۶ ستون سند مشخصات دلتا (Delta Spec):** `images/delta-spec-anatomy.png`
|
||||||
|
* **موضوع:** اینفوگرافیک ۶ بخشی: داستان کاربر، محدوده، تغییر دیتابیس، طراحی UI، شروط تایید و قیود منفی.
|
||||||
|
3. **خطای پرامپت مبهم در برابر موفقیت سند مشخصات:** `images/vague-prompt-vs-feature-spec.png`
|
||||||
|
* **موضوع:** کاریکاتور مقایسه‌ای: پرامپت یک‌خطی که صفحه اصلی را به هم می‌ریزد در برابر سند مشخصات که با جراحی تمیز فقط کامپوننت فیلتر را اضافه می‌کند.
|
||||||
|
4. **پیش‌نمایش قابلیت فیلتر تگ‌ها در صفحه پروژه‌ها:** `images/project-tags-filter-ui-preview.png`
|
||||||
|
* **موضوع:** اسکرین‌شات از بالای گرید پورتفولیو با چیپ‌های بنفش رنگ Next.js, Supabase, Tailwind و نمایش پروژه‌های فیلترشده.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||||
|
|
||||||
|
1. **تیتر اصلی:** `# تعریف ویژگی جدید و تدوین مشخصات دقیق (Feature Spec) برای ایجنت`
|
||||||
|
2. **مقدمه:** چگونه بدون اینکه کدهای قبلی پروژه به هم بریزد، یک فیچر جدید را مثل یک جراح ماهر به قلب محصول اضافه کنیم؟
|
||||||
|
3. **جدول کاور درس**
|
||||||
|
4. **استعاره بازسازی آپارتمان مسکونی در برابر ساخت زمین خالی:**
|
||||||
|
* خانواده داخل خانه زندگی می‌کنند؛ نباید لوله اصلی آب را قطع کنید یا دیوارهای حامل را تخریب نمایید!
|
||||||
|
5. **ارکان ۶ گانه سند مشخصات ویژگی (Feature Spec) در وایب کدینگ:**
|
||||||
|
* شرح گام‌به‌گام هر بخش با مثال ملموس پورتفولیو.
|
||||||
|
6. **مطالعه موردی: افزودن فیلتر تگ‌های مهارتی به پورتفولیو:**
|
||||||
|
* نوشتن کامل فایل `.specs/feature-project-tags.md`.
|
||||||
|
7. **جادوی قیود منفی (Negative Constraints):**
|
||||||
|
* چطور جلوی دستکاری ناخواسته فایل‌های حساس توسط ایجنت را با ۲ خط متن بگیریم.
|
||||||
|
8. **اجرای گام‌به‌گام با ارجاع به سند در ادیتور:**
|
||||||
|
* استفاده از `@specs` در کامپوزر Cursor یا Claude Code.
|
||||||
|
9. **جعبه پرامپت طلایی: پیاده‌سازی امن فیچر با استناد به سند مشخصات:**
|
||||||
|
* پرامپت دقیق:
|
||||||
|
> «من سند مشخصات فیچر جدید را در `@specs/feature-project-tags.md` نوشته‌ام. لطفاً ابتدا این سند را به دقت بخوان و ۱) فقط تغییرات دیتابیس را پیشنهاد بده، ۲) پس از تایید من، کامپوننت فیلتر را بر اساس دیزاین سیستم بساز و ۳) تمام قیود منفی ذکر شده را به شدت رعایت کن.»
|
||||||
|
10. **باکس نکته Quera (`<details class="violet">`):** استفاده از اسکریپت‌های SQL اضافه کردن ستون به صورت `ADD COLUMN IF NOT EXISTS` برای جلوگیری از خطای اجرای مجدد.
|
||||||
|
11. **باکس هشدار Quera (`<details class="red">`):** هرگز از کلمات کلی مثل «یه فیلتر خوشگل برای پروژه‌ها درست کن» استفاده نکنید؛ هرچه توصیف مبهم‌تر باشد، احتمال باگ‌های پس‌رفتی بیشتر است.
|
||||||
|
12. **باکس رضایت‌بخش Quera (`<details class="green">`):** مشاهده کارکرد بی‌نقص فیلتر تگ‌ها در سایت بدون اینکه حتی یک باگ کوچک در سایر بخش‌ها ایجاد شده باشد.
|
||||||
|
13. **جمع‌بندی درس‌نامه:** تسلط بر تدوین مشخصات افزونه‌ها؛ ورود به تکنیک‌های کاوش و درک کدهای موجود توسط ایجنت در درس بعدی.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||||
|
- [ ] تمایز میان Greenfield Spec و Brownfield Delta Spec به روشنی بیان شود.
|
||||||
|
- [ ] ساختار ۶ بخشی سند مشخصات فیچر به همراه مثال کاربردی فیلتر تگ‌ها ارائه گردد.
|
||||||
|
- [ ] مفهوم و اهمیت حیاتی قیود منفی (Negative Constraints) تبیین شود.
|
||||||
|
- [ ] پرامپت ارجاع سند مشخصات به کامپوزر در متن درس گنجانده شود.
|
||||||
@@ -0,0 +1,100 @@
|
|||||||
|
# مشخصات درس‌نامه: کالبدشکافی و کاوش در Codebase با ایجنت‌های هوش مصنوعی
|
||||||
|
- **شناسه در سیلابس:** `L15.4`
|
||||||
|
- **فصل:** فصل ۱۵: تکامل محصول با AI (Ch 15)
|
||||||
|
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||||
|
- **زمان تقریبی مطالعه:** ۱۶ دقیقه
|
||||||
|
- **پیش‌نیازهای مستقیم:** `L15.3` (تعریف ویژگی جدید و تدوین مشخصات دقیق)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||||
|
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||||
|
- [ ] **درک کند (Understand):** چگونه مدل‌های زبانی مجهز به پنجره‌های زمینه غول‌پیکر (Context Windows) و نمایه‌سازی برداری (Vector Indexing) به عنوان باستان‌شناسان کدهای نرم‌افزار عمل می‌کنند.
|
||||||
|
- [ ] **تحلیل/ارزیابی کند (Evaluate):** جریان داده و چرخه حیات یک رویداد کامل در سیستم (نظیر مسیر ثبت رزرو از کلیک تا پیامک) را با پرسشگری مهندسی از ایجنت ردگیری و تحلیل کند.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** قابلیت جستجوی معنایی در کل مخزن (`@codebase` در Cursor و ابزارهای تحلیلی Antigravity / Claude Code) را برای کشف فایل‌های مرتبط و تحلیل اثرگذاری تغییرات (Impact Analysis) به کار گیرد.
|
||||||
|
- [ ] **ایجاد کند (Create):** نمودارهای تعاملی و فلوچارت‌های زنده‌ی معماری پروژه را به صورت خودکار از روی کدهای واقعی با پرامپت‌نویسی استخراج کند.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||||
|
|
||||||
|
### آنچه باید پوشش داده شود (In-Scope):
|
||||||
|
1. **معمای فراموشی کدها: «این فایل ۳ هفته پیش چطور کار می‌کرد؟»:**
|
||||||
|
* حتی سازنده اصلی پروژه پس از چند هفته جزییات دقیق اتصالات توابع و روت‌ها را فراموش می‌کند؛ چه رسد به پیوستن به پروژه‌ای که فرد دیگری نوشته است!
|
||||||
|
2. **پشت صحنه ایندکس کردن کدهای پروژه (`@codebase` Indexing):**
|
||||||
|
* تبدیل قطعات کد به بردارهای معنایی (Embeddings) و امکان جستجوی مفهومی؛ مثلاً جستجوی «کجا پیامک ارسال می‌شود؟» به جای جستجوی کلمه به کلمه.
|
||||||
|
3. **تکنیک پرسشگری مهندسی از ایجنت (Architectural Inquiries):**
|
||||||
|
* پرسش ۱ (ردگیری چرخه حیات): «چرخه حیات یک رزرو مشاوره را از لحظه کلیک کاربر تا ثبت در Supabase، اتصال به زرین‌پال و ارسال پیامک کاوه‌نگار گام‌به‌گام با ذکر نام فایل‌ها و توابع توضیح بده.»
|
||||||
|
* پرسش ۲ (تحلیل اثر تغییر - Impact Analysis): «اگر ساختار فیلد `slug` را در جدول پروژه‌ها تغییر دهم، دقیقاً کدام کامپوننت‌ها و روت‌ها در خطر شکستن هستند؟»
|
||||||
|
* پرسش ۳ (نقشه‌برداری وابستگی‌ها): «کدام فایل‌ها از تابع `createClient` سوپابیس استفاده می‌کنند؟»
|
||||||
|
4. **تولید نمودارهای زنده از دل کدهای موجود:**
|
||||||
|
* درخواست از ایجنت برای تولید دیاگرام توالی (Sequence Diagram) با فرمت Mermaid برای درک سریع جریان احراز هویت.
|
||||||
|
5. **جعبه پرامپت طلایی برای کاوش و درک کدهای پروژه:**
|
||||||
|
* پرامپت جامع اسکن معماری و ایجاد سند `architecture-overview.md`.
|
||||||
|
6. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
|
||||||
|
* کال‌اوت بنفش (`<details class="violet">`): مفهوم پنجره زمینه بزرگ (Large Context)؛ تفاوت توانایی پردازش همزمان صدها فایل در مدل‌های روز در مقایسه با نسل‌های اولیه.
|
||||||
|
* کال‌اوت سبز (`<details class="green">`): توانایی شگفت‌انگیز برای ورود به هر ریپازیتوری اوپن‌سورس غریبه در گیت‌هاب و درک معماری آن در کمتر از ۱۵ دقیقه.
|
||||||
|
* کال‌اوت قرمز (`<details class="red">`): پرهیز از سوالات کلی و مبهم مانند «کل کدها رو توضیح بده»؛ همیشه سوالات مشخص با سناریوهای کاربردی بپرسید تا پاسخ دقیق بگیرید.
|
||||||
|
|
||||||
|
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||||
|
- مباحث ریاضیات و جبر خطی نحوه تولید بردارها در شبکه‌های عصبی (Vector Math).
|
||||||
|
- پیاده‌سازی دستی دیتابیس‌های برداری Pinecone یا Chroma از صفر.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||||
|
|
||||||
|
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| Codebase Comprehension | درک جامع ساختار کدبیس | فرآیند شناخت ساختار معماری، وابستگی‌ها و جریان داده در یک پروژه نرم‌افزاری بزرگ |
|
||||||
|
| Impact Analysis | تحلیل اثرگذاری تغییرات | پیش‌بینی دقیق تمام فایل‌ها و ماژول‌هایی که با تغییر یک تابع یا اسکیمای دیتابیس تحت‌تاثیر قرار می‌گیرند |
|
||||||
|
| Semantic Code Search | جستجوی معنایی کد | یافتن توابع و منطق‌های برنامه بر اساس مفهوم و کارکرد آنها، نه صرفاً تطابق نام کلمات |
|
||||||
|
| Context Window | پنجره کانتکست مدل | حجم داده و تعداد کدهایی که مدل زبانی می‌تواند در یک لحظه در حافظه خود نگه دارد |
|
||||||
|
| Sequence Diagram | دیاگرام توالی | نمودار زمانی نمایش‌دهنده ترتیب تبادل پیام‌ها و درخواست‌ها میان اجزای مختلف سیستم |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||||
|
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||||||
|
|
||||||
|
1. **تصویر کاور درس:** `images/cover.png`
|
||||||
|
* **موضوع:** ذره‌بین اشعه ایکس دیجیتال نئونی که لایه‌های تو در توی کدهای یک پروژه نرم‌افزاری را روشن و شفاف می‌کند.
|
||||||
|
2. **پشت صحنه ایندکس معنایی کدهای پروژه:** `images/codebase-indexing-architecture.png`
|
||||||
|
* **موضوع:** دیاگرام فرآیند: فایل‌های پروژه $\rightarrow$ تولید بردارها $\rightarrow$ دیتابیس برداری محلی ادیتور $\rightarrow$ پاسخگویی فوق‌سریع به پرامپت `@codebase`.
|
||||||
|
3. **نمودار توالی جریان داده رزرو در پورتفولیو:** `images/booking-sequence-diagram.png`
|
||||||
|
* **موضوع:** دیاگرام توالی Mermaid رندرشده: کاربر $\rightarrow$ فرم رزرو $\rightarrow$ Server Action $\rightarrow$ Supabase $\rightarrow$ زرین‌پال $\rightarrow$ کاوه‌نگار.
|
||||||
|
4. **نمایش پاسخ تحلیلی ایجنت به سوال اثرگذاری تغییر:** `images/ai-impact-analysis-chat.png`
|
||||||
|
* **موضوع:** اسکرین‌شات از چت‌باکس Cursor که لیست فایل‌های در معرض خطر تغییر ستون دیتابیس را با نشانه‌گذاری قرمز و سبز ردیف کرده است.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||||
|
|
||||||
|
1. **تیتر اصلی:** `# کالبدشکافی و کاوش در Codebase با ایجنت‌های هوش مصنوعی`
|
||||||
|
2. **مقدمه:** چگونه در پروژه‌ای با ده‌ها پوشه و هزاران خط کد، در عرض ۲ دقیقه بفهمیم هر قطعه دقیقاً چه وظیفه‌ای دارد؟
|
||||||
|
3. **جدول کاور درس**
|
||||||
|
4. **استعاره استخدام یک راهنمای محلی در شهری ناشناخته:**
|
||||||
|
* به جای سرگردانی در کوچه‌ها، از راهنمایی که تمام نقشه شهر را از حفظ است آدرس دقیق را بپرسید.
|
||||||
|
5. **قدرت جادویی نمایه برداری و جستجوی معنایی (`@codebase`):**
|
||||||
|
* چطور ادیتور بدون کپی کردن دستی فایل‌ها، تمام پروژه شما را می‌فهمد.
|
||||||
|
6. **هنر مصاحبه معمارانه با ایجنت:**
|
||||||
|
* ۳ فرمول پرامپت طلایی: ردگیری جریان داده، تحلیل اثر تغییر، و کشف منطق‌های پنهان.
|
||||||
|
7. **مطالعه موردی: استخراج چرخه کامل پرداخت و پیامک در پورتفولیو:**
|
||||||
|
* مشاهده خروجی گام‌به‌گام ایجنت و راستی‌آزمایی آن با فایل‌های واقعی.
|
||||||
|
8. **رسم خودکار دیاگرام‌های توالی با Mermaid:**
|
||||||
|
* دستور به ایجنت برای تبدیل منطق پنهان کدها به نقشه گرافیکی خوانا.
|
||||||
|
9. **جعبه پرامپت طلایی: تحلیل اثرگذاری تغییرات قبل از دستکاری کد:**
|
||||||
|
* پرامپت دقیق:
|
||||||
|
> «من می‌خواهم فیلد `price` را در جدول جلسات مشاوره به `amount_toman` تغییر نام دهم. لطفاً کل `@codebase` را تحلیل کن و ۱) تمام فایل‌ها، کامپوننت‌ها، تایپ‌ها و روت‌هایی که تحت‌تاثیر این تغییر قرار می‌گیرند را لیست کن، ۲) خطرات احتمالی در فرانت‌اند و درگاه پرداخت را شرح بده، و ۳) ترتیب امن اعمال این تغییر را مرحله‌بندی نما.»
|
||||||
|
10. **باکس نکته Quera (`<details class="violet">`):** کلید میانبر `@docs` برای اضافه کردن مستندات فریم‌ورک‌های خارجی در کنار `@codebase` خودی.
|
||||||
|
11. **باکس هشدار Quera (`<details class="red">`):** ایجنت‌ها ممکن است در پروژه‌های بسیار بزرگ فایل‌هایی با ایمپورت‌های داینامیک را از قلم بیندازند؛ همیشه از ابزار جستجوی سراسری متنی (Grep) به عنوان مکمل استفاده کنید.
|
||||||
|
12. **باکس رضایت‌بخش Quera (`<details class="green">`):** احساس تسلط مطلق بر کل پروژه؛ انگار که خودتان تک‌تک خطوط را از حفظ هستید.
|
||||||
|
13. **جمع‌بندی درس‌نامه:** تسلط بر تحلیل کدهای موجود؛ ورود به حوزه حساس و حیاتی بازنویسی و ریفکتورینگ امن (Safe Refactoring) در درس بعدی.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||||
|
- [ ] نحوه کارکرد ایندکس معنایی کدهای پروژه (`@codebase`) تشریح شود.
|
||||||
|
- [ ] تکنیک‌های تحلیل چرخه حیات داده و تحلیل اثرگذاری تغییرات (Impact Analysis) آموزش داده شود.
|
||||||
|
- [ ] شیوه تولید خودکار دیاگرام‌های معماری با Mermaid از روی کدهای پروژه ارائه گردد.
|
||||||
|
- [ ] پرامپت‌های مهندسی کاوش در کدهای موجود به همراه مثال‌های ملموس لحاظ شود.
|
||||||
@@ -0,0 +1,105 @@
|
|||||||
|
# مشخصات درس‌نامه: بهبود ساختار کد، پاک‌سازی و ریفکتورینگ امن (Safe Refactoring) با هوش مصنوعی
|
||||||
|
- **شناسه در سیلابس:** `L15.5`
|
||||||
|
- **فصل:** فصل ۱۵: تکامل محصول با AI (Ch 15)
|
||||||
|
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||||
|
- **زمان تقریبی مطالعه:** ۱۸ دقیقه
|
||||||
|
- **پیش‌نیازهای مستقیم:** `L15.4` (کالبدشکافی و کاوش در Codebase با ایجنت‌ها)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||||
|
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||||
|
- [ ] **درک کند (Understand):** مفهوم ریفکتورینگ (Refactoring: اصلاح ساختار درونی بدون تغییر در رفتار بیرونی سیستم) را شرح دهد و بداند چرا کدهای شتاب‌زده MVP نیازمند بازطراحی و پاک‌سازی هستند.
|
||||||
|
- [ ] **تحلیل/ارزیابی کند (Evaluate):** نشانه‌های بدبویی کد (Code Smells: کامپوننت‌های غول‌پیکر چندصدخطی، کدهای کپی-پیست تکراری، و تایپ‌های مجهول `any`) را در پروژه شناسایی و ارزیابی کند.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** پروتکل ۴ مرحله‌ای ریفکتورینگ امن (سپر تست قبلی $\rightarrow$ پرامپت ایزوله اتمیک $\rightarrow$ بازبینی Diff $\rightarrow$ بیلد مجدد) را برای شکستن کامپوننت‌های بزرگ به ماژول‌های تمیز پیاده کند.
|
||||||
|
- [ ] **ایجاد کند (Create):** یک کامپوننت ۳۰۰ خطی پنل مدیریت پورتفولیو را با هدایت ایجنت به ۴ ساب‌کامپوننت خوانا، ماژولار و تست‌پذیر تفکیک نماید.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||||
|
|
||||||
|
### آنچه باید پوشش داده شود (In-Scope):
|
||||||
|
1. **استعاره تمیزکاری و مرتب‌سازی ابزارهای کارگاه:**
|
||||||
|
* در هنگام ساخت اولیه میخ‌ها و اره‌ها کف کارگاه می‌ریزند؛ پس از ساخت، ابزارها را روی دیوار می‌چینید تا در کارهای بعدی مانع پای شما نشوند.
|
||||||
|
2. **شکار «بوی بد کد» (Code Smells) در پروژه‌های ساخته‌شده با AI:**
|
||||||
|
* بوی بد ۱: کامپوننت‌های خدای‌گونه (God Components)؛ یک فایل ۴۰۰ خطی که هم دیتابیس می‌خواند، هم فرم رندر می‌کند، هم مودال باز می‌کند و هم انیمیشن دارد!
|
||||||
|
* بوی بد ۲: منطق تکراری کپی-پیست‌شده (Duplicate Queries)؛ نوشتن کوئری‌های یکسان سوپابیس در ۵ صفحه مختلف به جای یک تابع واحد.
|
||||||
|
* بوی بد ۳: اعدام تایپ‌اسکریپت با کلمه `any`؛ تنبلی در تعریف تایپ داده‌ها که امنیت کد را از بین می‌برد.
|
||||||
|
3. **پروتکل ۴ مرحله‌ای ریفکتورینگ ایمن با ایجنت:**
|
||||||
|
* مرحله ۱ (سپر دفاعی): اطمینان از پاس شدن تست‌های Vitest/Playwright و اجرای بیلد سالم قبل از هرگونه تغییر.
|
||||||
|
* مرحله ۲ (پرامپت اتمیک ایزوله): درخواست جراحی محدود: «فقط این فایل را بشکن؛ به هیچ فایل دیگری دست نزن و نام Props را تغییر نده».
|
||||||
|
* مرحله ۳ (بازبینی خط‌به‌خط Git Diff): بررسی اینکه آیا منطق یا استایلی ناخواسته حذف یا مفقود شده است یا خیر.
|
||||||
|
* مرحله ۴ (تست تایید سلامت): اجرای مجدد تست‌ها و بیلد نهایی برای اطمینان از صفر بودن خطای پس‌رفتی.
|
||||||
|
4. **کارگاه عملی: جراحی و ماژولار کردن جدول مدیریت پروژه‌ها:**
|
||||||
|
* تبدیل فایل متورم `AdminProjectsTable.tsx` به:
|
||||||
|
- `ProjectRow.tsx` (رندر هر سطر)
|
||||||
|
- `DeleteProjectDialog.tsx` (مودال حذف)
|
||||||
|
- `ProjectStatusBadge.tsx` (بج وضعیت)
|
||||||
|
- `hooks/useProjects.ts` (هوک اختصاصی مدیریت استیت‌ها).
|
||||||
|
5. **جعبه پرامپت طلایی برای ریفکتورینگ تمیز:**
|
||||||
|
* پرامپت تخصصی بازنویسی با شرط حفظ ۱۰۰٪ رفتار قبلی.
|
||||||
|
6. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
|
||||||
|
* کال‌اوت بنفش (`<details class="violet">`): قانون طلایی مارتین فاولر؛ ریفکتورینگ نباید یک پروژه ۶ ماهه جداگانه باشد، بلکه عادتی پیوسته در حین اضافه کردن هر فیچر جدید است.
|
||||||
|
* کال‌اوت سبز (`<details class="green">`): لذت دیدن کدهای تمیز، خوانا و کوتاه که هر برنامه‌نویس ارشدی از دیدن آن شگفت‌زده می‌شود.
|
||||||
|
* کال‌اوت قرمز (`<details class="red">`): اشتباه فاجعه‌بار؛ هرگز به ایجنت نگویید: «کل پروژه را ریفکتور کن!»؛ این پرامپت به توهمات گسترده و شکستن کل برنامه منجر می‌شود.
|
||||||
|
|
||||||
|
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||||
|
- مهاجرت از فریم‌ورکی به فریم‌ورک دیگر (مثلاً Next.js به Remix یا Vue).
|
||||||
|
- بازطراحی کل اسکیمای دیتابیس که نیازمند از دست رفتن داده‌های پروداکشن باشد.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||||
|
|
||||||
|
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| Refactoring | بازنویسی و بهسازی ساختار | بهبود خوانایی، سادگی و نگهداری‌پذیری کدها بدون تغییر در عملکرد ظاهری آنها |
|
||||||
|
| Code Smell | نشانه‌های بدبویی کد | ساختارها و الگوهای نامناسب در کد که نشان‌دهنده نقص در طراحی یا پتانسیل بروز باگ در آینده هستند |
|
||||||
|
| God Component | کامپوننت همه‌کاره غول‌پیکر | کامپوننتی تک‌افتاده که وظایف بیش از حد متعددی را بر عهده گرفته و فهم و نگهداری آن کابوس است |
|
||||||
|
| Single Responsibility (SRP) | اصل تک‌مسئولیتی | اصل بنیادین مهندسی که می‌گوید هر ماژول یا کامپوننت فقط و فقط باید یک وظیفه مشخص داشته باشد |
|
||||||
|
| Atomic Refactoring | بازنویسی اتمیک و دانه‌دانه | اصلاح پله‌پله و ایزوله بخش‌های کوچک کد برای پیشگیری از بروز خطاهای آبشاری در پروژه |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||||
|
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||||||
|
|
||||||
|
1. **تصویر کاور درس:** `images/cover.png`
|
||||||
|
* **موضوع:** سیم‌پیچی‌های آشفته و گره‌خورده دیجیتال که توسط بازوهای نوری ایجنت باز شده و به کابل‌های مرتب و موازی درخشان تبدیل می‌شوند.
|
||||||
|
2. **شکستن یک کامپوننت غول‌پیکر به ماژول‌های تمیز:** `images/god-component-decomposition.png`
|
||||||
|
* **موضوع:** دیاگرام ساختاری: فایل ۴۰۰ خطی بزرگ در چپ $\rightarrow$ فلش بازطراحی $\rightarrow$ تفکیک به ۴ فایل کوچک، هوک و کامپوننت مستقل در راست.
|
||||||
|
3. **چرخه ۴ مرحله‌ای ریفکتورینگ امن:** `images/safe-refactoring-loop.png`
|
||||||
|
* **موضوع:** فلوچارت محافظتی: تست سبز قبلی $\rightarrow$ پرامپت ایزوله $\rightarrow$ بررسی Git Diff $\rightarrow$ راستی‌آزمایی با بیلد موفق.
|
||||||
|
4. **تفاوت Git Diff یک ریفکتور موفق:** `images/refactored-git-diff-view.png`
|
||||||
|
* **موضوع:** اسکرین‌شات از نمایش خطوط پاک‌شده اضافه و جایگزینی با ایمپورت‌های ماژولار و بسیار کوتاه.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||||
|
|
||||||
|
1. **تیتر اصلی:** `# بهبود ساختار کد، پاک‌سازی و ریفکتورینگ امن (Safe Refactoring) با هوش مصنوعی`
|
||||||
|
2. **مقدمه:** کدهایتان کار می‌کند، اما شبیه یک کمد لباس به هم ریخته است که هر بار درش را باز می‌کنید چیزی روی سرتان می‌افتد؟ وقت یک خانه‌تکانی لذت‌بخش مهندسی است!
|
||||||
|
3. **جدول کاور درس**
|
||||||
|
4. **تعریف ریفکتورینگ: تغییر لباس بدون تغییر ماهیت:**
|
||||||
|
* چرا کاربر نباید هیچ تفاوتی در ظاهر حس کند، اما شما در توسعه آینده ۱۰ برابر سریع‌تر می‌شوید.
|
||||||
|
5. **شکار ۳ بوی بد رایج در پروژه‌های وایب کدینگ:**
|
||||||
|
* کامپوننت‌های همه‌کاره (God Components)، کدهای تکراری، و فرار از تایپ‌های دقیق.
|
||||||
|
6. **پروتکل ۴ مرحله‌ای جراحی امن کد:**
|
||||||
|
* تست سلامت $\rightarrow$ پرامپت اتمیک $\rightarrow$ کنترل گیت‌دیف $\rightarrow$ تایید نهایی با بیلد.
|
||||||
|
7. **مطالعه موردی: جراحی جدول ۴۰۰ خطی پنل مدیریت پورتفولیو:**
|
||||||
|
* تفکیک عملی به ساب‌کامپوننت‌های `ProjectRow`, `DeleteDialog` و ساخت هوک `useProjects`.
|
||||||
|
8. **جعبه پرامپت طلایی: ریفکتورینگ اتمیک با ایجنت هوش مصنوعی:**
|
||||||
|
* پرامپت دقیق:
|
||||||
|
> «من می‌خواهم فایل `AdminProjectsTable.tsx` را ریفکتور کنم. بدون تغییر در هیچ‌یک از قابلیت‌های فعلی و بدون تغییر نام Props، ۱) این فایل را به ۳ کامپوننت تک‌مسئولیتی در پوشه `components/admin/` تقسیم کن، ۲) منطق مدیریت وضعیت‌ها را به یک کاستوم هوک در `hooks/useProjects.ts` منتقل کن، و ۳) تایپ‌های دقیق تایپ‌اسکریپت بدون استفاده از any برای آن بنویس.»
|
||||||
|
9. **باکس نکته Quera (`<details class="violet">`):** استفاده از تکنیک Boy Scout Rule: «کدبیس را همیشه تمیزتر از آنچه تحویل گرفته‌اید تحویل دهید».
|
||||||
|
10. **باکس هشدار Quera (`<details class="red">`):** هرگز فیچر جدید را همزمان با ریفکتورینگ کد قبلی ننویسید! این دو کار باید در دو کامیت کاملاً مجزا انجام شوند تا در صورت بروز باگ، تفکیک امکان‌پذیر باشد.
|
||||||
|
11. **باکس رضایت‌بخش Quera (`<details class="green">`):** باز کردن فایل اصلی پروژه و دیدن کاهش حجم کد از ۴۰۰ خط به ۵۰ خط بسیار تمیز و سازمان‌یافته.
|
||||||
|
12. **جمع‌بندی درس‌نامه:** مجهز شدن به سلاح پاک‌سازی کد؛ ورود به جهان هیجان‌انگیز قابلیت‌های پیشرفته هوش مصنوعی (Semantic Search و خلاصه‌سازها) در درس بعدی.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||||
|
- [ ] مفهوم ریفکتورینگ و چرایی اهمیت آن در پروژه‌های فعال تبیین شود.
|
||||||
|
- [ ] نشانه‌های بدبویی کد (Code Smells) با مثال‌های ملموس پورتفولیو شرح داده شوند.
|
||||||
|
- [ ] پروتکل ۴ مرحله‌ای ریفکتورینگ امن به همراه پرامپت‌های اتمیک ارائه گردد.
|
||||||
|
- [ ] کارگاه عملی شکستن کامپوننت بزرگ به کامپوننت‌های ماژولار در متن درس گنجانده شود.
|
||||||
@@ -0,0 +1,101 @@
|
|||||||
|
# مشخصات درس‌نامه: تزریق قابلیت‌های پیشرفته هوش مصنوعی؛ جستجوی معنایی (Vector Search) و تولید هوشمند محتوا
|
||||||
|
- **شناسه در سیلابس:** `L15.6`
|
||||||
|
- **فصل:** فصل ۱۵: تکامل محصول با AI (Ch 15)
|
||||||
|
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||||
|
- **زمان تقریبی مطالعه:** ۲۰ دقیقه
|
||||||
|
- **پیش‌نیازهای مستقیم:** `L15.5` (بهبود ساختار کد و ریفکتورینگ امن)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||||
|
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||||
|
- [ ] **درک کند (Understand):** تفاوت میان «جستجوی کلیدواژه‌ای سنتی» (Keyword Search) و «جستجوی معنایی برداری» (Semantic Vector Search) را شرح دهد و بداند چرا کاربری که کلمه «بانک اطلاعاتی» را سرچ می‌کند باید پروژه‌های برچسب‌خورده با «PostgreSQL» را ببیند.
|
||||||
|
- [ ] **تحلیل/ارزیابی کند (Evaluate):** نحوه کارکرد اکستنشن **pgvector** در پایگاه داده PostgreSQL و پایگاه داده Supabase را برای محاسبه شباهت کسینوسی (Cosine Similarity) میان بردارها ارزیابی کند.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** یک ویژگی هوشمند در پنل ادمین پیاده کند که با دریافت لینک گیت‌هاب پروژه، توضیحات جذاب فارسی، خلاصه فنی و تگ‌های سئو را به صورت خودکار با خروجی ساختاریافته JSON تولید نماید.
|
||||||
|
- [ ] **ایجاد کند (Create):** قابلیت جستجوی هوشمند در میان پروژه‌ها و مهارت‌های پورتفولیو را با مدل‌های تولید بردار (Text Embeddings) راه‌اندازی و به رابط کاربری متصل کند.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||||
|
|
||||||
|
### آنچه باید پوشش داده شود (In-Scope):
|
||||||
|
1. **فراتر از چت‌بات‌های ساده: هوش مصنوعی نامرئی در بافت محصول:**
|
||||||
|
* هوش مصنوعی فقط چت‌باکس گوشه صفحه نیست؛ می‌تواند موتور جستجو، دستیار تولید محتوا و پالایشگر داده‌های محصول باشد.
|
||||||
|
2. **کالبدشکافی جستجوی معنایی و بردارها (Vector Embeddings):**
|
||||||
|
* چرا جستجوی متنی معمولی شکست می‌خورد؟ (عدم تطابق کلمات هم‌معنی).
|
||||||
|
* بردار چیست؟ تبدیل معنای هر پروژه به یک رشته عدد در فضا (مثلاً ۱۵۳۶ بُعد) که پروژه‌های مشابه در نزدیکی هم قرار می‌گیرند.
|
||||||
|
3. **فعال‌سازی اکستنشن قدرتمند `pgvector` در Supabase:**
|
||||||
|
* فعال‌سازی با دستور تک‌خطی: `create extension if not exists vector;`.
|
||||||
|
* افزودن ستون `embedding vector(1536)` به جدول پروژه‌ها.
|
||||||
|
* نوشتن تابع جستجوی شباهت کسینوسی در SQL با عملگر `<=>`.
|
||||||
|
4. **تولید خودکار شناسنامه پروژه در پنل مدیریت با AI:**
|
||||||
|
* فیچر: ادمین آدرس گیت‌هاب یا چند خط یادداشت خام تایپ می‌کند $\rightarrow$ دکمه «تکمیل هوشمند با AI» را می‌زند $\rightarrow$ مدل با قابلیت Structured Outputs / JSON Schema یک پکیج کامل شامل: تیتر جذاب، ۳ پاراگراف توضیحات فارسی روان، دسته‌بندی و لیست تگ‌ها را استخراج و فیلدهای فرم را خودکار پر می‌کند!
|
||||||
|
5. **خروجی ساختارمند با JSON Schema (پرهیز از پرحرفی مدل):**
|
||||||
|
* الزام مدل زبانی به برگرداندن یک شیء JSON بدون احوالپرسی یا توضیحات اضافه.
|
||||||
|
6. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
|
||||||
|
* کال‌اوت بنفش (`<details class="violet">`): مفهوم شباهت کسینوسی (Cosine Similarity)؛ چگونگی سنجش زاویه میان دو بردار معنایی در فضای چندبُعدی.
|
||||||
|
* کال‌اوت سبز (`<details class="green">`): هزینه ناچیز مدل‌های Embedding (مانند `text-embedding-3-small`) که ساخت بردار برای هزاران پروژه کمتر از چند هزار تومان هزینه دارد.
|
||||||
|
* کال‌اوت قرمز (`<details class="red">`): تولید بردارها را در هنگام جستجوی کاربر فقط برای عبارت ورودی انجام دهید؛ بردار پروژه‌ها باید از قبل یک‌بار تولید و در دیتابیس ذخیره شده باشد.
|
||||||
|
|
||||||
|
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||||
|
- آموزش شبکه‌های عصبی Transformer و معماری داخلی آنها.
|
||||||
|
- پیاده‌سازی خوشه‌بندی‌های بدون نظارت K-Means در لایه دیتابیس.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||||
|
|
||||||
|
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| Semantic Search | جستجوی معنایی | جستجوی مبتنی بر درک مقصود و معنای عمیق مفاهیم به جای تطابق کلمه به کلمه متن |
|
||||||
|
| Vector Embedding | تعبیه برداری | تبدیل متون به بردارهای عددی چندبعدی به گونه‌ای که کلمات هم‌معنی در فضا به هم نزدیک باشند |
|
||||||
|
| pgvector | اکستنشن پی‌جی‌وکتور | افزونه رسمی پایگاه داده PostgreSQL برای ذخیره، ایندکس و جستجوی فوق‌سریع بردارها |
|
||||||
|
| Cosine Similarity | شباهت کسینوسی | معیار ریاضی سنجش زاویه میان دو بردار که میزان همبستگی مفهومی آنها را معین می‌کند |
|
||||||
|
| Structured JSON Output | خروجی ساختاریافته جیسون | وادار کردن مدل هوش مصنوعی به رعایت یک قالب و اسکیمای سخت‌گیرانه داده‌ها برای مصرف در برنامه |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||||
|
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||||||
|
|
||||||
|
1. **تصویر کاور درس:** `images/cover.png`
|
||||||
|
* **موضوع:** فضای سه‌بعدی نئونی پر از نقاط نوری معلق (بردارها) که با خطوط نورانی به کلمات «پایگاه داده»، «Supabase» و «SQL» متصل شده‌اند.
|
||||||
|
2. **تفاوت جستجوی کلیدواژه‌ای با جستجوی برداری معنایی:** `images/keyword-vs-semantic-search.png`
|
||||||
|
* **موضوع:** اینفوگرافیک مقایسه‌ای: جستجوی «فروشگاه آنلاین» در جستجوی سنتی نتایج «E-Commerce» را نمی‌یابد؛ در جستجوی معنایی این دو دقیقاً در کنار هم قرار دارند.
|
||||||
|
3. **معماری جستجوی معنایی در Supabase با pgvector:** `images/supabase-pgvector-flow.png`
|
||||||
|
* **موضوع:** فلوچارت: کاربر در اینپوت سرچ تایپ می‌کند $\rightarrow$ تولید بردار کوئری با مدل $\rightarrow$ کوئری SQL در سوپابیس با عملگر کسینوس $\rightarrow$ برگرداندن پروژه‌ها به ترتیب شباهت.
|
||||||
|
4. **دکمه جادویی تولید محتوای پروژه در پنل مدیریت:** `images/ai-project-generator-ui.png`
|
||||||
|
* **موضوع:** اسکرین‌شات از فرم ثبت پروژه در پنل ادمین با دکمه «تولید هوشمند با AI» و انیمیشن پر شدن خودکار فیلدهای توضیحات و تگ‌ها.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||||
|
|
||||||
|
1. **تیتر اصلی:** `# تزریق قابلیت‌های پیشرفته هوش مصنوعی؛ جستجوی معنایی (Vector Search) و تولید هوشمند محتوا`
|
||||||
|
2. **مقدمه:** هوش مصنوعی تا کنون کد می‌نوشت؛ حال وقت آن است که قابلیت‌های جادویی هوش مصنوعی را به عنوان قلب تپنده پورتفولیو به نمایش بگذاریم!
|
||||||
|
3. **جدول کاور درس**
|
||||||
|
4. **استعاره جستجوی کتاب در کتابخانه بر اساس موضوع به جای عنوان جلد:**
|
||||||
|
* وقتی از کتابدار کتابی درباره «آشپزی ایتالیایی» می‌خواهید، او کتاب «طرز تهیه پاستا» را می‌آورد حتی اگر کلمه ایتالیا روی جلد نباشد.
|
||||||
|
5. **مبانی بردارها و ریاضیات معنایی (Vector Embeddings):**
|
||||||
|
* چگونه هوش مصنوعی متون را به مختصات فضایی تبدیل می‌کند.
|
||||||
|
6. **راه‌اندازی `pgvector` در Supabase و ذخیره بردار پروژه‌ها:**
|
||||||
|
* نوشتن مایگریشن فعال‌سازی اکستنشن و افزودن ستون `embedding`.
|
||||||
|
7. **پیاده‌سازی ماژول جستجوی معنایی پورتفولیو در Next.js:**
|
||||||
|
* ساخت اینپوت جستجوی هوشمند در هدر سایت با افکت لودینگ برداری.
|
||||||
|
8. **ساخت ویژگی تولید خودکار مشخصات پروژه با Structured Outputs:**
|
||||||
|
* پرامپت فرمت JSON Schema برای استخراج سئو و متن فارسی از روی یادداشت‌های خام یا ریپوی گیت‌هاب.
|
||||||
|
9. **جعبه پرامپت طلایی: ساخت اندپوینت جستجوی معنایی با ایجنت:**
|
||||||
|
* پرامپت دقیق:
|
||||||
|
> «من اکستنشن `vector` را در Supabase فعال کرده‌ام. لطفاً ۱) یک تابع RPC در دیتابیس برای جستجوی شباهت کسینوسی پروژه‌ها بنویس، ۲) یک Route Handler برای تولید بردار متن سرچ با استفاده از مدل `text-embedding-3-small` اوپن‌ای‌آی یا OpenRouter ایجاد کن، و ۳) کامپوننت جستجو در فرانت‌اند را به گونه‌ای متصل کن که نتایج مرتبط را به صورت آنی نمایش دهد.»
|
||||||
|
10. **باکس نکته Quera (`<details class="violet">`):** استفاده از کش در جستجوی معنایی؛ برای عبارات جستجوی متداول، بردارها را کش کنید تا هزینه به حداقل برسد.
|
||||||
|
11. **باکس هشدار Quera (`<details class="red">`):** هرگز بردارها را به صورت پویا در سمت کلاینت تولید نکنید؛ کلید API هوش مصنوعی باید در محیط امن سرور اکشن بماند.
|
||||||
|
12. **باکس رضایت‌بخش Quera (`<details class="green">`):** تست سرچ کلماتی که در سایت نیستند (مثل «توسعه سمت کاربر») و دیدن لود شدن فوری پروژه‌های React و Next.js!
|
||||||
|
13. **جمع‌بندی درس‌نامه:** تسلط بر هوش مصنوعی پیشرفته داخلی؛ ورود به دنیای ساخت فرآیندهای خودمختار چندمرحله‌ای (Agentic Workflows) در درس بعدی.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||||
|
- [ ] تفاوت جستجوی متنی سنتی و جستجوی معنایی برداری با مثال‌های شفاف تبیین شود.
|
||||||
|
- [ ] نحوه فعال‌سازی و کاربرد اکستنشن `pgvector` در Supabase آموزش داده شود.
|
||||||
|
- [ ] تولید خروجی ساختاریافته JSON Schema برای تولید خودکار دیتای پروژه‌ها تشریح گردد.
|
||||||
|
- [ ] پرامپت‌های ساخت اندپوینت جستجوی برداری در متن درس لحاظ شوند.
|
||||||
@@ -0,0 +1,105 @@
|
|||||||
|
# مشخصات درس‌نامه: ساخت گردش‌کارهای ایجنتیک خودکار (Agentic Workflows) و الگوهای چندایجنت
|
||||||
|
- **شناسه در سیلابس:** `L15.7`
|
||||||
|
- **فصل:** فصل ۱۵: تکامل محصول با AI (Ch 15)
|
||||||
|
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||||
|
- **زمان تقریبی مطالعه:** ۱۸ دقیقه
|
||||||
|
- **پیش‌نیازهای مستقیم:** `L15.6` (تزریق قابلیت‌های پیشرفته هوش مصنوعی)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||||
|
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||||
|
- [ ] **درک کند (Understand):** تفاوت بنیادین میان «پرامپت تک‌مرحله‌ای ساده» (یک سوال $\rightarrow$ یک جواب) با «گردش‌کارهای ایجنتیک چندمرحله‌ای» (برنامه‌ریزی $\rightarrow$ فراخوانی ابزارها $\rightarrow$ بازخورد و خودارزیابی $\rightarrow$ تصمیم‌گیری خودمختار) را شرح دهد.
|
||||||
|
- [ ] **تحلیل/ارزیابی کند (Evaluate):** چهار الگوی کلیدی طراحی سیستم‌های ایجنتیک (بازتاب و خودانتقادی Reflection، استفاده از ابزارها Tool Use، برنامه‌ریزی Planning، و همکاری چندایجنت Multi-Agent Collaboration) را تحلیل کند.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** یک گردش‌کار خودکار «پاسخگویی هوشمند به درخواست همکاری» طراحی کند که با دریافت پیام کارفرما، سوابق پروژه‌های مرتبط را از دیتابیس استخراج کرده و پیش‌نویس یک پروپوزال رسمی را برای تایید ادمین آماده سازد.
|
||||||
|
- [ ] **ایجاد کند (Create):** یک مکانیسم ایمن نظارت انسانی (Human-in-the-Loop) پیاده کند تا هیچ ایمیل یا تصمیم حساسی بدون تایید نهایی شخص سازنده برای مخاطب ارسال نشود.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||||
|
|
||||||
|
### آنچه باید پوشش داده شود (In-Scope):
|
||||||
|
1. **گذار از دستیار چت به سیستم‌های خودمختار همکار:**
|
||||||
|
* چرا دیگر دوره چت‌های معمولی گذشته و سیستم‌هایی که زنجیره‌ای از کارها را پشت سر هم انجام می‌دهند آینده نرم‌افزار هستند.
|
||||||
|
2. **الگوهای ۴ گانه اندرو ان‌جی (Andrew Ng) برای سیستم‌های ایجنتیک:**
|
||||||
|
* الگوی ۱: بازتاب و بازبینی خودکار (Reflection)؛ ایجنت خروجی خود را نقد و عیب‌یابی می‌کند.
|
||||||
|
* الگوی ۲: استفاده از ابزارها (Tool / Function Calling)؛ ایجنت می‌تواند وب را بگردد، دیتابیس را بخواند یا تابع بفرستد.
|
||||||
|
* الگوی ۳: برنامه‌ریزی گام‌به‌گام (Planning)؛ شکستن هدف کلی به تسک‌های خرد ترتیبی.
|
||||||
|
* الگوی ۴: همکاری چند ایجنت تخصصی (Multi-Agent Collaboration)؛ کار گروهی ایجنت محقق، ایجنت نویسنده و ایجنت بازرس.
|
||||||
|
3. **مطالعه موردی در پروژه پورتفولیو: گردش‌کار خودکار پروپوزال‌ساز:**
|
||||||
|
* سناریو: کارفرما در فرم تماس می‌نویسد: «ما یک پلتفرم فروشگاهی با Next.js و درگاه زرین‌پال می‌خواهیم».
|
||||||
|
* گام ۱ (ایجنت محقق): جستجو در دیتابیس پورتفولیو برای یافتن پروژه‌های مرتبط قبلی دانشجو.
|
||||||
|
* گام ۲ (ایجنت برآورد): تخمین بازه زمانی و محدوده پروژه بر اساس نمونه‌های گذشته.
|
||||||
|
* گام ۳ (ایجنت نویسنده): تدوین پیش‌نویس شکیل یک ایمیل پاسخ حرفه‌ای شامل نمونه‌کارها و دعوت به جلسه مشاوره.
|
||||||
|
* گام ۴ (داشبورد ادمین): نمایش پیش‌نویس در پنل ادمین با دو دکمه «تایید و ارسال ایمیل» یا «ویرایش دستی».
|
||||||
|
4. **اصل حیاتی انسان در چرخه تصمیم (Human-in-the-Loop - HITL):**
|
||||||
|
* چرا نباید ارسال ایمیل یا تراکنش‌های مالی را کاملاً خودمختار و بدون نظارت انسانی رها کرد.
|
||||||
|
5. **معرفی ابزارهای پیاده‌سازی گردش‌کارها (اسکریپت‌های تایپ‌اسکریپت، n8n، LangChain):**
|
||||||
|
* سادگی ساخت زنجیره‌ها با توابع سرورلس در Next.js بدون نیاز به زیرساخت‌های غول‌پیکر.
|
||||||
|
6. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
|
||||||
|
* کال‌اوت بنفش (`<details class="violet">`): خطر حلقه‌های بی‌پایان ایجنت (Infinite Loops)؛ لزوم تعیین سقف تعداد گام‌ها (مثلاً حداکثر ۵ مرحله) برای جلوگیری از سوختن توکن‌ها.
|
||||||
|
* کال‌اوت سبز (`<details class="green">`): شگفتی از صرفه‌جویی ساعت‌ها وقت روزانه در پاسخ به ایمیل‌های کاری و تهیه پروپوزال‌های تخصصی.
|
||||||
|
* کال‌اوت قرمز (`<details class="red">`): هرگز به ایجنت‌ها اختیار حذف رکوردهای دیتابیس یا برداشت از حساب بانکی را به عنوان Tool بدون تایید مستقیم ندهید!
|
||||||
|
|
||||||
|
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||||
|
- مباحث فلسفی هوش عمومی مصنوعی (AGI).
|
||||||
|
- فریم‌ورک‌های ارکستراسیون پیچیده سازمانی نظیر AutoGen روی خوشه‌های سرور اختصاصی.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||||
|
|
||||||
|
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| Agentic Workflow | گردش‌کار ایجنتیک | زنجیره پیوسته‌ای از مراحل تفکر، ابزارورزی و ارزیابی خودکار توسط هوش مصنوعی برای انجام تسک‌های پیچیده |
|
||||||
|
| Tool Use / Function Calling | فراخوانی ابزارها | توانایی مدل در انتخاب و اجرای توابع برنامه‌نویسی برای خواندن دیتابیس، فراخوانی API یا محاسبات |
|
||||||
|
| Reflection | بازتاب و خودانتقادی | مکانیزمی که در آن مدل هوش مصنوعی خروجی مرحله قبل خود را ارزیابی و نقایص آن را اصلاح می‌کند |
|
||||||
|
| Human-in-the-Loop (HITL) | انسان در چرخه تصمیم | الگوی طراحی که در آن اقدامات حیاتی و پرریسک نیازمند تایید یا بازبینی مستقیم ناظر انسانی هستند |
|
||||||
|
| Multi-Agent Collaboration | همکاری چندایجنت | تقسیم وظایف میان چندین ایجنت تخصصی با پرامپت‌ها و اختیارات مجزا برای رسیدن به خروجی فاخر |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||||
|
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||||||
|
|
||||||
|
1. **تصویر کاور درس:** `images/cover.png`
|
||||||
|
* **موضوع:** زنجیره‌ای نئونی از ربات‌های هوشمند با مهارت‌های مختلف که دست به دست هم یک نامه اداری و فاکتور را پردازش و تحویل می‌دهند.
|
||||||
|
2. **الگوهای ۴ گانه سیستم‌های ایجنتیک اندرو ان‌جی:** `images/four-agentic-patterns-infographic.png`
|
||||||
|
* **موضوع:** اینفوگرافیک ۴ بخشی: بازتاب (آینه نقد)، ابزارها (آچار و پیچ‌گوشتی)، برنامه‌ریزی (نقشه راه)، و چندایجنت (تیم کاری).
|
||||||
|
3. **چرخه گردش‌کار پروپوزال‌ساز خودکار در پورتفولیو:** `images/proposal-drafter-workflow-flow.png`
|
||||||
|
* **موضوع:** فلوچارت: پیام کارفرما $\rightarrow$ استخراج دیتای پروژه‌ها از Supabase $\rightarrow$ نگارش پیش‌نویس توسط ایجنت $\rightarrow$ نمایش در پنل ادمین $\rightarrow$ تایید با یک کلیک انسان $\rightarrow$ ارسال ایمیل با لیارا.
|
||||||
|
4. **پیش‌نمایش کارت پیش‌نویس پروپوزال در پنل مدیریت:** `images/admin-proposal-draft-ui.png`
|
||||||
|
* **موضوع:** اسکرین‌شات از پنل ادمین با متن آماده پاسخ به کارفرما، دکمه بنفش «تایید و ارسال» و دکمه خاکستری «ویرایش متن».
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||||
|
|
||||||
|
1. **تیتر اصلی:** `# ساخت گردش‌کارهای ایجنتیک خودکار (Agentic Workflows) و الگوهای چندایجنت`
|
||||||
|
2. **مقدمه:** چرا به جای اینکه هر بار دستی به چت‌بات پرامپت بدهید، یک تیم خودمختار از ایجنت‌ها نسازید که کارهای تکراری شما را خودکار انجام دهند؟
|
||||||
|
3. **جدول کاور درس**
|
||||||
|
4. **استعاره خط تولید کارخانه در برابر کار تک‌نفره:**
|
||||||
|
* در یک خط تولید، هر ایستگاه کاری وظیفه‌ای مشخص دارد؛ قطعه از یک ایجنت به ایجنت دیگر پاس داده می‌شود.
|
||||||
|
5. **چهار الگوی طلایی طراحی سیستم‌های ایجنتیک:**
|
||||||
|
* بازتاب و خودانتقادی، جعبه ابزارها (Tools)، برنامه‌ریزی، و تیم‌های چندایجنت.
|
||||||
|
6. **معماری عملی گردش‌کار هوشمند پورتفولیو:**
|
||||||
|
* تحلیل پیام کارفرما $\rightarrow$ جستجوی سوابق در دیتابیس $\rightarrow$ تولید پیش‌نویس پروپوزال رسمی.
|
||||||
|
7. **کدنویسی زنجیره ابزارها در Server Actions:**
|
||||||
|
* پیاده‌سازی گام‌به‌گام با ابزار Tool Calling در مدل‌های OpenAI / OpenRouter.
|
||||||
|
8. **اصل طلایی Human-in-the-Loop:**
|
||||||
|
* چرا نباید اجازه دهید هوش مصنوعی بدون تایید شما با کارفرما مکاتبه کند؟ طراحی گیت تایید در داشبورد.
|
||||||
|
9. **جعبه پرامپت طلایی: طراحی گردش‌کار پروپوزال‌ساز با ایجنت:**
|
||||||
|
* پرامپت دقیق:
|
||||||
|
> «من می‌خواهم یک گردش‌کار خودکار در Next.js بسازم. هنگامی که کارفرمایی پیام ارسال می‌کند، یک تابع سرور باید: ۱) نیازهای اصلی پروژه را از متن پیام استخراج کند، ۲) با یک کوئری به جدول پروژه‌های پورتفولیو مرتبط‌ترین نمونه‌کار را پیدا کند، ۳) یک پیش‌نویس پاسخ مودبانه به همراه معرفی آن پروژه بنویسد و ۴) این پیش‌نویس را در جدول پیام‌های ادمین برای تایید و ارسال با یک کلیک ذخیره کند.»
|
||||||
|
10. **باکس نکته Quera (`<details class="violet">`):** مهار حلقه‌های بی‌پایان؛ همیشه یک شمارنده `maxIterations = 3` در کدهای گردش‌کار قرار دهید تا ایجنت در چرخه گیر نکند.
|
||||||
|
11. **باکس هشدار Quera (`<details class="red">`):** دسترسی به ابزارهای ویرانگر؛ ابزارهای حذف دیتا یا ارسال ایمیل مستقیم را هرگز به صورت خودکار بدون تایید انسان اجرا نکنید.
|
||||||
|
12. **باکس رضایت‌بخش Quera (`<details class="green">`):** تست ارسال یک پیام در فرم تماس و ورود به پنل ادمین و دیدن پیش‌نویس آماده یک ایمیل پروپوزال فوق‌العاده حرفه‌ای در عرض ۵ ثانیه.
|
||||||
|
13. **جمع‌بندی درس‌نامه:** تسلط بر گردش‌کارهای ایجنتیک؛ ورود به ایستگاه اتوماسیون نگهداری، تست و اسکریپت‌های خودترمیم در درس بعدی.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||||
|
- [ ] تفاوت پرامپت ساده با سیستم‌های ایجنتیک چندمرحله‌ای تشریح گردد.
|
||||||
|
- [ ] الگوهای چهارگانه طراحی سیستم‌های ایجنتیک اندرو ان‌جی با مثال‌های ملموس تبیین شود.
|
||||||
|
- [ ] گردش‌کار عملی پروپوزال‌ساز خودکار به همراه اصل Human-in-the-Loop پیاده‌سازی شود.
|
||||||
|
- [ ] کدهای زنجیره‌سازی ابزارها و تدابیر پیشگیری از لوپ‌های بی‌پایان لحاظ گردند.
|
||||||
@@ -0,0 +1,101 @@
|
|||||||
|
# مشخصات درس‌نامه: اتوماسیون نگهداری و توسعه؛ از تریاژ خودکار ایشیوها تا اسکریپت‌های خودترمیم
|
||||||
|
- **شناسه در سیلابس:** `L15.8`
|
||||||
|
- **فصل:** فصل ۱۵: تکامل محصول با AI (Ch 15)
|
||||||
|
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||||
|
- **زمان تقریبی مطالعه:** ۱۶ دقیقه
|
||||||
|
- **پیش‌نیازهای مستقیم:** `L15.7` (ساخت گردش‌کارهای ایجنتیک خودکار)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||||
|
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||||
|
- [ ] **درک کند (Understand):** مفهوم اتوماسیون نگهداری و توسعه (DevOps & Maintenance Automation) را شرح دهد و بداند چگونه کارهای روزمره و خسته‌کننده (تریاژ باگ‌ها، پاک‌سازی لاگ‌ها، ممیزی کدهای جدید) را به ربات‌های خودکار بسپارد.
|
||||||
|
- [ ] **تحلیل/ارزیابی کند (Evaluate):** کاربرد اکشن‌های گیت‌هاب (GitHub Actions) و ادغام مدل‌های زبانی را در بررسی خودکار کدهای Pull Request (AI Code Reviewer) و برچسب‌گذاری ایشیوها ارزیابی کند.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** یک کرون جاب (Cron Job) زمان‌بندی‌شده سرورلس برای پاک‌سازی خودکار رکوردهای موقت منقضی‌شده (کدهای پیامکی قدیمی، لاگ‌های بی‌استفاده) در Supabase پیاده نماید.
|
||||||
|
- [ ] **ایجاد کند (Create):** یک اسکریپت نظارت بر تست‌های خودکار بسازد که در صورت شکست تست‌ها، خطای مربوطه را تحلیل و پیش‌نویس اصلاحیه کد را تولید کند.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||||
|
|
||||||
|
### آنچه باید پوشش داده شود (In-Scope):
|
||||||
|
1. **استعاره ربات‌های جاروبرقی هوشمند در خانه:**
|
||||||
|
* شما در خواب هستید، اما ربات به طور خودکار کف خانه را جارو می‌کند، زباله‌ها را پاک می‌کند و شارژ می‌شود.
|
||||||
|
2. **اتوماسیون مخزن گیت‌هاب با اکشن‌های هوش مصنوعی (AI GitHub Actions):**
|
||||||
|
* تریاژ خودکار ایشیوها (Automated Issue Triage): وقتی کاربری در گیت‌هاب ایشیو می‌زند، مدل محتوا را می‌خواند، برچسب‌های `bug` یا `enhancement` می‌زند و در صورت ناقص بودن اطلاعات، کامنت راهنما می‌گذارد.
|
||||||
|
* بازبین خودکار کدها (AI Pull Request Reviewer): ربات هوشمندی که تغییرات PR را با قوانین `.cursorrules` مقایسه کرده و در صورت وجود کلید هاردکد شده یا توابع ناامن، هشدار درون‌خطی ثبت می‌کند.
|
||||||
|
3. **وظایف دوره‌ای پاک‌سازی پایگاه داده (Database Scheduled Maintenance):**
|
||||||
|
* راه‌اندازی توابع زمان‌بندی‌شده ابری (Cron Triggers):
|
||||||
|
- حذف رکوردهای منقضی‌شده OTP بعد از ۲۴ ساعت.
|
||||||
|
- پاک‌سازی لاگ‌های قدیمی و جلوگیری از پر شدن حجم رایگان دیتابیس Supabase.
|
||||||
|
4. **اسکریپت‌های تست خودترمیم (Self-Healing Tests):**
|
||||||
|
* سناریویی که در آن شکست تست به دلیل تغییر ساده نام یک کلاس Tailwind یا متن دکمه، توسط ایجنت شناسایی و فایل تست به صورت خودکار با برنچ جدید آپدیت می‌شود.
|
||||||
|
5. **ارسال گزارش خلاصه هفتگی سلامت به تلگرام سازنده:**
|
||||||
|
* گزارش خودکار هفتگی: «پورتفولیو در هفته گذشته ۱۰۰٪ آپتایم داشت، ۱۲ پیام ثبت شد و ۵۰ رکورد منقضی پاک‌سازی گردید.»
|
||||||
|
6. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
|
||||||
|
* کال‌اوت بنفش (`<details class="violet">`): مفهوم کرون جاب در معماری بدون سرور با اندپوینت‌های ایمن‌شده با توکن (`CRON_SECRET`).
|
||||||
|
* کال‌اوت سبز (`<details class="green">`): حس شگفت‌انگیز باز کردن گیت‌هاب و دیدن کامنت‌های دقیق ربات بازبین روی کدهای جدید.
|
||||||
|
* کال‌اوت قرمز (`<details class="red">`): مرز باریک اتوماسیون؛ هرگز اجازه ادغام خودکار (Auto-Merge) کدهای تغییریافته به شاخه اصلی پروداکشن را به ربات‌ها ندهید.
|
||||||
|
|
||||||
|
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||||
|
- پایپ‌لاین‌های پیچیده چندمرحله‌ای کلاود AWS CodePipeline.
|
||||||
|
- نوشتن افزونه‌های اختصاصی سیستم‌های مدیریت کانتینر داکر سوآرم.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||||
|
|
||||||
|
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| Maintenance Automation | خودکارسازی فرآیندهای نگهداری | برنامه‌ریزی سیستم‌ها برای انجام منظم کارهای اصلاحی و پاک‌سازی بدون دخالت دست انسان |
|
||||||
|
| Issue Triaging | تریاژ و اولویت‌بندی ایشیوها | فرآیند دسته‌بندی، ارزیابی فوریت و تعیین تکلیف گزارش‌های باگ دریافت شده از کاربران |
|
||||||
|
| Cron Job | وظیفه زمان‌بندی‌شده | فرآیندی که در ساعت‌ها یا روزهای معین به صورت خودکار در پس‌زمینه سرور اجرا می‌شود |
|
||||||
|
| Self-Healing System | سیستم خودترمیم | سامانه‌ای که پس از مواجهه با خطاهای سطحی، می‌تواند به صورت خودکار اقدامات اصلاحی اولیه را انجام دهد |
|
||||||
|
| PR Review Bot | ربات بازبین پول ریکوئست | ابزار هوش مصنوعی که پیش از ادغام کدهای جدید، آنها را از نظر کیفیت و امنیت نقد می‌کند |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||||
|
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||||||
|
|
||||||
|
1. **تصویر کاور درس:** `images/cover.png`
|
||||||
|
* **موضوع:** ربات دستیار مکانیک نئونی با ابزارهای دیجیتال در حال آچارکشی خودکار کدهای یک سرور ابری در طول شب.
|
||||||
|
2. **جریان کار ربات بازبین هوش مصنوعی در گیت‌هاب:** `images/ai-pr-reviewer-flow.png`
|
||||||
|
* **موضوع:** دیاگرام فرآیند: ارسال PR جدید $\rightarrow$ وب‌هوک گیت‌هاب اکشن $\rightarrow$ تحلیل تغییرات با پرامپت قوانین $\rightarrow$ ثبت کامنت‌های بازبینی هوشمند روی خطوط کد.
|
||||||
|
3. **نمونه کامنت ربات هوش مصنوعی روی پول ریکوئست:** `images/github-ai-bot-comment-preview.png`
|
||||||
|
* **موضوع:** اسکرین‌شات از گیت‌هاب با کامنت ربات: «نکته امنیتی: به نظر می‌رسد این متغیر نباید NEXT_PUBLIC_ باشد» و تایید سایر خطوط.
|
||||||
|
4. **گزارش تلگرامی کرون جاب پاک‌سازی دوره‌ای:** `images/telegram-cron-health-report.png`
|
||||||
|
* **موضوع:** اسکرین‌شات از پیام ربات تلگرام با خلاصه اقدامات نگهداری نیمه‌شب و وضعیت پایدار دیتابیس.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||||
|
|
||||||
|
1. **تیتر اصلی:** `# اتوماسیون نگهداری و توسعه؛ از تریاژ خودکار ایشیوها تا اسکریپت‌های خودترمیم`
|
||||||
|
2. **مقدمه:** چگونه کاری کنیم که پروژه حتی زمانی که ما در تعطیلات هستیم، خودش را تمیز کند، باگ‌هایش را گزارش دهد و کدهای جدید را بازرسی نماید؟
|
||||||
|
3. **جدول کاور درس**
|
||||||
|
4. **استعاره سرایدار شبانه‌روزی هوشمند ساختمان:**
|
||||||
|
* چک کردن شیرهای آب، بیرون گذاشتن زباله‌ها و ثبت ترددها بدون بیدار کردن ساکنان.
|
||||||
|
5. **ساخت ربات بازبین کد (AI Code Reviewer) با GitHub Actions:**
|
||||||
|
* نوشتن یک فایل YAML ساده در `.github/workflows/ai-review.yml`.
|
||||||
|
* ارسال کدهای تغییریافته به مدل زبانی و دریافت بازخورد خودکار.
|
||||||
|
6. **تریاژ خودکار گزارش‌های باگ در گیت‌هاب:**
|
||||||
|
* تشخیص نوع ایشیو و افزودن خودکار برچسب‌های رنگی.
|
||||||
|
7. **پاک‌سازی دوره‌ای دیتابیس با وظایف زمان‌بندی‌شده (Cron Jobs):**
|
||||||
|
* ساخت روت امن `/api/cron/cleanup` در Next.js با احراز هویت توکن `CRON_SECRET`.
|
||||||
|
* حذف خودکار رکوردهای باطله و حفظ سلامت جداول.
|
||||||
|
8. **جعبه پرامپت طلایی: طراحی ورک‌فلو گیت‌هاب اکشن برای بازبینی خودکار کد با ایجنت:**
|
||||||
|
* پرامپت دقیق:
|
||||||
|
> «من می‌خواهم یک GitHub Action بنویسم که در هنگام ثبت هر Pull Request جدید، تفاوت کدها (Git Diff) را به API هوش مصنوعی بفرستد و بر اساس راهنمای سبک کدنویسی من، کامنت‌های بهبود ساختار و هشدارهای امنیتی را مستقیماً روی PR ثبت کند. فایل کامل YAML و اسکریپت مربوطه را برایم بساز.»
|
||||||
|
9. **باکس نکته Quera (`<details class="violet">`):** استفاده از سرویس‌های رایگان کرون مانند cron-job.org برای فراخوانی منظم روت‌های پاک‌سازی سرورلس.
|
||||||
|
10. **باکس هشدار Quera (`<details class="red">`):** هرگز کلیدهای اکشن گیت‌هاب را بدون ماسک در فایل YAML ننویسید؛ همیشه از GitHub Secrets استفاده کنید.
|
||||||
|
11. **باکس رضایت‌بخش Quera (`<details class="green">`):** ایجاد یک PR آزمایشی و شگفت‌زده شدن از دیدن کامنت‌های فنی و موشکافانه ربات در کمتر از ۳۰ ثانیه.
|
||||||
|
12. **جمع‌بندی درس‌نامه:** تسلط بر اتوماسیون وظایف روزمره؛ ورود به دنیای استخراج بینش عمیق از داده‌های محصول با هوش مصنوعی در درس بعدی.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||||
|
- [ ] اصول و مزایای اتوماسیون نگهداری در عصر وایب کدینگ تبیین شود.
|
||||||
|
- [ ] نحوه پیاده‌سازی ربات بازبین کد در GitHub Actions آموزش داده شود.
|
||||||
|
- [ ] طراحی روت‌های زمان‌بندی‌شده (Cron Jobs) برای پاک‌سازی دیتابیس ارائه گردد.
|
||||||
|
- [ ] نمونه کدهای امنیتی برای محافظت از اندپوینت‌های کرون در متن درس گنجانده شود.
|
||||||
@@ -0,0 +1,103 @@
|
|||||||
|
# مشخصات درس‌نامه: استخراج بینش محصول (Product Insights) و بهینه‌سازی نرخ تبدیل با هوش مصنوعی
|
||||||
|
- **شناسه در سیلابس:** `L15.9`
|
||||||
|
- **فصل:** فصل ۱۵: تکامل محصول با AI (Ch 15)
|
||||||
|
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||||
|
- **زمان تقریبی مطالعه:** ۱۶ دقیقه
|
||||||
|
- **پیش‌نیازهای مستقیم:** `L15.8` (اتوماسیون نگهداری و توسعه)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||||
|
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||||
|
- [ ] **درک کند (Understand):** تفاوت میان «دیدن اعداد خام نمودارها» (Analytics Data) با «استخراج بینش عملیاتی» (Actionable Product Insights) را شرح دهد و بداند چگونه هوش مصنوعی به عنوان مدیر محصول ارشد تحلیلی عمل می‌کند.
|
||||||
|
- [ ] **تحلیل/ارزیابی کند (Evaluate):** داده‌های خروجی سرچ کنسول گوگل، کلاریتی و پایگاه داده Supabase را با هوش مصنوعی ترکیب کرده و نقاط افت کاربر در قیف تبدیل (Conversion Funnel Drop-offs) را تحلیل نماید.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** توصیه‌های بهینه‌سازی نرخ تبدیل (CRO: Conversion Rate Optimization) تولید شده توسط مدل را برای افزایش نرخ کلیک روی رزرو مشاوره و فرم تماس در پورتفولیو اعمال کند.
|
||||||
|
- [ ] **ایجاد کند (Create):** یک گزارش مدیریتی ماهانه خودکار (Monthly Executive Summary) به همراه ۳ اقدام اصلاحی اولویت‌دار از دل داده‌های واقعی تولید کند.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||||
|
|
||||||
|
### آنچه باید پوشش داده شود (In-Scope):
|
||||||
|
1. **استعاره آزمایش خون در برابر تشخیص بالینی پزشک:**
|
||||||
|
* نمودارهای گوگل آنالیتیکس و کلاریتی فقط برگه آزمایش هستند؛ هوش مصنوعی پزشک حاذقی است که علت بیماری و نسخه درمان را می‌نویسد.
|
||||||
|
2. **سناریوی واقعی پورتفولیو: کشف گره‌های پنهان رفتار کارفرما:**
|
||||||
|
* معما: آمار کلاریتی نشان می‌دهد کارفرمایان ۳ دقیقه روی پروژه پورتفولیو وقت می‌گذرانند، اما فقط ۲ درصد روی دکمه «رزرو مشاوره» کلیک می‌کنند! علت چیست؟
|
||||||
|
* پاسخ تحلیلی مدل با دیدن دیتا: «دکمه رزرو در فوتر مخفی است و ارتباطی با پروژه ندیده است؛ یک دکمه فراخوان به اقدام (CTA) با عنوان "سفارش پروژه‌ای مشابه این" در انتهای صفحه پروژه بگذارید».
|
||||||
|
3. **ترکیب چند منبع داده برای تحلیل جامع (Multi-Source Synthesis):**
|
||||||
|
* ترکیب فایل‌های خروجی CSV:
|
||||||
|
- کلمات ورودی از سرچ کنسول گوگل (GSC).
|
||||||
|
- زمان ماندگاری و عمق اسکرول از مایکروسافت کلاریتی.
|
||||||
|
- آمار واقعی فرم تماس و تراکنش‌های زرین‌پال از Supabase.
|
||||||
|
4. **تکنیک‌های بهینه‌سازی نرخ تبدیل (CRO):**
|
||||||
|
* بهبود متن دکمه‌های فراخوان (Copywriting CTA).
|
||||||
|
* رفع ابهام از قیمت‌ها و شرایط جلسات مشاوره.
|
||||||
|
5. **جعبه پرامپت طلایی برای تحلیل داده‌های محصول:**
|
||||||
|
* پرامپت تحلیل پیشرفته فایل‌های اکسل/CSV و استخراج گزارش راهبردی.
|
||||||
|
6. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
|
||||||
|
* کال‌اوت بنفش (`<details class="violet">`): پاک‌سازی داده‌های هویتی (Anonymization) در فایل‌های اکسل خروجی قبل از آپلود در چت‌بات‌ها.
|
||||||
|
* کال‌اوت سبز (`<details class="green">`): افزایش نرخ رزرو یا پیام‌های تماس با اعمال یک تغییر کوچک پیشنهادی هوش مصنوعی.
|
||||||
|
* کال‌اوت قرمز (`<details class="red">`): پرهیز از نتیجه‌گیری شتاب‌زده بر اساس داده‌های آماری اندک (حداقل ۱۰۰ تا ۲۰۰ بازدیدکننده برای نتیجه‌گیری معنادار لازم است).
|
||||||
|
|
||||||
|
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||||
|
- مدل‌سازی‌های پیچیده اقتصادسنجی و رگرسیون‌های آماری چندمتغیره در زبان R.
|
||||||
|
- تست‌های A/B سازمانی نیازمند ترافیک‌های میلیونی ماهانه.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||||
|
|
||||||
|
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| Product Insights | بینش‌های کاربردی محصول | درس‌آموخته‌ها و الگوهای کشف‌شده از رفتار کاربران که مستقیماً مبنای تصمیم‌گیری‌های بعدی قرار می‌گیرند |
|
||||||
|
| Conversion Funnel | قیف تبدیل کاربر | مسیر گام‌به‌گامی که کاربر از ورود اولیه تا انجام اقدام هدف نهایی (رزرو، خرید، تماس) طی می‌کند |
|
||||||
|
| CRO | بهینه‌سازی نرخ تبدیل | علم و هنر بازطراحی بخش‌هایی از محصول برای افزایش درصد بازدیدکنندگانی که به مشتری تبدیل می‌شوند |
|
||||||
|
| Call to Action (CTA) | فراخوان به اقدام | دکمه یا پیامی ترغیب‌کننده که کاربر را به انجام یک عمل مشخص (نظیر ثبت سفارش) دعوت می‌کند |
|
||||||
|
| Multi-Source Synthesis | تلفیق داده‌های چندمنبعی | ترکیب گزارش‌های ابزارهای مختلف (سئو، ترافیک، مالی) برای دیدن تصویر بزرگ سیستم |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||||
|
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||||||
|
|
||||||
|
1. **تصویر کاور درس:** `images/cover.png`
|
||||||
|
* **موضوع:** نمودارهای سه‌بعدی دیجیتال نئونی که از میان اعداد پراکنده، یک فلش درخشان صعودی رشد و چراغ‌های ایده را روشن می‌کنند.
|
||||||
|
2. **قیف تبدیل پورتفولیو و نقاط ریزش کاربران:** `images/portfolio-conversion-funnel.png`
|
||||||
|
* **موضوع:** اینفوگرافیک قیف: ۱۰۰۰ بازدیدکننده $\rightarrow$ ۳۰۰ مشاهده جزئیات پروژه $\rightarrow$ ۵۰ کلیک روی رزرو $\rightarrow$ ۱۰ تراکنش موفق (نمایش ریزش در هر مرحله).
|
||||||
|
3. **تزریق خروجی CSV ابزارهای تحلیلی به مدل زبانی:** `images/ai-csv-analytics-prompt.png`
|
||||||
|
* **موضوع:** اسکرین‌شات از پنجره چت مدل هوش مصنوعی با فایل‌های پیوست‌شده اکسل و تولید جدول تحلیل بینش‌ها.
|
||||||
|
4. **طراحی دکمه فراخوان به اقدام بهینه‌شده (قبل و بعد):** `images/cta-optimization-before-after.png`
|
||||||
|
* **موضوع:** مقایسه بصری: دکمه خاکستری مبهم قبلی در برابر دکمه بنفش جذاب و هدفمند جدید در انتهای کارت پروژه.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||||
|
|
||||||
|
1. **تیتر اصلی:** `# استخراج بینش محصول (Product Insights) و بهینه‌سازی نرخ تبدیل با هوش مصنوعی`
|
||||||
|
2. **مقدمه:** آمار بازدید سایت شما بالاست اما زنگ گوشی شما به صدا درنمی‌آید؟ چگونه از هوش مصنوعی بخواهیم گره کور رفتار کاربران را باز کند؟
|
||||||
|
3. **جدول کاور درس**
|
||||||
|
4. **استعاره داده‌های آزمایشگاهی و نسخه درمان:**
|
||||||
|
* تفاوت دیدن آمار با فهمیدن اینکه برای افزایش درآمد یا مصاحبه‌ها چه چیزی باید تغییر کند.
|
||||||
|
5. **رسم قیف تبدیل واقعی در پروژه پورتفولیو:**
|
||||||
|
* از ورود تا مشاهده پروژه، کلیک روی رزرو، و ثبت فاکتور پرداخت.
|
||||||
|
6. **تغذیه داده‌های چندگانه (GSC + Clarity + Supabase) به هوش مصنوعی:**
|
||||||
|
* نحوه خروجی گرفتن CSV تمیز و آپلود آن به چت‌بات بدون فاش کردن اطلاعات شخصی.
|
||||||
|
7. **کشف فرصت‌های طلایی بهینه‌سازی نرخ تبدیل (CRO):**
|
||||||
|
* ۳ تغییر کوچک که می‌توانند نرخ تبدیل را دو برابر کنند.
|
||||||
|
8. **تولید خودکار گزارش استراتژیک ماهانه با ایجنت:**
|
||||||
|
* فرمت گزارش شیک برای مرور وضعیت پیشرفت و دستاوردها.
|
||||||
|
9. **جعبه پرامپت طلایی: تحلیل عمیق داده‌های محصول توسط ایجنت:**
|
||||||
|
* پرامپت دقیق:
|
||||||
|
> «من داده‌های عملکرد ماه گذشته پورتفولیو را شامل آمار سرچ گوگل، عمق اسکرول کلاریتی و تعداد پیام‌های فرم تماس پیوست کرده‌ام. لطفاً به عنوان یک مدیر ارشد محصول و متخصص CRO: ۱) گلوگاه‌های اصلی ریزش کاربران را شناسایی کن، ۲) فرضیه‌های چرایی این رفتار را بیان کن، و ۳) سه آزمایش طراحی (A/B Test) ساده و قابل اجرا برای دو برابر کردن تماس‌های کارفرمایان پیشنهاد بده.»
|
||||||
|
10. **باکس نکته Quera (`<details class="violet">`):** استفاده از تکنیک Micro-copywriting؛ تغییر چند کلمه روی دکمه (مثلاً از «ارسال» به «دریافت مشاوره رایگان ۱۵ دقیقه‌ای») که غوغا می‌کند.
|
||||||
|
11. **باکس هشدار Quera (`<details class="red">`):** هرگز همزمان ۱۰ تغییر در صفحه اعمال نکنید؛ تغییرات را دانه‌دانه تست کنید تا بفهمید کدام عامل موثر بوده است.
|
||||||
|
12. **باکس رضایت‌بخش Quera (`<details class="green">`):** دیدن افزایش چشمگیر تعامل کاربران و دریافت اولین درخواست همکاری جدی پس از اصلاح دکمه فراخوان.
|
||||||
|
13. **جمع‌بندی درس‌نامه:** تسلط بر تحلیل عمیق کسب‌وکار؛ ورود به فاز جذاب چندسکویی: تبدیل سایت به وب‌اپلیکیشن پیش‌رونده (PWA) در درس بعدی.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||||
|
- [ ] تفاوت آمار خام با بینش‌های عملیاتی محصول تشریح گردد.
|
||||||
|
- [ ] نحوه تحلیل قیف تبدیل (Conversion Funnel) با داده‌های واقعی پورتفولیو تبیین شود.
|
||||||
|
- [ ] تکنیک‌های بهینه‌سازی نرخ تبدیل (CRO) با کمک هوش مصنوعی آموزش داده شود.
|
||||||
|
- [ ] پرامپت تلفیق داده‌های تحلیلی چندمنبعی در متن درس لحاظ گردد.
|
||||||
@@ -0,0 +1,119 @@
|
|||||||
|
# مشخصات درس‌نامه: تبدیل وب‌سایت به وب‌اپلیکیشن پیش‌رونده (PWA) با قابلیت نصب و کارکرد آفلاین
|
||||||
|
- **شناسه در سیلابس:** `L15.10`
|
||||||
|
- **فصل:** فصل ۱۵: تکامل محصول با AI (Ch 15)
|
||||||
|
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||||
|
- **زمان تقریبی مطالعه:** ۱۸ دقیقه
|
||||||
|
- **پیش‌نیازهای مستقیم:** `L15.9` (استخراج بینش محصول با هوش مصنوعی)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||||
|
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||||
|
- [ ] **درک کند (Understand):** فناوری وب‌اپلیکیشن پیش‌رونده (Progressive Web App - PWA) را به عنوان پلی میان دنیای وب و اپلیکیشن‌های بومی بشناسد و بداند چگونه می‌توان بدون نیاز به عبور از هفت‌خوان کافه‌بازار یا اپ‌استور، سایت را قابل نصب کرد.
|
||||||
|
- [ ] **تحلیل/ارزیابی کند (Evaluate):** سه ستون اصلی PWA شامل: فایل مانیفست وب (`manifest.json`)، سرویس‌ورکر (Service Worker) و استراتژی‌های کش حافظه موقت (Cache-First در برابر Network-First) را ارزیابی کند.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** افزونه استاندارد Next.js PWA را در پروژه پورتفولیو نصب کرده و آیکون‌ها، رنگ پوسته، و حالت تمام‌صفحه بدون نوار آدرس (`display: standalone`) را پیکربندی نماید.
|
||||||
|
- [ ] **ایجاد کند (Create):** یک سناریوی کارکرد آفلاین طراحی کند که در صورت قطع شدن کامل اینترنت، پروژه‌های پورتفولیو همچنان با سرعت بالا از روی کش باز شوند و صفحه آفلاین شکیل نمایش داده شود.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||||
|
|
||||||
|
### آنچه باید پوشش داده شود (In-Scope):
|
||||||
|
1. **جادوی PWA: نصب مستقیم از مرورگر با یک کلیک:**
|
||||||
|
* نمایش پیام «افزودن به صفحه اصلی» (Add to Home Screen) در اندروید، آیفون، ویندوز و مک.
|
||||||
|
* باز شدن سایت شبیه یک اپلیکیشن کاملاً بومی بدون نوار آدرس زشت مرورگر.
|
||||||
|
2. **کالبدشکافی ستون اول: فایل مانیفست وب (`app/manifest.ts`):**
|
||||||
|
* تعریف مشخصات هویتی: `name`, `short_name`, `theme_color`, `background_color`.
|
||||||
|
* تعیین آیکون‌های استاندارد ۱۹۲x۱۹۲ و ۵۱۲x۵۱۲ با قابلیت تطبیق‌پذیری ماسک (Maskable Icons).
|
||||||
|
* حالت نمایش تمام‌صفحه: `display: 'standalone'`.
|
||||||
|
3. **کالبدشکافی ستون دوم: سرویس‌ورکر (Service Worker):**
|
||||||
|
* مامور نامرئی پشت صحنه که میان مرورگر و شبکه اینترنت می‌نشیند و درخواست‌ها را مدیریت می‌کند.
|
||||||
|
* استراتژی‌های کش‌گذاری:
|
||||||
|
- برای عکس‌ها، فونت‌ها و استایل‌ها: استراتژی Cache-First (اول کش، اگر نبود دانلود).
|
||||||
|
- برای داده‌های داینامیک پروژه‌ها: استراتژی Stale-While-Revalidate (نمایش سریع دیتای قبلی کش و همزمان آپدیت از اینترنت).
|
||||||
|
4. **پیاده‌سازی در Next.js مدرن:**
|
||||||
|
* استفاده از پکیج‌های استاندارد PWA نظیر `@ducanh2912/next-pwa`.
|
||||||
|
* ساخت صفحه آفلاین اختصاصی `app/offline/page.tsx`.
|
||||||
|
5. **آزمایش امتیاز PWA در لایت‌هاوس:**
|
||||||
|
* اجرای ممیزی Lighthouse در Chrome DevTools و سبز شدن نشانگر قابلیت نصب.
|
||||||
|
6. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
|
||||||
|
* کال‌اوت بنفش (`<details class="violet">`): نحوه ذخیره‌سازی فایل‌های PWA در حافظه کش مرورگر (Cache Storage API) و تفاوت آن با localStorage.
|
||||||
|
* کال‌اوت سبز (`<details class="green">`): دیدن آیکون زیبای پورتفولیو در کنار سایر برنامه‌های گوشی در منوی اصلی اندروید و آیفون.
|
||||||
|
* کال‌اوت قرمز (`<details class="red">`): هرگز درخواست‌های دیتابیسی دارای جهش (POST/DELETE) را در سرویس‌ورکر کش نکنید!
|
||||||
|
|
||||||
|
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||||
|
- نوتیفیکیشن‌های پس‌زمینه وب‌پوش پیچیده با سرورهای VAPID اختصاصی.
|
||||||
|
- ساخت کدهای اختصاصی جاوا/کاتلین اندروید (در درس بعدی با Capacitor و Expo پوشش داده می‌شود).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||||
|
|
||||||
|
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| Progressive Web App (PWA) | وب‌اپلیکیشن پیش‌رونده | سایتی با قابلیت‌های ارتقایافته نظیر نصب روی هوم‌اسکرین، اجرای آفلاین و ظاهر بومی |
|
||||||
|
| Web App Manifest | مانیفست وب‌اپلیکیشن | سند پیکربندی استانداردی که نحوه نمایش، نام، آیکون‌ها و رنگ‌های برنامه را برای سیستم‌عامل مشخص می‌کند |
|
||||||
|
| Service Worker | سرویس‌ورکر / کارگر خدمت‌رسان | اسکریپت پس‌زمینه‌ای که درخواست‌های شبکه را مهار کرده و مدیریت حافظه کش آفلاین را بر عهده دارد |
|
||||||
|
| Standalone Display | نمایش مستقل تمام‌صفحه | حالتی از اجرای وب‌اپلیکیشن که تمام نوارها و دکمه‌های مرورگر حذف شده و حس اپلیکیشن نیتیو می‌دهد |
|
||||||
|
| Stale-While-Revalidate | استراتژی تحویل فوری و اعتبارسنجی مجدد | شیوه کش‌گذاری که ابتدا دیتای موجود در حافظه را فوراً نشان می‌دهد و سپس در پس‌زمینه آخرین تغییرات را بارگذاری می‌کند |
|
||||||
|
| Maskable Icons | آیکون‌های تطبیق‌پذیر | تصاویری با حاشیه امن که توسط اندروید به اشکال مربع گرد، دایره یا لوزی به درستی برش می‌خورند |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||||
|
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||||||
|
|
||||||
|
1. **تصویر کاور درس:** `images/cover.png`
|
||||||
|
* **موضوع:** گوشی موبایل هوشمند با آیکون درخشان پورتفولیو روی هوم‌اسکرین در کنار اپلیکیشن‌های معروف و بنر تایید «نصب با موفقیت انجام شد».
|
||||||
|
2. **تفاوت تجربه وب معمولی با PWA در موبایل:** `images/standard-web-vs-pwa-mobile.png`
|
||||||
|
* **موضوع:** اینفوگرافیک مقایسه‌ای: مرورگر شلوغ با نوار آدرس و تب‌ها در برابر اپلیکیشن PWA کاملاً تمیز، تمام‌صفحه و با تم رنگی اختصاصی.
|
||||||
|
3. **جریان کار سرویس‌ورکر در حالت آنلاین و آفلاین:** `images/service-worker-interception-flow.png`
|
||||||
|
* **موضوع:** دیاگرام معماری: مرورگر $\rightarrow$ سرویس‌ورکر $\rightarrow$ اگر نت وصل بود: دریافت از سرور + ذخیره در کش $\rightarrow$ اگر نت قطع بود: خواندن مستقیم از Cache Storage.
|
||||||
|
4. **صفحه خطای آفلاین شکیل پورتفولیو:** `images/offline-fallback-screen-preview.png`
|
||||||
|
* **موضوع:** اسکرین‌شات از نمایش صفحه در حالت قطع اینترنت با پیام ملایم: «شما آفلاین هستید، اما می‌توانید پروژه‌های ذخیره‌شده قبلی را مرور کنید.»
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||||
|
|
||||||
|
1. **تیتر اصلی:** `# تبدیل وب‌سایت به وب‌اپلیکیشن پیش‌رونده (PWA) با قابلیت نصب و کارکرد آفلاین`
|
||||||
|
2. **مقدمه:** چرا وقتی می‌توانید با چند خط کانفیگ، سایت خود را مستقیماً بدون نیاز به گوگل‌پلی یا اپ‌استور روی گوشی کارفرمایان نصب کنید، این کار را نکنید؟
|
||||||
|
3. **جدول کاور درس**
|
||||||
|
4. **استعاره تبدیل بروشور کاغذی به یک نرم‌افزار دائمی:**
|
||||||
|
* تفاوت سایتی که در تب‌های فراموش‌شده مرورگر گم می‌شود با اپلیکیشنی که روی صفحه اول گوشی جا خوش می‌کند.
|
||||||
|
5. **گام اول: ساخت سند مانیفست وب (`app/manifest.ts`):**
|
||||||
|
* کدنویسی مشخصات هویتی، آیکون‌ها و رنگ تم در Next.js.
|
||||||
|
6. **گام دوم: نصب و پیکربندی Service Worker:**
|
||||||
|
* نصب پکیج `@ducanh2912/next-pwa` در `next.config.js`.
|
||||||
|
* تنظیم استراتژی‌های کش‌گذاری برای سرعت برق‌آسا.
|
||||||
|
7. **گام سوم: طراحی صفحه آفلاین اختصاصی (`app/offline/page.tsx`):**
|
||||||
|
* احترام به کاربر در زمان قطعی شبکه و قطع امید نکردن از سایت.
|
||||||
|
8. **جعبه پرامپت طلایی: تبدیل پروژه به PWA کامل با ایجنت:**
|
||||||
|
* پرامپت دقیق:
|
||||||
|
> «من می‌خواهم پروژه پورتفولیو را به یک Progressive Web App کامل تبدیل کنم. لطفاً: ۱) فایل `app/manifest.ts` را با مشخصات برند، رنگ بنفش، و آیکون‌های استاندارد بساز، ۲) کانفیگ `@ducanh2912/next-pwa` را در `next.config.js` اضافه کن، و ۳) یک صفحه جذاب آفلاین در `app/offline/page.tsx` برای مواقع قطعی نت طراحی کن.»
|
||||||
|
9. **دستورات چندسکویی برای نصب پکیج PWA:**
|
||||||
|
* منوی کشویی سه‌گانه برای ویندوز، مک و لینوکس:
|
||||||
|
- Windows (PowerShell):
|
||||||
|
```powershell
|
||||||
|
npm install @ducanh2912/next-pwa
|
||||||
|
```
|
||||||
|
- macOS (Terminal):
|
||||||
|
```bash
|
||||||
|
npm install @ducanh2912/next-pwa
|
||||||
|
```
|
||||||
|
- Linux (Bash):
|
||||||
|
```bash
|
||||||
|
npm install @ducanh2912/next-pwa
|
||||||
|
```
|
||||||
|
10. **باکس نکته Quera (`<details class="violet">`):** تولید خودکار آیکون‌های ماسکبل با ابزارهای آنلاین نظیر Maskable.app در کمتر از ۳۰ ثانیه.
|
||||||
|
11. **باکس هشدار Quera (`<details class="red">`):** سرویس‌ورکرها فقط و فقط روی پروتکل امن HTTPS و روی localhost کار می‌کنند؛ سایت بدون SSL هرگز PWA نخواهد شد.
|
||||||
|
12. **باکس رضایت‌بخش Quera (`<details class="green">`):** کلیک روی دکمه Install در نوار آدرس کروم و باز شدن پورتفولیو در پنجره اختصاصی نرم‌افزار دسکتاپ و موبایل.
|
||||||
|
13. **جمع‌بندی درس‌نامه:** مجهز شدن سایت به قابلیت‌های PWA؛ ورود به ساخت فایل خروجی نصبی واقعی اپلیکیشن موبایل با Capacitor و Expo در درس بعدی.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||||
|
- [ ] ارکان سه‌گانه PWA (مانیفست، سرویس‌ورکر، HTTPS) به روشنی شرح داده شود.
|
||||||
|
- [ ] نحوه پیاده‌سازی گام‌به‌گام در فریم‌ورک Next.js با پکیج‌های مدرن آموزش داده شود.
|
||||||
|
- [ ] استراتژی‌های کش‌گذاری آفلاین و صفحه فال‌بک آفلاین لحاظ گردد.
|
||||||
|
- [ ] دستورات نصب پکیج در تب‌های چندسکویی ویندوز، مک و لینوکس گنجانده شود.
|
||||||
@@ -0,0 +1,137 @@
|
|||||||
|
# مشخصات درس‌نامه: ساخت اپلیکیشن موبایل اندروید و iOS؛ مقایسه و اجرای عملی با Capacitor و Expo
|
||||||
|
- **شناسه در سیلابس:** `L15.11`
|
||||||
|
- **فصل:** فصل ۱۵: تکامل محصول با AI (Ch 15)
|
||||||
|
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||||
|
- **زمان تقریبی مطالعه:** ۲۲ دقیقه
|
||||||
|
- **پیش‌نیازهای مستقیم:** `L15.10` (تبدیل وب‌سایت به وب‌اپلیکیشن پیش‌رونده PWA)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||||
|
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||||
|
- [ ] **درک کند (Understand):** دو رویکرد بنیادین ورود به دنیای موبایل را بشناسد: ۱) رویکرد پل بومی بدون بازنویسی با **Capacitor** و ۲) رویکرد فریم‌ورک نیتیو اختصاصی با **React Native / Expo**.
|
||||||
|
- [ ] **تحلیل/ارزیابی کند (Evaluate):** بده‌بستان‌های مهندسی (Trade-offs) میان کپسیتور (حداکثر اشتراک کد وب، سرعت راه‌اندازی فوق‌العاده) و اکسپو (عملکرد بومی ۶۰ فریم، تعامل عمیق با ژست‌های حرکتی و قطعات سخت‌افزاری) را مقایسه کند.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** پروژه Next.js پورتفولیو را با استفاده از قابلیت Static Export و Capacitor به یک پروژه اندروید با خروجی فایل نصبی APK تبدیل نماید.
|
||||||
|
- [ ] **ایجاد کند (Create):** با کمک ایجنت، یک کامپوننت وب واکنش‌گرا را به کدهای سازگار با المان‌های نیتیو Expo (`<View>`, `<Text>`) تبدیل کرده و آن را در اپلیکیشن موبایل Expo Go اجرا کند.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||||
|
|
||||||
|
### آنچه باید پوشش داده شود (In-Scope):
|
||||||
|
1. **انقلاب موبایل برای وب‌سازها: خروج از حصار مرورگر:**
|
||||||
|
* چرا داشتن فایل نصبی اندروید (`.apk`) برای معرفی به کارفرما، پرستیژ حرفه‌ای شما را به اوج می‌رساند؟
|
||||||
|
2. **مسیر اول: جادوی Capacitor (تبدیل مستقیم وب به موبایل در ۱۵ دقیقه):**
|
||||||
|
* کپسیتور چگونه کار می‌کند؟ قرار دادن کدهای بهینه وب درون یک وب‌ویو فوق‌پایدار بومی به همراه پل ارتباطی به سنسورهای گوشی (دوربین، ویبره هپتیک، نوتیفیکیشن).
|
||||||
|
* گام‌های عملی:
|
||||||
|
- تنظیم `output: 'export'` در `next.config.js`.
|
||||||
|
- اجرای بیلد استاتیک با `npm run build` (تولید پوشه `out`).
|
||||||
|
- نصب بسته‌های رسمی: `npm install @capacitor/core @capacitor/cli @capacitor/android`.
|
||||||
|
- اجرای دستورات `npx cap init` و `npx cap add android`.
|
||||||
|
- همگام‌سازی با `npx cap sync` و باز کردن در Android Studio با `npx cap open android`.
|
||||||
|
- گرفتن خروجی APK برای نصب روی گوشی واقعی.
|
||||||
|
3. **مسیر دوم: قدرت بومی React Native و Expo:**
|
||||||
|
* چرا و چه زمانی سراغ Expo می‌رویم؟ وقتی که نیازمند کامپوننت‌های بومی سیستم‌عامل، ژست‌های لمسی پیچیده یا اپ‌های بسیار سنگین هستیم.
|
||||||
|
* تفاوت المان‌های وب و موبایل: جایگزینی `<div>` با `<View>` و `<p>` با `<Text>`.
|
||||||
|
* قدرت ایجنت‌ها در ترجمه سریع کامپوننت‌های وب به کامپوننت‌های Expo.
|
||||||
|
* اجرای آنی اپلیکیشن روی گوشی با اسکن کد QR در برنامه Expo Go بدون نیاز به کابل.
|
||||||
|
4. **جدول مقایسه‌ای جامع: Capacitor در برابر Expo:**
|
||||||
|
* مقایسه در ۶ بعد: زمان تا خروجی، میزان نیاز به بازنویسی، دسترسی به سخت‌افزار، پرفورمنس انیمیشن‌ها، اندازه فایل نهایی و منحنی یادگیری.
|
||||||
|
5. **دستورات چندسکویی برای نصب و کامندهای کپسیتور و اکسپو:**
|
||||||
|
* دستورات در منوهای کشویی ویندوز، مک و لینوکس.
|
||||||
|
6. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
|
||||||
|
* کال‌اوت بنفش (`<details class="violet">`): پل ارتباطی کپسیتور (Capacitor Bridge) و نحوه ارسال پیام‌های JSON میان کدهای جاوااسکریپت و کدهای کاتلین/جاوا.
|
||||||
|
* کال‌اوت سبز (`<details class="green">`): ارسال فایل APK پورتفولیو به دوستان در تلگرام و دیدن باز شدن اپلیکیشن روی گوشی آنها درست مثل برنامه‌های کافه‌بازار!
|
||||||
|
* کال‌اوت قرمز (`<details class="red">`): محدودیت خروجی استاتیک؛ در حالت کپسیتور نمی‌توانید از Server-Side Rendering درون گوشی استفاده کنید؛ تمام فراخوانی‌های دیتابیس باید به دامنه آنلاین پروداکشن ارسال شوند.
|
||||||
|
|
||||||
|
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||||
|
- توسعه افزونه‌های اختصاصی C++ یا ماژول‌های Native Bridge سطح پایین با کاتلین خام.
|
||||||
|
- پرداخت‌های درون‌برنامه‌ای پیچیده کافه‌بازار و مایکت (در پروژه‌های تجاری بعدی).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||||
|
|
||||||
|
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| Capacitor | موتور رابط کپسیتور | ابزار متن‌باز شرکت Ionic برای بسته‌بندی برنامه‌های وب در پوسته‌های بومی iOS و Android |
|
||||||
|
| React Native | فریم‌ورک ری‌اکت نیتیو | فریم‌ورک ساخت اپلیکیشن با کامپوننت‌های بومی واقعی سیستم‌عامل با زبان جاوااسکریپت |
|
||||||
|
| Expo | پلتفرم ابزاری اکسپو | اکوسیستم مدرن و سریع برای ساخت، اجرا و تست برنامه‌های React Native بدون نیاز به Android Studio |
|
||||||
|
| APK (Android Package) | بسته نصبی اندروید | فرمت فایل اجرایی استاندارد برای نصب برنامه‌ها روی سیستم‌عامل اندروید |
|
||||||
|
| Static Export | خروجی استاتیک وب | تبدیل برنامه به مجموعه‌ای از فایل‌های آماده HTML, JS, CSS بدون نیاز به اجرای سرور Node.js |
|
||||||
|
| Expo Go | اپلیکیشن تست اکسپو گو | برنامه موبایلی که به توسعه‌دهنده اجازه می‌دهد کدهای خود را با اسکن QR کد فوراً روی گوشی تست کند |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||||
|
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||||||
|
|
||||||
|
1. **تصویر کاور درس:** `images/cover.png`
|
||||||
|
* **موضوع:** گوشی هوشمند نئونی با کابل اتصال که همزمان لوگوهای Capacitor و Expo از آن خارج شده و نشان‌دهنده دو مسیر است.
|
||||||
|
2. **کالبدشکافی نحوه کارکرد موتور Capacitor:** `images/capacitor-bridge-architecture.png`
|
||||||
|
* **موضوع:** دیاگرام معماری: کدهای وب پورتفولیو $\rightarrow$ وب‌ویو بومی $\rightarrow$ پل کپسیتور $\rightarrow$ دسترسی به دوربین، فایل‌ها و شتاب‌سنج گوشی.
|
||||||
|
3. **فرآیند خروجی APK در محیط Android Studio:** `images/android-studio-build-apk.png`
|
||||||
|
* **موضوع:** اسکرین‌شات از محیط اندروید استودیو با کلیک روی منوی Build Bundle/APK و نمایش نوتیفیکیشن موفقیت ساخت فایل `.apk`.
|
||||||
|
4. **اجرای اپلیکیشن در محیط Expo Go با اسکن QR:** `images/expo-go-qr-scan-flow.png`
|
||||||
|
* **موضوع:** اینفوگرافیک: اجرای دستور ترمینال `npx expo start` $\rightarrow$ نمایش کد QR $\rightarrow$ اسکن با دوربین گوشی $\rightarrow$ باز شدن آنی اپلیکیشن نیتیو.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||||
|
|
||||||
|
1. **تیتر اصلی:** `# ساخت اپلیکیشن موبایل اندروید و iOS؛ مقایسه و اجرای عملی با Capacitor و Expo`
|
||||||
|
2. **مقدمه:** پورتفولیوی وب شما آماده است؛ اما چه حسی دارد اگر فایل نصبی اپلیکیشن موبایل خود را در رزومه بگذارید تا کارفرما آن را روی گوشی‌اش نصب کند؟
|
||||||
|
3. **جدول کاور درس**
|
||||||
|
4. **دو راهی بزرگ موبایل: کپسیتور (Capacitor) یا اکسپو (Expo)؟**
|
||||||
|
* بررسی تفاوت‌های مفهومی؛ چرا هر دو مسیر باارزش هستند و کدام را کی انتخاب کنیم.
|
||||||
|
5. **کارگاه عملی مسیر اول: خروجی APK پورتفولیو با Capacitor در ۱۰ دقیقه:**
|
||||||
|
* گام ۱: فعال‌سازی `output: 'export'` در `next.config.js`.
|
||||||
|
* گام ۲: نصب پکیج‌های `@capacitor/core` و `@capacitor/android`.
|
||||||
|
* گام ۳: همگام‌سازی و تولید پروژه اندروید با `npx cap add android`.
|
||||||
|
* گام ۴: بیلد فایل APK در اندروید استودیو یا خط فرمان.
|
||||||
|
6. **کارگاه عملی مسیر دوم: دنیای نیتیو با React Native و Expo:**
|
||||||
|
* ترجمه عناصر وب (`div`, `p`, `img`) به المان‌های نیتیو (`View`, `Text`, `Image`).
|
||||||
|
* ساخت یک صفحه جدید موبایلی با Expo و تست لحظه‌ای با اپلیکیشن Expo Go.
|
||||||
|
7. **جدول مقایسه‌ای ماتریس تصمیم‌گیری: Capacitor vs Expo:**
|
||||||
|
* مقایسه سرعت، حجم، عملکرد و پیچیدگی پیاده‌سازی.
|
||||||
|
8. **جعبه پرامپت طلایی: ترجمه کامپوننت‌های وب به کدهای موبایل Expo با ایجنت:**
|
||||||
|
* پرامپت دقیق:
|
||||||
|
> «من این کامپوننت کارت پروژه پورتفولیو را در Next.js دارم: [کد کامپوننت]. لطفاً آن را به یک کامپوننت کاملاً بومی سازگار با React Native و Expo تبدیل کن. تمام تگ‌های div و span را با View و Text جایگزین نما و استایل‌های Tailwind را به StyleSheet نیتیو ترجمه کن.»
|
||||||
|
9. **دستورات چندسکویی برای راه‌اندازی کپسیتور:**
|
||||||
|
* منوی کشویی سه‌گانه برای ویندوز، مک و لینوکس:
|
||||||
|
- Windows (PowerShell):
|
||||||
|
```powershell
|
||||||
|
npm install @capacitor/core @capacitor/cli @capacitor/android
|
||||||
|
npx cap init "Portfolio" "com.portfolio.app" --web-dir out
|
||||||
|
npm run build
|
||||||
|
npx cap add android
|
||||||
|
npx cap copy
|
||||||
|
```
|
||||||
|
- macOS (Terminal):
|
||||||
|
```bash
|
||||||
|
npm install @capacitor/core @capacitor/cli @capacitor/android @capacitor/ios
|
||||||
|
npx cap init "Portfolio" "com.portfolio.app" --web-dir out
|
||||||
|
npm run build
|
||||||
|
npx cap add android
|
||||||
|
npx cap copy
|
||||||
|
```
|
||||||
|
- Linux (Bash):
|
||||||
|
```bash
|
||||||
|
npm install @capacitor/core @capacitor/cli @capacitor/android
|
||||||
|
npx cap init "Portfolio" "com.portfolio.app" --web-dir out
|
||||||
|
npm run build
|
||||||
|
npx cap add android
|
||||||
|
npx cap copy
|
||||||
|
```
|
||||||
|
10. **باکس نکته Quera (`<details class="violet">`):** اهمیت آدرس‌دهی مطلق (Absolute URLs) به APIهای پروداکشن در اپ موبایل کپسیتور به جای آدرس‌های نسبی (`/api/...`).
|
||||||
|
11. **باکس هشدار Quera (`<details class="red">`):** برای خروجی iOS به سیستم‌عامل macOS و نرم‌افزار Xcode نیاز دارید؛ اما خروجی اندروید روی ویندوز، مک و لینوکس به راحتی ساخته می‌شود.
|
||||||
|
12. **باکس رضایت‌بخش Quera (`<details class="green">`):** لمس آیکون اختصاصی اپلیکیشن روی گوشی و تجربه اسکرول نرم و پاسخگویی سریع آن.
|
||||||
|
13. **جمع‌بندی درس‌نامه:** تسلط بر مهندسی موبایل؛ ورود به آخرین ایستگاه پلتفرم‌ها: بسته‌بندی نرم‌افزار دسکتاپ با Tauri و Electron در درس بعدی.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||||
|
- [ ] هر دو رویکرد Capacitor و Expo به همراه کاربرد و مزایای هرکدام تشریح گردند.
|
||||||
|
- [ ] گام‌های عملی تبدیل پروژه Next.js به پروژه اندروید کپسیتور به طور دقیق ارائه شود.
|
||||||
|
- [ ] جدول مقایسه‌ای ماتریس تفاوت‌های Capacitor و Expo در متن لحاظ گردد.
|
||||||
|
- [ ] پرامپت تبدیل کدهای وب به کدهای نیتیو React Native برای ایجنت آموزش داده شود.
|
||||||
@@ -0,0 +1,128 @@
|
|||||||
|
# مشخصات درس‌نامه: ساخت اپلیکیشن دسکتاپ چندسکویی؛ انقلاب Tauri سبک در برابر غول Electron
|
||||||
|
- **شناسه در سیلابس:** `L15.12`
|
||||||
|
- **فصل:** فصل ۱۵: تکامل محصول با AI (Ch 15)
|
||||||
|
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||||
|
- **زمان تقریبی مطالعه:** ۲۰ دقیقه
|
||||||
|
- **پیش‌نیازهای مستقیم:** `L15.11` (ساخت اپلیکیشن موبایل اندروید و iOS با Capacitor و Expo)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||||
|
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||||
|
- [ ] **درک کند (Understand):** دلایل تمایل کاربران به استفاده از اپلیکیشن‌های دسکتاپ بومی (دسترسی به System Tray، کلیدهای میانبر سیستمی، نوتیفیکیشن‌های بومی و کارکرد مستقل از تب‌های مرورگر) را شرح دهد.
|
||||||
|
- [ ] **تحلیل/ارزیابی کند (Evaluate):** معماری سنگین **Electron** (حمل کامل موتور کرومیوم و نودجی‌اس با مصرف رم ۳۰۰ مگابایت و حجم بالای ۱۰۰ مگابایت) را در مقایسه با معماری انقلابی **Tauri** (استفاده از وب‌ویو نیتیو سیستم‌عامل، مصرف رم ۳۰ مگابایت و خروجی ۵ مگابایتی) ارزیابی کند.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** ابزار **Tauri CLI** را در پروژه Next.js راه‌اندازی کرده و پورتفولیو را در یک پنجره مستقل دسکتاپ با دستور `npx tauri dev` اجرا نماید.
|
||||||
|
- [ ] **ایجاد کند (Create):** فایل خروجی نصبی واقعی ویندوز (`.exe` / `.msi`) و مک (`.dmg`) را با یک دستور ساده بیلد تولید کرده و یک آیکون منوی سینی سیستم (System Tray) برای دسترسی سریع به سایت تعبیه کند.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||||
|
|
||||||
|
### آنچه باید پوشش داده شود (In-Scope):
|
||||||
|
1. **فراتر از مرورگر: حضور ماندگار روی دسکتاپ ویندوز، مک و لینوکس:**
|
||||||
|
* چرا وقتی می‌توانید برای پروژه‌تان یک برنامه دسکتاپ سبک با آیکون اختصاصی در تسک‌بار بسازید، نباید به یک تب در میان صدها تب باز مرورگر کاربر محدود بمانید؟
|
||||||
|
2. **کالبدشکافی الکترون (Electron)؛ پیشگام باسابقه اما سنگین:**
|
||||||
|
* نرم‌افزارهای موفقی مثل VS Code، Slack، Discord و Spotify چگونه با الکترون ساخته شدند؟
|
||||||
|
* نقطه ضعف بزرگ الکترون: همراه بردن یک مرورگر کروم کامل در دل فایل نصبی! (حجم فایل نصبی بالای ۸۰ مگابایت و مصرف سنگین حافظه رم).
|
||||||
|
3. **انقلاب تاوری (Tauri)؛ سبک، سریع و کم‌مصرف:**
|
||||||
|
* تاوری چگونه این مشکل را حل کرد؟ به جای نصب کروم جدید، از وب‌ویو پیش‌فرض خود ویندوز (Edge WebView2) و مک (WebKit) استفاده می‌کند.
|
||||||
|
* نتیجه شگفت‌انگیز: فایل نصبی فوق‌العاده کوچک (حدود ۵ مگابایت) و مصرف رم تنها در حد ۳۰ تا ۵۰ مگابایت!
|
||||||
|
4. **کارگاه عملی: بسته‌بندی پورتفولیو با Tauri در ۴ گام:**
|
||||||
|
* گام ۱: نصب Tauri CLI در پروژه: `npm install -D @tauri-apps/cli`.
|
||||||
|
* گام ۲: مقداردهی اولیه پروژه با `npx tauri init`.
|
||||||
|
* گام ۳: تنظیمات عنوان پنجره، ابعاد و آیکون در فایل `src-tauri/tauri.conf.json`.
|
||||||
|
* گام ۴: اجرای زنده با `npx tauri dev` و مشاهده باز شدن پنجره نرم‌افزار روی ویندوز/مک.
|
||||||
|
5. **ساخت فایل خروجی نصبی نهایی (Production Build):**
|
||||||
|
* اجرای دستور `npx tauri build` و تحویل فایل `.exe` در پوشه `src-tauri/target/release/bundle`.
|
||||||
|
6. **قابلیت‌های جذاب دسکتاپ: آیکون کنار ساعت (System Tray):**
|
||||||
|
* دسترسی سریع به پورتفولیو و پنل ادمین با کلیک راست روی آیکون در نوار وظیفه ویندوز.
|
||||||
|
7. **دستورات چندسکویی برای نصب و اجرای تاوری:**
|
||||||
|
* دستورات در منوهای کشویی ویندوز، مک و لینوکس.
|
||||||
|
8. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
|
||||||
|
* کال‌اوت بنفش (`<details class="violet">`): امنیت خارق‌العاده تاوری؛ هسته پشتیبان تاوری با زبان ایمن Rust نوشته شده و خطرات دسترسی ناامن به فایل‌های سیستم را مهار می‌کند.
|
||||||
|
* کال‌اوت سبز (`<details class="green">`): شگفتی از خروجی یک فایل نصبی ۵ مگابایتی شیک که در کسری از ثانیه نصب و اجرا می‌شود.
|
||||||
|
* کال‌اوت قرمز (`<details class="red">`): نبود ماژول‌های داخلی نودجی‌اس (`fs`, `path`) در فرانت‌اند تاوری؛ تمام دسترسی‌ها به فایل‌های هارد باید از طریق پلاگین‌های رسمی تاوری انجام شود.
|
||||||
|
|
||||||
|
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||||
|
- برنامه‌نویسی عمیق کدهای زبان Rust در بک‌اند تاوری (تسک‌ها از طریق لایه فرانت‌اند جاوااسکریپت هدایت می‌شوند).
|
||||||
|
- دریافت گواهی امضای دیجیتال گران‌قیمت کد (Code Signing Certificates) در ویندوز و اپل.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||||
|
|
||||||
|
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| Desktop Wrapper | بسته‌بند دسکتاپ | ابزاری برای تبدیل برنامه‌های وب به نرم‌افزارهای نصبی با پنجره مستقل برای ویندوز، مک و لینوکس |
|
||||||
|
| Tauri | فریم‌ورک تاوری | ابزار مدرن، امن و بسیار سبک ساخت نرم‌افزارهای دسکتاپ با وب‌ویو سیستم‌عامل و زبان راست |
|
||||||
|
| Electron | فریم‌ورک الکترون | بستر باسابقه ساخت نرم‌افزار دسکتاپ با ترکیب موتور کرومیوم و محیط اجرای Node.js |
|
||||||
|
| WebView2 | وب‌ویو تو مایکروسافت | کامپوننت داخلی ویندوز ۱۰ و ۱۱ برای رندر کردن محتوای وب در برنامه‌های دسکتاپ بدون نیاز به نصب کروم |
|
||||||
|
| System Tray | سینی سیستم / کنار ساعت | بخش اعلان‌ها در گوشه نوار وظیفه سیستم‌عامل برای دسترسی و کنترل سریع برنامه‌های در حال اجرا |
|
||||||
|
| Native Executable (.exe) | فایل اجرایی بومی | فایل باینری کامپایل‌شده سیستم‌عامل برای نصب و اجرای مستقیم نرم‌افزار |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||||
|
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||||||
|
|
||||||
|
1. **تصویر کاور درس:** `images/cover.png`
|
||||||
|
* **موضوع:** پنجره نرم‌افزار دسکتاپ نئونی با آیکون‌های ویندوز، اپل و لینوکس با لوگوی سبک‌بال تاوری و مصرف اندک رم.
|
||||||
|
2. **مقایسه ساختاری معماری Electron در برابر Tauri:** `images/electron-vs-tauri-architecture.png`
|
||||||
|
* **موضوع:** اینفوگرافیک مقایسه‌ای: الکترون با جعبه سنگین کرومیوم + نودجی‌اس در چپ در برابر تاوری با لایه سبک وب‌ویو سیستم‌عامل و هسته کم‌مصرف راست در راست.
|
||||||
|
3. **نمودار مصرف حافظه رم و اندازه فایل نصبی:** `images/tauri-vs-electron-ram-size.png`
|
||||||
|
* **موضوع:** نمودار میله‌ای مقایسه‌ای: مصرف رم (الکترون ۳۵۰ مگابایت vs تاوری ۳۵ مگابایت) و حجم فایل نصبی (الکترون ۹۰ مگابایت vs تاوری ۵ مگابایت).
|
||||||
|
4. **نرم‌افزار دسکتاپ پورتفولیو در حال اجرا با System Tray:** `images/tauri-desktop-portfolio-window.png`
|
||||||
|
* **موضوع:** اسکرین‌شات از دسکتاپ ویندوز با پنجره شیک پورتفولیو و منوی کوچک کلیک راست آیکون سایت در کنار ساعت ویندوز.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||||
|
|
||||||
|
1. **تیتر اصلی:** `# ساخت اپلیکیشن دسکتاپ چندسکویی؛ انقلاب Tauri سبک در برابر غول Electron`
|
||||||
|
2. **مقدمه:** سایت شما روی وب زنده است، PWA شده و فایل اندروید هم دارد؛ حال وقت آن است که یک فایل `.exe` شکیل بسازید و روی دسکتاپ ویندوز و مک بنشینید!
|
||||||
|
3. **جدول کاور درس**
|
||||||
|
4. **چرا اپلیکیشن دسکتاپ هنوز پادشاه تمرکز کاربران است؟**
|
||||||
|
* فرار از حواس‌پرتی تب‌های بی‌شمار مرورگر و حضور دائمی در کنار ساعت و تسک‌بار.
|
||||||
|
5. **دوئل بزرگ قرن: الکترون (Electron) در برابر تاوری (Tauri):**
|
||||||
|
* چرا الکترون با وجود شهرتش سنگین است و چگونه تاوری دنیای توسعه دسکتاپ را شگفت‌زده کرد؟
|
||||||
|
6. **پیش‌نیازهای اجرای تاوری در سیستم‌عامل‌ها:**
|
||||||
|
* ویندوز، مک و لینوکس (وجود پیش‌فرض WebView2 در ویندوز ۱۰ و ۱۱).
|
||||||
|
7. **کارگاه عملی: ساخت نرم‌افزار دسکتاپ پورتفولیو در ۴ گام ساده:**
|
||||||
|
* گام ۱: نصب ابزار خط فرمان با `npm install -D @tauri-apps/cli`.
|
||||||
|
* گام ۲: اجرای دستور جادویی `npx tauri init`.
|
||||||
|
* گام ۳: تنظیمات نام برنامه و پنجره در `tauri.conf.json`.
|
||||||
|
* گام ۴: ران زنده با `npx tauri dev` و تماشای پنجره واقعی دسکتاپ.
|
||||||
|
8. **بیلد فایل نصبی نصبی با پسوند `.exe` و `.dmg`:**
|
||||||
|
* اجرای دستور `npx tauri build` و دریافت بسته نصبی سبک ۵ مگابایتی.
|
||||||
|
9. **دستورات چندسکویی برای راه‌اندازی تاوری:**
|
||||||
|
* منوی کشویی سه‌گانه برای ویندوز، مک و لینوکس:
|
||||||
|
- Windows (PowerShell):
|
||||||
|
```powershell
|
||||||
|
npm install -D @tauri-apps/cli
|
||||||
|
npx tauri init
|
||||||
|
npx tauri dev
|
||||||
|
```
|
||||||
|
- macOS (Terminal):
|
||||||
|
```bash
|
||||||
|
npm install -D @tauri-apps/cli
|
||||||
|
npx tauri init
|
||||||
|
npx tauri dev
|
||||||
|
```
|
||||||
|
- Linux (Bash):
|
||||||
|
```bash
|
||||||
|
npm install -D @tauri-apps/cli
|
||||||
|
npx tauri init
|
||||||
|
npx tauri dev
|
||||||
|
```
|
||||||
|
10. **باکس نکته Quera (`<details class="violet">`):** فعال‌سازی ویژگی System Tray در تاوری برای کوچک شدن برنامه در کنار ساعت سیستم به جای بسته شدن کامل پنجره.
|
||||||
|
11. **باکس هشدار Quera (`<details class="red">`):** عدم وجود ماژول‌های نودجی‌اس در مرورگر داخلی تاوری؛ برای کارهای محلی از افزونه‌های استاندارد `@tauri-apps/plugin` استفاده کنید.
|
||||||
|
12. **باکس رضایت‌بخش Quera (`<details class="green">`):** دابل کلیک روی فایل `.exe` ساخته‌شده و باز شدن فوری برنامه پورتفولیو در کمتر از ۲۰۰ میلی‌ثانیه!
|
||||||
|
13. **جمع‌بندی فصل پانزدهم و ورود به فینال دوره:** جشن پایان فاز تکامل چندسکویی و هوشمندسازی محصول؛ ورود به فصل شانزدهم و پایانی: ادامه راه (فرهنگ مهندسی ایجنتیک، ارکستراسیون سیستم‌ها و آینده بازار کار).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||||
|
- [ ] تفاوت معماری Electron و Tauri با اعداد و ارقام مصرف منابع تبیین شود.
|
||||||
|
- [ ] مراحل گام‌به‌گام راه‌اندازی Tauri در پروژه Next.js ارائه گردد.
|
||||||
|
- [ ] نحوه تولید فایل نصبی نهایی (.exe / .dmg) آموزش داده شود.
|
||||||
|
- [ ] دستورات خط فرمان در تب‌های چندسکویی برای ویندوز، مک و لینوکس درج شود.
|
||||||
Reference in New Issue
Block a user