{
  "title": "Settlement Service",
  "slug": "team/backend/services/settlement-service",
  "url": "/docs/team/backend/services/settlement-service",
  "frontmatter": {
    "layout": "doc",
    "title": "Settlement Service",
    "description": "کمیسیون، تسویه فروشنده و مدیریت refund",
    "version": "1.0.0",
    "status": "BLUEPRINT",
    "author": "xoxxel",
    "owner": "xoxxel",
    "created_at": "2026-06-11",
    "updated_at": "2026-06-11",
    "tags": "",
    "reviewers": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "Settlement Service",
      "content": "> **Blueprint v1.0 — پیش از توسعه**\n\n---"
    },
    {
      "level": 2,
      "heading": "1. هدف سرویس",
      "content": "مدیریت چرخه مالی پس از تحویل سفارش: محاسبه کمیسیون پلتفرم بر اساس seller_tier، انتقال سهم فروشنده از escrow به seller_wallet از طریق TigerBeetle، تسویه دوره‌ای خودکار و دستی، و مدیریت refund و برگشت وجه.\n\n---"
    },
    {
      "level": 2,
      "heading": "2. مسئولیت‌ها",
      "content": "- گوش دادن به رویداد `nons.order.delivered` و شروع فرآیند تسویه\n- محاسبه کمیسیون پلتفرم بر اساس seller_tier (standard ۱۰٪، premium ۷٪، enterprise ۵٪)\n- انتقال سهم فروشنده از escrow به seller_wallet در TigerBeetle\n- انتقال کمیسیون از escrow به platform_revenue در TigerBeetle\n- تسویه دوره‌ای خودکار (هفتگی/ماهانه) از طریق cron job\n- تسویه دستی به درخواست فروشنده\n- مدیریت refund و chargeback\n- انتشار رویدادهای `nons.settlement.completed`، `nons.settlement.refund.initiated`، `nons.settlement.commission.calculated`\n- استفاده از currency-service برای تبدیل ارز تسویه\n\n---"
    },
    {
      "level": 2,
      "heading": "3. حوزه (Scope)",
      "content": "**در این سرویس:**\n- محاسبه کمیسیون سکو به ازای هر سفارش\n- انتقال سهم فروشنده از escrow به seller_wallet\n- تسویه خودکار دوره‌ای\n- تسویه دستی به درخواست فروشنده\n- مدیریت refund و chargeback\n- صدور صورت‌حساب برای فروشنده\n\n**نیست در این سرویس:**\n- دریافت وجه از gateway (مسئولیت payment-service)\n- مدیریت کیف پول کاربر (مسئولیت wallet-service)\n- نرخ ارز (مسئولیت currency-service)\n\n---"
    },
    {
      "level": 2,
      "heading": "4. تکنولوژی",
      "content": "| مؤلفه | فناوری |\n|---|---|\n| زبان | Node.js / NestJS |\n| دیتابیس | TigerBeetle (Double-Entry Ledger) |\n| کش | Redis (queues) |\n\n---"
    },
    {
      "level": 2,
      "heading": "5. قراردادهای داده",
      "content": ""
    },
    {
      "level": 3,
      "heading": "CommissionRule",
      "content": "```typescript\ninterface CommissionRule {\n  sellerTier: 'standard' | 'premium' | 'enterprise'\n  rate: number              // درصد کمیسیون (مثلاً ۱۰ = ۱۰%)\n  minAmountUsdCents: bigint // حداقل کمیسیون\n  maxAmountUsdCents: bigint // حداکثر کمیسیون\n}\n```"
    },
    {
      "level": 3,
      "heading": "SettlementRequest",
      "content": "```typescript\ninterface SettlementRequest {\n  sellerId: string\n  type: 'automatic' | 'manual'\n  periodStart?: string\n  periodEnd?: string\n}\n```"
    },
    {
      "level": 3,
      "heading": "RefundRequest",
      "content": "```typescript\ninterface RefundRequest {\n  orderId: string\n  reason: string\n  initiatedBy: 'system' | 'admin' | 'dispute'\n}\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "6. رویدادها",
      "content": ""
    },
    {
      "level": 3,
      "heading": "مصرف‌شونده (Inbound)",
      "content": "| رویداد | مالک | توضیح |\n|---|---|---|\n| `nons.order.delivered` | order-service | سفارش تحویل شد — شروع تسویه |\n| `nons.payment.confirmed` | payment-service | پرداخت تأیید شد |"
    },
    {
      "level": 3,
      "heading": "منتشرشونده (Outbound)",
      "content": "| رویداد | مصرف‌کنندگان | توضیح |\n|---|---|---|\n| `nons.settlement.completed` | wallet-service, notification-service, analytics-service | تسویه انجام شد |\n| `nons.settlement.refund.initiated` | wallet-service, notification-service | فرآیند refund شروع شد |\n| `nons.settlement.commission.calculated` | analytics-service | کمیسیون محاسبه شد |\n\n---"
    },
    {
      "level": 2,
      "heading": "7. تراکنش‌های TigerBeetle",
      "content": "```\ndebit:  escrow\ncredit: seller_wallet\ncredit: platform_revenue\n```\n\n| حساب | توضیح |\n|---|---|\n| escrow | وجه منتظر تحویل سفارش |\n| seller_wallet | کیف پول فروشنده |\n| platform_revenue | درآمد سکو (کمیسیون) |\n\n---"
    },
    {
      "level": 2,
      "heading": "8. نرخ کمیسیون بر اساس Seller Tier",
      "content": "| Tier | نرخ | حداقل (cents) | حداکثر (cents) |\n|---|---|---|---|\n| standard | ۱۰٪ | ۱۰۰۰ | ۵۰۰۰۰ |\n| premium | ۷٪ | ۵۰۰ | ۱۰۰۰۰۰ |\n| enterprise | ۵٪ | ۰ | نامحدود |\n\nsettlement-service سطح فروشنده را از IAM-service دریافت می‌کند.\n\n---"
    },
    {
      "level": 2,
      "heading": "9. وابستگی‌ها",
      "content": "| وابستگی | نوع |\n|---|---|\n| order-service | رویداد `nons.order.delivered` |\n| payment-service | رویداد `nons.payment.confirmed` |\n| currency-service | تبدیل ارز تسویه |\n| wallet-service | به‌روزرسانی موجودی seller_wallet |\n| IAM-service | دریافت seller_tier |\n| TigerBeetle | ثبت تراکنش‌های مالی |\n\n---"
    },
    {
      "level": 2,
      "heading": "10. الزامات Idempotency",
      "content": "هر `settlement_id` باید فقط یکبار پردازش شود. اگر تسویه失敗 شد، سفارش در وضعیت `RELEASED` می‌ماند و تسویه در صف بعدی مجدداً تلاش می‌شود.\n\n---"
    },
    {
      "level": 2,
      "heading": "11. خطا و Retry",
      "content": "**TigerBeetle:**\n\n| سناریو | رفتار |\n|---|---|\n| TigerBeetle در دسترس نیست (connection refused) | Retry با backoff |\n| TigerBeetle timeout | Retry با backoff |\n| تراکنش تکراری | تشخیص توسط unique `id` — نادیده گرفته می‌شود (idempotency) |\n| موجودی ناکافی در حساب | خطای کسب‌وکار — بررسی دستی |\n| عدم تطابق debit/credit | خطای بحرانی — لاگ + اخطار تیم |\n\n**Retry policy:**\n\n| تلاش | تأخیر | اقدام |\n|---|---|---|\n| ۱ | ۲ ثانیه | Retry تراکنش TigerBeetle |\n| ۲ | ۱۰ ثانیه | Retry |\n| ۳ | ۶۰ ثانیه | آخرین تلاش |\n| پس از ۳ تلاش | — | رویداد به DLQ + اخطار DevOps |\n\n---"
    },
    {
      "level": 2,
      "heading": "12. مسیر توسعه",
      "content": "| مرحله | وضعیت |\n|---|---|\n| Blueprint | ✅ تکمیل |\n| Demo | ⏳ در انتظار |\n| توسعه | ❌ شروع نشده |\n| تست | ❌ شروع نشده |\n| انتشار | ❌ شروع نشده |"
    }
  ]
}