clinicpro/.claude/prompt/qa-bug-audit.md

ممیزی کشف باگ — تست رفتاری کل سیستم

پروژه

clinicpro (Backend API + Admin SPA؛ منبع واحد داده/auth). جریان‌هایی که nobat724_front مصرف می‌کند هم از طریق همین APIها تست می‌شوند.

این یک پرامپت تست/ممیزی است، نه پیاده‌سازی قابلیت. هدف: پیدا کردن باگ‌های واقعی با شواهد، نه تغییر کد. هیچ فایل تولیدی را تغییر نده مگر برای رفع باگ‌های قطعیِ کم‌ریسک (آن هم با تأیید جداگانه). خروجی اصلی = گزارش باگ.

زمینه

سیستم suite تست خودکار ندارد (tests/ فقط bootstrap.php دارد)، ولی مرجع کاملِ رفتار در docs/api/*.md و کاربرانِ تست در TEST_USERS.md موجود است. این ممیزی باید رفتار واقعیِ APIها را با قرارداد مستندشده مقایسه کند و انحراف‌ها/نشتی‌ها/خطاهای ۵۰۰ را پیدا کند.

مشکل / هدف

کشف باگ در محورهای زیر و تولید یک گزارش باگ اولویت‌بندی‌شده (docs/qa/bug-report-<date>.md):

1. خطاهای ۵۰۰ / استثناهای کنترل‌نشده در endpointها (به‌ویژه با ورودی‌های مرزی).
2. نشتی دسترسی (authorization) بین نقش‌ها: admin / clinic / doctor / secretary / representation / user.
3. انحراف قرارداد API از docs/api/* (شکل پاسخ، nestی، status code، فیلدهای گمشده).
4. اعتبارسنجی ورودی (موبایل، کد ملی، تاریخ، مقادیر منفی/خالی/طولانی، تزریق).
5. سازگاری frontend↔backend: جاهایی که SPA یا nobat724_front شکل پاسخ را اشتباه باز می‌کند (الگوی double-nested).

فایل‌های مرتبط

فایل/مسیر	نقش
docs/api/*.md	قرارداد مرجع — هر تست باید با این مقایسه شود
TEST_USERS.md	کاربران هر نقش برای تولید توکن
src/*/Controller/*.php	endpointها — سطح دسترسی #[IsGranted] و منطق
src/Shared/Controller/BaseController.php	شکل success/paginated/error
config/packages/security.yaml	firewall و access_control
assets/admin/lib/api.ts, services/response.js (front عمومی)	مصرف پاسخ‌ها

ابزارها و روش تست (واقعی، داخل ddev)

تولید توکن هر نقش:

ddev exec bash -c 'php bin/console lexik:jwt:generate-token <mobile> --user-class="App\\Auth\\Entity\\User"'

لیست همه‌ی routeها:

ddev exec php bin/console debug:router | grep api/v1

صدا زدن endpoint (prod host، مثل مصرف واقعی):

curl -sk "https://clinic-pro.ddev.site/api/v1/<path>" -H "Authorization: Bearer <token>"

بررسی DB برای تأیید اثر:

ddev exec bash -c "mysql -uroot -proot db -e \"<SQL>\""

سلامت TS/build فرانت:

ddev exec npx tsc --noEmit --project tsconfig.json
ddev exec yarn dev

وظایف

۱. نقشه‌برداری endpointها و دامنه‌ی تست

• خروجی debug:router | grep api/v1 را بگیر و لیست کامل endpointها را با method/path استخراج کن.
• برای هر دامنه (auth, doctor, clinic, appointment, payment, representation, secretary, sms, blog, rating, settlement, user-profile, ...) فایل docs متناظر را بخوان و «قرارداد مورد انتظار» را یادداشت کن (status، شکل پاسخ، permission).

۲. تست خطاهای ۵۰۰ و ورودی مرزی

برای endpointهای پرریسک (به‌خصوص آن‌هایی که از relation/Entity proxy می‌خوانند یا ورودی JSON می‌گیرند):

• ورودی‌های مرزی بفرست: بدنه‌ی خالی {}، فیلد گمشده، نوع اشتباه (string به‌جای int)، عدد منفی، رشته‌ی خیلی بلند، uuid نامعتبر، تاریخ نامعتبر، صفحه/limit خیلی بزرگ.
• هر پاسخی با "code":"ERR_INTERNAL_001" یا HTTP 500 = باگ (باید ۴xx ساختاریافته باشد). نمونه‌ی شناخته‌شده‌ی این کلاس باگ: دسترسی به getter روی proxyِ موجودیتِ حذف‌شده (مثل author در بلاگ) → EntityNotFoundException → 500.
• لیست‌های paginated را با page=99999 و limit=0/-1/9999 بزن.

۳. ماتریس دسترسی نقش‌ها (مهم‌ترین بخش)

برای هر نقش یک توکن بساز و endpointهای خارج از حوزه‌اش را صدا بزن؛ انتظار 403:

• user عادی → هر /api/v1/admin/* و /api/v1/representation/* و /api/v1/sms/* → باید 403.
• representation → /api/v1/admin/users, /admin/payments, /admin/settlements → باید 403؛ ولی /representation/me|doctors|clinics|appointments → 200.
• doctor (مهمان کلینیک، نه مالک) → endpointهای مدیریت کلینیک (staff/clinic-service برای کلینیکِ دیگران، ویرایش کلینیک) → باید 403 یا scopeِ شخصی؛ نباید روی کلینیک عمل کند.
• secretary → فقط در محدوده‌ی scope مجازش؛ خارج از آن 403.
• IDOR: با توکن نقش A، منبع متعلق به B را با uuid/id مستقیم بخوان/ویرایش کن (مثلاً GET/PATCH /representation/{uuidِ نفر دیگر}، نوبت/پروفایل کاربر دیگر). هر دسترسی موفق = باگ امنیتی.
• هر endpointی که مالکیت را از ورودی کلاینت (uuid/id در query/path) تعیین می‌کند نه از #[CurrentUser] → مشکوک؛ تست و گزارش کن.

۴. انطباق قرارداد API

برای نمونه‌ای از هر دامنه، پاسخ واقعی را با docs مقایسه کن:

• شکل nestی درست است؟ (paginated → data تخت + meta؛ success(['data'=>...]) → double-nested data.data). جاهایی که SPA/nobat724_front این nestی را اشتباه باز می‌کند را به‌عنوان باگ مصرف ثبت کن.
• status codeها و فیلدهای الزامی مطابق docs هستند؟ فیلد گمشده/اضافه را گزارش کن.
• تاریخ‌ها Unix timestamp صحیح‌اند (نه DateTime serialize‌شده‌ی خراب)؟

۵. اعتبارسنجی ورودی

• موبایل: ارقام فارسی/عربی، طول غلط، حروف → باید رد شود (۴۲۲)، نه ذخیره‌ی خراب.
• کد ملی: الگوریتم رقم کنترلی (سمت سرور هم چک می‌شود یا فقط فرانت؟ اگر فقط فرانت = باگ).
• مقادیر مالی/درصد کمیسیون/limit عکس گالری (سقف ۵) و امثال آن: مرزها را تست کن.

۶. سلامت build و سازگاری

• ddev exec npx tsc --noEmit → هر خطای TS = باگ.
• ddev exec yarn dev → هر خطای کامپایل = باگ.
• (front عمومی) cd nobat724_front && npm run build → خطاهای صفحه/متادیتا.

۷. تولید گزارش باگ

فایل docs/qa/bug-report-<YYYY-MM-DD>.md بساز با جدول اولویت‌بندی‌شده:

# گزارش باگ — <date>

## خلاصه
- تعداد کل: X | بحرانی: a | بالا: b | متوسط: c | پایین: d

## باگ‌ها
### [CRITICAL] <عنوان کوتاه>
- **دامنه:** auth/clinic/...
- **endpoint/صفحه:** `METHOD /api/v1/...`
- **مراحل بازتولید:** دستور curl دقیق + توکن نقش
- **انتظار:** (طبق docs) ...
- **واقعیت:** (پاسخ واقعی + HTTP code) ...
- **اثر:** (نشتی داده / 500 / خرابی UI / ...)
- **فایل محتمل:** `src/...:line`
- **رفع پیشنهادی:** یک جمله

اولویت‌بندی: نشتی دسترسی/IDOR = CRITICAL؛ 500 روی مسیر پرکاربرد = HIGH؛ انحراف قرارداد که UI را می‌شکند = HIGH/MEDIUM؛ اعتبارسنجی ناقص = MEDIUM؛ کاسمتیک = LOW.

نکات مهم

• تخریب‌نکن: برای تست‌های نوشتنی (POST/PATCH/DELETE) از داده‌ی تستیِ جداگانه استفاده کن و در پایان پاک/بازگردانی کن؛ روی داده‌ی واقعیِ کاربران اصلی عملیات مخرب نزن.
• محیط: باگ‌های مخصوص prod ممکن است فقط روی https://clinic-pro.ddev.site (APP_ENV=prod) ظاهر شوند؛ بعد از تغییر config cache:clear --env=prod. dev هم خطای کامل‌تر می‌دهد (var/log), از آن برای تشخیص ریشه استفاده کن.
• توکن: کد OTP در dev همیشه 12345؛ یا مستقیم با lexik:jwt:generate-token توکن هر نقش را بساز.
• هر یافته باید بازتولیدپذیر باشد (دستور دقیق + پاسخ واقعی)؛ حدس و گمان بدون شواهد در گزارش نیاید.
• این پرامپت فقط گزارش تولید می‌کند؛ رفع باگ‌ها در پرامپت‌های جداگانه (بعد از تأیید اولویت‌ها) انجام شود — مگر باگِ تک‌خطیِ بدیهی و کم‌ریسک که می‌توان با ذکر در گزارش، هم‌زمان رفع کرد.
• دامنه را کنترل کن: اگر تعداد endpointها زیاد است، اول دامنه‌های پرریسک (auth, representation, clinic, appointment, payment) را کامل کن، سپس بقیه.