132 lines
9.8 KiB
Markdown
132 lines
9.8 KiB
Markdown
# ممیزی کشف باگ — تست رفتاری کل سیستم
|
|
|
|
## پروژه
|
|
|
|
`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)
|
|
|
|
تولید توکن هر نقش:
|
|
```bash
|
|
ddev exec bash -c 'php bin/console lexik:jwt:generate-token <mobile> --user-class="App\\Auth\\Entity\\User"'
|
|
```
|
|
لیست همهی routeها:
|
|
```bash
|
|
ddev exec php bin/console debug:router | grep api/v1
|
|
```
|
|
صدا زدن endpoint (prod host، مثل مصرف واقعی):
|
|
```bash
|
|
curl -sk "https://clinic-pro.ddev.site/api/v1/<path>" -H "Authorization: Bearer <token>"
|
|
```
|
|
بررسی DB برای تأیید اثر:
|
|
```bash
|
|
ddev exec bash -c "mysql -uroot -proot db -e \"<SQL>\""
|
|
```
|
|
سلامت TS/build فرانت:
|
|
```bash
|
|
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` بساز با جدول اولویتبندیشده:
|
|
|
|
```markdown
|
|
# گزارش باگ — <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) را کامل کن، سپس بقیه.
|