feat: Implement permission gate for appointment and billing controllers

- Added PermissionGateTrait to manage access control for AppointmentPlanController and BillingController.
- Introduced denyUnlessGrantedForPlanning method in AppointmentPlanController to handle specific permission checks for planning appointments.
- Updated existing methods in both controllers to utilize the new permission checks.
- Refactored ResourcePermissionTrait to use PermissionGateTrait for cleaner permission management.
- Added tests to ensure proper permission enforcement across different scenarios, including cross-tenant access restrictions for staff.

src/Appointment/Controller/MyAppointmentsController.php

@@ -29,6 +29,17 @@ use OpenApi\Attributes as OA;
 #[OA\Tag(name: 'My Appointments')]
 class MyAppointmentsController extends BaseController
 {
+    use \App\Shared\Controller\PermissionGateTrait;
+
+    /**
+     * همهٔ روت‌های این کنترلر زیرِ توگلِ «مدیریت نوبت‌ها»ی پنل‌اند: فهرست، آمار روز،
+     * تب‌های پزشک و خودِ فرمِ ثبت نوبت. `patient-lookup` هم بخشی از همان فرم است.
+     */
+    private function permissionResource(): string
+    {
+        return 'appointments';
+    }
+
     public function __construct(
         private readonly EntityManagerInterface        $em,
         private readonly AppointmentRepository         $appointmentRepo,
@@ -63,6 +74,8 @@ class MyAppointmentsController extends BaseController
     #[IsGranted('IS_AUTHENTICATED_FULLY')]
     public function myClinicDoctors(#[CurrentUser] User $user): JsonResponse
     {
+        $this->denyUnlessGranted($user, 'view');
+
         $roles   = $user->getRoles();
         $doctors = [];
 
@@ -116,6 +129,8 @@ class MyAppointmentsController extends BaseController
             return $this->error(ErrorCodes::FORBIDDEN, 'دسترسی ندارید', 403);
         }
 
+        $this->denyUnlessGranted($user, 'create');
+
         $data        = json_decode($request->getContent(), true) ?? [];
         $doctorUuid  = trim($data['doctor_uuid']    ?? '');
         $slotStart   = (int) ($data['slot_start']   ?? 0);
@@ -394,6 +409,10 @@ class MyAppointmentsController extends BaseController
             return $this->error(ErrorCodes::FORBIDDEN, 'دسترسی ندارید', 403);
         }
 
+        // بخشی از فرمِ ثبت نوبت است، پس همان `appointments.create` — نه `patients.view`.
+        // با گیتِ پرونده، منشی‌ای که فقط اجازهٔ نوبت‌دهی دارد فرمش را از دست می‌داد.
+        $this->denyUnlessGranted($user, 'create');
+
         // Lookup by mobile OR national code — the booking form lets the user
         // search either way. National code takes precedence when both are sent.
         $mobile       = InputValidator::toEnglishDigits(trim((string) $request->query->get('mobile', '')));
@@ -430,6 +449,8 @@ class MyAppointmentsController extends BaseController
     #[IsGranted('IS_AUTHENTICATED_FULLY')]
     public function myAppointments(Request $request, #[CurrentUser] User $user): JsonResponse
     {
+        $this->denyUnlessGranted($user, 'view');
+
         $page       = max(1, (int) $request->query->get('page', 1));
         $limit      = min(500, max(1, (int) $request->query->get('limit', 15)));
         $search     = trim((string) $request->query->get('search', ''));
@@ -620,6 +641,8 @@ class MyAppointmentsController extends BaseController
     #[IsGranted('IS_AUTHENTICATED_FULLY')]
     public function todayStats(Request $request, #[CurrentUser] User $user): JsonResponse
     {
+        $this->denyUnlessGranted($user, 'view');
+
         $date = trim((string) $request->query->get('date', date('Y-m-d')));
         if (!preg_match('/^\d{4}-\d{2}-\d{2}$/', $date)) {
             $date = date('Y-m-d');

src/Appointment/Plan/Controller/AppointmentPlanController.php

@@ -26,6 +26,38 @@ use Symfony\Component\Security\Http\Attribute\IsGranted;
 #[IsGranted('IS_AUTHENTICATED_FULLY')]
 class AppointmentPlanController extends BaseController
 {
+    use \App\Shared\Controller\PermissionGateTrait;
+
+    /**
+     * بخش‌بندی یک خاصیتِ `ServiceItem` است و صفحه‌اش داخل کاتالوگ خدمات، پس همان
+     * منبعِ `services` — نه `appointments`. دقیقاً همان استدلالِ پروتکل درمان در
+     * آدیت ۲۰۲۶-۰۸-۰۷.
+     */
+    private function permissionResource(): string
+    {
+        return 'services';
+    }
+
+    /**
+     * پیش‌نمایشِ برنامهٔ یک نوبت — ورودیِ فرمِ ثبت نوبت است، نه پیکربندیِ سرویس.
+     *
+     * قرینهٔ `ResourcePermissionTrait::denyUnlessGrantedForBooking`: منشی‌ای که
+     * اجازهٔ ثبت نوبت دارد ولی کاتالوگ خدمات برایش بسته است، وگرنه نمی‌توانست همان
+     * نوبتی را که مجاز است ثبت کند.
+     */
+    private function denyUnlessGrantedForPlanning(User $user): void
+    {
+        $allowed =
+            ($this->secretaryAccess->canOrNonSecretary($user, 'services', 'view')
+                && $this->clinicDoctorAccess->canOrNonMember($user, 'services', 'view'))
+            || ($this->secretaryAccess->canOrNonSecretary($user, 'appointments', 'view')
+                && $this->clinicDoctorAccess->canOrNonMember($user, 'appointments', 'view'));
+
+        if (!$allowed) {
+            throw new AppException(ErrorCodes::ERR_FORBIDDEN_001, null, 403);
+        }
+    }
+
     public function __construct(
         private readonly SegmentTemplateRepository $templates,
         private readonly ServiceItemRepository     $items,
@@ -38,6 +70,8 @@ class AppointmentPlanController extends BaseController
     #[Route('/api/v1/service-item/{uuid}/segments', name: 'service_segments_show', methods: ['GET'])]
     public function show(#[CurrentUser] User $user, string $uuid): JsonResponse
     {
+        $this->denyUnlessGranted($user, 'view');
+
         $service = $this->requireItem($user, $uuid);
 
         return $this->success(array_map(
@@ -55,6 +89,8 @@ class AppointmentPlanController extends BaseController
     #[Route('/api/v1/service-item/{uuid}/segments', name: 'service_segments_replace', methods: ['PUT'])]
     public function replace(#[CurrentUser] User $user, string $uuid, Request $request): JsonResponse
     {
+        $this->denyUnlessGranted($user, 'update');
+
         $data = json_decode($request->getContent(), true);
 
         if (!is_array($data) || !is_array($data['segments'] ?? null)) {
@@ -198,6 +234,8 @@ class AppointmentPlanController extends BaseController
     #[Route('/api/v1/appointment-plan/preview', name: 'appointment_plan_preview', methods: ['POST'])]
     public function preview(#[CurrentUser] User $user, Request $request): JsonResponse
     {
+        $this->denyUnlessGrantedForPlanning($user);
+
         $data = json_decode($request->getContent(), true);
 
         if (!is_array($data) || !is_string($data['service_uuid'] ?? null)) {