{
  "title": "استاندارد چرخه فروش، پرداخت و تسویه",
  "slug": "team/platform/order-payment-wallet-flow",
  "url": "/docs/team/platform/order-payment-wallet-flow",
  "frontmatter": {
    "layout": "doc",
    "title": "استاندارد چرخه فروش، پرداخت و تسویه",
    "description": "مدل نهایی Order–Payment–Settlement–Wallet Flow — جداسازی کامل چهار دامنه",
    "version": "1.1.0",
    "status": "PRIVATE",
    "author": "Platform Team",
    "owner": "Platform Team",
    "created_at": "2026-06-10",
    "updated_at": "2026-06-11",
    "tags": "",
    "reviewers": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "استاندارد چرخه فروش، پرداخت و تسویه",
      "content": "**Order–Payment–Settlement–Wallet Flow**\n\nنسخه 1.0 | جایگزین مدل‌های قبلی OrderStatus و PaymentFlow پراکنده\n\n---"
    },
    {
      "level": 2,
      "heading": "1. هدف سند",
      "content": "این سند، مدل استاندارد و نهایی چرخه کامل فروش در سیستم NONS را تعریف می‌کند و جایگزین تمام برداشت‌های قبلی از:\n\n- Order Statusهای ترکیبی (حاوی Escrow)\n- Escrow در Order Service\n- تسویه مستقیم در Payment Service\n\nمی‌شود.\n\n---"
    },
    {
      "level": 2,
      "heading": "2. اصل معماری (Core Principle)",
      "content": ""
    },
    {
      "level": 3,
      "heading": "❗ جداسازی کامل سه دامنه مستقل",
      "content": "سیستم فروش از 3 دامنه کاملاً جدا تشکیل می‌شود:\n\n```text\n1. Order Domain        → وضعیت کسب‌وکار معامله\n2. Payment Domain      → مدیریت پرداخت و Escrow\n3. Settlement Domain   → کمیسیون، تسویه فروشنده، مدیریت refund\n4. Wallet Domain       → نگهداری و مدیریت موجودی مالی\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "3. Wallet Service (سرویس کیف پول)",
      "content": ""
    },
    {
      "level": 3,
      "heading": "نقش",
      "content": "Wallet Service **تنها منبع حقیقت (Source of Truth)** برای موجودی مالی کاربران است."
    },
    {
      "level": 3,
      "heading": "مسئولیت‌ها",
      "content": "- نگهداری موجودی کاربران (Balance)\n- ثبت تراکنش‌های مالی (Ledger)\n- مدیریت ورود و خروج پول\n- نگهداری درآمد فروشندگان\n- مدیریت برداشت (Withdrawal)"
    },
    {
      "level": 3,
      "heading": "❌ چه کاری انجام نمی‌دهد",
      "content": "- پردازش پرداخت (Payment Processing)\n- اتصال به درگاه پرداخت\n- مدیریت سفارش\n- مدیریت اختلاف"
    },
    {
      "level": 3,
      "heading": "ارتباط Wallet با Payment",
      "content": "```text\nPayment Service → Wallet Service (only for balance mutation)\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "4. Payment Service (اصلاح شده)",
      "content": ""
    },
    {
      "level": 3,
      "heading": "نقش",
      "content": "Payment Service فقط مسئول:\n\n- دریافت پول از کاربر\n- نگهداری پول در حالت Escrow\n- آزادسازی یا برگشت پول به Wallet"
    },
    {
      "level": 3,
      "heading": "Payment مالک پول نیست",
      "content": "Wallet مالک پول است. Payment فقط پول را بین حالت‌ها جابه‌جا می‌کند."
    },
    {
      "level": 3,
      "heading": "وضعیت‌های Payment",
      "content": "```ts\nenum PaymentStatus {\n  PENDING = 'PENDING',\n  ESCROW_HELD = 'ESCROW_HELD',\n  RELEASED = 'RELEASED',\n  REFUNDED = 'REFUNDED',\n}\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "5. Order Service (اصلاح شده)",
      "content": ""
    },
    {
      "level": 3,
      "heading": "نقش",
      "content": "Order فقط نماینده «فرآیند تجاری معامله» است."
    },
    {
      "level": 3,
      "heading": "Order چه چیزی نیست",
      "content": "- مسئول پول نیست\n- مسئول escrow نیست\n- مسئول کیف پول نیست"
    },
    {
      "level": 3,
      "heading": "وضعیت‌های Order",
      "content": "```ts\nenum OrderStatus {\n  CREATED = 'CREATED',\n  ACTIVE = 'ACTIVE',\n  COMPLETED = 'COMPLETED',\n  CANCELLED = 'CANCELLED',\n  DISPUTED = 'DISPUTED',\n}\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "6. چرخه کامل فروش (Final Flow)",
      "content": ""
    },
    {
      "level": 3,
      "heading": "🟢 مرحله 1: ایجاد سفارش",
      "content": "```text\nOrder: CREATED\n```\n\nEvent: `nons.order.created`\n\n---"
    },
    {
      "level": 3,
      "heading": "🟡 مرحله 2: پرداخت و قفل پول (Escrow)",
      "content": "```text\nPayment: PENDING → ESCROW_HELD\n```\n\nEvent: `nons.payment.escrow.held`\n\n---"
    },
    {
      "level": 3,
      "heading": "🟡 مرحله 3: تحویل کالا",
      "content": "```text\nOrder: CREATED → ACTIVE\n```\n\nEvent: `nons.order.fulfillment.completed`\n\n---"
    },
    {
      "level": 3,
      "heading": "🟠 مرحله 4: تأیید",
      "content": "سه حالت تأیید:\n\n- **A: تأیید کاربر** — `buyer.confirmed = true`\n- **B: تأیید ادمین** — پس از پایان دوره ضمانت ۲۴ ساعته، `system.confirmed = true`\n- **C: Auto-confirm** — این رویکرد وجود دارد ولی در این فاز فعال نیست. توسط ادمین در پرفورمنس فعال می‌شود\n\n---"
    },
    {
      "level": 3,
      "heading": "🟢 مرحله 5: آزادسازی پول",
      "content": "```text\nPayment:  ESCROW_HELD → RELEASED\nWallet:   balance(seller) += amount\n```\n\nEvents:\n- `nons.payment.released`\n- `nons.wallet.credit.posted`\n\n---"
    },
    {
      "level": 3,
      "heading": "🟢 مرحله 6: تسویه فروشنده (Settlement)",
      "content": "```text\nSettlement: commission calculated → seller settled\nTigerBeetle: escrow → seller_wallet\nTigerBeetle: escrow → platform_revenue\n```\n\nEvents:\n- `nons.settlement.completed`\n- `nons.settlement.commission.calculated`\n\nهمچنین این رویداد از سمت payment-service شنیده می‌شود:\n- `nons.payment.confirmed` (contains rate_at_payment, amount_local, provider)\n\n> settlement-service پس از آزادسازی پول از Escrow، کمیسیون پلتفرم را کسر می‌کند و باقی را به seller_wallet تسویه می‌کند. تسویه به صورت دوره‌ای (خودکار) یا با درخواست دستی فروشنده انجام می‌شود.\n\n---"
    },
    {
      "level": 3,
      "heading": "🔴 مرحله 7: لغو سفارش (قبل از تحویل)",
      "content": "```text\nPayment:  ESCROW_HELD → REFUNDED\nWallet:   balance(buyer) += amount\n```\n\nEvent: `nons.payment.refunded`\n\n---"
    },
    {
      "level": 3,
      "heading": "⚠️ مرحله 8: اختلاف (Dispute)",
      "content": "```text\nOrder:    → DISPUTED\nPayment:  → FROZEN\nWallet:   → no change\n```\n\nتصمیم نهایی توسط: `dispute-service`\n\nپس از رأی:\n- به نفع خریدار → `Payment: REFUNDED` → `Wallet: balance(buyer) += amount`\n- به نفع فروشنده → `Payment: RELEASED` → `Wallet: balance(seller) += amount`\n\n---"
    },
    {
      "level": 2,
      "heading": "7. قوانین مهم معماری (Critical Rules)",
      "content": "| قانون | توضیح |\n|---|---|\n| ❌ Order پول را مدیریت نمی‌کند | Order هیچ اطلاعی از escrow، wallet، balance ندارد |\n| ❌ Payment مالک پول نیست | Payment فقط پول را بین حالت‌ها جابه‌جا می‌کند |\n| ❌ Wallet تنها منبع پول است | تمام balanceها فقط در Wallet است |\n\n---"
    },
    {
      "level": 2,
      "heading": "8. تغییر مهم (Breaking Change)",
      "content": ""
    },
    {
      "level": 3,
      "heading": "🧨 حذف مفهوم Escrow از Order",
      "content": "```text\n❌ قبلی: OrderStatus.ESCROW_LOCKed\n✅ جدید: PaymentStatus.ESCROW_HELD\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "9. رویدادهای سیستم",
      "content": ""
    },
    {
      "level": 3,
      "heading": "Domain: Order",
      "content": "| رویداد | توضیح |\n|---|---|\n| `nons.order.created` | سفارش جدید ایجاد شد |\n| `nons.order.fulfillment.completed` | کالا تحویل داده شد |\n| `nons.order.completed` | سفارش تکمیل شد |\n| `nons.order.cancelled` | سفارش لغو شد |\n| `nons.order.disputed` | سفارش وارد اختلاف شد |"
    },
    {
      "level": 3,
      "heading": "Domain: Payment",
      "content": "| رویداد | توضیح |\n|---|---|\n| `nons.payment.escrow.held` | وجه در Escrow قفل شد |\n| `nons.payment.released` | وجه از Escrow آزاد شد |\n| `nons.payment.refunded` | وجه به خریدار برگشت داده شد |"
    },
    {
      "level": 3,
      "heading": "Domain: Settlement",
      "content": "| رویداد | توضیح |\n|---|---|\n| `nons.payment.confirmed` | پرداخت تأیید شد — آغازگر settlement |\n| `nons.settlement.completed` | تسویه فروشنده انجام شد |\n| `nons.settlement.refund.initiated` | برگشت وجه شروع شد |\n| `nons.settlement.commission.calculated` | کمیسیون محاسبه شد |"
    },
    {
      "level": 3,
      "heading": "Domain: Wallet",
      "content": "| رویداد | توضیح |\n|---|---|\n| `nons.wallet.credit.posted` | بستانکاری به حساب واریز شد |\n| `nons.wallet.debit.posted` | بدهکاری از حساب کسر شد |\n| `nons.wallet.withdrawal.requested` | درخواست برداشت ثبت شد |\n\n---"
    },
    {
      "level": 2,
      "heading": "10. جایگاه Wallet Service در معماری",
      "content": "```text\nلایه کسب‌وکار (Business Layer):\n- Marketplace Service\n- Order Service\n- Payment Service\n- Wallet Service\n- Currency Service      ← NEW\n- Settlement Service    ← NEW\n- Chat Service\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "11. تعامل بین سرویس‌ها",
      "content": "```text\nOrder Service ──→ Payment Service       (trigger payment)\nPayment Service ──→ Currency Service    (currency conversion at payment)\nPayment Service ──→ Wallet Service      (balance mutation)\nPayment Service ──→ Settlement Service  (payment.confirmed → trigger settlement)\nSettlement Service ──→ Currency Service (currency conversion for settlement)\nSettlement Service ──→ Wallet Service   (commission + seller balance)\nDispute Service ──→ Payment + Wallet    (override decisions)\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "12. اصل طلایی جدید سیستم",
      "content": "```text\nOrder ≠ Money\nPayment ≠ Ownership\nWallet = Truth of Funds\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "13. معماری نهایی سرویس‌های مالی",
      "content": "```text\npayment-service\n      │\n      ├── currency-service   ← تبدیل ارز\n      │\n      ├── wallet-service     ← pass-through کیف پول\n      │         │\n      │         ▼\n      │   TigerBeetle\n      │   buyer_wallet → escrow\n      │\n      └── NATS: payment.confirmed.v1\n                │\n                ▼\n        settlement-service\n              │\n              ├── currency-service   ← تبدیل ارز تسویه\n              │\n              ├── TigerBeetle\n              │   escrow → seller_wallet\n              │   escrow → platform_revenue\n              │\n              └── NATS: settlement.completed.v1\n```"
    }
  ]
}