# مشخصات درس‌نامه: تزریق قابلیت‌های پیشرفته هوش مصنوعی؛ جستجوی معنایی (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 برای تولید خودکار دیتای پروژه‌ها تشریح گردد.
- [ ] پرامپت‌های ساخت اندپوینت جستجوی برداری در متن درس لحاظ شوند.