{
  "title": "سیاست قراردادها",
  "slug": "team/platform/package/contract_catalog",
  "url": "/docs/team/platform/package/contract_catalog",
  "frontmatter": {},
  "sections": [
    {
      "level": 1,
      "heading": "سیاست قراردادها",
      "content": "**Contract Catalog Policy**\n\nنسخه 2.0 | مرجع رسمی قراردادهای ارتباطی سیستم\n\n> **به‌روزرسانی:** با تصویب ADR-Platform-001، قراردادهای مشترک پلتفرم از TypeScript به Protocol Buffers مهاجرت کرده‌اند. این سند بر اساس معماری جدید به‌روز شده است.\n\n---"
    },
    {
      "level": 2,
      "heading": "1. هدف",
      "content": "Contract Catalog مرجع رسمی تعریف و نگهداری قراردادهای ارتباطی بین سرویس‌ها است — شامل ساختار درخواست‌ها و پاسخ‌ها، قرارداد خطاها و قوانین نسخه‌بندی.\n\nقراردادهای مشترک پلتفرم در قالب **Protocol Buffers** در `nons-api/contracts/` تعریف می‌شوند (منبع حقیقت). Bindingهای TypeScript و Go از طریق Code Generation (Buf) تولید می‌شوند.\n\n---"
    },
    {
      "level": 2,
      "heading": "2. لایه‌های قرارداد",
      "content": ""
    },
    {
      "level": 3,
      "heading": "۲.۱ Platform Contracts — `nons-api/contracts/`",
      "content": "قراردادهای مشترک پلتفرم که توسط Proto تعریف می‌شوند:\n\n```text\ncontracts/\n├── envelope.proto      # Event Envelope\n├── registry.proto      # Service Registry\n├── errors.proto        # Platform Error Codes\n└── permissions.proto   # Permissions\n```\n\nمنبع حقیقت: فایل‌های `.proto`\nابزار: Buf (lint, break check, generate)\nBindingها: در CI تولید و به عنوان Artifact توزیع می‌شوند"
    },
    {
      "level": 3,
      "heading": "۲.۲ Domain Contracts — داخل سرویس‌ها",
      "content": "قراردادهای دامنه‌ای (مانند `CreateOrderRequest`, `PaymentResponse`) در داخل همان سرویس تعریف می‌شوند و به لایه پلتفرم منتقل نمی‌شوند.\n\n```text\nnons-api/services/order-service/contracts/\nnons-api/services/payment-service/contracts/\n```\n\nمالک هر Domain Contract همان سرویس است.\n\n---"
    },
    {
      "level": 2,
      "heading": "3. قرارداد چیست؟",
      "content": "قرارداد مشخص می‌کند:\n\n```text\nچه داده‌ای\n\nبا چه ساختاری\n\nبین چه اجزایی\n\nمبادله می‌شود\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "4. فرمت قرارداد (Platform Contracts)",
      "content": "قراردادهای پلتفرم با **Protocol Buffers** تعریف می‌شوند:\n\n```protobuf\n// contracts/envelope.proto\nmessage EventEnvelope {\n  string event_name = 1;\n  string event_version = 2;\n  string trace_id = 3;\n  string correlation_id = 4;\n  int64 timestamp = 5;\n  string producer = 6;\n  bytes payload = 7;\n}\n```\n\n```protobuf\n// contracts/errors.proto\nenum PlatformErrorCode {\n  PLATFORM_ERROR_UNSPECIFIED = 0;\n  PLATFORM_INTERNAL_ERROR = 1;\n  PLATFORM_VALIDATION_ERROR = 2;\n  PLATFORM_RATE_LIMIT_EXCEEDED = 3;\n  PLATFORM_SERVICE_UNAVAILABLE = 4;\n}\n```\n\n> Bindingهای TypeScript و Go از این فایل‌ها به صورت خودکار تولید می‌شوند. هیچ‌کس فایل‌های تولیدشده را دستی ویرایش نمی‌کند.\n\n---"
    },
    {
      "level": 2,
      "heading": "5. قراردادهای دامنه (Domain Contracts)",
      "content": "قراردادهای دامنه مختص هر سرویس هستند و در داخل آن سرویس تعریف می‌شوند. این بخش در مستندات سرویس مربوطه ثبت می‌شود.\n\nمثال — سفارش:\n\n```text\nnons-api/services/order-service/docs/contracts.md\n```\n\n**مالک:** order-service\n\nمثال — پرداخت:\n\n```text\nnons-api/services/payment-service/docs/contracts.md\n```\n\n**مالک:** payment-service\n\n---"
    },
    {
      "level": 2,
      "heading": "6. نسخه‌بندی",
      "content": "همان سیاست Semantic Versioning موجود اعمال می‌شود (نیاز به ایجاد سیاست جدید نیست).\n\nتغییر در Proto:\n\n```text\n- افزودن فیلد جدید ← MINOR (غیرمخرب)\n- حذف یا تغییر فیلد ← MAJOR (مخرب)\n```\n\nتغییر در Domain Contract:\n\n```text\n- هر سرویس طبق سیاست نسخه‌بندی خود\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "7. مالکیت",
      "content": "| قرارداد                | مالک             | لایه     |\n| ---------------------- | ---------------- | -------- |\n| EventEnvelope          | Platform Team    | Platform |\n| Error Codes (Platform) | Platform Team    | Platform |\n| Permissions            | Platform Team    | Platform |\n| CreateOrder            | order-service    | Domain   |\n| PaymentRequest         | payment-service  | Domain   |\n| ConvertRequest         | currency-service | Domain   |\n\n---"
    },
    {
      "level": 2,
      "heading": "8. حذف قرارداد",
      "content": "حذف مستقیم ممنوع است.\n\nقرارداد فقط می‌تواند:\n\n```text\nDeprecated\n```\n\nشود.\n\n---"
    },
    {
      "level": 2,
      "heading": "9. اصل مرجع واحد",
      "content": "Contract Catalog تنها مرجع معتبر برای تمام قراردادهای ارتباطی سیستم است.\n\nهیچ سرویسی نباید قرارداد اختصاصی و مستندسازی‌نشده ایجاد کند.\n\n---"
    },
    {
      "level": 2,
      "heading": "10. قراردادهای جدید — Currency Service",
      "content": ""
    },
    {
      "level": 3,
      "heading": "GET /rates",
      "content": "دریافت نرخ‌های لحظه‌ای همه ارزهای پشتیبانی‌شده.\n\n**مالک:** currency-service — domain contract\n\n```ts\n// services/currency-service/docs/contracts.md\nexport interface GetRatesResponse {\n  USD_IRR: number;\n  USD_TRY: number;\n  USD_EUR: number;\n  updatedAt: string;\n}\n```"
    },
    {
      "level": 3,
      "heading": "POST /convert",
      "content": "**مالک:** currency-service — domain contract\n\n```ts\nexport interface ConvertRequest {\n  amount: number;\n  from: \"USD\" | \"IRR\" | \"TRY\" | \"EUR\";\n  to: \"USD\" | \"IRR\" | \"TRY\" | \"EUR\";\n}\n\nexport interface ConvertResponse {\n  result: number;\n  rate: number;\n  rateAt: string;\n}\n\nexport interface ConvertError {\n  code: \"UNSUPPORTED_PAIR\" | \"RATE_UNAVAILABLE\" | \"INVALID_AMOUNT\";\n  message: string;\n}\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "11. قراردادهای جدید — Settlement Service",
      "content": ""
    },
    {
      "level": 3,
      "heading": "CommissionRule",
      "content": "**مالک:** settlement-service — domain contract\n\n```ts\nexport interface CommissionRule {\n  sellerTier: \"standard\" | \"premium\" | \"enterprise\";\n  rate: number;\n  minAmountUsdCents: number;\n  maxAmountUsdCents: number;\n}\n```"
    },
    {
      "level": 3,
      "heading": "SettlementRequest",
      "content": "**مالک:** settlement-service — domain contract\n\n```ts\nexport interface SettlementRequest {\n  sellerId: string;\n  type: \"automatic\" | \"manual\";\n  periodStart?: string;\n  periodEnd?: string;\n}\n```"
    },
    {
      "level": 3,
      "heading": "RefundRequest",
      "content": "**مالک:** settlement-service — domain contract\n\n```ts\nexport interface RefundRequest {\n  orderId: string;\n  reason: string;\n  initiatedBy: \"system\" | \"admin\" | \"dispute\";\n}\n```"
    }
  ]
}