{
  "title": "راهنمای اتصال سرویس‌های بکند به پنل ادمین",
  "slug": "team/backend/admin-panel-integration",
  "url": "/docs/team/backend/admin-panel-integration",
  "frontmatter": {},
  "sections": [
    {
      "level": 1,
      "heading": "راهنمای اتصال سرویس‌های بکند به پنل ادمین",
      "content": "**تاریخ:** 2026-07-16 (بروزرسانی: اصلاح بخش user-service بر اساس endpointهای جدید)\n**وضعیت:** پیش‌نویس برای تیم پنل ادمین\n**محدوده:** ۵ سرویس بکند آماده برای ادغام — `user-service`, `pool-service`, `auth-service`, `token-service`, `iam-service`\n\n---"
    },
    {
      "level": 2,
      "heading": "۰. مقدمه و نحوه استفاده",
      "content": "این سند فهرستی جامع از داده‌ها و نقاط پایانی (endpoints) هر یک از ۵ سرویس بکند را ارائه می‌دهد که می‌توانید مستقیماً به **پنل ادمین** متصل کنید. برای هر سرویس، ابتدا خلاصه‌ای از قابلیت‌های قابل نمایش در پنل آمده، سپس لیست دقیق endpointها با متد، مسیر، هدف و نوع پاسخ.\n\n> **قراردادهای عمومی:**\n> - تمام سرویس‌ها زیر پیشوند `/v1` هستند.\n> - فرمت پاسخ موفق در `user-service`: `{ \"success\": true, \"data\": ..., \"meta\": ... }` (envelope جدید با فیلد `success`).\n> - فرمت پاسخ موفق در `pool-service`: `{ \"data\": ... }` (envelope ساده).\n> - احراز هویت پنل ادمین از طریق:\n>   - `CookieSession` (کوکی `session`) — حالت پیش‌فرض پنل\n>   - `BearerJWT` (هدر `Authorization: Bearer <token>`) — سرویس‌ها/CLI/موبایل\n>   - `ApiKey` (هدر `X-API-Key`) — ادغام‌های خارجی و endpointهای ادمین `pool-service`\n> - فرمت خطا یکسان: `{ \"error\": { \"code\": string, \"message\": string } }`\n> - مستندات OpenAPI تولید‌شده (با ابزار `nons-openapi`) برای `user-service` و `pool-service` در `services/<name>/docs/openapi.yaml` موجود است و منبع رسمی schemaها می‌باشد.\n\n---"
    },
    {
      "level": 2,
      "heading": "۱. user-service — مدیریت پروفایل کاربر",
      "content": "**مسیر پایه:** `/v1/users`\n**نوع داده‌ها:** پروفایل عمومی، پروفایل خصوصی، تنظیمات، یوزرنام، آواتار، وضعیت، لیست کاربران\n**مناسب برای پنل ادمین:** لیست/جستجوی کاربران (admin)، نمایش پروفایل، ویرایش نمایشی نام و ترجیحات، نظارت بر تغییرات یوزرنام/آواتار، مدیریت آواتارهای پیش‌فرض.\n**مستند OpenAPI:** `services/user-service/docs/openapi.yaml` (تولید شده، معتبر ۳.۱.۰ — ۸ مسیر)\n\n> **تغییر فرمت پاسخ (مهم):** پاسخ موفق اکنون envelope جدید دارد:\n> ```json\n> { \"success\": true, \"data\": ..., \"meta\": { ... } }\n> ```\n> (پیش‌تر فقط `{ \"data\": ... }` بود). پاسخ خطا نیز یکسان است:\n> ```json\n> { \"success\": false, \"error\": { \"code\": string, \"message\": string, \"details\": [...] } }\n> ```"
    },
    {
      "level": 3,
      "heading": "۱.۱ قابلیت‌های قابل اتصال به پنل",
      "content": "| قابلیت پنل | Endpoint | دسترسی |\n|---|---|---|\n| لیست کاربران (صفحه‌بندی) | `GET /v1/users` | ادمین |\n| جستجو/فیلتر کاربران | `GET /v1/users?status=&search=&cursor=&limit=` | ادمین |\n| نمایش پروفایل عمومی | `GET /v1/users/{publicId}` | عمومی |\n| پروفایل من (ادمین) | `GET /v1/users/me` | BearerJWT |\n| ویرایش نام نمایشی | `PATCH /v1/users/me/profile` | BearerJWT |\n| ویرایش ترجیحات | `PATCH /v1/users/me/preferences` | BearerJWT |\n| تغییر یوزرنام | `PATCH /v1/users/me/username` | BearerJWT |\n| تغییر آواتار | `PATCH /v1/users/me/avatar` | BearerJWT |\n| لیست آواتارهای پیش‌فرض | `GET /v1/users/avatars` | عمومی |"
    },
    {
      "level": 3,
      "heading": "۱.۲ endpointهای دقیق",
      "content": "| متد | مسیر | امنیت | کاربرد در پنل |\n|---|---|---|---|\n| GET | `/v1/users?cursor=&limit=&status=&search=` | Admin | لیست کاربران با صفحه‌بندی cursor-based و فیلتر وضعیت/جستجو |\n| GET | `/v1/users/{publicId}` | Public | نمایش پروفایل عمومی (یوزرنام، نام، آواتار) |\n| GET | `/v1/users/me` | BearerJWT | پروفایل کامل ادمین جاری (شامل status, created_at, updated_at) |\n| PATCH | `/v1/users/me/profile` | BearerJWT | ویرایش display_name (بدنه: `{display_name}`) |\n| PATCH | `/v1/users/me/preferences` | BearerJWT | ویرایش ترجیحات (بدنه: `{currency, theme, language}`) |\n| PATCH | `/v1/users/me/username` | BearerJWT | تغییر یوزرنام (بدنه: `{username}`) — خطای ۴۰۹ اگر تکراری |\n| PATCH | `/v1/users/me/avatar` | BearerJWT | انتصاب آواتار (بدنه: `{avatar_id}`) |\n| GET | `/v1/users/avatars` | Public | لیست آواتارهای پیش‌فرض سیستم |"
    },
    {
      "level": 3,
      "heading": "۱.۳ ساختار پاسخ‌های کلیدی (schema)",
      "content": "**لیست کاربران — `GET /v1/users`**\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"public_id\": \"usr_xxx\",\n      \"username\": \"game_lord_42\",\n      \"display_name\": \"Lord\",\n      \"avatar_url\": \"https://...\",\n      \"status\": \"ACTIVE\",\n      \"created_at\": \"2026-07-16T10:00:00Z\"\n    }\n  ],\n  \"meta\": {\n    \"pagination\": {\n      \"next_cursor\": \"usr_yyy\",\n      \"prev_cursor\": null,\n      \"has_more\": true,\n      \"limit\": 20\n    }\n  }\n}\n```\n\n**پارامترهای `GET /v1/users`:**\n| پارامتر | نوع | توضیح |\n|---|---|---|\n| `cursor` | string | کورسر صفحه‌بندی (از `meta.pagination.next_cursor`) |\n| `limit` | int | تعداد در صفحه (پیش‌فرض ۲۰) |\n| `status` | string | فیلتر وضعیت (مثلاً `ACTIVE`, `SUSPENDED`) |\n| `search` | string | جستجوی متنی در یوزرنام/نام |\n\n**آواتار پیش‌فرض — `GET /v1/users/avatars`**\n```json\n{\n  \"success\": true,\n  \"data\": [\n    { \"id\": \"default_01\", \"asset_url\": \"https://cdn.nons.app/avatars/default_01.png\", \"type\": \"DEFAULT\", \"status\": \"ACTIVE\" }\n  ]\n}\n```"
    },
    {
      "level": 3,
      "heading": "۱.۴ تست عملی (واقعی — ۱۴۰۶/۰۷/۱۶)",
      "content": "سرویس روی پورت `3003` اجرا شد و endpointها با داده واقعی تست شدند:\n\n**نتایج:**\n| تست | نتیجه |\n|---|---|\n| `GET /v1/users` (بدون فیلتر) | ۲ کاربر برگشت، `has_more=false` |\n| `GET /v1/users?search=admin` | ۱ نتیجه: `admin_user` |\n| `GET /v1/users?status=ACTIVE&limit=1` | `has_more=true`، `next_cursor` مقدار داشت (صفحه‌بندی درست کار می‌کند) |\n| `GET /v1/users/avatars` | ۵ آواتار پیش‌فرض (`default_01` تا `default_05`) |\n\n**داده فعلی پایگاه (تعداد کاربران: ۲):**\n```\npub_f7fe46a1 | admin_user   | ACTIVE | 2026-07-16\nid123456789 | tester_123  | ACTIVE | 2026-07-10\n```\n\n> **منبع داده:** جدول `users` در PostgreSQL (پایگاه `user_db`). فیلتر `status != 'DELETED'` اعمال می‌شود. کاربران هنگام ثبت‌نام (مصرف رویداد `nons.auth.user.registered`) توسط `CreateProfile` ایجاد می‌شوند.\n> **توجه:** Avatar URL در پاسخ لیست کاربران (`avatar_url`) فعلاً فقط ID آواتار را برمی‌گرداند (مثلاً `\"default_01\"`)، نه URL کامل — چون `avatarRepo.GetByID` در لیست صدا زده نمی‌شود (فقط در `GetProfilePublic`/`GetProfilePrivate`). پنل ادمین باید برای نمایش تصویر، `GET /v1/users/avatars` را جداگانه فراخوانی کند یا آواتار را از Pool بگیرد."
    },
    {
      "level": 3,
      "heading": "۱.۵ باگ اصلاح‌شده",
      "content": "- **مشکل:** `GET /v1/users/avatars` پاسخ را به صورت تو در تو برمی‌گرداند: `{\"success\":true,\"data\":{\"data\":[...]}}` (double envelope).\n- **علت:** فراخوانی `sendSuccess(w, ListAvatarsResponse{...})` در حالی که `ListAvatarsResponse` خودش فیلد `data` دارد و `sendSuccess` دورش یک `data` دیگر می‌پیچد.\n- **رفع:** تغییر به `sendJSON(w, http.StatusOK, ListAvatarsResponse{...})` (همان الگوی `ListUsers`).\n\n> **نکته IAM:** تغییر یوزرنام/آواتار توسط کاربر نهایی از طریق پالیسی `iam-service` کنترل می‌شود (مالکیت پالیسی در D8/D9). پنل ادمین برای اقدامات نیابتی (impersonation) باید مجوز `users.updateProfile:any` را چک کند. لیست کاربران (`GET /v1/users`) نیازمند مجوز `users.list` است.\n\n---"
    },
    {
      "level": 2,
      "heading": "۲. pool-service — داده‌های مرجع و مواد (Reference Data & Material Pools)",
      "content": "**مسیر پایه:** `/v1/pool`\n**نوع داده‌ها:** مواد یوزرنام (adjective/noun)، یوزرنام‌های رزرو شده، آواتارها، ارزهای پشتیبانی‌شده\n**مناسب برای پنل ادمین:** مدیریت واژگان تولید یوزرنام، مدیریت لیست سیاه/رزرو یوزرنام، کاتالوگ آواتارها، تنظیم ارزهای سیستم.\n**مستند OpenAPI:** `services/pool-service/docs/openapi.yaml` (تولید شده، معتبر ۳.۱.۰)"
    },
    {
      "level": 3,
      "heading": "۲.۱ قابلیت‌های قابل اتصال به پنل",
      "content": "| قابلیت پنل | Endpoint | دسترسی |\n|---|---|---|\n| کاتالوگ مواد یوزرنام | `GET /v1/pool/username/materials` | عمومی (نمایش) |\n| افزودن ماده جدید | `POST /v1/pool/username/materials` | ادمین (`X-API-Key`) |\n| لیست یوزرنام‌های رزرو شده | `GET /v1/pool/username/reserved` | عمومی (نمایش) |\n| رزرو یوزرنام جدید | `POST /v1/pool/username/reserved` | ادمین |\n| بررسی در دسترس بودن | `POST /v1/pool/username/check` | عمومی |\n| رزرو در زمان ثبت‌نام | `POST /v1/pool/username/reserve` | سرویس (ApiKey) |\n| کاتالوگ آواتارها | `GET /v1/pool/avatars` | عمومی |\n| جزئیات آواتار | `GET /v1/pool/avatars/{id}` | عمومی |\n| افزودن آواتار | `POST /v1/pool/avatars` | ادمین |\n| لیست ارزها | `GET /v1/pool/currencies` | عمومی |"
    },
    {
      "level": 3,
      "heading": "۲.۲ endpointهای دقیق",
      "content": "| متد | مسیر | امنیت | کاربرد در پنل |\n|---|---|---|---|\n| GET | `/v1/pool/username/materials?category=ADJECTIVE\\|NOUN` | Public | نمایش/فیلتر مواد یوزرنام |\n| POST | `/v1/pool/username/materials` | ApiKey | ایجاد ماده (بدنه: `{value, category}`) |\n| GET | `/v1/pool/username/reserved` | Public | نمایش یوزرنام‌های رزرو شده |\n| POST | `/v1/pool/username/reserved` | ApiKey | رزرو (بدنه: `{username, reason}`) |\n| POST | `/v1/pool/username/check` | Public | بررسی در دسترس بودن (بدنه: `{username}`) → `{available, reason}` |\n| POST | `/v1/pool/username/reserve` | ApiKey | رزرو هنگام ثبت‌نام (بدنه: `{username}`) |\n| GET | `/v1/pool/avatars` | Public | کاتالوگ آواتارها |\n| GET | `/v1/pool/avatars/{id}` | Public | جزئیات آواتار |\n| POST | `/v1/pool/avatars` | ApiKey | ثبت آواتار (بدنه: `{id, asset_url, category, skin_tone, tags}`) |\n| GET | `/v1/pool/currencies` | Public | لیست ارزها (code, name, symbol, precision, country) |\n\n> **نکته معماری:** `pool-service` فقط **مواد** را فراهم می‌کند؛ الگوریتم تولید یوزرنام (adjective_noun_NNN) در `user-service` (Consumer) باقی می‌ماند (D2). پنل ادمین نباید خودش یوزرنام تولید کند — فقط مواد را مدیریت کند.\n\n---"
    },
    {
      "level": 2,
      "heading": "۳. auth-service — احراز هویت و نشست (Kratos wrapper)",
      "content": "**مسیر پایه:** `/v1/auth`\n**تکنولوژی:** ORY Kratos + Go wrapper، پشتیبانی از JSON (بدون HTML) از طریق هدر `Accept: application/json`\n**مناسب برای پنل ادمین:** نمایش وضعیت نشست ادمین، مدیریت جریان‌های ورود/ثبت‌نام، تایید/رد درخواست‌ها، صفحه خطا و تنظیمات."
    },
    {
      "level": 3,
      "heading": "۳.۱ قابلیت‌های قابل اتصال به پنل",
      "content": "| قابلیت پنل | Endpoint | توضیح |\n|---|---|---|\n| وضعیت نشست فعلی | `GET /v1/auth/session` | `{authenticated, user, logoutUrl}` |\n| شروع جریان ورود/ثبت‌نام | `POST /v1/auth/entry` | برمی‌گرداند `{flowId, type}` |\n| فرم ورود | `GET/POST /v1/auth/login` | دریافت/ارسال flow |\n| فرم ثبت‌نام | `GET/POST /v1/auth/register` | دریافت/ارسال flow (شامل فیلدهای OTP) |\n| خروج | `GET /v1/auth/logout` | باطل‌سازی نشست |\n| داشبورد | `GET /v1/auth/dashboard` | اطلاعات کاربر (JSON در صورت `Accept: application/json`) |\n| تنظیمات | `GET/POST /v1/auth/settings` | تغییر رمز/Recovery |\n| اعتبارسنجی توکن | `GET /v1/auth/validate` | بررسی اعتبار |\n| تایید (Verification) | `GET/POST /v1/auth/verification` | تایید ایمیل/شماره |\n| صفحه خطا | `GET /v1/auth/error` | نمایش خطاهای Kratos |\n| URL هدایت OIDC | `GET /v1/auth/oidc-url` | دریافت URL ریدایرکت تامین‌کننده |\n| وبهوک ثبت‌نام | `POST /v1/auth/webhooks/kratos/register` | دریافت رویداد ثبت‌نام از Kratos |\n| مسیر محافظت‌شده | `GET /v1/protected` | تست دسترسی |"
    },
    {
      "level": 3,
      "heading": "۳.۲ endpointهای دقیق",
      "content": "| متد | مسیر | کاربرد در پنل |\n|---|---|---|\n| GET | `/v1/auth/session` | وضعیت نشست (JSON: `{authenticated, user, logoutUrl}`) |\n| POST | `/v1/auth/entry` | شروع flow (پاسخ: `{flowId, type}`) |\n| GET | `/v1/auth/login` | دریافت فرم ورود (FlowResponseJSON) |\n| POST | `/v1/auth/login` | ارسال فرم ورود |\n| GET | `/v1/auth/register` | دریافت فرم ثبت‌نام (شامل codeNodes/socialNodes) |\n| POST | `/v1/auth/register` | ارسال فرم ثبت‌نام |\n| GET | `/v1/auth/logout` | خروج کاربر |\n| GET | `/v1/auth/dashboard` | اطلاعات داشبورد (JSON) |\n| GET | `/v1/auth/settings` | فرم تنظیمات |\n| POST | `/v1/auth/settings` | به‌روزرسانی تنظیمات |\n| GET | `/v1/auth/validate` | اعتبارسنجی درخواست |\n| GET | `/v1/auth/verification` | فرم تایید |\n| POST | `/v1/auth/verification` | ارسال تایید |\n| GET | `/v1/auth/error` | صفحه خطا |\n| GET | `/v1/auth/oidc-url` | URL ریدایرکت OIDC |\n| POST | `/v1/auth/webhooks/kratos/register` | وبهوک ثبت‌نام (داخلی) |\n| GET | `/v1/protected` | تست مسیر محافظت‌شده |\n\n> **توجه:** endpointهای `/v1/auth/static/` (فایل‌های ایستا) و خود فرم‌ها عمدتاً برای UI هستند؛ پنل ادمین ترجیحاً از نسخه JSON (هدر `Accept: application/json` یا `?format=json`) استفاده کند.\n\n---"
    },
    {
      "level": 2,
      "heading": "۴. token-service — صدور و اعتبارسنجی توکن (Ory Hydra)",
      "content": "**وضعیت:** Blueprint نهایی (نسخه ۳.۴) — پیاده‌سازی با Helm (بدون کد wrapper) + `login-consent-app`\n**مسیر پایه (Public):** `/v1/auth/hydra` (از طریق Gateway)\n**مناسب برای پنل ادمین:** نمایش وضعیت صدور توکن، ابطال توکن کاربران دیگر (Admin)، مشاهده JWKS، نظارت بر رویدادهای صدور/ابطال."
    },
    {
      "level": 3,
      "heading": "۴.۱ قابلیت‌های قابل اتصال به پنل",
      "content": "| قابلیت پنل | Endpoint | دسترسی |\n|---|---|---|\n| آغاز جریان Authorization | `GET /oauth2/auth` | عمومی (از طریق Gateway) |\n| صدور/تمدید توکن | `POST /oauth2/token` | عمومی |\n| ابطال توکن کاربر جاری | `POST /oauth2/revoke` | کاربر |\n| **ابطال توکن سایر کاربران** | `POST /oauth2/revoke` + مجوز `token.revoke:any` | **ادمین** |\n| کلیدهای عمومی (JWKS) | `GET /.well-known/jwks.json` | عمومی |\n| متادیتا OIDC | `GET /.well-known/openid-configuration` | عمومی |\n| خروج OIDC | `GET /oauth2/sessions/logout` | عمومی |"
    },
    {
      "level": 3,
      "heading": "۴.۲ endpointهای دقیق (سطح Public)",
      "content": "| متد | مسیر (نسبت به پایه Gateway) | کاربرد در پنل |\n|---|---|---|\n| GET | `/v1/auth/hydra/oauth2/auth` | شروع جریان OAuth2 |\n| POST | `/v1/auth/hydra/oauth2/token` | صدور/تمدید (grant_type: authorization_code, refresh_token) |\n| POST | `/v1/auth/hydra/oauth2/revoke` | ابطال توکن |\n| GET | `/v1/auth/hydra/.well-known/jwks.json` | دریافت کلیدهای عمومی جهت نمایش/audit |\n| GET | `/v1/auth/hydra/.well-known/openid-configuration` | متادیتا |\n| GET | `/v1/auth/hydra/oauth2/sessions/logout` | خروج OIDC |\n\n> **نکته امنیتی:** Admin API هیدرا (port 4445) **فقط** در شبکه داخلی و صرفاً توسط `login-consent-app` فراخوانی می‌شود (NetworkPolicy) — پنل ادمین هرگز مستقیم به آن دسترسی ندارد.\n> **مجوز Admin:** ابطال توکن کاربران دیگر نیازمند `token.revoke:any` (در IAM ثبت شده، بخش ۵).\n\n---"
    },
    {
      "level": 2,
      "heading": "۵. iam-service — مدیریت دسترسی‌ها (RBAC/ABAC)",
      "content": "**مسیر پایه:** `/v1/iam`\n**نوع داده‌ها:** نقش‌ها (Role)، قابلیت‌ها (Capability)، مجوزها (Permission)، پالیسی‌ها، کاربران، محدودیت‌ها (Restriction)، اووررایدها، پلن‌ها، entitlementها، ورک‌اسپیس‌ها، لاگ حسابرسی\n**مناسب برای پنل ادمین:** این سرویس **قلب پنل ادمین** است — مدیریت نقش‌ها، انتصاب نقش به کاربر، تعلیق/فعال‌سازی کاربر، محدودیت‌ها، اووررایدها، پالیسی‌ها، و جستجوی دسترسی."
    },
    {
      "level": 3,
      "heading": "۵.۱ قابلیت‌های قابل اتصال به پنل (تفکیک شده)",
      "content": "**الف) کاربران و دسترسی**\n| قابلیت پنل | Endpoint |\n|---|---|\n| مشاهده کاربر | `GET /v1/iam/users/{id}` |\n| انتصاب نقش | `POST /v1/iam/users/{id}/roles` |\n| حذف نقش | `DELETE /v1/iam/users/{id}/roles/{roleKey}` |\n| تغییر وضعیت (فعال/تعلیق) | `PUT /v1/iam/users/{id}/status` |\n| تاریخچه وضعیت | `GET /v1/iam/users/{id}/status/history` |\n| افزودن محدودیت | `POST /v1/iam/users/{id}/restrictions` |\n| حذف محدودیت | `DELETE /v1/iam/users/{id}/restrictions/{key}` |\n| لیست محدودیت‌ها | `GET /v1/iam/users/{id}/restrictions` |\n| افزودن اوورراید | `POST /v1/iam/users/{id}/overrides` |\n| حذف اوورراید | `DELETE /v1/iam/users/{id}/overrides/{overrideId}` |\n| لیست اووررایدها | `GET /v1/iam/users/{id}/overrides` |\n| تنظیم پلن | `PUT /v1/iam/users/{id}/plan` |\n| لیست نقش‌های کاربر | `GET /v1/iam/users/{id}/roles` |\n| بررسی دسترسی | `POST /v1/iam/authorization/check` |\n| کانتکست دسترسی من | `GET /v1/iam/me/context` |\n| کانتکست دسترسی کاربر | `GET /v1/iam/users/{id}/context` |\n\n**ب) نقش‌ها (Roles)**\n| قابلیت پنل | Endpoint |\n|---|---|\n| لیست نقش‌ها | `GET /v1/iam/roles` |\n| جزئیات نقش | `GET /v1/iam/roles/{key}` |\n| ایجاد نقش | `POST /v1/iam/roles` |\n| ویرایش نقش | `PATCH /v1/iam/roles/{key}` |\n| حذف نقش | `DELETE /v1/iam/roles/{key}` |\n| افزودن قابلیت به نقش | `POST /v1/iam/roles/{key}/capabilities` |\n| حذف قابلیت | `DELETE /v1/iam/roles/{key}/capabilities/{capKey}` |\n| لیست قابلیت‌های نقش | `GET /v1/iam/roles/{key}/capabilities` |\n\n**ج) قابلیت‌ها (Capabilities) و مجوزها (Permissions)**\n| قابلیت پنل | Endpoint |\n|---|---|\n| لیست قابلیت‌ها | `GET /v1/iam/capabilities` |\n| جزئیات قابلیت | `GET /v1/iam/capabilities/{key}` |\n| ایجاد قابلیت | `POST /v1/iam/capabilities` |\n| ویرایش قابلیت | `PATCH /v1/iam/capabilities/{key}` |\n| حذف قابلیت | `DELETE /v1/iam/capabilities/{key}` |\n| افزودن مجوز به قابلیت | `POST /v1/iam/capabilities/{key}/permissions` |\n| حذف مجوز | `DELETE /v1/iam/capabilities/{key}/permissions/{permKey}` |\n| لیست مجوزهای قابلیت | `GET /v1/iam/capabilities/{key}/permissions` |\n| لیست مجوزها | `GET /v1/iam/permissions` |\n| جزئیات مجوز | `GET /v1/iam/permissions/{key}` |\n| ایجاد مجوز | `POST /v1/iam/permissions` |\n| ویرایش مجوز | `PATCH /v1/iam/permissions/{key}` |\n| حذف مجوز | `DELETE /v1/iam/permissions/{key}` |\n\n**د) پالیسی‌ها (Policies)، محدودیت‌ها، اووررایدها، پلن‌ها**\n| قابلیت پنل | Endpoint |\n|---|---|\n| لیست پالیسی‌ها | `GET /v1/iam/policies` |\n| جزئیات پالیسی | `GET /v1/iam/policies/{id}` |\n| ایجاد پالیسی | `POST /v1/iam/policies` |\n| ویرایش پالیسی | `PATCH /v1/iam/policies/{id}` |\n| حذف پالیسی | `DELETE /v1/iam/policies/{id}` |\n| اجرای پالیسی (تست) | `POST /v1/iam/policies/{id}/execute` |\n| لیست محدودیت‌ها | `GET /v1/iam/restrictions` |\n| جزئیات محدودیت | `GET /v1/iam/restrictions/{key}` |\n| ایجاد محدودیت | `POST /v1/iam/restrictions` |\n| ویرایش محدودیت | `PATCH /v1/iam/restrictions/{key}` |\n| حذف محدودیت | `DELETE /v1/iam/restrictions/{key}` |\n| لیست اووررایدها | `GET /v1/iam/overrides` |\n| لیست پلن‌ها | `GET /v1/iam/plans` |\n| جزئیات پلن | `GET /v1/iam/plans/{key}` |\n| ایجاد پلن | `POST /v1/iam/plans` |\n| ویرایش پلن | `PATCH /v1/iam/plans/{key}` |\n| حذف پلن | `DELETE /v1/iam/plans/{key}` |\n| لیست entitlementها | `GET /v1/iam/entitlements` |\n| جزئیات entitlement | `GET /v1/iam/entitlements/{key}` |\n| ویرایش entitlement | `PATCH /v1/iam/entitlements/{key}` |\n| حذف entitlement | `DELETE /v1/iam/entitlements/{key}` |\n| تنظیم entitlement پلن | `POST /v1/iam/entitlements/plan` |\n| حذف entitlement پلن | `DELETE /v1/iam/entitlements/plan/{planKey}/{entKey}` |\n\n**ه) ورک‌اسپیس‌ها و حسابرسی**\n| قابلیت پنل | Endpoint |\n|---|---|\n| لیست ورک‌اسپیس‌ها | `GET /v1/iam/workspaces` |\n| جزئیات ورک‌اسپیس | `GET /v1/iam/workspaces/{key}` |\n| ایجاد ورک‌اسپیس | `POST /v1/iam/workspaces` |\n| ویرایش ورک‌اسپیس | `PATCH /v1/iam/workspaces/{key}` |\n| حذف ورک‌اسپیس | `DELETE /v1/iam/workspaces/{key}` |\n| جستجوی لاگ حسابرسی | `GET /v1/iam/audit` |"
    },
    {
      "level": 3,
      "heading": "۵.۲ نمونه‌های پاسخ کلیدی",
      "content": "- **بررسی دسترسی:** `POST /v1/iam/authorization/check` با بدنه `{subject, permission, resource}` → نتیجه allow/deny\n- **تغییر وضعیت کاربر:** `PUT /v1/iam/users/{id}/status` با بدنه `{status: \"SUSPENDED\"|\"ACTIVE\"}`\n- **لاگ حسابرسی:** `GET /v1/iam/audit?actor=&action=&from=&to=` → لیست رخدادهای دسترسی\n\n---"
    },
    {
      "level": 2,
      "heading": "۶. نقشه راه پیشنهادی برای پنل ادمین",
      "content": "| اولویت | سرویس | ماژول پنل |\n|---|---|---|\n| ۱ (ضروری) | iam-service | مدیریت نقش‌ها، کاربران، وضعیت، حسابرسی |\n| ۲ | user-service | نمایش/ویرایش پروفایل، یوزرنام، آواتار |\n| ۳ | pool-service | مدیریت مواد یوزرنام، رزروها، آواتارها، ارزها |\n| ۴ | auth-service | نظارت نشست، خروج اجباری، خطاها |\n| ۵ | token-service | ابطال توکن ادمین، مشاهده JWKS (پس از استقرار Hydra) |\n\n---"
    },
    {
      "level": 2,
      "heading": "۷. منابع و مراجع",
      "content": "- OpenAPI (تولید شده): `services/user-service/docs/openapi.yaml`, `services/pool-service/docs/openapi.yaml`\n- Blueprintها: `services/{service}/blueprint.md`\n- README سرویس‌ها: `services/{service}/README.md`\n- مستندات تیم: `dotdive/docs/team/backend/services/`\n- ADRها: `dotdive/docs/team/backend/ADR/` (ADR-Backend-006 برای token-service، ADR-Backend-007 برای pool-service)\n- رویدادهای سیستم: `nons-api/catalog/events/`"
    }
  ]
}