{
  "title": "لایه قراردادها و پکیج‌های اشتراکی",
  "slug": "team/platform/package/index",
  "url": "/docs/team/platform/package/index",
  "frontmatter": {},
  "sections": [
    {
      "level": 1,
      "heading": "لایه قراردادها و پکیج‌های اشتراکی",
      "content": "**Contracts & Shared Packages**\n\nاین بخش شامل دو لایه مجزا است: **قراردادهای پلتفرم (Proto)** و **پکیج‌های اشتراکی (TypeScript)**. برای توضیح دقیق این رویکرد، [معماری لایه قراردادها](./shared-packages-architecture) را ببینید.\n\n---"
    },
    {
      "level": 2,
      "heading": "ساختار",
      "content": "```text\nnons-api/contracts/        ← لایه قراردادهای پلتفرم (Proto — Source of Truth)\n├── envelope.proto\n├── registry.proto\n├── errors.proto\n└── permissions.proto\n\nnons-api/packages/         ← پکیج‌های اشتراکی\n├── contracts/    → @nons/contracts  (generated from Proto)\n├── events/       → @nons/events     (generated from Proto)\n└── logging/      → @nons/logging    (قرارداد ثبت وقایع — مستقل)\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "لایه‌ها",
      "content": ""
    },
    {
      "level": 3,
      "heading": "[قراردادهای پلتفرم (Contract Layer)](./shared-packages-architecture)",
      "content": "قراردادهای مشترک پلتفرم در قالب **Protocol Buffers** در `nons-api/contracts/` تعریف می‌شوند. Bindingهای TypeScript و Go از طریق Buf در CI تولید می‌شوند. هیچ زبانی مالک قراردادها نیست — Proto منبع حقیقت است."
    },
    {
      "level": 3,
      "heading": "[تایپ‌ها (Type Catalog)](./type_catalog)",
      "content": "مرجع واژگان رسمی دامنه و مدل‌های داده‌ای مشترک. تایپ‌های مورد نیاز فرانت‌اند توسط `nons generate` در `.nons/generated/types/` تولید می‌شوند. Domain Types در سرویس‌های مربوطه تعریف می‌شوند."
    },
    {
      "level": 3,
      "heading": "[قراردادها (Contracts)](./contract_catalog)",
      "content": "مرجع رسمی قراردادهای پلتفرم (Proto) و قراردادهای دامنه‌ای (در سرویس‌ها). Platform Contracts در `nons-api/contracts/` با Proto تعریف می‌شوند. Domain Contracts در هر سرویس نگهداری می‌شوند."
    },
    {
      "level": 3,
      "heading": "[کاتالوگ رویدادها (Event Catalog)](./event-catalog)",
      "content": "مرجع رسمی تعریف، نسخه‌بندی و نگهداری رویدادهای پلتفرم. Event Envelope در Proto تعریف می‌شود. نام رویدادها و payloadها در Catalog با فرمت YAML/JSON نگهداری می‌شوند."
    },
    {
      "level": 3,
      "heading": "[قرارداد ثبت وقایع (Logging Contract)](../standards/logging-standard)",
      "content": "مرجع رسمی ساختار لاگ‌های پلتفرم. این بخش تنها قرارداد، ساختار، فیلدهای اجباری، سطوح لاگ و قوانین اعتبارسنجی را تعریف می‌کند. **پیاده‌سازی لاگر نیست** — سرویس‌ها در انتخاب کتابخانه آزاد هستند. این قرارداد در Proto تعریف نمی‌شود (خارج از محدوده ADR-Platform-001)."
    },
    {
      "level": 3,
      "heading": "[راهنمای مدیریت قراردادها با CLI (nons)](./nons-ContractManagement-guide)",
      "content": "راهنمای معماری `nons` به عنوان ابزار مدیریت قرارداد (Contract Management Tool) پلتفرم — دریافت OpenAPI، ساخت Registry، مدیریت Bundle و تولید مصنوعات پروژه."
    },
    {
      "level": 3,
      "heading": "[راهنمای ابزار خط فرمان Nons CLI](./cli-reference)",
      "content": "راهنمای کامل نصب، راه‌اندازی و استفاده از دستورات ابزار خط فرمان رسمی `nons` — مدیریت رجیستری، باندل‌ها و تولید مصنوعات پروژه.\n\n---"
    },
    {
      "level": 2,
      "heading": "قوانین نگهداری",
      "content": "1. هر پکیج باید دارای README و مستندات کامل باشد\n2. تغییرات باید از طریق CHANGELOG پیگیری شود\n3. نسخه‌بندی مطابق استاندارد Semantic Versioning\n4. هرگونه تغییر مخرب باید با افزایش Major Version همراه باشد\n5. **`nons-api/contracts/` (Proto):** تغییرات با Buf بررسی می‌شوند — breaking change detection اجباری\n6. **`.nons/generated/` (مصنوعات کلاینت):** کدها توسط `nons generate` تولید می‌شوند — ویرایش دستی ممنوع\n7. **`nons-api/packages/logging`:** مطابق قوانین قبلی\n\n---"
    },
    {
      "level": 2,
      "heading": "منابع مرتبط",
      "content": "- [معماری لایه قراردادها](./shared-packages-architecture) — توضیح کامل رویکرد Proto\n- [ADR-Platform-001: Contract Layer](../ADR/ADR-Platform-001) — سند تصمیم معماری لایه قراردادها\n- [ADR-Platform-004: Platform CLI، Registry و استراتژی تولید مصنوعات](../ADR/ADR-Platform-004) — سند تصمیم یکپارچه‌سازی کلاینت و رجیستری\n- [ADR-Platform-005: Generator Metadata و Template-per-Framework](../ADR/ADR-Platform-005) — معماری جنریتور و استراتژی template\n- [استاندارد نام‌گذاری](../standards/naming-conventions)\n- [نسخه‌بندی](../standards/versioning-policy)\n- [ساختار مخزن](../standards/repository-structure)"
    }
  ]
}