{
  "title": "راهنمای مدیریت قراردادها با CLI (nons)",
  "slug": "team/platform/package/nons-ContractManagement-guide",
  "url": "/docs/team/platform/package/nons-ContractManagement-guide",
  "frontmatter": {
    "layout": "doc",
    "title": "راهنمای مدیریت قراردادها با CLI (nons)",
    "description": "راهنمای معماری، جریان مدیریت قرارداد و تولید مصنوعات توسط ابزار رسمی پلتفرم NONS",
    "version": "2.0.0",
    "status": "APPROVED",
    "author": "Platform Team",
    "owner": "Platform Team",
    "created_at": "2026-07-03",
    "updated_at": "2026-07-03",
    "tags": "",
    "reviewers": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "راهنمای مدیریت قراردادها با CLI (nons)",
      "content": "**NONS Contract Management Guide**\n\n> ابزار رسمی و مستقل پلتفرم NONS برای مدیریت قراردادها، رجیستری، باندل‌ها و تولید مصنوعات پروژه.\n\n---"
    },
    {
      "level": 2,
      "heading": "۱. نمای کلی",
      "content": "`nons` (مخفف NONS CLI) یک **ابزار مدیریت قرارداد (Contract Management Tool)** است — نه یک پکیج TypeScript و نه یک کتابخانه زمان اجرا.\n\nمسئولیت `nons` مدیریت چرخه حیات قراردادهای API است:\n\n```\nBackend Service\n    │\n    └── openapi.yaml (قرارداد فنی سرویس)\n          │\n          ▼ [nons]\n    Service Manifest (رجیستری محلی)\n          │\n          ▼ [nons]\n    مصنوعات پروژه (Types, API Client, Hooks)\n          │\n          ▼\n    پروژه مصرف‌کننده (React, Vue, Flutter, ...)\n```"
    },
    {
      "level": 3,
      "heading": "ویژگی‌های معماری",
      "content": "| ویژگی | توضیح |\n|--------|--------|\n| **مستقل** | یک فایل اجرایی واحد — بدون وابستگی به Node.js، Python یا هر runtime دیگر |\n| **چندسکویی** | پشتیبانی از Windows, macOS, Linux |\n| **زبان‌آگنوستیک** | مستقل از زبان برنامه‌نویسی پروژه مصرف‌کننده |\n| **Contract Management** | مدیریت قراردادها، رجیستری، باندل‌ها — نه Business Logic |\n| **خروجی پروژه‌محور** | مصنوعات متناسب با فریم‌ورک هدف تولید می‌شوند |\n\n---"
    },
    {
      "level": 2,
      "heading": "۲. Contract Management — چرخه مدیریت قرارداد",
      "content": "`nons` قراردادهای فنی سرویس‌ها (OpenAPI) را دریافت، پردازش و به فرمت مناسب پروژه مصرف‌کننده تبدیل می‌کند."
    },
    {
      "level": 3,
      "heading": "۲.۱ دریافت قرارداد (Contract Acquisition)",
      "content": "`nons` OpenAPI سرویس را دریافت می‌کند و یک **Service Manifest** از آن می‌سازد:\n\n```\nnons registry build user --source services/user-service/docs/openapi.yaml\n```\n\nService Manifest یک JSON غنی شامل:\n- **Operations:** متد HTTP، مسیر، Schema درخواست/پاسخ\n- **Metadata:** احراز هویت، timeout، retry، cache\n- **Types:** تعاریف داده‌ای هر Operation\n- **Security:** طرح‌های امنیتی"
    },
    {
      "level": 3,
      "heading": "۲.۲ رجیستری محلی (Local Registry)",
      "content": "Service Manifestها در دایرکتوری `.nons/registry/{service}/` ذخیره می‌شوند. هر پروژه فقط Registryهای مورد نیاز خود را نگهداری می‌کند.\n\n```\n.nons/\n└── registry/\n    ├── user/\n    │   └── manifest.json\n    └── auth/\n        └── manifest.json\n```"
    },
    {
      "level": 3,
      "heading": "۲.۳ باندل (Bundle)",
      "content": "Bundle یک **Feature** است، نه یک Service. یک Bundle می‌تواند شامل Operationهایی از چند سرویس مختلف باشد.\n\n```\nOnboard Bundle:\n  ├── auth.login\n  ├── auth.register\n  ├── profile.create\n  └── avatar.upload\n```\n\nBundleها در `.nons/bundles/` ذخیره می‌شوند."
    },
    {
      "level": 3,
      "heading": "۲.۴ تولید مصنوعات (Artifact Generation)",
      "content": "`nons` بر اساس Service Manifestها و فریم‌ورک هدف پروژه، مصنوعات مصرفی را تولید می‌کند:\n\n```\nnons generate\n```\n\nخروجی بر اساس فریم‌ورک پروژه:\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|  ... | سایر فریم‌ورک‌ها |\n\n**خروجی همیشه پروژه‌محور است — نه یک محصول عمومی.**\nمصنوعات تولیدشده در `.nons/generated/` قرار می‌گیرند:\n\n```\n.nons/generated/\n├── types/\n│   └── user.ts           (یا .dart, .swift, ...)\n├── api-client/\n│   └── user.ts\n└── hooks/\n    └── useUsers.ts       (یا composables/, services/, ...)\n```"
    },
    {
      "level": 3,
      "heading": "۲.۵ اعتبارسنجی (Validation)",
      "content": "`nons` قراردادها، رجیستری‌ها و سلامت اندپوینت‌ها را اعتبارسنجی می‌کند:\n\n```\nnons validate\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "۳. مرزهای مسئولیت",
      "content": ""
    },
    {
      "level": 3,
      "heading": "`nons` مسئول است",
      "content": "- دریافت و اعتبارسنجی قراردادهای OpenAPI\n- ساخت و مدیریت Service Manifestها (Registry)\n- نصب فقط Registryهای مورد نیاز پروژه\n- مدیریت Bundleها (Feature-based grouping)\n- تولید فایل‌های مصرفی متناسب با تکنولوژی پروژه\n- اعتبارسنجی قراردادها و سلامت اندپوینت‌ها\n- بروزرسانی Registryها"
    },
    {
      "level": 3,
      "heading": "`nons` مسئول نیست",
      "content": "- نوشتن Business Logic\n- مدیریت state فرانت‌اند\n- اجرای درخواست‌های API در زمان اجرا\n- جایگزینی برای ابزارهای بیلد (Vite, Webpack, ...)\n- تعیین نحوه نمایش داده‌ها در UI\n\n---"
    },
    {
      "level": 2,
      "heading": "۴. جریان یکپارچه",
      "content": ""
    },
    {
      "level": 3,
      "heading": "۴.۱ نصب",
      "content": "```bash\ncurl -fsSL https://nons.dev/cli/install.sh | sh\n```\n\n`nons` به صورت یک باینری مستقل توزیع می‌شود — بدون نیاز به Node.js، npm یا هر runtime دیگری."
    },
    {
      "level": 3,
      "heading": "۴.۲ مقداردهی اولیه پروژه",
      "content": "```bash\nnons init\n```"
    },
    {
      "level": 3,
      "heading": "۴.۳ افزودن سرویس به پروژه",
      "content": "```bash\nnons registry build user --source path/to/openapi.yaml\n```"
    },
    {
      "level": 3,
      "heading": "۴.۴ تولید مصنوعات",
      "content": "```bash\nnons generate\n```"
    },
    {
      "level": 3,
      "heading": "۴.۵ بروزرسانی پس از تغییر بک‌اند",
      "content": "```bash\nnons registry build user --update\nnons generate\n```\n\nپروژه مصرف‌کننده نیازی به تغییر کد ندارد.\n\n---"
    },
    {
      "level": 2,
      "heading": "۵. ساختار دایرکتوری `.nons/`",
      "content": "```\nproject/\n└── .nons/\n    ├── config.yaml             # تنظیمات پروژه (فریم‌ورک، مسیرها)\n    │\n    ├── registry/               # ← Service Manifestها\n    │   ├── user/\n    │   │   └── manifest.json\n    │   └── auth/\n    │       └── manifest.json\n    │\n    ├── bundles/                # ← Bundleها\n    │   └── onboard/\n    │       └── bundle.json\n    │\n    └── generated/              # ← مصنوعات تولیدشده\n        ├── types/\n        ├── api-client/\n        └── hooks/\n```\n\n**قوانین:**\n1. هیچ فایلی در `.nons/` دستی ویرایش نمی‌شود — به جز `config.yaml`\n2. `registry/` فقط توسط `nons` مدیریت می‌شود\n3. `bundles/` فقط توسط `nons` مدیریت می‌شود\n4. `generated/` فقط توسط `nons generate` تولید می‌شود\n5. `.nons/` در git commit می‌شود\n\n---"
    },
    {
      "level": 2,
      "heading": "مستندات مرتبط",
      "content": "| سند | توضیح |\n|-----|--------|\n| [ADR-Platform-004](../ADR/ADR-Platform-004) | تصمیمات معماری CLI و Registry |\n| [راهنمای CLI (CLI Reference)](./cli-reference) | دستورات و مسئولیت‌های `nons` |\n| [OpenAPI Guidelines](../api/openapi-guidelines) | استاندارد تولید OpenAPI |\n| [API Design Guidelines](../api/api-design-guidelines) | استاندارد طراحی API |\n| [Repository Structure](../standards/repository-structure) | مسیر فایل‌ها در سرویس |"
    }
  ]
}