{
  "title": "معماری پروژه",
  "slug": "team/platform/Architecture",
  "url": "/docs/team/platform/Architecture",
  "frontmatter": {
    "layout": "doc",
    "title": "معماری پروژه",
    "description": "معماری Monorepo، ساختار هسته مشترک، سرویس‌ها و لایه‌های سیستم",
    "version": "0.3.0",
    "status": "PRIVATE",
    "author": "xoxxel",
    "owner": "xoxxel",
    "created_at": "2026-06-06",
    "updated_at": "2026-06-18",
    "tags": "",
    "reviewers": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "معماری پروژه",
      "content": "**Monorepo Architecture**\nاین پروژه بر پایه معماری Monorepo طراحی شده است. هر سرویس مالک یک حوزه مشخص از کسب‌وکار بوده و به صورت مستقل توسعه، استقرار و مقیاس‌پذیر می‌شود. ارتباط میان سرویس‌ها از طریق قراردادهای مشخص (Contracts) و رویدادها (Events) انجام می‌شود تا وابستگی مستقیم میان اجزا به حداقل برسد.\n\n```\nnons/                          ← پوشه والد (مرز یا ریشه پروژه نیست)\n│\n├── dotdive/                   ← VitePress Docs (فقط مستندات پلتفرم - بدون کد)\n│\n├── nons-api/                  ← ریشه اصلی پروژه (Monorepo همه سرویس‌ها و پکیج‌ها)\n│   │\n│   ├── contracts/             ← **لایه قراردادهای پلتفرم (Proto — Source of Truth)**\n│   │   ├── envelope.proto\n│   │   ├── registry.proto\n│   │   ├── errors.proto\n│   │   └── permissions.proto\n│   │\n│   ├── core/                  ← Go Core (از Bindingهای Go تولیدشده از Proto استفاده می‌کند)\n│   │\n│   ├── packages/              ← Bindingهای تولیدشده از Proto + قراردادهای مستقل\n│   │   ├── contracts/         ← Binding TS از Proto (Error Codes, Permissions)\n│   │   ├── events/            ← Binding TS از Proto (Event Envelope)\n│   │   └── logging/           ← قرارداد لاگینگ (خارج از Proto)\n│   │\n│   ├── services/\n│   │   ├── auth-service/       ← احراز هویت و مدیریت نشست (Ory Kratos)\n│   │   ├── token-service/      ← صدور و اعتبارسنجی توکن OAuth2/OIDC (Ory Hydra)\n│   │   ├── login-consent-app/  ← سرویس مستقل Go — واسط بین Hydra و Kratos (Login & Consent flow + Token Hook)\n│   │   ├── IAM/\n│   │   ├── keto/\n│   │   ├── user-service/\n│   │   ├── kyc-service/\n│   │   ├── marketplace-service/\n│   │   ├── order-service/\n│   │   ├── payment-service/\n│   │   ├── wallet-service/\n│   │   ├── currency-service/\n│   │   ├── settlement-service/\n│   │   ├── chat-service/\n│   │   ├── dispute-service/\n│   │   ├── zone-service/\n│   │   ├── review-service/\n│   │   ├── moderation-service/\n│   │   ├── boost-service/\n│   │   ├── search-service/\n│   │   ├── notification-service/\n│   │   ├── analytics-service/\n│   │   └── storage-service/\n│   │\n│   └── infra/\n│       ├── gateway/\n│       └── k8s/\n│           ├── services/\n│           ├── configmaps/\n│           └── secrets/\n│\n├── AGENTS.md                  ← راهنمای ایجنت\n├── rule.md                    ← قوانین حاکمیتی\n├── task.md                    ← فعال تسک\n└── project-audit.md           ← حسابرسی پروژه\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "Core (Platform Control Plane)",
      "content": "`nons-api/core/`\n\nCore یک **سرویس زیرساختی** (Go) است — نه Framework و نه Shared Library. Core مسئول دغدغه‌های فنی مشترک در سطح پلتفرم است و هیچ مسئولیت کسب‌وکاری ندارد.\n\n- همه ارتباطات از طریق NATS انجام می‌شود — Core توسط هیچ سرویس دیگری import نمی‌شود\n- Core از Bindingهای Go تولیدشده از `nons-api/contracts/` (Proto) برای اعتبارسنجی و Registry استفاده می‌کند\n- Core به هیچ پکیج TypeScript (`nons-api/packages/*`) وابسته نیست\n\nبرای جزئیات بیشتر: [معماری Core](./core/Architecture) و [بلوپرینت Core](./core/blueprint).\n\n---"
    },
    {
      "level": 2,
      "heading": "استاندارد طراحی API",
      "content": "پلتفرم نونز دارای استاندارد رسمی طراحی API است که تمام سرویس‌ها موظف به رعایت آن هستند:\n\n| سند | توضیح |\n|-----|--------|\n| [راهنمای طراحی API](./api/api-design-guidelines) | مرجع رسمی — نسخه‌گذاری، پوسته پاسخ، خطا، صفحه‌بندی، فیلتر، مرتب‌سازی، جستجو، تاریخ، شناسه، احراز هویت، نام‌گذاری، کدهای وضعیت، Nullable، Deprecation |\n| [راهنمای تولید OpenAPI](./api/openapi-guidelines) | استاندارد تولید، اعتبارسنجی و انتشار OpenAPI — نسخه، ابزار، پایپلاین CI، فراداده، امنیت |\n\n**جریان اطلاعات از API تا کلاینت:**\n\n```\nBackend Service\n    │\n    └── OpenAPI 3.1 (بر اساس استاندارد طراحی API)\n          │\n          ▼ [nons registry build]\n    Registry (.nons/registry/{service}/manifest.json)\n          │\n          ▼ [nons generate]\n    Generated Artifacts (.nons/generated/)\n          │\n          ▼\n    Project Code (Hooks, API Client, Types)\n```\n\nبرای جزئیات فرآیند یکپارچه‌سازی کلاینت به [ADR-Platform-004](./ADR/ADR-Platform-004) و [راهنمای مدیریت قراردادها با CLI (nons)](./package/nons-ContractManagement-guide) مراجعه کنید.\n\n---"
    },
    {
      "level": 2,
      "heading": "لایه قراردادها (Contract Layer)",
      "content": "`nons-api/contracts/`\n\nقراردادهای مشترک پلتفرم در قالب **Protocol Buffers** در `nons-api/contracts/` تعریف می‌شوند. این لایه منبع حقیقت (Source of Truth) برای قراردادهای پلتفرم است. هیچ زبانی مالک قراردادها نیست — Proto مصرف‌کننده نهایی را تعیین نمی‌کند. Bindingها از طریق Buf در CI تولید و به صورت Artifact توزیع می‌شوند.\n\n```text\nnons-api/contracts/\n├── envelope.proto      # Event Envelope\n├── registry.proto      # Service Registry\n├── errors.proto        # Platform Error Codes\n└── permissions.proto   # Permissions\n```"
    },
    {
      "level": 2,
      "heading": "پکیج‌های اشتراکی",
      "content": "`nons-api/packages/`\n\nپکیج‌های اشتراکی شامل Bindingهای تولیدشده از Proto و قراردادهای مستقل (Logging) هستند."
    },
    {
      "level": 3,
      "heading": "رویدادها",
      "content": "`nons-api/packages/events` (`@nons/events`)\n\nBindingهای Event Envelope تولیدشده از Proto. نام رویدادها و مستندات payload در Catalog (YAML/JSON) نگهداری می‌شوند."
    },
    {
      "level": 3,
      "heading": "قراردادها",
      "content": "`nons-api/packages/contracts` (`@nons/contracts`)\n\nBindingهای قراردادهای پلتفرم تولیدشده از Proto. شامل Error Codes و Permissions."
    },
    {
      "level": 3,
      "heading": "لاگینگ (قرارداد ثبت وقایع)",
      "content": "`nons-api/packages/logging` (`@nons/logging`)\n\nقرارداد ثبت وقایع پلتفرم — نه پیاده‌سازی نهایی. این پکیج شامل types و interfaces است و در Proto تعریف نمی‌شود (خارج از محدوده ADR-Platform-001). سرویس‌ها در انتخاب کتابخانه لاگر آزاد هستند، اما خروجی نهایی باید با قرارداد این پکیج مطابقت داشته باشد."
    },
    {
      "level": 3,
      "heading": "مصنوعات تولیدشده توسط CLI",
      "content": "پلتفرم NONS ابزار رسمی **`nons`** را ارائه می‌دهد. `nons` مصنوعات پروژه‌محور را برای فریم‌ورک هدف تولید می‌کند. برای جزئیات به [ADR-Platform-004](./ADR/ADR-Platform-004) و [راهنمای مدیریت قراردادها با CLI (nons)](./package/nons-ContractManagement-guide) مراجعه کنید.\n\n**جریان یکپارچه‌سازی:**\n\n```\nBackend Service\n    │\n    └── openapi.yaml\n          │\n          ▼ [nons registry build user]\n    .nons/registry/user/manifest.json (Service Manifest)\n          │\n          ▼ [nons generate]\n    .nons/generated/\n      ├── types/user.ts\n      ├── api-client/user.ts\n      └── hooks/useUsers.ts\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "سرویس‌ها",
      "content": "`nons-api/services/`\n\nهر سرویس مسئول یک حوزه مشخص از سیستم بوده و مالک کامل داده‌ها، قوانین و منطق تجاری مربوط به همان حوزه است.\n\n---"
    },
    {
      "level": 2,
      "heading": "هویت و کنترل دسترسی",
      "content": "**Identity & Access Layer**\n\nاین لایه مسئول شناسایی کاربران، مدیریت دسترسی‌ها و اعمال سیاست‌های امنیتی در کل پلتفرم است."
    },
    {
      "level": 3,
      "heading": "احراز هویت",
      "content": "لایه احراز هویت NONS از سه مؤلفه مجزا تشکیل شده است:"
    },
    {
      "level": 4,
      "heading": "Ory Kratos — مدیریت هویت",
      "content": "`nons-api/services/auth-service` (از سرویس آماده **Ory Kratos** استفاده می‌کند)\n\nمسئول مدیریت هویت کاربران (Identity Management):\n- ایجاد خودکار هویت (Auto Sign-Up) در اولین ورود\n- ورود (Login) با Magic Code و Google OIDC\n- بازیابی حساب (Recovery)\n- مدیریت Credentialها (Magic Code, OIDC, MFA در آینده)\n- نشست‌های کاربری (Sessions)\n- ارسال ایمیل‌های Magic Code و تایید از طریق SMTP اختصاصی NONS\n\n> **نکته:** Kratos یک ابزار آماده (off-the-shelf) است و از صفر توسعه داده نمی‌شود. تیم باید از قابلیت‌های آماده Kratos استفاده کند و توسعه اختصاصی روی آن انجام ندهد.\n>\n> **روش‌های احراز هویت فعال در MVP:** `code` (Magic Code) و `oidc` (Google Login). روش `password` و `oidc/discord` غیرفعال هستند."
    },
    {
      "level": 4,
      "heading": "Auth Service — واسط و مدیریت نشست کاربری",
      "content": "`nons-api/services/auth-service` (سرویس اختصاصی NONS — Go Auth Service)\n\nسرویس اختصاصی NONS که وظیفه ارائه رابط کاربری و هماهنگی نشست‌ها را بر عهده دارد:\n\n- **مدیریت فلو ورود و ثبت‌نام یکپارچه:** پیاده‌سازی فرم یکپارچه ورود/ثبت‌نام، بررسی وضعیت نشست کاربری و هدایت کاربران بر پایه متد Code (ارسال کدهای OTP یکبار مصرف) و Google OIDC در Ory Kratos.\n- **ارائه صفحات محلی (Embedded UI):** رندرسازی و سرو صفحات وب احراز هویت (Login، Register، Dashboard و Error) به صورت داخلی.\n- **اعتبارسنجی نشست‌ها برای درگاه (ForwardAuth):** ارائه نقطه پایانی `/v1/auth/validate` جهت تأیید نشست‌های کوکی‌محور یا هدرهای سشن برای درگاه Traefik Gateway با استعلام مستقیم از Kratos.\n- **مدیریت وضعیت اونبوردینگ:** به‌روزرسانی مقدار `onboarded` در traits هویت کاربر پس از اولین ورود موفق از طریق Kratos Admin API.\n- **دریافت وب‌هوک‌های Kratos:** دریافت رویداد پس از ثبت‌نام Kratos در مسیر `/v1/auth/webhooks/kratos/register`.\n\n**این سرویس Stateless است** — فاقد دیتابیس مستقل بوده و مدیریت کامل داده‌های هویت و نشست‌ها به عهده Ory Kratos است."
    },
    {
      "level": 4,
      "heading": "Token Service — صدور و اعتبارسنجی توکن (Ory Hydra)",
      "content": "`nons-api/services/token-service` (از سرویس آماده **Ory Hydra** استفاده می‌کند)\n\nسرویس اختصاصی NONS که لایه صدور و اعتبارسنجی **توکن‌های API** (OAuth2/OIDC) را از لایه هویت/نشست جدا می‌کند:\n\n- **سرور OAuth2/OIDC:** صدور `access_token` (JWT)، `refresh_token` و `id_token` از طریق Hydra.\n- **تبدیل نشست Kratos به توکن:** اجرای جریان Login & Consent از طریق `login-consent-app` که نشست Kratos را با استعلام `GET /sessions/whoami` تأیید می‌کند.\n- **افشای JWKS:** انتشار کلیدهای عمومی در `/.well-known/jwks.json` جهت اعتبارسنجی stateless توکن توسط میکروسرویس‌ها (بدون تماس شبکه‌ای هر بار — کلیدها cache می‌شوند).\n- **ابطال توکن:** پشتیبانی از `refresh_token rotation`، `/oauth2/revoke` و `/oauth2/sessions/logout`.\n- **دیتابیس مجزا:** Hydra دیتابیس اختصاصی (جدا از Kratos) برای client، consent و grants دارد تا coupling نداشته باشد.\n\n> **نکته:** میکروسرویس‌ها توکن را به‌صورت **stateless و محلی** با استفاده از JWKS اعتبارسنجی می‌کنند و به Hydra Admin API دسترسی ندارند (فقط JWKS عمومی). Kratos Admin API و Hydra Admin API صرفاً در شبکه داخلی در دسترس هستند.\n>\n> 📖 مطالعه کامل: [Blueprint سرویس Token](../backend/services/token-service)"
    },
    {
      "level": 4,
      "heading": "Login-Consent App — واسط مستقل Login & Consent (Go)",
      "content": "`nons-api/services/login-consent-app` (سرویس اختصاصی NONS — Go)\n\nسرویس مستقل (مانند auth-service و iam-service) که طبق الگوی رسمی Ory بین **Hydra** (token-service) و **Kratos** (auth-service) قرار می‌گیرد و **تنها کد اختصاصی** در حوزه توکن است:\n\n- **واسط Login & Consent:** دریافت `login_challenge`، استعلام نشست Kratos با `GET /sessions/whoami` (forward کوکی `ory_kratos_session`)، سپس accept کردن Login/Consent Request در Hydra Admin با `subject = <kratos-identity-id>`.\n- **Token Hook:** endpoint `/token-hook` که پیش از صدور توکن توسط Hydra فراخوانی می‌شود تا claims (نقش از iam-service) را غنی‌سازی کند.\n- **ایزوله‌سازی Admin API:** طبق NetworkPolicy، **تنها Pod مجاز** به دسترسی به Hydra Admin (port 4445) است.\n\n> این سرویس بخشی از token-service یا auth-service نیست؛ به صورت مستقل در `services/login-consent-app/` توسعه، استقرار و مقیاس‌پذیر می‌شود.\n>\n> 📖 مطالعه کامل: [سرویس Login-Consent App](../backend/services/login-consent-app)"
    },
    {
      "level": 3,
      "heading": "احراز هویت مشتریان (KYC)",
      "content": "`nons-api/services/kyc-service`\n\nسرویس احراز هویت مشتریان (Know Your Customer) مسئول تأیید هویت کاربران پیش از انجام معاملات حساس است. این سرویس شامل موارد زیر است:\n\n- **تأیید هویت** — بررسی مدارک هویتی (کارت ملی، پاسپورت)\n- **تأیید آدرس** — تأیید محل سکونت کاربر\n- **تأیید شماره تلفن** — تأیید شماره تلفن همراه\n- **تأیید ایمیل** — تأیید آدرس ایمیل\n- **سطوح احراز هویت** — سطوح مختلف KYC (پایه، پیشرفته، حرفه‌ای)\n- **مدیریت وضعیت** — وضعیت احراز هویت کاربران (تأیید شده، در انتظار، رد شده)\n- **مدیریت محدودیت‌ها** — اعمال محدودیت بر اساس سطح احراز هویت\n\n> این سرویس پس از احراز هویت اولیه (Auth Service) فعالیت می‌کند و مسئول تأیید هویت دقیق‌تر کاربران برای معاملات مالی و حساس است."
    },
    {
      "level": 3,
      "heading": "دسترسی و مجوز ها",
      "content": "`nons-api/services/iam-service`\n\nمرکز حکمرانی دسترسی‌ها و قوانین سامانه است. نقش‌ها (Roles)، قابلیت‌ها (Capabilities)، مجوزها (Permissions)، طرح‌های اشتراک (Plans)، امتیازات ویژه (Entitlements)، محدودیت‌ها، وضعیت کاربران و سیاست‌های دسترسی در این سرویس مدیریت می‌شوند. همچنین تمامی تغییرات امنیتی و مدیریتی برای اهداف حسابرسی ثبت می‌گردند.\n\n> 📖 مطالعه کامل: [Blueprint سرویس IAM](../backend/services/iam-service.md)\n\n> **مرز مسئولیت IAM:** سرویس IAM فقط مالک **Authorization** است: Role، Permission، Access Policy.\n>\n> اطلاعات پروفایل کاربر (preferred_currency، نام نمایشی، Avatar، Username) در **User Service** نگهداری می‌شود.\n> preferred_currency از طریق API داخلی **User Service** در دسترس payment-service قرار می‌گیرد."
    },
    {
      "level": 4,
      "heading": "مدل مالکیت خط‌مشی (Policy Ownership)",
      "content": "هر سرویس کسب‌وکاری مالک قوانین و Business Rules خود است. IAM خط‌مشی‌های حاکمیتی را نگهداری می‌کند اما منطق کسب‌وکار را اجرا نمی‌کند.\n\n```\nهر سرویس:\n  ۱. Permissions مورد نیاز خود را تعریف می‌کند\n  ۲. در IAM ثبت می‌کند (Permission Contract)\n  ۳. در زمان اجرا از POST /v1/iam/authorization/check استفاده می‌کند\n  ۴. Business Rules خود را خودش اجرا می‌کند\n```\n\n> 📖 مطالعه کامل: [استاندارد قرارداد مجوز](./standards/permission-contract-standard.md)"
    },
    {
      "level": 4,
      "heading": "جریان بررسی مجوز",
      "content": "```\nBusiness Service → POST /v1/iam/authorization/check { userId, action }\n                ← 200: { allowed: true/false, reason: \"...\" }\n```\n\nسرویس‌ها هرگز مستقیماً به دیتابیس IAM دسترسی ندارند. تمام بررسی‌ها از طریق API انجام می‌شود."
    },
    {
      "level": 4,
      "heading": "CommissionRule و ارتباط با settlement-service",
      "content": "سطوح کمیسیون فروشنده در IAM تعریف می‌شوند:\n\n```typescript\ninterface CommissionRule {\n  sellerTier: \"standard\" | \"premium\" | \"enterprise\";\n  rate: number; // درصد کمیسیون\n  minAmountUsd: number;\n  maxAmountUsd: number;\n}\n```\n\nsettlement-service برای محاسبه کمیسیون هر سفارش، tier فروشنده را از IAM دریافت می‌کند."
    },
    {
      "level": 4,
      "heading": "مجوزهای مالی جدید",
      "content": "| مجوز                        | توضیح                       |\n| --------------------------- | --------------------------- |\n| `can_withdraw`              | اجازه برداشت از کیف پول     |\n| `can_settle`                | اجازه درخواست تسویه دستی    |\n| `can_view_financial_report` | اجازه مشاهده صورت‌حساب مالی |"
    },
    {
      "level": 4,
      "heading": "محدودیت‌های KYC",
      "content": "| سطح KYC         | سقف برداشت روزانه | سقف تسویه        |\n| --------------- | ----------------- | ---------------- |\n| سطح ۱ (پایه)    | ۵۰۰,۰۰۰ تومان     | ۱,۰۰۰,۰۰۰ تومان  |\n| سطح ۲ (پیشرفته) | ۵,۰۰۰,۰۰۰ تومان   | ۱۰,۰۰۰,۰۰۰ تومان |\n| سطح ۳ (حرفه‌ای) | بدون محدودیت      | بدون محدودیت     |"
    },
    {
      "level": 3,
      "heading": "سرویس کاربر",
      "content": "`nons-api/services/user-service`\n\nمسئول مدیریت اطلاعات مرتبط با تجربه کاربری و پروفایل است. این سرویس منبع حقیقت برای:\n\n- **پروفایل کاربر** — Display Name، Avatar، Username\n- **شناسه عمومی (Public ID)** — جایگزین ایمن UUID در فضای عمومی\n- **تنظیمات شخصی** — `preferred_currency`، تم و زبان کاربر\n\n| سوال | جواب |\n|---------|--------|\n| **این شخص کیست؟** | Auth Service / Kratos |\n| **چطور نمایش داده شود؟** | **User Service** |\n| **چه کاری اجازه دارد؟** | IAM Service |\n| **چه سطح خدماتی دارد؟** | Billing Service |\n\nاین سرویس **Stateful** است و دیتابیس PostgreSQL مستقل دارد.\n\nبرای جزئیات کامل: [User Service Blueprint](../backend/services/user-service)"
    },
    {
      "level": 3,
      "heading": "بررسی مجوزها",
      "content": "`nons-api/services/iam-service`\n\nتمامی بررسی‌های مجوز از طریق IAM Service و با API `POST /v1/iam/authorization/check` انجام می‌شود. سرویس‌های کسب‌وکاری در زمان اجرا مجوز کاربر را از IAM می‌پرسند.\n\n```\nBusiness Service → POST /v1/iam/authorization/check { userId, action }\n                ← 200: { allowed: true/false, reason: \"...\" }\n```\n\n> **نکته:** معماری اولیه از Ory Keto استفاده می‌کرد اما در نسخه نهایی، Policy Engine داخلی IAM جایگزین آن شد. سرویس `keto-service` منسوخ شده است.\n\n---"
    },
    {
      "level": 2,
      "heading": "هسته کسب‌وکار",
      "content": "**Core Business Layer**\n\nاین لایه مسئول اجرای فرآیندهای اصلی بازار و مدیریت چرخه کامل معاملات است."
    },
    {
      "level": 3,
      "heading": "مارکت پلیس",
      "content": "`nons-api/services/marketplace-service`\n\nمدیریت محصولات، فروشگاه‌ها، موجودی‌ها و کالاهای خودکار را بر عهده دارد. هر محصول دارای نسخه‌بندی بوده و هنگام خرید، یک Snapshot از وضعیت محصول ثبت می‌شود تا در آینده برای بررسی اختلافات و حسابرسی قابل استناد باشد. نام فروشگاه‌ها یکتا و تغییرناپذیر است."
    },
    {
      "level": 3,
      "heading": "سفارشات",
      "content": "`nons-api/services/order-service`\n\nمسئول مدیریت چرخه کامل سفارش از زمان ایجاد تا تکمیل یا لغو است. هر سفارش Snapshot نسخه خریداری‌شده محصول را نگهداری می‌کند تا از تغییرات بعدی مستقل باشد. Order فقط نماینده «فرآیند تجاری معامله» است و هیچ اطلاعی از escrow، wallet یا balance ندارد.\n\nوضعیت‌های سفارش: `CREATED` → `ACTIVE` → `COMPLETED` | `CANCELLED` | `DISPUTED`"
    },
    {
      "level": 3,
      "heading": "پرداخت",
      "content": "`nons-api/services/payment-service`\n\nمدیریت پرداخت امن و Escrow را بر عهده دارد. Payment فقط مسئول دریافت پول از کاربر، نگهداری پول در حالت Escrow و آزادسازی یا برگشت پول به Wallet است. Payment **مالک پول نیست** — Wallet تنها منبع حقیقت موجودی مالی کاربران است.\n\nوضعیت‌های پرداخت: `PENDING` → `ESCROW_HELD` → `RELEASED` | `REFUNDED`"
    },
    {
      "level": 3,
      "heading": "چت آنلاین",
      "content": "`nons-api/services/chat-service`\n\nزیرساخت ارتباط چت آنلاین میان کاربران را فراهم می‌کند. پیام‌ها قابل ویرایش نیست . این داده‌ها به عنوان بخشی از سوابق رسمی معامله نگهداری شده و در فرآیند داوری قابل استناد هستند."
    },
    {
      "level": 3,
      "heading": "کیف پول",
      "content": "`nons-api/services/wallet-service`\n\nتنها منبع حقیقت (Source of Truth) برای موجودی مالی کاربران. مسئول نگهداری balance، ثبت تراکنش‌های مالی (Ledger)، مدیریت برداشت و درآمد فروشندگان. Wallet مستقیماً با Payment Service در تعامل است و پول را فقط پس از آزادسازی از Escrow جابه‌جا می‌کند."
    },
    {
      "level": 3,
      "heading": "ارز",
      "content": "`nons-api/services/currency-service`\n\nتنها مرجع نرخ ارز و تبدیل مبلغ در کل پلتفرم. هر سرویسی که نیاز به تبدیل ارز دارد فقط با این سرویس صحبت می‌کند. نرخ‌ها از منابع خارجی (Nobitex، fixer.io) دریافت و در Redis cache می‌شوند (هر ۵ دقیقه یک‌بار). تبدیل مبلغ با rounding صحیح و مدیریت precision انجام می‌شود.\n\nAPI: `GET /rates` (نرخ خام)، `POST /convert` (تبدیل مبلغ)"
    },
    {
      "level": 3,
      "heading": "تسویه",
      "content": "`nons-api/services/settlement-service`\n\nمدیریت چرخه مالی پس از تحویل سفارش: محاسبه کمیسیون پلتفرم بر اساس seller_tier (standard ۱۰٪، premium ۷٪، enterprise ۵٪)، انتقال سهم فروشنده از escrow به seller_wallet از طریق TigerBeetle، تسویه دوره‌ای خودکار (هفتگی/ماهانه) و دستی، و مدیریت refund و برگشت وجه.\n\nرویدادهای دریافتی: `order.delivered.v1`, `order.cancelled.v1`, `dispute.resolved.v1`\nرویدادهای خروجی: `settlement.completed.v1`, `refund.initiated.v1`, `commission.calculated.v1`\n\n> برای جزئیات کامل چرخه فروش به [استاندارد چرخه فروش و تسویه](./order-payment-wallet-flow) مراجعه کنید.\n\n---"
    },
    {
      "level": 2,
      "heading": "عملیات و نظارت",
      "content": "**Operations Layer**\n\nاین لایه مسئول اعتماد، اعتبار، نظارت و پایداری اکوسیستم بازار است."
    },
    {
      "level": 3,
      "heading": "داوری",
      "content": "`nons-api/services/dispute-service`\n\nمدیریت اختلافات میان خریدار و فروشنده را بر عهده دارد. این سرویس شواهد مورد نیاز را از سایر سرویس‌ها جمع‌آوری کرده، پرونده را به داور اختصاص داده و پس از صدور رأی، نتیجه را اجرا می‌کند."
    },
    {
      "level": 3,
      "heading": "حوزه تخصصی",
      "content": "`nons-api/services/zone-service`\n\nمسئول ایجاد و مدیریت ساختار حوزه تخصصی فروشندگان است. این سرویس اطلاعات مورد نیاز را از سایر سرویس‌ها جمع‌آوری میکنه و بر اساس فعالیت واقعی کاربران، میزان تخصص، اعتبار و جایگاه آنان را در حوزه‌های مختلف محاسبه میکنه. زون ها هویت تخصصی فروشندگان را نمایش می‌دهند و حاصل عملکرد واقعی آنها در پلتفرم هستند."
    },
    {
      "level": 3,
      "heading": "بازخورد",
      "content": "`nons-api/services/review-service`\n\nمدیریت بازخوردها و ارزیابی‌های کاربران پس از تکمیل سفارش را انجام می‌دهد. ثبت نظر، نمایش امتیازات، مدیریت درخواست بازبینی و نگهداری سوابق بازخوردها در این سرویس انجام می‌شود."
    },
    {
      "level": 3,
      "heading": "نظارت",
      "content": "`nons-api/services/moderation-service`\n\nبه صورت کلی روی جریان رویدادهای سامانه فعالیت می‌کند و مسئول نظارت و شناسایی رفتارهای مشکوک، تخلفات و محتوای نامناسب است. در صورت تشخیص تخلف، پیشنهاد اعمال محدودیت یا تغییر وضعیت کاربر را به IAM ارسال می‌کند.\n\n---"
    },
    {
      "level": 2,
      "heading": "کشف و رشد",
      "content": "**Discovery & Growth Layer**\n\nاین لایه مسئول افزایش دیده‌شدن محصولات و بهبود فرصت‌های فروش در بازار است."
    },
    {
      "level": 3,
      "heading": "بوست",
      "content": "`nons-api/services/boost-service`\n\nسیستم تبلیغات و ارتقای نمایش محصولات را مدیریت می‌کند. رتبه‌بندی تبلیغات بر اساس مدل رقابتی انرژی انجام شده و هر ارتقا دارای مدت اعتبار مشخص است. نتایج فعال در فرآیند جستجو و نمایش محصولات لحاظ می‌شوند."
    },
    {
      "level": 3,
      "heading": "جستجو",
      "content": "`nons-api/services/search-service`\n\nسرویس مستقل جستجو با Elasticsearch. مسئول ایندکس‌سازی محصولات، full-text search، فیلترها و رتبه‌بندی ترکیبی. ایندکس از رویدادهای سایر سرویس‌ها ساخته می‌شود و هیچ دسترسی مستقیم به دیتابیس سرویس‌های دیگر ندارد."
    },
    {
      "level": 4,
      "heading": "فیلتر قیمتی پویا با ارز کاربر",
      "content": "برای فیلتر محصولات بر اساس محدوده قیمت در ارز کاربر، search-service از currency-service استفاده می‌کند:\n\n```text\nکاربر با preferred_currency = \"IRR\" فیلتر «کمتر از ۵۰۰,۰۰۰ تومان» را اعمال می‌کند\n  → search-service از currency-service می‌خواهد:\n     POST /convert { amount: 500000, from: \"IRR\", to: \"USD\" }\n  → نتیجه: ~$5.88\n  → ایندکس Elasticsearch روی price_usd_cents فیلتر می‌شود\n```\n\n`price_usd_cents` در ایندکس Elasticsearch ذخیره می‌شود تا فیلتر بر اساس آن امکان‌پذیر باشد.\n\n---"
    },
    {
      "level": 2,
      "heading": "سرویس‌های زیرساختی",
      "content": "**Utility Services**\n\nاین سرویس‌ها قابلیت‌های عمومی مورد نیاز سایر بخش‌های پلتفرم را فراهم می‌کنند."
    },
    {
      "level": 3,
      "heading": "اعلانات",
      "content": "`nons-api/services/notification-service`\n\nمسئول ارسال اعلان‌های داخلی، ایمیل‌های تراکنشی و پیام‌های اطلاع‌رسانی از طریق کانال‌های مختلف است. این سرویس صرفاً مصرف‌کننده رویدادها بوده و هیچ منطق تجاری مستقلی ندارد."
    },
    {
      "level": 3,
      "heading": "فضای ذخیره",
      "content": "`nons-api/services/storage-service`\n\nمدیریت فایل‌ها، رسانه‌ها و داده‌های مرتبط با محصولات خودکار و مدیا ها را بر عهده دارد. دسترسی به فایل‌ها از طریق لینک‌های موقت و امضاشده (Signed URL) یا لینک های عمومی مدیریت میکند تا امنیت و محدودیت دسترسی قابل کنترل گردد."
    },
    {
      "level": 3,
      "heading": "استخر داده‌های مرجع (Pool Service)",
      "content": "`nons-api/services/pool-service`\n\nسرویس متمرکز مدیریت **داده‌های مرجع (Reference Data)** و مواد اولیه تولید. تنها منبع حقیقت لیست‌های ایستا و مشترک شامل: مواد اولیه تولید Username (adjectives/nouns)، آواتارهای پیش‌فرض، نام‌ها و الگوهای رزرو شده (Reserved)، کلمات نامناسب، لیست کشورها/زبان‌ها، و اطلاعات مرجع ارز (کد/نام/نماد/دقت).\n\nاین سرویس **هیچ داده عملیاتی نگهداری نمی‌کند**؛ صرفاً داده مرجع را تعریف و نگهداری می‌کند و اجرا/تولید بر عهده Consumer (مانند user-service) است. در نسخه فعلی (MVP) فایل‌های Asset به‌صورت موقت در Pool نگهداری می‌شوند و در معماری نهایی به Storage Service منتقل خواهند شد (Pool تنها متادیتا و Reference را حفظ می‌کند).\n\n> 📖 مطالعه کامل: [Blueprint سرویس Pool](../backend/services/pool-service/blueprint.md)"
    },
    {
      "level": 3,
      "heading": "تحلیل",
      "content": "`nons-api/services/analytics-service`\n\nسیستم تحلیل و گزارش‌گیری کل پلتفرم. Read-only است و فقط از Event Stream تغذیه می‌شود. شامل گزارش فروشندگان، داشبورد مدیریتی و تحلیل رفتار خریدار.\n\n---"
    },
    {
      "level": 2,
      "heading": "زیرساخت و معماری استقرار",
      "content": "**Infrastructure & Deployment Architecture**\n\nاین بخش شامل تنظیمات و ابزارهای مورد نیاز برای اجرای محیط‌های توسعه، آزمایش و عملیاتی پلتفرم NONS است. بستر اصلی و رسمی اجرای پلتفرم بر پایه **Kubernetes (K3s/K3d)** طراحی شده است."
    },
    {
      "level": 3,
      "heading": "ساختار پوشه استقرار (Deployment Directory Structure)",
      "content": "تمامی دارایی‌ها، اسکریپت‌ها و فایل‌های مربوط به استقرار پروژه در پوشه `deploy/` در روت اصلی سازمان‌دهی می‌شوند:\n```text\ndeploy/\n├── helm/                    # چارت‌های Helm برای میکروسرویس‌ها و متعلقات\n├── environments/            # پیکربندی محیط‌های مختلف\n│   ├── local/               # تنظیمات مخصوص توسعه محلی\n│   ├── staging/             # تنظیمات محیط تست و پیش‌تولید\n│   └── production/          # تنظیمات نهایی عملیاتی (Production)\n├── scripts/                 # اسکریپت‌های راه‌اندازی و اتوماسیون استقرار\n└── docs/                    # مستندات و راهنماهای مرتبط با DevOps و Deployment\n```"
    },
    {
      "level": 3,
      "heading": "بستر استقرار: Kubernetes-Native First Architecture (D13)",
      "content": "- **مسیر رسمی توسعه و استقرار:** کلاستر کوبرنتیز مبتنی بر توزیع سبک **K3s** بستر رسمی استقرار پلتفرم NONS در محیط‌های عملیاتی و پیش‌ تولید است. کلاستر محلی **K3d** نیز تنها مسیر رسمی و استاندارد توسعه و تست‌های محلی می‌باشد."
    },
    {
      "level": 3,
      "heading": "استاندارد استقرار: Helm as Deployment Standard (D15)",
      "content": "استقرار رسمی کلیه میکروسرویس‌ها در محیط کلاستر صرفاً از طریق ابزار **Helm** انجام می‌شود. چارت‌های استقرار کلیه منابع زیر را مدیریت می‌کنند:\n- `Deployment` و `Service` برای فرآیندهای ران‌تایم\n- `Ingress` جهت کنترل ترافیک ورودی\n- `Secret` و `ConfigMap` جهت مدیریت پیکربندی‌ها\n- `HPA (Horizontal Pod Autoscaler)` برای مقیاس‌پذیری خودکار"
    },
    {
      "level": 3,
      "heading": "استراتژی کشف سرویس (Service Discovery Strategy - D17)",
      "content": "کشف سرویس‌ها و مسیریابی ترافیک به صورت Kubernetes-Native مدیریت می‌شود:\n- **مسیر رسمی (Kubernetes-Native):** در کل محیط‌های رسمی (کلاستر محلی K3d برای توسعه و کلاستر K3s برای پروداکشن)، کشف سرویس به صورت پویا از طریق Traefik Ingress Controller و با استفاده از منابع استاندارد Kubernetes Ingress / IngressRoute CRD انجام می‌شود."
    },
    {
      "level": 3,
      "heading": "نقشه راه مدیریت رازها (Secrets Management Roadmap - D18)",
      "content": "- **فاز فعلی (MVP):** تمامی کلیدها، پسوردها و داده‌های حساس از طریق **Kubernetes Secrets** به صورت ایمن مدیریت و به کانتینرها تزریق می‌شوند.\n- **فاز آینده (Advanced):** انتقال سیستم مدیریت رازها به ابزار پیشرفته **HashiCorp Vault** در نقشه راه آینده پروژه پیش‌بین شده است."
    },
    {
      "level": 3,
      "heading": "ابزارهای مشترک توسعه محلی",
      "content": ""
    },
    {
      "level": 4,
      "heading": "TigerBeetle — Ledger مالی",
      "content": "دفترکل تراکنش‌های مالی با double-entry accounting. حساب‌های مجزا: `buyer_wallet`, `seller_wallet`, `escrow`, `platform_revenue`, `platform_fees`, `refund_pool`. مکانیزم Hold/Release داخلی برای escrow: پرداخت → PENDING, تأیید → RELEASE, لغو → VOID."
    },
    {
      "level": 4,
      "heading": "Redis — کش نرخ ارز و محدودیت نرخ",
      "content": "ذخیره‌سازی موقت نرخ‌های ارز دریافتی از منابع خارجی و شمارنده‌های Rate Limiting درگاه API Gateway.\n\n---"
    },
    {
      "level": 2,
      "heading": "اصول معماری",
      "content": "**Architecture Principles**\n\n- هر سرویس مالک کامل داده‌ها و منطق تجاری خود است.\n- ارتباط میان سرویس‌ها صرفاً از طریق Contract و Event انجام می‌شود.\n- هیچ سرویسی به پایگاه داده سرویس دیگر دسترسی مستقیم ندارد.\n- احراز هویت از مدیریت دسترسی و مجوزها جدا نگه داشته شده است.\n- تمامی تراکنش‌های مالی قابلیت حسابرسی کامل دارند.\n- سوابق گفتگوها و اسناد معامله تغییرناپذیر هستند.\n- تمامی سرویس‌ها قابلیت استقرار و مقیاس‌پذیری مستقل دارند.\n- طراحی سیستم بر مبنای توسعه تدریجی، نگهداری بلندمدت و تحمل خطا انجام شده است.\n- قرارداد ثبت وقایع (Logging Contract) از پیاده‌سازی لاگر جدا است. سرویس‌ها آزادند اما باید با استاندارد یکسان لاگ‌نویسی کنند."
    }
  ]
}