{
  "title": "قرارداد رویداد",
  "slug": "team/platform/standards/event-contract",
  "url": "/docs/team/platform/standards/event-contract",
  "frontmatter": {
    "layout": "doc",
    "title": "قرارداد رویداد",
    "description": "پوسته استاندارد NATS، فیلدها، نسخه‌بندی payload و مثال‌ها",
    "version": "1.0.0",
    "status": "PRIVATE",
    "author": "xoxxel",
    "owner": "xoxxel",
    "created_at": "2026-06-07",
    "updated_at": "2026-06-07",
    "tags": "",
    "reviewers": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "قرارداد رویداد",
      "content": "**Event Payload Contract**\n\nنسخه 1.0 | الزامی برای همه رویدادهای NATS\n\n---"
    },
    {
      "level": 2,
      "heading": "1. پوسته استاندارد (Envelope)",
      "content": "هر رویداد منتشر شده در NATS باید از این پوسته پیروی کند:\n\n```json\n{\n  \"id\": \"evt_01j2k3m4n5p6q7r8\",\n  \"subject\": \"nons.order.completed\",\n  \"version\": \"1.0\",\n  \"timestamp\": \"2026-06-03T10:54:00.000Z\",\n  \"source\": \"order-service\",\n  \"traceId\": \"trace_abc123\",\n  \"payload\": {}\n}\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "2. توضیح فیلدها",
      "content": "| فیلد | نوع | قانون | مثال |\n|---|---|---|---|\n| `id` | `evt_<ulid>` | یکتا در کل پلتفرم — هر انتشار یک id جدید | `evt_01j2k3m4n5p6q7r8` |\n| `subject` | string | فرمت `nons.<domain>.<entity>.<action>` — مطابق با subject NATS | `nons.order.completed` |\n| `version` | string | `major.minor` — با تغییرات مخرب major افزایش می‌یابد | `\"1.0\"`, `\"2.0\"` |\n| `timestamp` | string | ISO 8601 UTC — همیشه UTC، همیشه با میلی‌ثانیه | `2026-06-03T10:54:00.000Z` |\n| `source` | string | نام دقیق سرویس مبدأ | `order-service`, `payment-service` |\n| `traceId` | string | شناسه ردیابی در سراسر سرویس‌ها — **الزامی** | `trace_abc123` |\n| `payload` | object | فقط فیلدهای ضروری — نه کل موجودیت | `{ \"orderId\": \"...\" }` |\n\n---"
    },
    {
      "level": 2,
      "heading": "3. قوانین payload",
      "content": "| قانون | توضیح |\n|---|---|\n| حداقلی | فقط فیلدهای ضروری برای مصرف‌کنندگان — نه کل موجودیت دیتابیس |\n| بدون وابسته | payload شامل داده‌های سرویس‌های دیگر نشود |\n| انگلیسی | همه نام فیلدها و مقادیر به انگلیسی |\n| نوع ثابت | نوع فیلدها در طول نسخه تغییر نمی‌کند |\n\n```json\n// ✅ درست — حداقلی\n{\n  \"orderId\": \"018e1234-...\",\n  \"sellerId\": \"018e1234-...\",\n  \"amount\": 15000,\n  \"status\": \"paid\"\n}\n\n// ❌ غلط — کل موجودیت دیتابیس\n{\n  \"id\": \"...\",\n  \"orderId\": \"...\",\n  \"sellerId\": \"...\",\n  \"buyerId\": \"...\",\n  \"amount\": 15000,\n  \"status\": \"paid\",\n  \"createdAt\": \"...\",\n  \"updatedAt\": \"...\",\n  \"internalNote\": \"...\",\n  \"paymentGatewayId\": \"...\",\n  \"cancelledAt\": null,\n  \"deliveredAt\": null\n}\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "4. نسخه‌بندی رویداد (Event Versioning)",
      "content": "**تغییر مخرب در payload رویداد** = افزایش major version.\n\nمصرف‌کنندگان قدیمی باید در طول انتقال هر دو نسخه را مدیریت کنند.\n\n| نوع تغییر | مثال | افزایش version |\n|---|---|---|\n| افزودن فیلد اختیاری | اضافه شدن `discount` به payload | minor — `1.0` → `1.1` |\n| افزودن فیلد اجباری | اضافه شدن `region` به payload | major — `1.x` → `2.0` |\n| حذف فیلد | حذف `oldField` | major — `1.x` → `2.0` |\n| تغییر نوع فیلد | `amount` از integer به string | major — `1.x` → `2.0` |\n| تغییر نام فیلد | `createdAt` → `timestamp` | major — `1.x` → `2.0` |"
    },
    {
      "level": 3,
      "heading": "مثال انتشار همزمان دو نسخه:",
      "content": "```\nnons.order.completed با version 1.0 → مصرف‌کنندگان قدیمی\nnons.order.completed با version 2.0 → مصرف‌کنندگان جدید\n```\n\nپس از اطمینان از مهاجرت همه مصرف‌کنندگان، نسخه قدیمی متوقف می‌شود.\n\n---"
    },
    {
      "level": 2,
      "heading": "5. مثال‌های کامل",
      "content": ""
    },
    {
      "level": 3,
      "heading": "رویداد ایجاد سفارش",
      "content": "```json\n{\n  \"id\": \"evt_01j2k3m4n5p6q7r8\",\n  \"subject\": \"nons.order.completed\",\n  \"version\": \"1.0\",\n  \"timestamp\": \"2026-06-03T10:54:00.000Z\",\n  \"source\": \"order-service\",\n  \"traceId\": \"trace_abc123\",\n  \"payload\": {\n    \"orderId\": \"018e1234-...\",\n    \"sellerId\": \"018e1234-...\",\n    \"buyerId\": \"018e1234-...\",\n    \"amount\": 25000,\n    \"currency\": \"USD\"\n  }\n}\n```"
    },
    {
      "level": 3,
      "heading": "رویداد پرداخت (version 2.0 با فیلد جدید)",
      "content": "```json\n{\n  \"id\": \"evt_01j2k3m4n5p6q7r9\",\n  \"subject\": \"nons.payment.released\",\n  \"version\": \"2.0\",\n  \"timestamp\": \"2026-06-03T10:55:00.000Z\",\n  \"source\": \"payment-service\",\n  \"traceId\": \"trace_abc123\",\n  \"payload\": {\n    \"orderId\": \"018e1234-...\",\n    \"sellerId\": \"018e1234-...\",\n    \"amount\": 25000,\n    \"fee\": 250,\n    \"releaseType\": \"standard\"\n  }\n}\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "6. استاندارد subject NATS",
      "content": "فرمت کامل: `nons.<domain>.<entity>.<action>`\n\n```\nnons.order.completed\nnons.order.paid\nnons.order.delivered\nnons.payment.escrow.released\n```\n\nبرای مصرف‌کنندگان از wildcard: `nons.order.*` — همه رویدادهای یک entity را دریافت کنید.\n\n---"
    },
    {
      "level": 2,
      "heading": "خلاصه",
      "content": "| مورد | قانون |\n|---|---|\n| پوسته ثابت | `id`, `subject`, `version`, `timestamp`, `source`, `traceId`, `payload` |\n| id یکتا | `evt_<ulid>` برای هر رویداد |\n| traceId | اجباری — ردیابی در سراسر سرویس‌ها |\n| payload حداقلی | فقط فیلدهای ضروری |\n| تغییر مخرب | افزایش version + انتشار همزمان دو نسخه |"
    }
  ]
}