{
  "title": "استاندارد قرارداد مجوز",
  "slug": "team/platform/standards/permission-contract-standard",
  "url": "/docs/team/platform/standards/permission-contract-standard",
  "frontmatter": {
    "layout": "doc",
    "title": "استاندارد قرارداد مجوز",
    "description": "نحوه تعریف، ثبت و استفاده از Permission Contractها در سرویس‌های پلتفرم NONS",
    "version": "1.0.0",
    "status": "APPROVED",
    "author": "Backend Team",
    "owner": "Backend Team",
    "created_at": "2026-06-22",
    "updated_at": "2026-06-22",
    "tags": "",
    "reviewers": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "استاندارد قرارداد مجوز",
      "content": "**Permission Contract Standard**\n\n> این سند نحوه تعریف، ثبت و مصرف Permission Contractها توسط سرویس‌های کسب‌وکاری را مشخص می‌کند. هر سرویس مسئول تعریف Permissions و Business Rules خود است و IAM صرفاً این قراردادها را نگهداری و برای Authorization استفاده می‌کند.\n\n---"
    },
    {
      "level": 2,
      "heading": "۱. اصل بنیادین",
      "content": "**هر سرویس مالک Permissions خود است. IAM نگهبان قراردادهاست.**\n\n```\nسرویس تعریف می‌کند:  چه Permissionsی نیاز دارد\nIAM ثبت می‌کند:     قرارداد در دیتابیس\nسرویس بررسی می‌کند: از طریق POST /v1/iam/authorization/check\nIAM پاسخ می‌دهد:    allowed / denied\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "۲. چرخه عمر Permission Contract",
      "content": "| مرحله | توضیح | مسئول |\n|-------|-------|-------|\n| **۱. تعریف** | سرویس Permissions مورد نیاز خود را مشخص می‌کند | سرویس کسب‌وکاری |\n| **۲. ثبت** | Permissions از طریق API IAM ثبت می‌شوند | توسعه‌دهنده / CD |\n| **۳. نگهداری** | IAM قراردادها را ذخیره و در Context محاسبه می‌کند | IAM |\n| **۴. مصرف** | سرویس در زمان اجرا مجوز را از IAM بررسی می‌کند | سرویس کسب‌وکاری |\n| **۵. تغییر** | تغییر Permission = Breaking Change، نیاز به انتشار نسخه جدید | سرویس کسب‌وکاری |"
    },
    {
      "level": 3,
      "heading": "قانون ثبت",
      "content": "Permissions **باید** قبل از اینکه یک سرویس به تولید برود در IAM ثبت شده باشند. روش‌های ثبت:\n\n| روش | توضیح | زمان |\n|-----|-------|------|\n| **API دستی** | POST /v1/iam/permissions در زمان راه‌اندازی | توسعه |\n| **اسکریپت Seed** | فایل seed در مخزن سرویس | CI/CD |\n| **مقادیر پیش‌فرض** | توسط ادمین در پنل مدیریت | runtime |\n\n---"
    },
    {
      "level": 2,
      "heading": "۳. فرمت کلید Permission",
      "content": ""
    },
    {
      "level": 3,
      "heading": "قاعده نام‌گذاری",
      "content": "```\n{resource}.{action}\n```\n\n| بخش | قاعده | مثال |\n|-----|-------|------|\n| `resource` | kebab-case، مفرد | `product`، `order`، `wallet` |\n| `action` | kebab-case، فعل ساده | `create`، `edit`، `delete`، `view` |"
    },
    {
      "level": 3,
      "heading": "نمونه‌های مجاز",
      "content": "| سرویس | Permission | توضیح |\n|-------|-----------|-------|\n| marketplace-service | `products.create` | ایجاد محصول جدید |\n| marketplace-service | `products.update` | ویرایش محصول |\n| marketplace-service | `products.delete` | حذف محصول |\n| marketplace-service | `products.publish` | انتشار محصول |\n| order-service | `orders.create` | ایجاد سفارش |\n| order-service | `orders.cancel` | لغو سفارش |\n| wallet-service | `wallets.read` | مشاهده کیف پول |\n| wallet-service | `wallets.withdraw` | برداشت از کیف پول |\n| iam-service | `admin.access` | دسترسی به پنل مدیریت |\n| iam-service | `settings.read` | مشاهده تنظیمات سیستم |\n\n> نکته: کلیدهای مجوز در namespaceهای جمع تعریف می‌شوند (مثلاً `products.*`، `orders.*`) هرچند نام پوشهٔ سرویس ممکن است مفرد باشد (`order-service`). این تفاوت عمدی است."
    },
    {
      "level": 3,
      "heading": "کلیدهای ممنوع",
      "content": "| الگوی ممنوع | دلیل |\n|-------------|------|\n| `user.*` | متعلق به IAM نیست — User Service پروفایل را مدیریت می‌کند |\n| `admin.*` | `admin.access` کافی است — بقیه بر اساس resource تعریف می‌شوند |\n| `*.*` | وایلدکارد ممنوع — هر Permission باید صریح باشد |\n\n---"
    },
    {
      "level": 2,
      "heading": "۴. فرمت کلید Entitlement",
      "content": "```\n{owner}.{resource}.{metric}\n```\n\n| بخش | قاعده | مثال |\n|-----|-------|------|\n| `owner` | مفرد، kebab-case | `seller`، `buyer` |\n| `resource` | مفرد، kebab-case | `product`، `withdraw` |\n| `metric` | kebab-case | `limit`، `count`، `enabled` |"
    },
    {
      "level": 3,
      "heading": "نمونه‌ها",
      "content": "| کلید | type | مفهوم |\n|------|------|-------|\n| `seller.product.limit` | NUMBER | حداکثر تعداد محصول مجاز |\n| `seller.boost.count` | NUMBER | تعداد بوست مجاز در ماه |\n| `buyer.order.limit` | NUMBER | حداکثر سفارش همزمان |\n| `daily.withdraw.limit` | NUMBER | سقف برداشت روزانه |\n| `feature.analytics` | BOOLEAN | دسترسی به داشبورد تحلیلی |\n| `feature.auto_boost` | BOOLEAN | دسترسی به بوست خودکار |\n\n---"
    },
    {
      "level": 2,
      "heading": "۵. Business Rule Ownership",
      "content": ""
    },
    {
      "level": 3,
      "heading": "قاعده",
      "content": "هر سرویس کسب‌وکاری مالک Business Rules خود است. Policy و Business Rule توسط IAM ساخته نمی‌شوند."
    },
    {
      "level": 3,
      "heading": "مدل",
      "content": "```\nسرویس:\n  - تعریف می‌کند: Entitlement key + مقدار پیش‌فرض\n  - ثبت می‌کند: در IAM از طریق API\n  - بررسی می‌کند: از IAM می‌پرسد کاربر چه Entitlementی دارد\n  - تصمیم می‌گیرد: خودش اعمال محدودیت می‌کند\n\nمثال:\n  IAM ذخیره می‌کند:  seller.product.limit = 10 (برای نقش SELLER)\n  Marketplace:       current_products_count = 8\n  تصمیم:             8 < 10 → مجاز است (تصمیم با Marketplace است)\n```"
    },
    {
      "level": 3,
      "heading": "قانون اجرا",
      "content": "| مؤلفه | محل اجرا |\n|-------|---------|\n| Permission check (allowed/denied) | IAM |\n| Entitlement values (limits, counts) | ارائه توسط IAM، اجرا توسط سرویس |\n| Business Logic (شرط‌های پیچیده) | سرویس کسب‌وکاری |\n\n---"
    },
    {
      "level": 2,
      "heading": "۶. Permission Registration Checklist",
      "content": "هر سرویس پیش از راه‌اندازی باید چک‌لیست زیر را تکمیل کند:\n\n- [ ] تمام Permissions مورد نیاز در IAM ثبت شده‌اند\n- [ ] تمام Entitlements با مقادیر پیش‌فرض تعریف شده‌اند\n- [ ] Business Rules سرویس در مستندات سرویس ثبت شده‌اند\n- [ ] رویدادهای IAM مصرف‌شده در سرویس مستند شده‌اند\n- [ ] Authorization Context در endpointهای敏感 بررسی می‌شود\n\n---"
    },
    {
      "level": 2,
      "heading": "۷. منابع بیشتر",
      "content": "- [Blueprint سرویس IAM](../../backend/services/iam-service.md)\n- [استاندارد امنیت](security-policy.md)\n- [استاندارد نام‌گذاری رویدادها (ADR-EVENT-001)](../ADR/ADR-EVENT-001.md)\n- [معماری پلتفرم](../Architecture.md)"
    }
  ]
}