feat(subscription): implement feature gating for subscription-based access in admin panel
This commit is contained in:
hamed
@@ -0,0 +1,369 @@
|
||||
# اعمال محدودیتهای اشتراک در پنل ادمین (Frontend Gate)
|
||||
|
||||
## زمینه
|
||||
|
||||
سیستم اشتراک در backend کاملاً پیاده است:
|
||||
- `SubscriptionService::hasFeature(entityType, entityId, feature)` — بررسی دسترسی به قابلیت
|
||||
- `SubscriptionService::getSecretaryLimit(...)` — حداکثر منشی مجاز
|
||||
- `SubscriptionPlan::features` — یک آرایه JSON مثل `{ "patient_records": true, "services": true, "sms_panel": true }`
|
||||
- backend روی API های `PatientController` و `ClinicServiceController` گیت دارد (`ERR_SUBSCRIPTION_REQUIRED`)
|
||||
|
||||
**مشکل:** Frontend هیچ اطلاعی از اشتراک فعال کاربر ندارد. Sidebar همه منوها را به همه نقشها نشان میدهد، صفحات بدون هشدار باز میشوند، و کاربر با پیام خطای backend مواجه میشود بجای راهنمای ارتقاء پنل.
|
||||
|
||||
**هدف:** وقتی کاربر (پزشک / کلینیک / منشی) وارد پنل میشود:
|
||||
1. اطلاعات اشتراک فعال لود شود و در یک context/hook مشترک در دسترس باشد
|
||||
2. آیتمهای Sidebar که نیاز به feature دارند — اگر feature فعال نیست — با آیکون قفل نمایش داده شوند یا پنهان شوند
|
||||
3. صفحاتی که feature ندارند، یک بنر «برای استفاده از این قابلیت پنل خود را ارتقاء دهید» نمایش دهند
|
||||
|
||||
---
|
||||
|
||||
## مشکل / هدف
|
||||
|
||||
### قابلیتهای محدودشده توسط اشتراک
|
||||
|
||||
| Feature Key | صفحه/منو | نقش مرتبط |
|
||||
|-------------|----------|----------|
|
||||
| `patient_records` | `/admin/my-patients` | doctor, clinic, secretary |
|
||||
| `services` | `/admin/clinic-services` | doctor, clinic |
|
||||
| `sms_panel` | `/admin/sms-wallet` | doctor, clinic |
|
||||
| `max_secretaries` | `/admin/my-secretaries` (تعداد) | doctor, clinic |
|
||||
|
||||
**نکته منشی:** منشی اشتراک مستقل ندارد — اشتراک entity ای که به آن متصل است (دکتر یا کلینیک) اعمال میشود. endpoint `/api/v1/subscription/my` برای منشی null برمیگرداند (چون `resolveEntity` در `SubscriptionController` فقط ROLE_DOCTOR و ROLE_CLINIC را handle میکند).
|
||||
|
||||
---
|
||||
|
||||
## فایلهای مرتبط
|
||||
|
||||
| فایل | نقش |
|
||||
|------|-----|
|
||||
| `src/Subscription/Controller/SubscriptionController.php` | endpoint `GET /api/v1/subscription/my` — برای doctor و clinic |
|
||||
| `src/Subscription/Service/SubscriptionService.php` | `hasFeature()`, `getSecretaryLimit()` |
|
||||
| `assets/admin/stores/authStore.ts` | state مرکزی auth — باید subscription هم اینجا باشد |
|
||||
| `assets/admin/components/layout/Sidebar.tsx` | `buildSections()` — منوها بر اساس `primaryRole` |
|
||||
| `assets/admin/App.tsx` | `RoleRoute` — گیت نقشها، باید feature gate هم اضافه شود |
|
||||
| `assets/admin/pages/MyPatientsPage.tsx` | نیاز به `patient_records` |
|
||||
| `assets/admin/pages/ClinicServicesPage.tsx` | نیاز به `services` |
|
||||
| `assets/admin/pages/SmsWalletPage.tsx` | نیاز به `sms_panel` |
|
||||
| `assets/admin/pages/MySecretariesPage.tsx` | نیاز به `max_secretaries` بیش از ۱ |
|
||||
| `assets/admin/pages/SubscriptionPage.tsx` | صفحه ارتقاء پنل — مقصد CTA ها |
|
||||
|
||||
---
|
||||
|
||||
## وضعیت فعلی
|
||||
|
||||
### Backend — endpoint اشتراک
|
||||
```php
|
||||
// SubscriptionController.php — GET /api/v1/subscription/my
|
||||
// فقط doctor و clinic را handle میکند
|
||||
private function resolveEntity(User $user): array
|
||||
{
|
||||
if ($user->hasRole('ROLE_DOCTOR')) {
|
||||
$doctor = $this->doctorRepo->findByUser($user);
|
||||
return $doctor !== null ? ['doctor', $doctor->getId()] : ['doctor', null];
|
||||
}
|
||||
if ($user->hasRole('ROLE_CLINIC')) {
|
||||
$clinic = $this->clinicRepo->findByUser($user);
|
||||
return $clinic !== null ? ['clinic', $clinic->getId()] : ['clinic', null];
|
||||
}
|
||||
return ['unknown', null]; // منشی → 403
|
||||
}
|
||||
```
|
||||
|
||||
پاسخ:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"subscription": {
|
||||
"uuid": "...",
|
||||
"plan": { "name": "basic", "level": 1, "features": { "patient_records": true, "services": true, "sms_panel": false }, "max_secretaries": 3 },
|
||||
"is_trial": false,
|
||||
"expires_at": 1750000000,
|
||||
"days_remaining": 45
|
||||
},
|
||||
"used_trial": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
اگر اشتراک فعال نداشته باشد: `"subscription": null`
|
||||
|
||||
### Frontend — authStore
|
||||
```ts
|
||||
// authStore.ts — فعلاً subscription اصلاً در store نیست
|
||||
interface AuthState {
|
||||
primaryRole: 'admin' | 'clinic' | 'doctor' | 'secretary' | 'user' | null;
|
||||
dbUuid: string | null;
|
||||
// ... subscription وجود ندارد
|
||||
}
|
||||
```
|
||||
|
||||
### Frontend — Sidebar
|
||||
```tsx
|
||||
// Sidebar.tsx — همه آیتمها را بدون بررسی feature نمایش میدهد
|
||||
if (primaryRole === 'doctor') {
|
||||
return [{
|
||||
label: 'مدیریت',
|
||||
items: [
|
||||
{ to: '/admin/my-patients', icon: FolderOpenIcon, label: 'پرونده بیماران' },
|
||||
{ to: '/admin/clinic-services', icon: WrenchScrewdriverIcon, label: 'سرویسها' },
|
||||
{ to: '/admin/sms-wallet', icon: DevicePhoneMobileIcon, label: 'کیف پول پیامک' },
|
||||
],
|
||||
}];
|
||||
}
|
||||
```
|
||||
|
||||
### Frontend — App.tsx
|
||||
```tsx
|
||||
// فقط نقشها چک میشوند، feature gate وجود ندارد
|
||||
<Route path="my-patients" element={<RoleRoute roles={['doctor', 'secretary', 'clinic']}><MyPatientsPage /></RoleRoute>} />
|
||||
<Route path="clinic-services" element={<RoleRoute roles={['doctor', 'clinic']}><ClinicServicesPage /></RoleRoute>} />
|
||||
<Route path="sms-wallet" element={<RoleRoute roles={['doctor', 'clinic']}><SmsWalletPage /></RoleRoute>} />
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## وظایف
|
||||
|
||||
### ۱. Backend — منشی میتواند اشتراک entity خود را ببیند
|
||||
|
||||
در `SubscriptionController::resolveEntity()` حالت `ROLE_SECRETARY` را اضافه کن:
|
||||
|
||||
```php
|
||||
if ($user->hasRole('ROLE_SECRETARY')) {
|
||||
$dbUuid = $this->contextRepo->findByUser($user)?->getDbUuid();
|
||||
if ($dbUuid) {
|
||||
$clinic = $this->clinicRepo->findByUuid($dbUuid);
|
||||
if ($clinic) return ['clinic', $clinic->getId()];
|
||||
$doctor = $this->doctorRepo->findByUuid($dbUuid);
|
||||
if ($doctor) return ['doctor', $doctor->getId()];
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
نیاز به inject کردن `UserActiveContextRepository` و `ClinicRepository` و `DoctorRepository` به `SubscriptionController` دارد.
|
||||
|
||||
### ۲. Frontend — hook مشترک `useSubscription`
|
||||
|
||||
یک فایل `assets/admin/hooks/useSubscription.ts` بساز:
|
||||
|
||||
```ts
|
||||
import { useQuery } from '@tanstack/react-query';
|
||||
import { api } from '../lib/api';
|
||||
import { useAuthStore } from '../stores/authStore';
|
||||
import type { ApiResponse, MySubscriptionData } from '../types';
|
||||
|
||||
export function useSubscription() {
|
||||
const primaryRole = useAuthStore((s) => s.primaryRole);
|
||||
const enabled = primaryRole === 'doctor' || primaryRole === 'clinic' || primaryRole === 'secretary';
|
||||
|
||||
const { data } = useQuery<ApiResponse<MySubscriptionData>>({
|
||||
queryKey: ['subscription-my'],
|
||||
queryFn: () => api.get('/api/v1/subscription/my'),
|
||||
enabled,
|
||||
staleTime: 2 * 60 * 1000,
|
||||
});
|
||||
|
||||
const sub = data?.data?.subscription ?? null;
|
||||
const features: Record<string, boolean> = sub?.plan?.features ?? {};
|
||||
const maxSecretaries: number = sub?.plan?.max_secretaries ?? 1;
|
||||
const hasPlan = sub !== null;
|
||||
|
||||
return {
|
||||
subscription: sub,
|
||||
hasFeature: (key: string) => hasPlan && (features[key] ?? false),
|
||||
maxSecretaries,
|
||||
hasPlan,
|
||||
isExpiringSoon: (sub?.days_remaining ?? 0) > 0 && (sub?.days_remaining ?? 0) <= 7,
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
**نکته:** query key `['subscription-my']` همان key ی است که `SubscriptionPage` هم استفاده میکند — cache مشترک، یک بار fetch.
|
||||
|
||||
### ۳. Frontend — Sidebar با قفل feature
|
||||
|
||||
در `Sidebar.tsx`:
|
||||
|
||||
```tsx
|
||||
import { useSubscription } from '../../hooks/useSubscription';
|
||||
// ...
|
||||
|
||||
export default function Sidebar() {
|
||||
const primaryRole = useAuthStore((s) => s.primaryRole);
|
||||
const dbUuid = useAuthStore((s) => s.dbUuid);
|
||||
const { hasFeature } = useSubscription();
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
نوع `SectionItem` را گسترش بده:
|
||||
```ts
|
||||
type SectionItem = {
|
||||
to: string;
|
||||
icon: React.ElementType;
|
||||
label: string;
|
||||
feature?: string; // اگر تعریف شد، بدون آن feature → آیکون قفل
|
||||
};
|
||||
```
|
||||
|
||||
آیتمهای محدود را با `feature` mark کن:
|
||||
```tsx
|
||||
{ to: '/admin/my-patients', icon: FolderOpenIcon, label: 'پرونده بیماران', feature: 'patient_records' },
|
||||
{ to: '/admin/clinic-services',icon: WrenchScrewdriverIcon, label: 'سرویسها', feature: 'services' },
|
||||
{ to: '/admin/sms-wallet', icon: DevicePhoneMobileIcon, label: 'کیف پول پیامک', feature: 'sms_panel' },
|
||||
```
|
||||
|
||||
در render هر آیتم:
|
||||
```tsx
|
||||
const isLocked = item.feature ? !hasFeature(item.feature) : false;
|
||||
|
||||
<NavLink
|
||||
to={isLocked ? '/admin/subscription' : item.to}
|
||||
style={isLocked ? { opacity: 0.5 } : {}}
|
||||
title={isLocked ? 'نیاز به ارتقاء پنل' : undefined}
|
||||
>
|
||||
<item.icon />
|
||||
{item.label}
|
||||
{isLocked && <LockClosedIcon style={{ width: 12, marginRight: 'auto' }} />}
|
||||
</NavLink>
|
||||
```
|
||||
|
||||
import کن: `import { LockClosedIcon } from '@heroicons/react/24/outline';`
|
||||
|
||||
### ۴. Frontend — FeatureGate component
|
||||
|
||||
یک component کوچک `assets/admin/components/ui/FeatureGate.tsx` بساز:
|
||||
|
||||
```tsx
|
||||
import React from 'react';
|
||||
import { Link } from 'react-router-dom';
|
||||
import { LockClosedIcon } from '@heroicons/react/24/outline';
|
||||
import { useSubscription } from '../../hooks/useSubscription';
|
||||
|
||||
interface FeatureGateProps {
|
||||
feature: string;
|
||||
children: React.ReactNode;
|
||||
}
|
||||
|
||||
export default function FeatureGate({ feature, children }: FeatureGateProps) {
|
||||
const { hasFeature, hasPlan } = useSubscription();
|
||||
|
||||
if (hasFeature(feature)) return <>{children}</>;
|
||||
|
||||
return (
|
||||
<div style={{
|
||||
display: 'flex', flexDirection: 'column',
|
||||
alignItems: 'center', justifyContent: 'center',
|
||||
minHeight: 320, gap: 16, padding: 40, textAlign: 'center',
|
||||
}}>
|
||||
<div style={{
|
||||
width: 64, height: 64, borderRadius: '50%',
|
||||
background: 'oklch(0.97 0.01 256)',
|
||||
display: 'grid', placeItems: 'center',
|
||||
}}>
|
||||
<LockClosedIcon style={{ width: 28, color: 'var(--text-3)' }} />
|
||||
</div>
|
||||
<div>
|
||||
<div style={{ fontWeight: 700, fontSize: 16, marginBottom: 6 }}>
|
||||
این قابلیت در پنل فعلی شما فعال نیست
|
||||
</div>
|
||||
<div style={{ color: 'var(--text-3)', fontSize: 13.5, maxWidth: 360 }}>
|
||||
{hasPlan
|
||||
? 'برای استفاده از این قابلیت پنل خود را ارتقاء دهید'
|
||||
: 'برای استفاده از این قابلیت یک پنل اشتراکی فعال کنید'}
|
||||
</div>
|
||||
</div>
|
||||
<Link to="/admin/subscription" className="btn primary sm" style={{ textDecoration: 'none' }}>
|
||||
{hasPlan ? 'ارتقاء پنل' : 'مشاهده پنلهای اشتراکی'}
|
||||
</Link>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### ۵. Frontend — استفاده از FeatureGate در صفحات
|
||||
|
||||
در **`MyPatientsPage.tsx`** محتوای اصلی را wrap کن:
|
||||
```tsx
|
||||
import FeatureGate from '../components/ui/FeatureGate';
|
||||
// ...
|
||||
return (
|
||||
<FeatureGate feature="patient_records">
|
||||
{/* کد فعلی صفحه */}
|
||||
</FeatureGate>
|
||||
);
|
||||
```
|
||||
|
||||
در **`ClinicServicesPage.tsx`**:
|
||||
```tsx
|
||||
return (
|
||||
<FeatureGate feature="services">
|
||||
{/* کد فعلی */}
|
||||
</FeatureGate>
|
||||
);
|
||||
```
|
||||
|
||||
در **`SmsWalletPage.tsx`**:
|
||||
```tsx
|
||||
return (
|
||||
<FeatureGate feature="sms_panel">
|
||||
{/* کد فعلی */}
|
||||
</FeatureGate>
|
||||
);
|
||||
```
|
||||
|
||||
### ۶. Frontend — محدودیت تعداد منشی در MySecretariesPage
|
||||
|
||||
در **`MySecretariesPage.tsx`** وقتی کاربر میخواهد منشی جدید اضافه کند:
|
||||
|
||||
```tsx
|
||||
import { useSubscription } from '../hooks/useSubscription';
|
||||
// ...
|
||||
const { maxSecretaries } = useSubscription();
|
||||
// تعداد فعلی منشیان از data موجود
|
||||
const activeCount = secretaries.filter(s => s.is_active).length;
|
||||
const isAtLimit = activeCount >= maxSecretaries;
|
||||
|
||||
// روی دکمه «افزودن منشی»:
|
||||
<button
|
||||
className="btn primary sm"
|
||||
onClick={() => setAddOpen(true)}
|
||||
disabled={isAtLimit}
|
||||
title={isAtLimit ? `حداکثر ${maxSecretaries} منشی در پنل فعلی مجاز است` : undefined}
|
||||
>
|
||||
افزودن منشی
|
||||
</button>
|
||||
{isAtLimit && (
|
||||
<div style={{ fontSize: 12, color: 'var(--text-3)', marginTop: 4 }}>
|
||||
برای افزودن منشی بیشتر <Link to="/admin/subscription">پنل خود را ارتقاء دهید</Link>
|
||||
</div>
|
||||
)}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## نکات مهم
|
||||
|
||||
- **admin نقش اشتراک ندارد:** `useSubscription` فقط برای doctor/clinic/secretary فعال است. در Sidebar ادمین هیچ feature gate نداشته باشد.
|
||||
- **secretary اشتراک entity خود را میبیند:** بعد از task 1، `/api/v1/subscription/my` برای secretary هم کار میکند. اگر db_uuid هنوز set نشده (قبل از انتخاب context)، `subscription: null` برمیگردد — `useSubscription` بهدرستی `hasPlan: false` برمیگرداند.
|
||||
- **Cache مشترک:** SubscriptionPage هم از `queryKey: ['subscription-my']` استفاده میکند — تغییر ندهید تا cache reuse شود.
|
||||
- **پلن free:** در DB ممکن است اصلاً subscription نداشته باشند (`subscription: null`). این حالت را با `hasPlan: false` handle کن. فرض نکن که "free" یک plan object است.
|
||||
- **LockClosedIcon** را import کن از `@heroicons/react/24/outline` — باید در heroicons وجود داشته باشد.
|
||||
- **migration لازم نیست** — فقط backend method و frontend تغییر میکند.
|
||||
- **مستندات:** بعد از تغییر `SubscriptionController`، فایل `docs/api/subscription.md` باید بهروز شود تا `GET /api/v1/subscription/my` برای secretary هم مستند شود.
|
||||
|
||||
---
|
||||
|
||||
## ترتیب اجرا
|
||||
|
||||
1. Backend: `SubscriptionController::resolveEntity()` — حالت secretary
|
||||
2. تست route: `ddev exec php bin/console cache:clear`
|
||||
3. Frontend: `assets/admin/hooks/useSubscription.ts` — hook جدید
|
||||
4. Frontend: `assets/admin/components/ui/FeatureGate.tsx` — component جدید
|
||||
5. Frontend: `Sidebar.tsx` — اضافه کردن `feature` به آیتمها و render قفل
|
||||
6. Frontend: `MyPatientsPage.tsx`، `ClinicServicesPage.tsx`، `SmsWalletPage.tsx` — wrap با FeatureGate
|
||||
7. Frontend: `MySecretariesPage.tsx` — محدودیت تعداد منشی
|
||||
8. Build: `ddev exec yarn dev`
|
||||
9. TypeScript: `ddev exec npx tsc --noEmit`
|
||||
10. مستندات: `docs/api/subscription.md`
|
||||
Reference in New Issue
Block a user