104 lines
11 KiB
Markdown
104 lines
11 KiB
Markdown
# مشخصات درس‌نامه: فیچرها و معیارهای پذیرش (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 به همراه ساختار منطقی در متن آموزش داده شود.
|
||
- [ ] معیارهای قبولی برای ۳ بخش اصلی پروژه محوری (لاگین، مدیریت پروژه، پنل سئو) به طور کامل مستند شده باشد.
|
||
- [ ] نقد واژگان مبهم کیفی و لزوم شفافیت عددی و رفتاری به صراحت در متن حضور داشته باشد.
|