168 lines
14 KiB
Markdown
168 lines
14 KiB
Markdown
# رفع مشکلات دسترسی: پزشکِ عضو کلینیک + scope نماینده
|
||
|
||
## پروژه
|
||
|
||
`clinicpro` (Backend auth/permission + Admin React SPA). کاملاً داخل همین پروژه است.
|
||
|
||
## زمینه
|
||
|
||
دو نشتیِ دسترسی در پنل ادمین وجود دارد:
|
||
|
||
1. **پزشکِ عضو کلینیک، دسترسی کاملِ مالک کلینیک میگیرد.** وقتی یک پزشک از طریق دعوتنامه به کلینیک اضافه میشود، در `buildAvailableContexts` برایش یک context با `'role' => 'clinic'` ساخته میشود. چون `switchContext` در فرانت `primaryRole = context.role` میگذارد، آن پزشک با سوییچ به این context عملاً «مالک کلینیک» میشود و به **کل پنل کلینیک** (پرسنل، مالی، خدمات، اشتراک، ویرایش کلینیک و...) دسترسی پیدا میکند. درست این است که او فقط «پزشکِ شاغل در آن کلینیک» باشد (نوبتهای خودش در آن کلینیک)، نه مدیر کلینیک.
|
||
|
||
2. **نماینده همهی پزشکان/کلینیکها را میبیند، نه فقط مالِ خودش.** صفحات `DoctorsPage`/`ClinicsPage` در حالت نماینده از endpointهای **عمومی** `/api/v1/doctors` و `/api/v1/clinics` استفاده میکنند که هیچ فیلتری روی `representation_id` ندارند. ضمناً `RepresentationActionController::createClinic` هنگام ساخت کلینیک، `representation_id` را ست **نمیکند** (فقط createDoctor این کار را میکند). نتیجه: نماینده همهی دکترها/کلینیکهای سیستم را میبیند و کلینیکهای خودش هم تگگذاری نمیشوند.
|
||
|
||
## مشکل / هدف
|
||
|
||
- پزشکِ عضو کلینیک نباید نقش/دسترسی مالک کلینیک بگیرد.
|
||
- نماینده فقط باید پزشکان و کلینیکهایی را ببیند که `representation_id` آنها = id همان نماینده است (همانهایی که خودش ثبت کرده).
|
||
|
||
## فایلهای مرتبط
|
||
|
||
| فایل | نقش |
|
||
|------|-----|
|
||
| `src/Auth/Controller/AuthController.php` | `buildAvailableContexts()` — ساخت context پزشکِ عضو کلینیک با role اشتباه `clinic` |
|
||
| `assets/admin/stores/authStore.ts` | `switchContext` → `primaryRole = context.role`؛ و type نقش |
|
||
| `assets/admin/components/layout/Sidebar.tsx` | منوی هر نقش (باید برای پزشکِ مهمانِ کلینیک محدود باشد) |
|
||
| `assets/admin/App.tsx` | `RoleRoute` صفحات کلینیک |
|
||
| `src/Representation/Controller/RepresentationActionController.php` | `createClinic` که `representation_id` ست نمیکند؛ مرجع `createDoctor` که میکند |
|
||
| `src/Doctor/Repository/DoctorRepository.php` | `findWithFilters` — فاقد فیلتر `representation` |
|
||
| `src/Clinic/Repository/ClinicRepository.php` | `findWithFilters` — فاقد فیلتر `representation` |
|
||
| `src/Doctor/Controller/DoctorController.php` / `src/Clinic/Controller/ClinicController.php` | endpointهای عمومی `GET /api/v1/doctors` و `/api/v1/clinics` |
|
||
| `assets/admin/pages/DoctorsPage.tsx` / `ClinicsPage.tsx` | لیست نماینده که از endpoint عمومی بدون scope استفاده میکند |
|
||
| `docs/api/auth.md`, `docs/api/doctor.md`, `docs/api/clinic.md`, `docs/api/representation.md` | مستندسازی |
|
||
|
||
## وضعیت فعلی (کد واقعی)
|
||
|
||
`buildAvailableContexts` — context پزشکِ عضو کلینیک با role اشتباه:
|
||
```php
|
||
if ($doctor = $this->doctorRepo->findByUser($user)) {
|
||
$contexts[] = [ 'type'=>'doctor', 'db_uuid'=>$doctor->getUuid(), 'name'=>'مطب شخصی '.$doctor->getName(), 'role'=>'doctor' ];
|
||
foreach ($this->clinicRepo->findByDoctor($doctor) as $clinic) {
|
||
$contexts[] = [
|
||
'type' => 'clinic',
|
||
'db_uuid' => $clinic->getUuid(),
|
||
'name' => $clinic->getName() ?? '',
|
||
'role' => 'clinic', // ← اشتباه: پزشکِ عضو، نقش مالک کلینیک میگیرد
|
||
'doctor_uuid' => $doctor->getUuid(),
|
||
];
|
||
}
|
||
}
|
||
|
||
// مالک واقعی کلینیک (این درست است — فقط وقتی clinic.user === خود کاربر)
|
||
if ($clinic = $this->clinicRepo->findByUser($user)) { ... 'role'=>'clinic' ... }
|
||
```
|
||
|
||
`switchContext` در authStore (نقش از context میآید):
|
||
```ts
|
||
primaryRole: res.data.context?.role ?? null,
|
||
```
|
||
|
||
`RepresentationActionController::createClinic` — بدون ست representation_id:
|
||
```php
|
||
$clinic = new Clinic($ownerUser);
|
||
$clinic->setName($name);
|
||
// ... telephone/address/info
|
||
$this->em->persist($clinic); // ← representation_id ست نمیشود
|
||
```
|
||
(در مقابل، `createDoctor` این را دارد: `$doctor->setRepresentationId($rep->getId());`)
|
||
|
||
`DoctorsPage`/`ClinicsPage` (حالت نماینده، بدون scope):
|
||
```ts
|
||
const base = isRepresentation ? '/api/v1/doctors' : '/api/v1/admin/doctors'; // عمومی، بدون representation
|
||
const listBase = isRepresentation ? '/api/v1/clinics' : '/api/v1/admin/clinics'; // عمومی، بدون representation
|
||
```
|
||
|
||
## وظایف
|
||
|
||
### ۱. نقشِ محدود برای پزشکِ عضو کلینیک (رفع نشتی دسترسی)
|
||
|
||
در `buildAvailableContexts`، context کلینیک برای **پزشکِ عضو** باید نقش مالک کلینیک ندهد. یک نقش/scope محدود بده، مثلاً `role => 'doctor'` با `scope => 'clinic'` (یعنی همان پزشک، ولی در محیط آن کلینیک — برای دیدن نوبتهای خودش در آن کلینیک):
|
||
|
||
```php
|
||
foreach ($this->clinicRepo->findByDoctor($doctor) as $clinic) {
|
||
$contexts[] = [
|
||
'type' => 'clinic',
|
||
'db_uuid' => $clinic->getUuid(),
|
||
'name' => $clinic->getName() ?? '',
|
||
'role' => 'doctor', // پزشک میماند، نه مالک کلینیک
|
||
'scope' => 'clinic',
|
||
'doctor_uuid' => $doctor->getUuid(),
|
||
];
|
||
}
|
||
```
|
||
- بخش «صاحب کلینیک» (`$this->clinicRepo->findByUser($user)`) باید **دستنخورده** بماند و همان `role => 'clinic'` را داشته باشد — فقط مالک واقعی، نقش کامل کلینیک میگیرد.
|
||
- **نکتهی مهم Backend:** هر endpointی که فرض میکند «کاربرِ با context کلینیک = مالک کلینیک» باید بازبینی شود تا با scope محدود سازگار باشد (دسترسی نوشتن روی پرسنل/خدمات/اشتراک/ویرایش کلینیک نباید برای پزشکِ مهمان باز باشد). مالکیت را با `clinic.getUser()->getId() === $user->getId()` چک کن (الگوی موجود در `ClinicInvitationController` خط ۲۰۰).
|
||
|
||
### ۲. Admin SPA — منو و مسیرهای محدود برای پزشکِ مهمانِ کلینیک
|
||
|
||
چون با اصلاح وظیفه ۱ نقش این کاربر در آن context `doctor` میشود (نه `clinic`)، `Sidebar.tsx` و `RoleRoute`های `App.tsx` خودبهخود منوی پزشک را نشان میدهند و صفحات اختصاصی کلینیک (`/admin/staff`, `/admin/my-financial` با نقش clinic، ویرایش کلینیک، اشتراک) برای او باز نمیشوند. این را **تأیید کن**:
|
||
- در `App.tsx` مطمئن شو صفحاتی مثل `clinics/:uuid` (ClinicDetailPage)، `staff`, `subscription` برای نقش `doctor` فقط در حدی باز است که منطقی است (مشاهده، نه مدیریت). اگر صفحهای با `roles={['doctor','clinic']}` هست که نباید برای پزشکِ مهمان نوشتنی باشد، در همان صفحه بر اساس مالکیت (context.role === 'clinic') دکمههای مدیریتی را پنهان کن.
|
||
- اگر `scope` در context هست، میتوان در فرانت از `context.scope === 'clinic'` برای تمایز «پزشک در محیط کلینیک» استفاده کرد.
|
||
|
||
### ۳. نماینده — ستکردن representation_id روی کلینیک
|
||
|
||
در `RepresentationActionController::createClinic`، مثل createDoctor مالکیت نماینده را ست کن:
|
||
```php
|
||
$clinic = new Clinic($ownerUser);
|
||
$clinic->setName($name);
|
||
// ...
|
||
$rep = $this->representationRepo->findByUser($user);
|
||
if ($rep !== null) {
|
||
$clinic->setRepresentationId($rep->getId());
|
||
}
|
||
$this->em->persist($clinic);
|
||
```
|
||
|
||
### ۴. فیلتر `representation` در لیست پزشکان و کلینیکها
|
||
|
||
در `DoctorRepository::findWithFilters` و `ClinicRepository::findWithFilters` یک فیلتر اختیاری `representation` اضافه کن:
|
||
```php
|
||
// DoctorRepository
|
||
if (!empty($filters['representation'])) {
|
||
$qb->andWhere('d.representationId = :rep')->setParameter('rep', (int) $filters['representation']);
|
||
}
|
||
// ClinicRepository
|
||
if (!empty($filters['representation'])) {
|
||
$qb->andWhere('c.representationId = :rep')->setParameter('rep', (int) $filters['representation']);
|
||
}
|
||
```
|
||
- در controllerهای عمومی `GET /api/v1/doctors` و `GET /api/v1/clinics`، پارامتر `representation` از query عبور داده شود به `findWithFilters` (همان الگوی بقیهی فیلترها). چون این پارامتر اختیاری است، رفتار عمومی سایت تغییری نمیکند.
|
||
|
||
> هشدار امنیتی: نماینده نباید بتواند با دستکاری `representation` در query، لیست نمایندهی دیگری را ببیند. بهترین کار: یک endpoint اختصاصیِ scoped برای نماینده بساز که id را از کاربر جاری میگیرد (مثل `/api/v1/representation/doctors` و `/api/v1/representation/clinics` در همان `RepresentationActionController` با `findByUser`)، نه از query. این امنتر از پارامتر عمومی است. (پیشنهادِ ترجیحی.)
|
||
|
||
### ۵. Admin SPA — اتصال لیستهای نماینده به endpoint scoped
|
||
|
||
در `DoctorsPage.tsx` و `ClinicsPage.tsx` حالت نماینده را به endpoint scoped (وظیفه ۴) وصل کن:
|
||
```ts
|
||
// بهجای /api/v1/doctors عمومی:
|
||
const base = isRepresentation ? '/api/v1/representation/doctors' : '/api/v1/admin/doctors';
|
||
// بهجای /api/v1/clinics عمومی:
|
||
const listBase = isRepresentation ? '/api/v1/representation/clinics' : '/api/v1/admin/clinics';
|
||
```
|
||
- adapter نگاشت شکل پاسخ (که قبلاً برای DoctorsPage اضافه شده) را با شکل خروجی endpoint جدید هماهنگ کن. سادهترین کار: endpoint scoped همان شکل `/api/v1/admin/doctors` و `/api/v1/admin/clinics` را برگرداند تا نیازی به adapter نباشد.
|
||
|
||
### ۶. داشبورد نماینده — اعداد فقط از دامنهی خودش
|
||
|
||
مطمئن شو کارتها/آمار داشبورد نماینده (`RepresentationDashboard` در `DashboardPage.tsx`) از endpointهای نماینده میآیند که از قبل scoped هستند (`/representation/{uuid}/dashboard/*` و `/representation/appointments`). اگر شمارش «تعداد پزشکان من / کلینیکهای من» اضافه میشود، از همان endpoint scoped جدید بگیر (نه عمومی).
|
||
|
||
### ۷. مستندسازی
|
||
|
||
- `docs/api/auth.md`: در توضیح `available_contexts`/`primary_role`، تفاوت «مالک کلینیک» (`role: clinic`) و «پزشکِ عضو در محیط کلینیک» (`role: doctor`, `scope: clinic`) را شرح بده.
|
||
- `docs/api/doctor.md` و `docs/api/clinic.md`: پارامتر/endpoint جدید فیلتر `representation`.
|
||
- `docs/api/representation.md`: endpointهای جدید `GET /api/v1/representation/doctors` و `/clinics` (اگر مسیر scoped انتخاب شد)؛ و اینکه createClinic حالا `representation_id` ست میکند.
|
||
|
||
## نکات مهم
|
||
|
||
- **امنیت اول:** مالکیت همیشه از `#[CurrentUser]` تعیین شود؛ هرگز به `representation` در query برای scope اعتماد نکن (وظیفه ۴ پیشنهادِ endpoint scoped را ترجیح میدهد).
|
||
- `Clinic.representationId` و `Doctor.representationId` ستون scalar هستند؛ فیلتر مستقیم روی همان ستون.
|
||
- نقش `clinic` در سیستم = «مالک/مدیر کلینیک». پزشکِ عضو هرگز نباید این نقش را در context بگیرد.
|
||
- تغییر `buildAvailableContexts` رفتار سوییچ context را برای پزشکانِ چندکلینیکه عوض میکند؛ تست کن که مالک واقعی کلینیک هنوز نقش کامل دارد و پزشکِ مهمان فقط نوبتهای خودش را میبیند.
|
||
- بعد از تغییر هر controller/مسیر، `cache:clear` و بهروزرسانی `docs/api/*` در همان session.
|
||
- migration لازم نیست (هر دو ستون `representation_id` از قبل وجود دارند؛ این تسک فقط منطق/فیلتر/نقش است).
|
||
- **تستها** (با `lexik:jwt:generate-token`):
|
||
- پزشکی که عضو یک کلینیک است → `available_contexts` آن کلینیک باید `role: doctor`/`scope: clinic` باشد، نه `clinic`؛ و بعد از switch، منوی پزشک ببیند نه پنل کامل کلینیک.
|
||
- مالک واقعی کلینیک → همچنان `role: clinic` و دسترسی کامل.
|
||
- نماینده → `GET /api/v1/representation/doctors|clinics` فقط ردیفهای با `representation_id = نمایندهی جاری`؛ و کلینیکِ تازهساخته توسط نماینده باید `representation_id` داشته باشد.
|
||
- نماینده نتواند با تغییر query، دادهی نمایندهی دیگر را ببیند.
|