vibe-coding-college-specs/chapters/04-idea-to-product/05-lesson-features-and-acceptance-criteria/spec.md

مشخصات درس‌نامه: فیچرها و معیارهای پذیرش (Features & Acceptance Criteria)

• شناسه در سیلابس: L4.6
• فصل: فصل ۴: از ایده تا محصول (Ch 4)
• نوع محتوا: 📘 درس‌نامه متنی
• زمان تقریبی مطالعه: ۱۵ دقیقه
• پیش‌نیازهای مستقیم: L4.5 (محدوده محصول و تعریف MVP)

---

۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)

دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:

• درک کند (Understand): تفاوت اساسی میان یک ویژگی کلی (Feature) با معیارهای پذیرش شفاف و سنجش‌پذیر (Acceptance Criteria - AC) چیست.
• تحلیل/ارزیابی کند (Evaluate): چرا ارائه معیارهای پذیرش دقیق به ایجنت‌های هوش مصنوعی، خطاهای پیاده‌سازی و نادیده گرفتن حالت‌های خطا (Edge Cases) را به حداقل می‌رساند.
• به‌کار ببندد (Apply): الگوی استاندارد Given-When-Then (فرض کنید - هنگامی که - آن‌گاه) را برای توصیف سناریوهای آزمون فیچرها به کار گیرد.
• به‌کار ببندد (Apply): معیارهای پذیرش شفاف را برای فیچرهای کلیدی پروژه محوری (ورود ادمین، مدیریت پروژه‌ها و پنل متادیتا سئو) فرمول‌بندی کند.
• تحلیل/ارزیابی کند (Evaluate): عبارات کیفی و مبهم (مانند «فرم زیبا باشد» یا «سرعت بالا باشد») را با شروط مشخص و قابل راستی‌آزمایی جایگزین کند.

---

۲. محدوده و مرزهای محتوا (Scope & Boundaries)

آنچه باید پوشش داده شود (In-Scope):

1. معماری فیچر و راز پایان ابهام در وایب کدینگ:
   • وقتی به هوش مصنوعی می‌گویید «یک فرم برای اضافه کردن پروژه بساز»، او یک فرم ساده بدون اعتبارسنجی، بدون پیام خطا، بدون لودینگ و بدون تایید ذخیره می‌سازد!
   • برای اینکه خروجی حرفه‌ای باشد، باید «معیار پذیرش» (شرط قبولی تحویل کار) را تعیین کنید.
2. الگوی طلایی Given-When-Then (چارچوب رفتاری BDD):
   • Given (فرض کنید): وضعیت اولیه سیستم یا کاربر کجاست؟ (مثلاً: فرض کنید ادمین لاگین کرده و در پنل مدیریت است).
   • When (هنگامی که): کاربر چه رویدادی را آغاز می‌کند؟ (مثلاً: فیلدهای عنوان و لینک را پر کرده و روی دکمه «ذخیره» کلیک می‌کند).
   • Then (آن‌گاه): نتیجه دقیق و بدون ابهام چیست؟ (مثلاً: پیام توست سبز نمایش داده شود، فرم بسته شود و پروژه جدید به بالای لیست پروژه‌ها بدون رفرش صفحه اضافه گردد).
3. تدوین معیارهای پذیرش سه فیچر کلیدی پروژه محوری (پورتفولیوی پویا):
   • فیچر ۱: احراز هویت و ورود ادمین (Admin Auth):
     • شرط ۱: اگر رمز عبور اشتباه وارد شود \rightarrow پیام خطای قرمزرنگ «رمز عبور نادرست است» نمایش داده شود و کاربر وارد نشود.
     • شرط ۲: اگر رمز درست بود \rightarrow کوکی سشن ایمن ست شود و کاربر به آدرس /admin هدایت گردد.
     • شرط ۳: اگر کاربری بدون لاگین به آدرس /admin رفت \rightarrow خودکار به صفحه لاگین ریدایرکت شود (Route Guard).
   • فیچر ۲: فرم ایجاد و ویرایش پروژه (Project Management):
     • شرط ۱: فیلدهای «عنوان» و «تصویر» الزامی باشند و در صورت خالی بودن دکمه ذخیره پیام هشدار بدهد.
     • شرط ۲: امکان انتخاب چندین تگ مهارتی (مثل Next.js, Tailwind, Supabase) وجود داشته باشد.
     • شرط ۳: دکمه حذف باید دارای پنجره تایید نهایی (Confirmation Modal) باشد تا از حذف تصادفی جلوگیری کند.
   • فیچر ۳: پنل تنظیمات سئو (SEO Management Panel):
     • شرط ۱: فرم دارای فیلدهای عنوان سئو (حداکثر ۶۰ کاراکتر)، توضیحات متا (حداکثر ۱۶۰ کاراکتر) و آدرس تصویر OG باشد.
     • شرط ۲: شمارنده تعداد کاراکتر به صورت زنده نمایش داده شود و در صورت رد شدن از سقف رنگش قرمز شود.
     • شرط ۳: با ذخیره تنظیمات، تگ‌های <title> و <meta> در سورس صفحه اصلی فوراً آپدیت شوند.
4. پرامپت استخراج معیارهای پذیرش با هوش مصنوعی:
   • پرامپت حرفه‌ای: «این فیچر را در نظر بگیر؛ تمام حالت‌های مرزی (Edge Cases)، خطاهای اعتبارسنجی و سناریوهای کاربری را در قالب Given-When-Then برای من استخراج کن.»
5. کال‌اوت‌های Quera:
   • <details class="violet">: قدرت الگوی Given-When-Then؛ چگونه بدون نوشتن یک خط کد تست، ایجنت را در ریل درست تست‌نویسی قرار دهیم؟
   • <details class="red">: تله واژگان مبهم؛ هرگز در معیارهای پذیرش از کلمات «زیبا»، «سریع»، «مدرن» یا «راحت» استفاده نکنید؛ اعداد، رنگ‌ها و رفتارها را دقیق بنویسید.

آنچه نباید وارد آن شویم (Out-of-Scope):

• تفکیک تفصیلی شاخص‌های معماری و نیازمندی‌های غیرکارکردی (درس بعدی ۴.۷).
• پیاده‌سازی کدهای اعتبارسنجی Zod یا React Hook Form (در فصل‌های ۶ و ۷).

---

۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)

اصطلاح انگلیسی	معادل فارسی مصوب	توضیح یک‌خطی ساده
Acceptance Criteria (AC)	معیارهای پذیرش	مجموعه‌ای از شروط شفاف و آزمون‌پذیر که یک فیچر برای تایید نهایی باید داشته باشد
Given-When-Then	فرض کنید - هنگامی که - آن‌گاه	الگوی ساخت‌یافته استاندارد برای بیان سناریوهای آزمون رفتار کاربر در نرم‌افزار
Edge Case	حالت مرزی	موقعیت خاص و استثنایی در اجرای نرم‌افزار (مانند ورودی نامعتبر، دیسکانکت شدن اینترنت)
Route Guard	محافظ مسیر / گیت دسترسی	سازوکاری که مانع ورود کاربران تاییدنشده به صفحات خصوصی و پنل ادمین می‌شود
Toast Notification	پیام اعلان توست	پیام کوچک و موقتی که در گوشه صفحه برای اعلام موفقیت یا خطای یک عملیات ظاهر می‌شود

---

۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)

راهنمای ایجنت نویسنده: تمام تصاویر باید در پوشهٔ images/ قرار گرفته و در قالب جدول تک‌خانه‌ای وسط‌چین با کپشن تفصیلی درج شوند:

1. تصویر کاور درس: images/cover.png
   • موضوع: کاور مدرن با تم تیره و چک‌لیست سبز هولوگرافیک دیجیتال که مهر تایید قبولی (Approved) را روی کارت یک فیچر ثبت می‌کند.
2. کالبدشکافی فیچر در برابر معیارهای پذیرش: images/feature-vs-ac-breakdown.png
   • موضوع: مقایسه دو کارت: کارت عنوان کلی فیچر («فرم ایجاد پروژه») در برابر لیست ۵ شرط قبولی شفاف و بدون ابهام.
3. دیاگرام سه‌گانه Given-When-Then: images/given-when-then-loop.png
   • موضوع: اینفوگرافیک چرخشی ۳ رنگ: ۱. وضعیت اولیه (Given) \rightarrow ۲. رویداد و کنش (When) \rightarrow ۳. نتیجه قطعی (Then).
4. معیارهای قبولی پنل سئو پورتفولیو در عمل: images/seo-ac-visual-card.png
   • موضوع: ماکت رابط پنل سئو با نمایش فیلد تایتل، شمارنده ۶۰ کاراکتر و فلش شرط‌های تایید سبز.

---

۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (README.md)

1. تیتر اصلی: # فیچرها و معیارهای پذیرش: هنر شفاف‌سازی شروط قبولی
2. مقدمه: چرا هوش مصنوعی بدون معیارهای پذیرش، خروجی‌های ناقص و پر از باگ تحویل می‌دهد؟
3. جدول کاور درس
4. تفاوت بنیادین فیچر (ویژگی) با معیار پذیرش (AC): از عنوان تا جزئیات آزمون‌پذیر.
5. الگوی طلایی Given-When-Then: چارچوب مهندسی برای نگارش شروط قبولی.
6. باکس شگفت‌انگیز Quera (<details class="violet">): چگونه با Given-When-Then رفتار ایجنت را قفل کنیم؟
7. کالبدشکافی معیارهای قبولی در ۳ فیچر پورتفولیوی پویا:
   • فیچر ۱: سیستم لاگین و محافظت از پنل ادمین.
   • فیچر ۲: فرم‌های مدیریت و ویرایش پروژه‌ها.
   • فیچر ۳: پنل تنظیمات متا تگ‌های سئو همراه با شمارنده کاراکتر.
8. استخراج شروط مرزی (Edge Cases) با کمک هوش مصنوعی: پرامپت منتقد حالت‌های شکست.
9. باکس هشدار Quera (<details class="red">): مرگ بر صفت‌های مبهم! پرهیز از کلماتی مثل زیبا و سریع در تعریف معیار.
10. جمع‌بندی درس‌نامه: تسلط بر مهارت نگارش شرط‌های قبولی و آماده‌سازی برای تحلیل نیازمندی‌های کیفی و فنی.

---

۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)

• تمایز میان Feature و Acceptance Criteria با مثال‌های قابل درک روشن شده باشد.
• چارچوب Given-When-Then به همراه ساختار منطقی در متن آموزش داده شود.
• معیارهای قبولی برای ۳ بخش اصلی پروژه محوری (لاگین، مدیریت پروژه، پنل سئو) به طور کامل مستند شده باشد.
• نقد واژگان مبهم کیفی و لزوم شفافیت عددی و رفتاری به صراحت در متن حضور داشته باشد.