{
  "title": "سیاست کاتالوگ رویدادها",
  "slug": "team/platform/package/event-catalog",
  "url": "/docs/team/platform/package/event-catalog",
  "frontmatter": {},
  "sections": [
    {
      "level": 1,
      "heading": "سیاست کاتالوگ رویدادها",
      "content": "**Event Catalog Policy**\n\nنسخه 2.0 | مرجع رسمی ثبت و نگهداری رویدادهای سیستم\n\n> **به‌روزرسانی:** با تصویب ADR-Platform-001، ساختار Event Envelope در Proto تعریف می‌شود اما Event Catalog همچنان به صورت انسانی (yaml/json) نگهداری می‌شود. Proto فقط ساختار قراردادها را تعریف می‌کند — مالکیت Event Names در Catalog باقی می‌ماند.\n\n---"
    },
    {
      "level": 2,
      "heading": "مفهوم کلیدی",
      "content": "```text\nEvent Catalog = فقط معنی و قرارداد (خوانایی انسانی)\nProto         = فقط ساختار Envelope (Code Generation)\nNATS          = فقط حمل‌کننده پیام\n```\n\nکاتالوگ رویدادها تنها مرجع تعریف **معنی، نام، مالکیت و مصرف‌کنندگان** رویدادها است.\nProto (`envelope.proto`) فقط ساختار Event Envelope را تعریف می‌کند.\nNATS صرفاً نقش **حمل‌کننده پیام** را دارد.\n\n---"
    },
    {
      "level": 2,
      "heading": "1. هدف",
      "content": "کاتالوگ رویدادها (Event Catalog) مرجع رسمی تعریف، نسخه‌بندی و نگهداری رویدادهای پلتفرم است.\n\nاین بخش نام رویدادها، مالک، مصرف‌کنندگان، قوانین نام‌گذاری و الزامات سازگاری را تعریف می‌کند و به Message Broker خاصی وابسته نیست.\n\nکاتالوگ مسئول انتشار یا دریافت رویداد نیست.\n\n---"
    },
    {
      "level": 2,
      "heading": "2. محل نگهداری",
      "content": "Event Catalog به صورت فایل‌های انسانی (YAML یا JSON) نگهداری می‌شود:\n\n```text\ncatalog/\n└── events/\n    ├── index.yaml          ← فهرست همه رویدادها\n    ├── auth/\n    │   └── events.yaml\n    ├── order/\n    │   └── events.yaml\n    ├── payment/\n    │   └── events.yaml\n    ├── wallet/\n    │   └── events.yaml\n    ├── settlement/\n    │   └── events.yaml\n    └── ...\n```\n\nهر سرویس مالک رویدادهای خود را در فایل مربوطه تعریف می‌کند.\n\n---"
    },
    {
      "level": 2,
      "heading": "3. ساختار تعریف رویداد",
      "content": ""
    },
    {
      "level": 3,
      "heading": "Event Envelope — در Proto",
      "content": "```protobuf\n// contracts/envelope.proto\n// فقط ساختار حمل پیام — نه نام رویدادها\nmessage EventEnvelope {\n  string id = 1;\n  string subject = 2;\n  string version = 3;\n  string timestamp = 4;\n  string source = 5;\n  string trace_id = 6;\n  bytes payload = 7;\n}\n```"
    },
    {
      "level": 3,
      "heading": "نام رویدادها — در Catalog",
      "content": "```yaml"
    },
    {
      "level": 1,
      "heading": "nons-api/catalog/events/order/events.yaml",
      "content": "events:\n  - name: nons.order.created\n    version: 1\n    owner: order-service\n    description: Order successfully created\n    consumers:\n      - payment-service\n      - notification-service\n    payload:\n      orderId: string\n      buyerId: string\n      sellerId: string\n      amount: number\n      createdAt: string\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "4. محتوای هر رویداد",
      "content": "هر رویداد باید شامل اطلاعات زیر باشد:\n\n```yaml\nname: nons.order.created.v1\n\nowner: order-service\n\nversion: 1\n\ndescription: Order successfully created\n\nconsumers:\n  - payment-service\n  - notification-service\n\npayload:\n  orderId: string\n\n  buyerId: string\n\n  sellerId: string\n\n  amount: number\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "5. مالکیت رویداد",
      "content": "هر رویداد فقط یک مالک دارد.\n\nمثال:\n\n```text\nnons.order.created.v1\n```\n\nمالک:\n\n```text\norder-service\n```\n\nتنها سرویس مالک مجاز به انتشار این رویداد است.\n\nسایر سرویس‌ها فقط مجاز به مصرف آن هستند.\n\n---"
    },
    {
      "level": 2,
      "heading": "6. فرآیند ایجاد رویداد جدید",
      "content": "قبل از ایجاد رویداد جدید باید بررسی شود:\n\n1. آیا رویداد مشابهی از قبل وجود دارد؟\n2. آیا رویداد متعلق به سرویس فعلی است؟\n3. آیا نام رویداد با استاندارد نام‌گذاری سازگار است؟\n4. آیا نسخه مشخص شده است؟\n\nپس از تأیید:\n\n```text\n1. ثبت رویداد در Catalog (فایل YAML)\n\n2. تعریف Payload در مستندات\n\n3. مشخص کردن مالک\n\n4. ثبت مصرف‌کنندگان احتمالی\n```\n\n> توجه: Event Nameها در Proto به Enum تبدیل نمی‌شوند. آنها در Catalog باقی می‌مانند تا خوانایی انسانی و مستندسازی بهتر حفظ شود.\n\n---"
    },
    {
      "level": 2,
      "heading": "7. فرآیند تغییر رویداد",
      "content": "تغییرات غیرمخرب:\n\n```text\nافزودن توضیحات\nافزودن مصرف‌کننده جدید\nاصلاح مستندات\n```\n\nنیازی به نسخه جدید ندارند.\n\n---\n\nتغییرات مخرب:\n\n```text\nحذف فیلد\nتغییر نام فیلد\nتغییر نوع فیلد\nافزودن فیلد اجباری\n```\n\nباید نسخه جدید ایجاد کنند.\n\nمثال:\n\n```text\nnons.order.created.v1\n```\n\n↓\n\n```text\nnons.order.created.v2\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "8. حذف رویداد",
      "content": "حذف رویداد ممنوع است.\n\nرویدادها فقط می‌توانند:\n\n```text\nDeprecated\n```\n\nشوند.\n\nمثال:\n\n```yaml\nstatus: deprecated\nreplacement: order.created.v2\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "9. ثبت مصرف‌کنندگان",
      "content": "تمام مصرف‌کنندگان شناخته‌شده باید در مستند رویداد ثبت شوند.\n\nمثال:\n\n```yaml\nconsumers:\n  - payment-service\n  - notification-service\n  - audit-service\n```\n\nاین اطلاعات برای تحلیل اثر تغییرات الزامی است.\n\n---"
    },
    {
      "level": 2,
      "heading": "10. کشف رویدادها",
      "content": "توسعه‌دهندگان قبل از:\n\n- Publish\n- Subscribe\n- ایجاد Event جدید\n\nباید ابتدا کاتالوگ رویدادها را بررسی کنند.\n\nهیچ رویدادی نباید خارج از Event Catalog ایجاد یا استفاده شود.\n\n---"
    },
    {
      "level": 2,
      "heading": "11. ساختار پیشنهادی Catalog",
      "content": "```text\ncatalog/\n└── events/\n    ├── index.yaml\n    ├── auth/\n    │   └── events.yaml\n    ├── order/\n    │   └── events.yaml\n    ├── payment/\n    │   └── events.yaml\n    ├── wallet/\n    │   └── events.yaml\n    ├── settlement/\n    │   └── events.yaml\n    ├── review/\n    │   └── events.yaml\n    └── platform/\n        └── events.yaml      # رویدادهای سطح پلتفرم (heartbeat, registry)\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "12. اصل مرجع واحد",
      "content": "کاتالوگ رویدادها:\n\n```text\nSingle Source of Truth\n```\n\nبرای نام، مالکیت، نسخه و مصرف‌کنندگان Eventهای سیستم است.\n\nProto (`envelope.proto`):\n\n```text\nSingle Source of Truth\n```\n\nبرای ساختار Event Envelope است.\n\nاین دو مکمل یکدیگر هستند — نه رقیب.\n\n---"
    },
    {
      "level": 2,
      "heading": "13. رویدادهای جدید دامنه مالی",
      "content": ""
    },
    {
      "level": 3,
      "heading": "۱۳.۱ سفارش",
      "content": "| رویداد                 | Owner         | Consumers          | Payload                                              |\n| ---------------------- | ------------- | ------------------ | ---------------------------------------------------- |\n| `nons.order.delivered` | order-service | settlement-service | `{ orderId, sellerId, amountUsdCents, deliveredAt }` |"
    },
    {
      "level": 3,
      "heading": "۱۳.۲ پرداخت",
      "content": "| رویداد                   | Owner           | Consumers                             | Payload                                                                       |\n| ------------------------ | --------------- | ------------------------------------- | ----------------------------------------------------------------------------- |\n| `nons.payment.confirmed` | payment-service | settlement-service, analytics-service | `{ orderId, amountUsdCents, amountLocal, currency, rateAtPayment, provider }` |"
    },
    {
      "level": 3,
      "heading": "۱۳.۳ تسویه",
      "content": "| رویداد                                  | Owner              | Consumers                                               | Payload                                                                       |\n| --------------------------------------- | ------------------ | ------------------------------------------------------- | ----------------------------------------------------------------------------- |\n| `nons.settlement.completed`             | settlement-service | wallet-service, notification-service, analytics-service | `{ sellerId, amountUsdCents, commissionUsdCents, settledAt }`                 |\n| `nons.settlement.refund.initiated`      | settlement-service | wallet-service, notification-service                    | `{ orderId, buyerId, amountUsdCents, reason }`                                |\n| `nons.settlement.commission.calculated` | settlement-service | analytics-service                                       | `{ sellerId, orderId, rate, amountUsdCents, commissionUsdCents, sellerTier }` |"
    },
    {
      "level": 3,
      "heading": "۱۳.۴ پلتفرم",
      "content": "| رویداد | Owner | Consumers | Payload |\n|---|---|---|---|\n| `platform.service.status_changed` | core-service (Go) | notification-service, analytics-service | `{ serviceName, version, environment, oldStatus, newStatus, timestamp }` |"
    },
    {
      "level": 3,
      "heading": "۱۳.۵ احراز هویت",
      "content": "| رویداد | Owner | Consumers | Payload |\n|---|---|---|---|\n| `nons.auth.user.registered` | auth-service | iam-service, notification-service | `{ id, email, name, registeredAt }` |\n| `nons.auth.user.logged_in` | auth-service | iam-service, notification-service | `{ id, email, loggedInAt }` |\n| `nons.auth.user.logged_out` | auth-service | iam-service | `{ id, loggedOutAt }` |\n| `nons.auth.user.password_changed` | auth-service | notification-service | `{ id, changedAt }` |"
    },
    {
      "level": 3,
      "heading": "۱۳.۶ توکن (Token Service)",
      "content": "| رویداد | Owner | Consumers | Payload |\n|---|---|---|---|\n| `nons.token.issued` | token-service | audit-service, analytics-service | `{ sub, client_id, scope, grantedAt }` |\n| `nons.token.revoked` | token-service | audit-service, iam-service | `{ sub, client_id, revokedAt }` |"
    }
  ]
}