{
  "title": "تصمیم معماری: Platform CLI، مدیریت رجیستری و استراتژی تولید مصنوعات کلاینت",
  "slug": "team/platform/ADR/ADR-Platform-004",
  "url": "/docs/team/platform/ADR/ADR-Platform-004",
  "frontmatter": {
    "layout": "doc",
    "title": "'ADR-Platform-004: Platform CLI، Registry و استراتژی تولید مصنوعات کلاینت'",
    "description": "Architectural Decision Record defining the platform CLI, service registry, client artifact generation strategy, and validation pipeline.",
    "version": "2.2.0",
    "status": "APPROVED",
    "author": "Platform Team",
    "owner": "Platform Team",
    "created_at": "2026-07-01",
    "updated_at": "2026-07-04",
    "tags": "",
    "reviewers": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "تصمیم معماری: Platform CLI، مدیریت رجیستری و استراتژی تولید مصنوعات کلاینت",
      "content": "**Architectural Decision Record — Platform CLI, Registry and Client Artifact Generation Strategy**\n\n> **ADR-Platform-004 — Approved (Rev. 2.1)**\n\n---"
    },
    {
      "level": 2,
      "heading": "وضعیت (Status)",
      "content": "APPROVED (تایید شده)\n\n---"
    },
    {
      "level": 2,
      "heading": "تاریخ (Date)",
      "content": "2026-07-01 (آخرین به‌روزرسانی: 2026-07-03)\n\n---"
    },
    {
      "level": 2,
      "heading": "زمینه (Context)",
      "content": "در توسعه معماری میکروسرویس‌های پلتفرم NONS، ارتباط میان پروژه‌های کلاینت (Client Applications شامل فرانت‌اند، ابزارهای خط فرمان، برنامه‌های دسکتاپ و ابزارهای Builder) و سرویس‌های بک‌اند نیازمند یک ابزار رسمی، مستقل و زبان‌آگنوستیک است.\n\n**تصمیم:** پلتفرم NONS یک **Platform CLI** به نام `nons` به عنوان ابزار رسمی توسعه‌دهنده ارائه می‌دهد. CLI مسئول مدیریت قراردادها، رجیستری، باندل‌ها و تولید مصنوعات پروژه‌محور می‌باشد.\n\n---"
    },
    {
      "level": 2,
      "heading": "تصمیمات مصوب (Decisions)",
      "content": ""
    },
    {
      "level": 3,
      "heading": "۱. جایگاه رجیستری (Service Registry Ownership)",
      "content": "Service Registry به عنوان بخشی از لایه یکپارچه‌سازی کلاینت (Client Integration Layer) تعریف می‌شود و به هیچ عنوان نباید درون کدهای اصلی بک‌اند نگهداری شود. بک‌اند صرفاً وظیفه دارد OpenAPI خود را منتشر کند.\n\nجریان رسمی:\n\n```\nService (سرویس بک‌اند)\n   │\n   └── openapi.yaml (قرارداد فنی)\n         │\n         ▼\n   Platform CLI (nons)\n         │\n         ▼\n   .nons/registry/{service}/manifest.json (دایرکتوری محلی پروژه کلاینت)\n```\n\n*   **بک‌اند فقط می‌گوید:** \"من چه APIهایی دارم (قرارداد فنی).\"\n*   **بک‌اند هرگز نمی‌گوید:** \"فرانت‌اند چطور داده‌ها را نمایش دهد (UI decisions).\"\n\n---"
    },
    {
      "level": 3,
      "heading": "۲. ابزار خط فرمان پلتفرم (Platform CLI)",
      "content": "**`nons`** تنها ابزار رسمی توسعه‌دهنده برای تعامل با سرویس‌های پلتفرم است."
    },
    {
      "level": 4,
      "heading": "ویژگی‌های معماری CLI",
      "content": "| ویژگی | توضیح |\n|--------|--------|\n| **مستقل (Standalone)** | یک فایل اجرایی واحد — بدون وابستگی به Node.js، Python یا هر runtime دیگر |\n| **چندسکویی (Cross-platform)** | پشتیبانی از Windows, macOS, Linux |\n| **زبان‌آگنوستیک** | مستقل از زبان برنامه‌نویسی پروژه مصرف‌کننده |\n| **تک‌فایل (Single Binary)** | توزیع به صورت یک باینری قابل اجرا |\n\nCLI یک **ابزار مدیریت قرارداد (Contract Management Tool)** است، نه یک پکیج TypeScript. CLI:\n- قراردادهای OpenAPI سرویس‌ها را دریافت و اعتبارسنجی می‌کند\n- Registryهای محلی از Endpointها و Operationها می‌سازد\n- Bundleهای پروژه‌محور را مدیریت می‌کند\n- فایل‌های مصرفی را متناسب با تکنولوژی پروژه هدف تولید می‌کند\n\nTypeScript تنها یکی از **خروجی‌های ممکن** CLI است — خود CLI به هیچ زبان یا فریم‌ورکی وابسته نیست.\n\nزبان پیاده‌سازی CLI در این سند مشخص نمی‌شود و به ADR جداگانه واگذار می‌گردد."
    },
    {
      "level": 4,
      "heading": "حوزه‌های مسئولیتی (مسئولیت‌ها فعلاً به صورت حوزه مشخص می‌شوند — دستورات دقیق در فاز پیاده‌سازی تعیین می‌گردند)",
      "content": "| دستور | مسئولیت |\n|-------|---------|\n| `nons init` | مقداردهی اولیه پروژه کلاینت و ساخت دایرکتوری `.nons/` |\n| `nons registry build <service>` | ساخت Service Manifest از OpenAPI سرویس |\n| `nons registry list` | فهرست رجیستری‌های محلی |\n| `nons bundle create` | ساخت باندل از مجموعه‌ای از سرویس‌ها |\n| `nons generate` | تولید مصنوعات پروژه (Types, API Client, Hooks) متناسب با فریم‌ورک هدف |\n| `nons validate` | اعتبارسنجی قراردادها، رجیستری‌ها و باندل‌ها |\n| `nons interactive` / `nons ui` | حالت تعاملی (TUI) |\n\n---"
    },
    {
      "level": 3,
      "heading": "۳. مدیریت تغییر اندپوینت‌ها (Endpoint Change)",
      "content": "در صورتی که مسیر یک اندپوینت در بک‌اند تغییر کند:\n\n*   **قبل:** `/v1/auth/login`\n*   **بعد:** `/v2/auth/login`\n\n**پروژه کلاینت به هیچ عنوان تغییر کدی نخواهد داشت.** مراحل اعمال تغییر:\n\n1. بروزرسانی رجیستری محلی: `nons registry build auth --update`\n2. بازتولید مصنوعات: `nons generate`\n\n---"
    },
    {
      "level": 3,
      "heading": "۴. مصنوعات تولیدشده (Generated Artifacts)",
      "content": "CLI بر اساس Service Manifest و فریم‌ورک هدف پروژه، مصنوعات زیر را تولید می‌کند:\n\n| فریم‌ورک هدف | مصنوعات تولیدشده |\n|-------------|-------------------|\n| React / Next.js | Custom Hooks, Types, API Client Functions |\n| Vue / Nuxt | Composables, Types, API Client Functions |\n| Flutter | Dart Classes, API Service |\n| React Native | Custom Hooks, Types |\n| Angular | Services, Types, HTTP Interceptors |\n| Swift | Swift Models, API Client |\n| Kotlin | Data Classes, Retrofit Service |\n\n**خروجی همیشه پروژه‌محور است — نه یک محصول عمومی و از پیش‌ساخته.**\nCLI کدها را متناسب با ساختار و فریم‌ورک پروژه مصرف‌کننده تولید می‌کند.\n\n---"
    },
    {
      "level": 3,
      "heading": "۵. زنجیره اعتبارسنجی قرارداد (Contract Validation Pipeline)",
      "content": "```\nOpenAPI Source (تولیدشده توسط سرویس)\n      │\n      ▼\nOpenAPI Lint (اعتبارسنجی ساختار)\n      │\n      ▼\nSchema Validation (بررسی هماهنگی با طرح‌های داده)\n      │\n      ▼\nBreaking Change Detection (شناسایی تغییرات مخرب)\n      │\n      ▼\nContract Test (تست‌های قرارداد)\n      │\n      ▼\nPublish (انتشار به Registry)\n```\n\n> مرحله تولید کدهای مصرف‌کننده از این Pipeline حذف شده است — CLI مسئول تولید مصنوعات است. جزئیات کامل در [OpenAPI Guidelines](../api/openapi-guidelines).\n\n> [!IMPORTANT]\n> هرگونه حذف فیلد، تغییر نام فیلدهای اجباری، یا تغییر در کدهای وضعیت HTTP بدون ارتقای نسخه API، به عنوان تغییر مخرب شناسایی شده و فرآیند بیلد متوقف خواهد شد.\n\n---"
    },
    {
      "level": 3,
      "heading": "۶. تفکیک مسئولیت‌های CLI",
      "content": ""
    },
    {
      "level": 4,
      "heading": "CLI مسئول است:",
      "content": "- مدیریت قراردادها (دریافت، اعتبارسنجی، همگام‌سازی)\n- مدیریت رجیستری (ساخت، نصب، به‌روزرسانی، حذف)\n- مدیریت باندل‌ها (ساخت، نصب، به‌روزرسانی، وابستگی‌ها)\n- تولید مصنوعات پروژه (Types, API Client, Hooks)\n- همگام‌سازی پروژه (رجیستری، باندل‌ها، مصنوعات)\n- اعتبارسنجی (قرارداد، رجیستری، باندل، سلامت اندپوینت)\n- تجربه تعاملی (پروژه جدید، انتخاب باندل، انتخاب سرویس)"
    },
    {
      "level": 4,
      "heading": "CLI مسئول نیست:",
      "content": "- منطق کسب‌وکار\n- مدیریت state فرانت‌اند\n- کدهای مختص فریم‌ورک (بیرون از مصنوعات تولیدشده)\n- اجرای درخواست‌های API در زمان اجرا\n\n---"
    },
    {
      "level": 3,
      "heading": "۷. استراتژی تولید مبتنی بر مدل (Model-Driven Artifact Generation)",
      "content": "CLI از استراتژی **Model-Driven Generation** پیروی می‌کند: ساختار مصنوعات به عنوان یک «مدل داده‌ای» (Service Manifest) تعریف شده و تولید کد برای هر فریم‌ورک به صورت خودکار توسط CLI انجام می‌شود.\n\n**لایه قرارداد (Source of Truth):**\n\n| لایه | منبع حقیقت | ابزار Generation | خروجی |\n|------|-----------|-------------------|-------|\n| Platform Contracts (Platform Types) | `nons-api/contracts/*.proto` | Buf (`buf generate`) | TypeScript bindings (برای CLI)، Go bindings (برای Core) |\n| Service APIs (HTTP endpoints) | کد منبع سرویس | OpenAPI Generator → CLI (`nons registry build`) | `.nons/registry/{service}/manifest.json` |\n| Client Artifacts | Service Manifest | CLI (`nons generate`) | کدهای پروژه‌محور (Hooks, Types, API Client) |\n\n---"
    },
    {
      "level": 2,
      "heading": "پیامدها (Consequences)",
      "content": ""
    },
    {
      "level": 3,
      "heading": "پیامدهای مثبت (Positive)",
      "content": "- **حذف وابستگی به زبان:** CLI مستقل از زبان پروژه مصرف‌کننده است\n- **انعطاف‌پذیری در خروجی:** پشتیبانی از فریم‌ورک‌های مختلف (React, Vue, Flutter, ...)\n- **کاهش هزینه نگهداری:** تغییر اندپوینت = `nons generate`\n- **تفکیک کامل وظایف:** بک‌اند و فرانت‌اند بدون تداخل با یکدیگر توسعه می‌کنند\n- **توسعه آفلاین:** Mock Server داخلی CLI (`nons mock`)"
    },
    {
      "level": 3,
      "heading": "پیامدهای منفی (Negative)",
      "content": "- **سربار مدیریت محلی:** نیاز به اجرای دوره‌ای `nons generate`\n- **هزینه پیاده‌سازی CLI:** ساخت CLI مستقل نیاز به توسعه اختصاصی دارد\n- **تغییر عادت تیم:** transition به ابزار جدید CLI نیاز به آموزش دارد\n\n---"
    },
    {
      "level": 2,
      "heading": "تکمیل و گسترش",
      "content": "تصمیمات معماری جنریتور (metadata strategy و template-per-framework) در **[ADR-Platform-005](./ADR-Platform-005)** رسمی شده‌اند.\n\nADR-005 به طور مستقیم بر این سند بنا شده و آن را گسترش می‌دهد — نه جایگزین آن."
    }
  ]
}