feat(permissions): expose the registry over GET /api/v1/permission-catalog

Both permission forms in the admin panel can now render from the backend registry instead of their own hardcoded lists. Resources come back as an array so display order is part of the contract, each carrying its Persian label, its actions, and the clinic_only flag that used to live in the frontend. contextPermissions() normalizes the no-row branch through the registry too, so a doctor whose permission row was never provisioned sees the same shape as one who has it. Two existing assertions compared the API response against DEFAULT_PERMISSIONS by identity. The values are unchanged; only key order moved to the registry's, so both now compare through PermissionCatalog::merge. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-07 17:39:45 +03:30
parent aff7b7fd4a
commit 5211b34d0e
8 changed files with 264 additions and 3 deletions
@@ -96,6 +96,7 @@ Only **digits** are translated — no characters are stripped, so `IR` in a sheb
 | [settlement.md](settlement.md) | Wallet & settlement requests | 7 |
 | [rating.md](rating.md) | Ratings, comments, likes | 9 |
 | [secretary.md](secretary.md) | Doctor secretaries | 5 |
+| [permission.md](permission.md) | Permission catalog — single registry of permissionable resources | 1 |
 | [representation.md](representation.md) | Representations (agents) | 6 |
 | [sms.md](sms.md) | SMS send & templates | 10 |
 | [blog.md](blog.md) | Blog posts | 6 |
@@ -0,0 +1,111 @@
+# Permission Catalog API
+
+> **Prefix:** `/api/v1/permission-catalog`
+
+## چرا این اندپوینت هست
+
+فهرستِ منابعِ قابل‌مجوزدهی تا پیش از این شش جا تکرار شده بود — دو Entity، سه فایل UI و
+یک interface تایپ‌اسکریپت — و از هم واگرا شده بودند. نتیجه‌اش این بود که صفحهٔ تازه
+به‌جای منبعِ خودش، مجوزِ نزدیک‌ترین صفحهٔ موجود را قرض می‌گرفت.
+
+حالا `App\Shared\Security\PermissionCatalog` تنها جایی است که می‌گوید چه منابع و
+اکشن‌هایی وجود دارند. این اندپوینت همان رجیستری را به پنل می‌دهد تا هر دو فرمِ
+مجوز — منشی و پزشکِ عضو کلینیک — به‌جای فهرستِ هاردکد از آن رندر شوند.
+
+**افزودن صفحهٔ تازه = یک ردیف در `PermissionCatalog::RESOURCES`.** فرانت تغییری لازم ندارد.
+
+رجیستری فقط **ساختار** می‌دهد. مقدارِ پیش‌فرضِ هر نقش سیاست است و در Entity خودش
+می‌ماند: `DoctorSecretary::DEFAULT_PERMISSIONS` و `ClinicDoctorPermission::DEFAULT_PERMISSIONS`.
+
+---
+
+## GET `/api/v1/permission-catalog`
+
+فهرستِ کاملِ منابع و اکشن‌ها با برچسب فارسی.
+
+**Permission:** `IS_AUTHENTICATED_FULLY`
+
+پاسخ به کاربر بستگی ندارد و تا وقتی رجیستری عوض نشود ثابت است، پس کلاینت می‌تواند
+بلندمدت cache کند (`staleTime: Infinity`). مقدارِ واقعیِ مجوزِ هر رابطه از
+اندپوینت‌های خودِ منشی/پزشک می‌آید، نه از اینجا.
+
+`resources` آرایه است نه object، تا ترتیبِ نمایش بخشی از قرارداد باشد؛ ترتیبِ
+کلیدهای JSON قرارداد نیست.
+
+### Response `200` (خروجی واقعی، بریده‌شده)
+
+```json
+{
+  "success": true,
+  "data": {
+    "version": 1,
+    "resources": [
+      {
+        "key": "appointments",
+        "label": "مدیریت نوبت‌ها",
+        "clinic_only": false,
+        "actions": [
+          { "key": "view", "label": "مشاهده نوبت‌ها" },
+          { "key": "create", "label": "ایجاد نوبت" },
+          { "key": "cancel", "label": "لغو نوبت" },
+          { "key": "update_status", "label": "تغییر وضعیت نوبت" }
+        ]
+      },
+      {
+        "key": "clinic_doctors",
+        "label": "مدیریت پزشکان کلینیک",
+        "clinic_only": true,
+        "actions": [
+          { "key": "view", "label": "مشاهده پزشکان" },
+          { "key": "create", "label": "افزودن پزشک" },
+          { "key": "update", "label": "ویرایش پزشک" },
+          { "key": "delete", "label": "حذف پزشک" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+| فیلد | نوع | توضیح |
+| --- | --- | --- |
+| `version` | int | نسخهٔ شِمای مجوزها. همان چیزی که در envelope ذخیره می‌شود |
+| `resources[].key` | string | کلیدِ منبع — همان چیزی که در `permission` JSON می‌نشیند |
+| `resources[].label` | string | برچسب فارسی برای نمایش |
+| `resources[].clinic_only` | bool | فقط در محیطِ کلینیک معنا دارد؛ پزشکِ مستقل نباید ببیندش |
+| `resources[].actions[].key` | string | `view` / `create` / `update` / `delete` / `cancel` / `update_status` |
+| `resources[].actions[].label` | string | برچسب فارسیِ همان اکشن |
+
+### منابعِ فعلی (۱۷)
+
+`appointments` · `patients` · `treatment` · `payments` · `insurances` · `addresses` ·
+`clinic_info` · `services` · `inventory` · `staff` · `tags` · `discounts` · `sms` ·
+`appointment_settings` · `resources` · `clinic_doctors` · `subscription`
+
+اکشن‌ها یکسان نیستند: `subscription` فقط `view/create` دارد، و
+`clinic_info` / `appointment_settings` / `treatment` فقط `view/update`.
+
+### Errors
+
+| Status | شرایط |
+| --- | --- |
+| `401` | بدون توکن یا توکنِ نامعتبر |
+
+---
+
+## سازگاری با دادهٔ موجود
+
+`getPermissions()` روی هر دو Entity، JSONِ ذخیره‌شده را روی پیش‌فرضِ نقش merge می‌کند:
+
+- منبعی که در رجیستری هست و در JSONِ ردیف نیست (یعنی بعد از ساختِ آن ردیف اضافه شده)
+  **پیش‌فرضِ نقش** را می‌گیرد، نه `false`. بدون این، هر منبع تازه برای همهٔ ردیف‌های
+  موجود خاموش می‌ماند.
+- مقدارِ صریحِ ذخیره‌شده هرگز بازنویسی نمی‌شود — حتی `false`.
+- هیچ migration دادهٔ انبوهی لازم نیست؛ ستون `permission` از نوع `json` است و
+  schema عوض نمی‌شود.
+
+نوشتن‌ها از `PermissionCatalog::filterPatch()` عبور می‌کنند: منبع یا اکشنِ خارج از
+رجیستری **بی‌صدا** کنار گذاشته می‌شود (نه `422`) — همان رفتاری که کلاینت‌های فعلی روی
+آن حساب کرده‌اند. بقیهٔ کلیدهای همان درخواست اعمال می‌شوند.
+
+مصرف‌کننده‌ها: [secretary.md](secretary.md) · [clinic.md](clinic.md)
@@ -132,7 +132,13 @@ Create a secretary for a doctor.

 **Permissions Structure:**

-مجموعهٔ منابع (resources) بر اساس صفحات و ماژول‌های در دسترسِ منشی است: `appointments`, `patients`, `payments`, `insurances`, `addresses`, `clinic_info`, `inventory`, `tags`, `services`, `staff`, `discounts`, `sms`, `appointment_settings`, `clinic_doctors`, `subscription`. منبعِ `subscription` فقط `view/create` دارد. `mergePermissions` هر منبع/اکشن ارسال‌شده را deep-merge می‌کند. منابعِ `inventory`, `tags`, `services`, `staff`, `discounts`, `sms`, `appointment_settings`, `clinic_doctors` به‌صورت پیش‌فرض همه `false`‌اند (default-deny)؛ بقیه طبق `DEFAULT_PERMISSIONS`. منبعِ `appointment_settings` فقط `view/update` دارد. منبعِ `clinic_doctors` **فقط در حالت کلینیک** معنا دارد (پزشک مستقل نه toggle نه منو).
+مجموعهٔ منابع را دیگر این فایل تعیین نمی‌کند: منبعِ واحد `App\Shared\Security\PermissionCatalog` است و از `GET /api/v1/permission-catalog` هم خوانده می‌شود — [permission.md](permission.md). فهرستِ فعلی: `appointments`, `patients`, `treatment`, `payments`, `insurances`, `addresses`, `clinic_info`, `services`, `inventory`, `staff`, `tags`, `discounts`, `sms`, `appointment_settings`, `resources`, `clinic_doctors`, `subscription`.
+
+منبعِ `subscription` فقط `view/create` دارد؛ `clinic_info`, `appointment_settings` و `treatment` فقط `view/update`. منبعِ `clinic_doctors` **فقط در حالت کلینیک** معنا دارد (پزشک مستقل نه toggle نه منو) و در کاتالوگ با `clinic_only: true` علامت خورده.
+
+`mergePermissions` هر منبع/اکشن ارسال‌شده را deep-merge می‌کند و **هر دو شکلِ ورودی** را می‌پذیرد: با envelope (`{version, resources:{…}}`) و نقشهٔ تخت (`{patients:{…}}`). تا پیش از این فقط شکلِ اول خوانده می‌شد و صفحهٔ ادمین که تخت می‌فرستد بی‌صدا بی‌اثر بود. منبع یا اکشنِ خارج از رجیستری بی‌صدا کنار گذاشته می‌شود؛ بقیهٔ کلیدهای همان درخواست اعمال می‌شوند.
+
+پیش‌فرض‌ها (`DEFAULT_PERMISSIONS`) سیاستِ نقشِ منشی‌اند، نه ساختار: `appointments`, `patients`, `treatment`, `payments`, `insurances`, `addresses`, `clinic_info` با `view` روشن؛ بقیه default-deny. منبعی که بعد از ساختِ یک ردیف به رجیستری اضافه شود، هنگام خواندن **پیش‌فرضِ نقش** را می‌گیرد نه `false` — پس نیازی به migration داده نیست.

 **اعمال (enforcement):** همهٔ منابع در بک‌اند enforce می‌شوند، نه فقط `appointments`. منبعِ حقیقت، ستون JSON `permission` روی ردیفِ فعالِ `DoctorSecretary` در محیطِ فعالِ کاربر (`UserActiveContext.db_uuid`) است؛ نقطهٔ مرکزی `App\Secretary\Security\SecretaryAccessChecker` (`can` / `canOrNonSecretary` / `denyUnlessGranted`). نبودِ مجوز → `403 ERR_FORBIDDEN_001`. نقشه: