# نقشه جامع پوشش تست‌های سرتاسری (E2E Test Coverage Map) — پروژه Canina

این سند شامل استخراج و فهرست کامل تمامی قابلیت‌های کاربرمحور، فرم‌ها، جریان‌های خرید و احراز هویت، عملیات CRUD پنل مدیریت و حالت‌های مرزی (Edge Cases) در پلتفرم Canina است.

---

## ۱. معماری و نقش‌های کاربری (User Roles)
1. **مهمان / کاربر عمومی (Guest / Public User)**:
   - مشاهده لندینگ اصلی و بنرها
   - جستجو و فیلتر محصولات در آرشیو فروشگاه (`/shop`)
   - مشاهده صفحه جزئیات محصول (PDP)، دوزبندی و مشخصات مکمل
   - افزودن به سبد خرید و مدیریت مقادیر در Drawer سبد خرید
   - جریان تسویه‌حساب (Checkout Flow) با ثبت آدرس و اطلاعات تماس
   - ثبت درخواست همکاری تجاری / داروخانه‌ای (`/b2b`)
   - ثبت فرم تماس و استعلام مشاوره دارویی (`/contact`)
   - پیگیری وضعیت سفارش با کد پیگیری (`/track`)
   - مطالعه وبلاگ (`/blog`) و مقالات دانشنامه دارویی (`/wiki/[slug]`)
   - مشاهده صفحه ویدیوهای آموزشی (`/videos`)
   - جستجوی سراسری محصولات و مقالات (`/search`)

2. **کاربر ثبت‌نام‌شده / صاحب پت (Authenticated User / Pet Owner)**:
   - ورود/ثبت‌نام با شماره موبایل و کد تایید OTP (`/profile` یا مودال ورود)
   - مدیریت پروفایل کاربری و آدرس‌ها
   - مدیریت پروفایل پت‌ها (سگ/گربه، نژاد، وزن، سن، بیماری‌های زمینه‌ای)
   - داشبورد سوابق سفارشات و نسخه‌ها (`/dashboard`)
   - ثبت تیکت پشتیبانی و استعلام دارویی

3. **مدیر ارشد و کادر مدیریت (Admin / Store Manager)**:
   - احراز هویت با ایمیل/رمز عبور یا OTP در پنل مدیریت (`/login`)
   - مدیریت محصولات (ایجاد، ویرایش، حذف، قیمت‌گذاری، کنترل موجودی، گالری، فیلدهای پیشرفته سئو SERP)
   - مدیریت دسته‌بندی‌ها و ویژگی‌های درمانی
   - مدیریت مقالات وبلاگ و دانشنامه تخصصی (Wiki)
   - مدیریت و تغییر وضعیت سفارشات (Orders)
   - بررسی و تایید درخواست‌های همکاری تجاری B2B و فرم‌های تماس
   - تنظیمات عمومی سایت، درگاه‌های پرداخت، پیامک و سئو

---

## ۲. ماتریس جریان‌ها و قابلیت‌های کاربرمحور (Feature & Flow Matrix)

| کد | بخش / صفحه | قابلیت / سناریو | Happy Path | ورودی نامعتبر / منفی | حالت مرزی / Edge Case | وضعیت فعلی تست |
|---|---|---|---|---|---|---|
| **ST-01** | صفحه اصلی (`/`) | بارگذاری هدر، منوها، بنر اسلایدر، محصولات برگزیده | ✅ | ❌ | لود در شبکه کند | ✅ تست ضمنی |
| **ST-02** | فروشگاه (`/shop`) | فیلتر دسته‌بندی، مرتب‌سازی، جستجو و صفحه‌بندی | ✅ | جستجوی بدون نتیجه | فیلتر هم‌زمان چندگانه | ⚠️ ناقص |
| **ST-03** | جزئیات محصول (`/shop/[slug]`) | تغییر وزن/دوز، ماشین‌حساب مصرف پت، افزودن به سبد | ✅ | محصول ناموجود | گالری تصاویر چندگانه | ⚠️ ناقص |
| **ST-04** | سبد خرید (Cart Drawer) | افزایش/کاهش تعداد، حذف آیتم، محاسبه جمع کل | ✅ | سبد خرید خالی | کوپن تخفیف نامعتبر | ⚠️ ناقص |
| **ST-05** | تسویه حساب (`/checkout`) | ثبت اطلاعات گیرنده، انتخاب روش ارسال و پرداخت | ✅ | اعتبارسنجی فیلدهای ضروری | لغو پرداخت و بازگشت | ✅ پوشش داده شد |
| **ST-06** | همکاری تجاری (`/b2b`) | ارسال فرم همکاری کلینیک/پت‌شاپ با مدارک | ✅ | فیلدهای ناقص/موبایل اشتباه | ارسال فرم تکراری | ✅ پوشش داده شد |
| **ST-07** | تماس با ما (`/contact`) | ارسال پیام مشاوره و استعلام دارویی | ✅ | ایمیل/موبایل نامعتبر | فیلد پیام خالی | ✅ پوشش داده شد |
| **ST-08** | وبلاگ و دانشنامه (`/blog`, `/wiki`) | مشاهده مقالات، جستجو، جدول ترکیبات دارویی | ✅ | اسلاگ ناموجود (404) | لینک‌های بین‌مقالات | ✅ پوشش داده شد |
| **ST-09** | پیگیری سفارش (`/track`) | استعلام وضعیت سفارش با شماره موبایل و کد سفارش | ✅ | کد پیگیری نامعتبر | سفارش یافت نشد | ❌ بدون تست |
| **ST-10** | جستجوی سراسری (`/search`) | سرچ زنده محصولات، پیشنهادات هوشمند | ✅ | کلمه کلیدی بدون نتیجه | عبارات خاص فارسی/انگلیسی | ❌ بدون تست |
| **ST-11** | احراز هویت و ثبت‌نام (`AuthModal`) | لاگین/ثبت‌نام با OTP، فرم ورود با پسورد | ✅ | کد OTP اشتباه یا منقضی | خروج از حساب (Logout) | ⚠️ نیازمند تست اختصاصی |
| **ST-12** | بازیابی و فراموشی رمز عبور | درخواست ریست پسورد با پیامک OTP و تغییر رمز | ✅ | شماره اشتباه / کد نامعتبر | تلاش‌های بیش از حد (Rate limit) | ⚠️ نیازمند تست اختصاصی |
| **ST-13** | صفحات خطا و روت‌های نامعتبر | رندر صفحه ۴۰۴ سفارشی، خطای ۵۰۰ و بازگشت به خانه | ✅ | ورود به آدرس‌های ناموجود | خطای کرش سرور یا کامپوننت | ⚠️ نیازمند تست اختصاصی |
| **SEC-01**| امنیت و اعتبارسنجی ورودی‌ها | جلوگیری از XSS و SQLi در جستجو و فرم‌های تماس | ✅ | ارسال اسکریپت `<script>` | مقادیر غیرمجاز طولانی | ⚠️ نیازمند تست اختصاصی |
| **SEC-02**| کنترل هجوم و Rate Limiting | اعمال Cooldown در ارسال پیامک OTP (۶۰ ثانیه‌ای) | ✅ | درخواست مکرر OTP در بازه کوتاه | خطای `429 Too Many Requests` | ⚠️ نیازمند تست اختصاصی |
| **CONC-01**| مدیریت هم‌زمانی و موجودی انبار | رقابت هم‌زمان دو کاربر برای خرید آخرین موجودی کالا | ✅ | اتمام موجودی حین پرداخت | ثبت همزمان بیش از موجودی | ⚠️ نیازمند تست بار |
| **AD-01** | لاگین ادمین (`/login`) | ورود با رمز عبور و سشن توکن JWT | ✅ | رمز اشتباه / دسترسی غیرمجاز | سشن منقضی‌شده | ✅ پوشش داده شد |
| **AD-02** | سطوح دسترسی و رول‌های ادمین | دسترسی SUPER_ADMIN در برابر محدودیت‌های روت | ✅ | تلاش کاربر عادی برای ورود به ادمین | دسترسی به صفحات بدون مجوز | ⚠️ نیازمند تست اختصاصی |
| **AD-03** | مدیریت محصولات (`/products`) | ساخت، ویرایش، تب سئو، آپلود تصویر و حذف | ✅ | نام خالی / فرمت اشتباه | مقادیر طولانی سئو | ✅ پوشش داده شد |
| **AD-04** | مدیریت سفارشات (`/orders`) | فیلتر وضعیت، مشاهده جزئیات، تغییر وضعیت به ارسال‌شده | ✅ | تغییر غیرمجاز وضعیت | لیست سفارش خالی | ✅ پوشش داده شد |
| **AD-05** | مدیریت B2B (`/b2b`) | مشاهده درخواست‌های دریافتی، تغییر وضعیت و یادداشت | ✅ | بدون داده | تایید نهایی همکاری | ✅ پوشش داده شد |
| **AD-06** | مدیریت مقالات (`/blogs`) | ایجاد مقاله، ویرایش تگ‌ها، وضعیت انتشار | ✅ | عنوان خالی | ویرایش محتوای حجیم | ✅ پوشش داده شد |
| **AD-07** | تنظیمات سئو و عمومی (`/settings`) | تغییر متادیتا، فعال/غیرفعال کردن حالت کاتالوگ | ✅ | ساختار نامعتبر JSON | ذخیره فوری تنظیمات | ⚠️ نیازمند تست |

---

## ۳. وضعیت پوشش نهایی سوئیت ۱۱گانه (Final 11 Test Suites Status)
تمام ۱۱ سوئیت تست زیر با استانداردهای بدون `if-isVisible`، حذف سلکتورهای فال‌بک، assertion دقیق روی مقادیر رشته‌ای و محاسبات ریاضی، و اعتبارسنجی با Mutation Testing پیاده‌سازی و در CI ادغام شدند:

1. `tests/e2e/storefront/shop-filter-search.spec.ts`: تست کامل جستجو، فیلتر دسته‌ها، ماشین‌حساب دوز و حالت‌های بدون نتیجه.
2. `tests/e2e/storefront/order-tracking.spec.ts`: تست پیگیری سفارشات با سناریوهای موفق و ناموفق.
3. `tests/e2e/storefront/cart-operations.spec.ts`: تست تعاملی سبد خرید، محاسبه دقیق ریاضی `unitPrice * 2`، تغییر تعداد، حذف و سبد خالی.
4. `tests/e2e/admin/admin-orders-flow.spec.ts`: تست مدیریت سفارشات، تغییر وضعیت فاکتور و فیلترها در پنل مدیریت.
5. `tests/e2e/admin/admin-blogs-crud.spec.ts`: تست ایجاد و ویرایش مقالات وبلاگ و دانشنامه در پنل ادمین.
6. `tests/e2e/admin/admin-b2b-submissions.spec.ts`: تست مشاهده و مدیریت فرم‌های ثبت شده B2B و تماس.
7. `tests/e2e/storefront/auth-otp-recovery.spec.ts`: تست جریان OTP و بازیابی و تنظیم رمز عبور جدید.
8. `tests/e2e/admin/admin-rbac-roles.spec.ts`: تفکیک سطوح دسترسی، نقش‌های کاربران و ادمین ارشد.
9. `tests/e2e/storefront/error-pages-404-500.spec.ts`: رندر و ناوبری صفحات خطای ۴۰۴ و ۵۰۰.
10. `tests/e2e/security/xss-ratelimit.spec.ts`: تست مقاومت امنیتی در برابر حملات XSS و محدودیت نرخ ارسال پیامک (Cooldown Timer).
11. `tests/e2e/storefront/concurrency-stock.spec.ts`: رقابت موازی همزمان (Parallel Race با `Promise.all`) روی آخرین موجودی کالا در دو کانتکست مجزا.

> [!WARNING]
> **محدودیت شناخته‌شده در تست همزمانی سطح E2E (Stock Concurrency & Race Conditions):**
> تست `concurrency-stock.spec.ts` رفتار لایه فرانت‌اند و کلاینت در برابر پاسخ‌های همزمان را پوشش می‌دهد. از آنجا که اجرای تست‌های مرورگری E2E به صورت ایزوله انجام شده و دیتابیس مشترک تست را مسدود نمی‌کند، برای راستی‌آزمایی دقیق تراکنش‌های ACID دیتابیس (مانند `SELECT FOR UPDATE`، جلوگیری از Overselling و قفل‌های ردیفی در Postgres)، قویاً توصیه می‌شود یک **Integration Test اختصاصی** مستقیماً روی لایه سرویس بک‌اند (`orders.service.ts` با یک نمونه تست واقعی PostgreSQL) اجرا گردد.

---

## ۴. راهنمای نگهداری و افزودن فیچرهای جدید بدون شکستن تست‌ها (Developer Maintenance Guide)

برای اینکه توسعه‌دهندگان جدید یا تغییرات آینده باعث رگرسیون یا شکست بی‌دلیل سوئیت نشوند، قوانین زیر الزامی است:

1. **استفاده اجباری از `data-testid`**:
   - برای هر المان قابل تعامل جدید (دکمه، اینپوت، کارت، فیلتر)، به جای اتکا به کلاس CSS یا متن فارسی، حتماً `data-testid="..."` اضافه کنید.
2. **پرهیز از Assertionهای شکننده متن یا کلاس**:
   - از چک کردن کلاس‌های ظاهری (مانند `text-canina-blue`) خودداری کنید. به جای آن، وضعیت بیزینسی (مقدار عددی، مقدار فیلد فرم با `.toHaveValue()`, یا URL با `.toHaveURL()`) را راستی‌آزمایی کنید.
3. **ممنوعیت استفاده از الگوی کاذب `if (await element.isVisible())`**:
   - اگر حضور یک المان بخشی از کارکرد صفحه است، آن را مستقیماً با `await expect(locator).toBeVisible()` بنویسید تا در صورت بروز باگ، تست فیل شود و بی‌صدا عبور نکند.
4. **اجرای محلی قبل از Push**:
   - همیشه قبل از ایجاد PR یا Push، دستور زیر را اجرا کنید:
     ```bash
     npx playwright test --project=chromium-desktop --project=admin-chromium
     ```
5. **به‌روزرسانی خودکار در گیت‌هاب/گیتیا (CI Pipeline)**:
   - فایل `.gitea/workflows/e2e.yml` روی هر Push و Pull Request روی برنچ‌های `main` و `develop` تمام سوئیت‌ها را به طور خودکار اجرا می‌کند.