clinicpro/docs/phase2_taskes/task-12-secretary-completion/task.md

تسک ۱۲: تکمیل منشی — محدودیت پنل + UI Permissions

توضیح

Entity DoctorSecretary و API کامل موجود است (src/Secretary/). این تسک فقط دو چیز اضافه می‌کند:

1. Backend: بررسی سقف تعداد منشی بر اساس پنل اشتراکی
2. Frontend: Modal با checkbox matrix برای ویرایش permissions

هیچ endpoint جدیدی ایجاد نمی‌شود.

فایل‌های موجود که تغییر می‌کنند

فایل	تغییر
src/Secretary/Controller/SecretaryController.php	inject SubscriptionService، اضافه کردن limit check در create()
assets/admin/pages/SecretariesPage.tsx	Modal ویرایش با checkbox matrix برای permissions

API موجود (بدون تغییر)

متد	مسیر	توضیح
GET	/api/v1/secretaries/{doctorUuid}	لیست منشی ها
POST	/api/v1/secretary	ایجاد منشی ← اینجا limit check اضافه می‌شود
PATCH	/api/v1/secretary/{uuid}	ویرایش ← permissions هم قابل ویرایش می‌شود
DELETE	/api/v1/secretary/{uuid}	غیرفعال‌سازی (soft delete)

پیش‌نیازها

• تسک ۱۴ (Secretary — موجود در کد)
• تسک ۱۱ (Subscription — SubscriptionService باید موجود باشد)

زمان تخمینی

۴ تا ۵ ساعت

تغییر Backend — SecretaryController::create()

وضعیت فعلی (قبل):

public function create(Request $request): JsonResponse
{
    // validate fields
    // create DoctorSecretary
    // persist
    return $this->success($secretary->toArray());
}

وضعیت جدید (بعد):

public function create(Request $request): JsonResponse
{
    // 1. پیدا کردن دکتر از doctorUuid در body
    $doctor = $this->doctorRepo->findByUuid($request->get('doctor_uuid'));

    // 2. بررسی سقف پنل
    $entityType = 'doctor';
    $entityId   = $doctor->getId();
    $limit   = $this->subscriptionService->getSecretaryLimit($entityType, $entityId);
    $current = $this->secretaryRepo->countActive($doctor->getId());
    if ($current >= $limit) {
        return $this->error(
            ErrorCodes::ERR_SECRETARY_LIMIT_REACHED,
            'سقف تعداد منشی پنل اشتراکی شما رسیده است',
            Response::HTTP_FORBIDDEN
        );
    }

    // 3. ادامه ایجاد منشی ...
}

خطای جدید که باید در ErrorCodes.php اضافه شود:

// src/Shared/Constant/ErrorCodes.php
const ERR_SECRETARY_LIMIT_REACHED = 'ERR_SECRETARY_LIMIT_REACHED';
// messages: 'سقف تعداد منشی پنل اشتراکی شما رسیده است'

تغییر Frontend — SecretariesPage.tsx

ساختار DEFAULT_PERMISSIONS (از DoctorSecretary::DEFAULT_PERMISSIONS):

[
    'version'   => 1,
    'resources' => [
        'appointments' => ['view' => true,  'create' => true,  'cancel' => false, 'update_status' => true],
        'addresses'    => ['view' => true,  'create' => false, 'update' => false, 'delete' => false],
        'clinic_info'  => ['view' => true,  'update' => false],
        'insurances'   => ['view' => true,  'create' => false, 'update' => false, 'delete' => false],
    ],
]

نمونه UI Permissions checkbox matrix در Modal:

┌─────────────────────────────────────────────────────┐
│  دسترسی‌های منشی                                    │
├──────────────┬───────┬────────┬────────┬────────────┤
│ بخش          │ مشاهده│ ایجاد  │ ویرایش │ حذف/لغو   │
├──────────────┼───────┼────────┼────────┼────────────┤
│ نوبت‌ها      │  ☑    │  ☑    │  ☑    │  ☐         │
│ آدرس‌ها      │  ☑    │  ☐    │  ☐    │  ☐         │
│ اطلاعات کلینیک│ ☑    │  -    │  ☐    │  -         │
│ بیمه‌ها      │  ☑    │  ☐    │  ☐    │  ☐         │
└──────────────┴───────┴────────┴────────┴────────────┘

PATCH /api/v1/secretary/{uuid} با permissions:

{
    "permissions": {
        "version": 1,
        "resources": {
            "appointments": {
                "view": true,
                "create": true,
                "cancel": true,
                "update_status": true
            },
            "addresses": {
                "view": true,
                "create": false,
                "update": false,
                "delete": false
            }
        }
    }
}

کدهای خطای جدید

کد	پیام فارسی
ERR_SECRETARY_LIMIT_REACHED	سقف تعداد منشی پنل اشتراکی شما رسیده است

Response خطا (403)

{
    "success": false,
    "errors": [
        {
            "code": "ERR_SECRETARY_LIMIT_REACHED",
            "message": "سقف تعداد منشی پنل اشتراکی شما رسیده است. برای افزودن منشی بیشتر پنل را ارتقاء دهید."
        }
    ]
}