{
  "title": "تصمیم معماری الگوی رجیستری (Registry Pattern Decision)",
  "slug": "team/frontend/architecture/registry-pattern",
  "url": "/docs/team/frontend/architecture/registry-pattern",
  "frontmatter": {
    "layout": "doc",
    "title": "الگوی رجیستری (Registry Pattern)",
    "description": "تصمیم رسمی معماری و استانداردهای پیاده‌سازی الگوی رجیستری (Registry) در فرانت‌اند",
    "version": "1.1.0",
    "status": "PRIVATE",
    "author": "Antigravity",
    "owner": "xoxxel",
    "created_at": "2026-06-30",
    "updated_at": "2026-06-30",
    "tags": "",
    "reviewers": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "تصمیم معماری الگوی رجیستری (Registry Pattern Decision)",
      "content": "الگوی رجیستری به عنوان لایه میانی اتصال‌دهنده برنامه‌/صفحات فرانت‌اند (`Pages` / `Templates`) به API Client تولیدشده عمل می‌کند. ثبت این تصمیم با هدف خروج وابستگی‌های فنی وب‌سرویس از بدنه لایه‌های نمایش و کامپوننت‌های پنل صورت گرفته است.\n\n---"
    },
    {
      "level": 2,
      "heading": "دلیل اتخاذ تصمیم (Context)",
      "content": "در توسعه رابط‌های کاربری چندگانه، صفحات نباید مستقیماً API Client را فراخوانی کنند. ایجاد لایه واسط به ما اجازه می‌دهد:\n1. **استقلال لایه رندرینگ:** فریم‌ورک‌های بصری مجزا (مانند React و Vue) بدون وابستگی مستقیم به API Client، صرفاً رجیستری را صدا می‌زنند.\n2. **شبیه‌سازی آسان داده‌ها (Mocking):** با جداسازی متدها، می‌توان به سادگی داده‌های فیک را جهت تست‌های بصری یا دمو بدون فعال بودن وب‌سرویس‌ها به صفحات تزریق کرد.\n\n---"
    },
    {
      "level": 2,
      "heading": "الگوی جریان ارتباطی (Conceptual Flow)",
      "content": "جریان ارتباطی داده‌ها و متدها از لایه نمایش تا API سرور به صورت زیر است:\n\n```mermaid\ngraph LR\n    Page[Page / Template] --> Registry[Registry]\n    Registry --> APIClient[API Client]\n    APIClient --> API[API / Backend]\n    \n    style Registry fill:#f9f,stroke:#333,stroke-width:2px\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "قوانین و محدودیت‌های توسعه (Strict Rules)",
      "content": "1. **ممنوعیت مصرف مستقیم API Client:** هیچ صفحه یا قالبی (`Page` / `Template`) مجاز به فراخوانی یا ایمپورت مستقیم کلاس‌ها یا نمونه‌های API Client نیست. تمام فراخوانی‌ها باید از کانال واسط رجیستری عبور کنند.\n2. **پوشش‌دهی از رجیستری محلی:** ساختار متدهای API Client از Service Manifestها (تولیدشده توسط `nons registry build`) تأمین می‌شود. لایه رجیستری (Registry) این متدها را در زمان اجرا مصرف می‌کند.\n3. **عدم ارتباط مستقیم با وب‌سرویس در لایه نمایش:** صفحات کلاینت نباید نگران کوکی‌ها، هدرها، پروتکل‌های شبکه یا خطاهای خام HTTP باشند. لایه رجیستری خطاها را قالب‌بندی کرده و خروجی تمیز را تحویل صفحه می‌دهد.\n\n---"
    },
    {
      "level": 2,
      "heading": "نمونه پیاده‌سازی ساختاری (TypeScript Structure Example)",
      "content": ""
    },
    {
      "level": 3,
      "heading": "تعریف ساختار میانی رجیستری (`src/registry/users.registry.ts`)",
      "content": "لایه رجیستری از مصنوعات تولیدشده توسط `nons generate` استفاده می‌کند. متدهای API Client از روی Service Manifestها به صورت خودکار تولید شده‌اند:\n\n```typescript\n// کد تولیدشده توسط CLI — مسیر: .nons/generated/api-client/\n// این کدها توسط nons generate بازتولید می‌شوند — ویرایش دستی ممنوع\n// بدون وابستگی NPM — کاملاً تایپ‌پذیر\nimport { userClient } from '../../.nons/generated/api-client/user';\n\nexport const usersRegistry = {\n  /**\n   * دریافت لیست کاربران\n   */\n  async list() {\n    try {\n      // استفاده از متد تولیدشده API Client\n      const users = await userClient.list();\n      return users;\n    } catch (error) {\n      console.error('Registry Error (Users List):', error);\n      throw error;\n    }\n  },\n\n  /**\n   * ایجاد کاربر جدید\n   */\n  async create(data: { name: string; email: string }) {\n    const cleanData = {\n      ...data,\n      email: data.email.toLowerCase().trim()\n    };\n    return userClient.create(cleanData);\n  }\n};\n```"
    }
  ]
}