{
  "title": "بلوپرینت درگاه API Gateway",
  "slug": "team/platform/gateway/blueprint",
  "url": "/docs/team/platform/gateway/blueprint",
  "frontmatter": {
    "layout": "doc",
    "title": "بلوپرینت درگاه API Gateway",
    "description": "بلوپرینت معماری، استراتژی‌ها، امنیت، قابلیت مشاهده و دیاگرام‌های توالی درگاه API Gateway",
    "version": "1.0.0",
    "status": "BLUEPRINT",
    "author": "Antigravity",
    "owner": "Platform Team",
    "created_at": "2026-06-14",
    "updated_at": "2026-06-14",
    "tags": "",
    "reviewers": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "بلوپرینت درگاه API Gateway",
      "content": "**API Gateway Service Blueprint**\n\n> **Blueprint v1.0 — پیش از توسعه**\n\n---"
    },
    {
      "level": 2,
      "heading": "فهرست محتوا",
      "content": "**Table of Contents**\n\n1. [اهداف سرویس](#۱-اهداف-سرویس)\n2. [مسئولیت‌ها](#۲-مسئولیت‌ها)\n3. [خارج از مسئولیت‌ها (Non-Goals)](#۳-خارج-از-مسئولیت‌ها-non-goals)\n4. [معماری ران‌تایم و وابستگی‌ها](#۴-معماری-ران‌تایم-و-وابستگی‌ها)\n5. [استراتژی مسیریابی (Routing Strategy)](#۵-استراتژی-مسیریابی-routing-strategy)\n6. [یکپارچگی با احراز هویت (Authentication Integration Flow)](#۶-یکپارچگی-با-احراز-هویت-authentication-integration-flow)\n7. [مدل امنیتی (Security Model)](#۷-مدل-امنیتی-security-model)\n8. [استراتژی قابلیت مشاهده (Observability Strategy)](#۸-استراتژی-قابلیت-مشاهده-observability-strategy)\n9. [استراتژی مدیریت خطا (Error Handling Strategy)](#۹-استراتژی-مدیریت-خطا-error-handling-strategy)\n10. [دیاگرام‌های توالی (Sequence Diagrams)](#۱۰-دیاگرام‌های-توالی-sequence-diagrams)\n\n---"
    },
    {
      "level": 2,
      "heading": "۱. اهداف سرویس",
      "content": "**Service Objectives**\n\nسرویس درگاه API Gateway به عنوان **تنها نقطه ورود رسمی** برای تمام کلاینت‌ها (Frontend, Mobile App, Third-party) عمل می‌کند. هدف اصلی این سرویس، یکپارچه‌سازی نقاط دسترسی کلاینت به میکروسرویس‌ها، پنهان کردن پیچیدگی‌های توپولوژی شبکه داخلی بک‌اند، و پیاده‌سازی عملکردهای زیرساختی مشترک به شیوه‌ای متمرکز و با کارایی بالا است.\n\n---"
    },
    {
      "level": 2,
      "heading": "۲. مسئولیت‌ها",
      "content": "**Responsibilities**\n\n- **مسیریابی هوشمند (Routing):** هدایت ترافیک ورودی به میکروسرویس‌های متناظر بر اساس الگوهای مشخص آدرس.\n- **اعتبارسنجی توکن دسترسی (Stateless JWT Validation):** بررسی صحت امضا، انقضا و کلایم‌های اصلی توکن دسترسی با استفاده از کلیدهای عمومی JWKS که توسط **Token Service (Ory Hydra)** منتشر می‌شود.\n- **تزریق هدرهای هویتی:** اضافه کردن هدرهای امن کاربر (مانند `X-User-Id` و `X-User-Roles`) پس از احراز هویت موفق جهت مصرف در سرویس‌های بالادستی.\n- **تولید و انتشار Correlation ID:** بررسی وجود `X-Correlation-ID` در هدرها و ایجاد آن در صورت عدم وجود، جهت ایجاد قابلیت پیگیری تراکنش‌ها در سیستم توزیع‌شده.\n- **مدیریت CORS:** پاسخ‌دهی متمرکز به درخواست‌های Preflight (OPTIONS) و مدیریت دسترسی‌های دامنه‌ها.\n- **اعمال نرخ درخواست (Rate Limiting):** محدود کردن تعداد درخواست‌های هر کاربر/IP به منظور جلوگیری از حملات Brute Force و سوءاستفاده از سیستم.\n- **امنیت لبه (Security Headers):** تزریق هدرهای امنیتی استاندارد مانند HSTS, CSP, X-Frame-Options و X-Content-Type-Options.\n- **مدیریت خطاهای انتقال (Gateway Errors):** تولید ساختار خطای استاندارد و یکپارچه در زمان‌های قطعی سرویس‌های بالادست (502 Bad Gateway) یا Timeout (504).\n\n---"
    },
    {
      "level": 2,
      "heading": "۳. خارج از مسئولیت‌ها (Non-Goals)",
      "content": "**Non-Responsibilities**\n\n- **منطق کسب‌وکار (Business Logic):** درگاه هیچ اطلاعی از سفارش‌ها، تراکنش‌های مالی، کاتالوگ محصولات یا چت‌ها ندارد.\n- **ارزیابی مجوزهای دسترسی (Permission Evaluation):** بررسی اینکه آیا کاربر حق دسترسی به رکورد خاصی را دارد یا خیر، بر عهده IAM Service است (از طریق `POST /v1/iam/authorization/check`)؛ درگاه فقط نقش‌ها و صحت توکن کاربر را احراز می‌کند.\n- **اعتبارسنجی داده‌های ورودی (Domain Validation):** بررسی صحت ساختار داده‌ها (مانند فرمت ایمیل یا قیمت مثبت) وظیفه سرویس مقصد است.\n- **پایداری داده‌ها (State Persistence):** درگاه کاملاً بدون حالت (Stateless) است و هیچ داده‌ای را در دیتابیس محلی ذخیره نمی کند (از Redis صرفاً به عنوان کش و مدیریت Rate Limiting استفاده می‌کند).\n\n---"
    },
    {
      "level": 2,
      "heading": "۴. معماری ران‌تایم و وابستگی‌ها",
      "content": "**Runtime Architecture & Dependencies**\n\nدرگاه API Gateway پلتفرم NONS بر پایه **Traefik v3** راه‌اندازی می‌شود."
    },
    {
      "level": 3,
      "heading": "ارتباطات فیزیکی لایه لبه (Network Edge Topology)",
      "content": "```mermaid\ngraph TD\n    Client[\"Client (Browser / User)\"] -->|HTTPS (Port 443/80)| Gateway[\"API Gateway (Traefik)\"]\n    Gateway -->|Forward Auth /v1/auth/validate| AuthService[\"Auth Service\"]\n    AuthService -->|Validate Session| Kratos[\"Ory Kratos\"]\n    Gateway -->|Route /v1/orders/*| OrderService[\"Order Service\"]\n    Gateway -->|Route /v1/wallet/*| WalletService[\"Wallet Service\"]\n    Gateway -->|Route /v1/chat/*| ChatService[\"Chat Service\"]\n    Gateway -->|Route /v1/marketplace/*| MarketService[\"Marketplace Service\"]\n```"
    },
    {
      "level": 3,
      "heading": "وابستگی‌های سرویس (Service Dependencies)",
      "content": "| وابستگی | نقش | حیاتی (Critical) | توضیحات |\n| :---: | --- | :---: | --- |\n| **Kubernetes API** | کشف پویای سرویس‌ها | بله | در تمامی محیط‌های رسمی K3s/K3d از Kubernetes Ingress/CRD Provider استفاده می‌شود. |\n| **Auth Service** | اعتبارسنجی نشست‌ها | بله | برای تمامی مسیرهای محافظت‌شده (Protected Routes) نیاز است. |\n| **Redis** | مدیریت محدودیت نرخ | بله | برای ذخیره‌سازی شمارنده‌های محدودیت نرخ از روز اول (Day 1). |\n\n---"
    },
    {
      "level": 2,
      "heading": "۵. استراتژی مسیریابی (Routing Strategy)",
      "content": "**Routing Strategy**\n\nمسیریابی درگاه بر اساس ساختار استاندارد آدرس‌های پلتفرم انجام می‌شود:"
    },
    {
      "level": 3,
      "heading": "الگوهای مسیردهی (Path Patterns)",
      "content": "هر سرویس مسیر مشخص خود را در درگاه تصاحب می‌کند. تمامی مسیرها با `/v{version}` آغاز می‌شوند:\n\n| الگو در درگاه | سرویس بالادستی (Upstream Service) | دسترسی |\n| --- | --- | :---: |\n| `/v1/auth/kratos/*` | `Ory Kratos` (Public/Admin APIs) | عمومی |\n| `/v1/auth/*` | `Auth Service` | عمومی |\n| `/v1/marketplace/*` | `Marketplace Service` | عمومی / احراز هویت‌شده |\n| `/v1/orders/*` | `Order Service` | احراز هویت‌شده |\n| `/v1/wallet/*` | `Wallet Service` | احراز هویت‌شده |\n| `/v1/chat/*` | `Chat Service` | احراز هویت‌شده |"
    },
    {
      "level": 3,
      "heading": "کشف پویای سرویس‌ها (Service Discovery)",
      "content": "اضافه شدن سرویس‌های جدید بدون نیاز به تغییر در پیکربندی درگاه انجام می‌شود. استراتژی کشف سرویس و مسیریابی به شرح زیر سازمان‌دهی می‌شود (D17):\n- **مسیر رسمی توسعه و استقرار (Kubernetes-Native):** مسیریابی و کشف سرویس‌ها در کلیه محیط‌ها (شامل توسعه محلی در کلاستر K3d و استقرار پروداکشن در K3s) به صورت پویا بر پایه Traefik + Kubernetes Ingress / IngressRoute CRD انجام می‌شود.\n```yaml\nlabels:\n  - \"traefik.enable=true\"\n  - \"traefik.http.routers.order-service.rule=PathPrefix(`/v1/orders`)\"\n  - \"traefik.http.routers.order-service.entrypoints=web\"\n  - \"traefik.http.services.order-service.loadbalancer.server.port=8080\"\n  - \"traefik.http.routers.order-service.middlewares=protected-auth@file\"\n```\n\n**عدم بازنویسی مسیر (No Path Rewriting):** درگاه عمل بازنویسی مسیر را انجام نمی‌دهد؛ هر میکروسرویس مسئول نسخه‌بندی APIهای اختصاصی خود است و درگاه صرفاً ترافیک کامل را فوروارد می‌کند.\n\n---"
    },
    {
      "level": 2,
      "heading": "۶. یکپارچگی با احراز هویت (Authentication Integration Flow)",
      "content": "**Authentication Integration Flow**\n\nدرگاه ترافیک‌ها را به دو دسته **عمومی (Public)** و **محافظت‌شده (Protected)** تقسیم می‌کند:\n\n1. **مسیرهای عمومی (مانند کاتالوگ محصولات یا صفحه‌ی ورود Kratos):** بدون ارزیابی توکن، مستقیماً به سرویس بالادست هدایت می‌شوند.\n2. **مسیرهای محافظت‌شده (مانند ایجاد سفارش یا کیف پول):** ابتدا باید از فیلتر اعتبارسنجی عبور کنند."
    },
    {
      "level": 3,
      "heading": "نحوه اعتبارسنجی با Forward Auth:",
      "content": "```text\n[درخواست کلاینت با Bearer Token] \n         ↓\n[درگاه Traefik میان‌افزار Forward Auth را اجرا می‌کند]\n         ↓\n[ارسال درخواست به Auth Service: GET /v1/auth/validate]\n         ↓\n[بررسی امضای توکن دسترسی با کلیدهای عمومی JWKS توسط Auth Service]\n         ↓\n  ┌──────┴──────┐\n  ↓ (نامعتبر)   ↓ (معتبر)\n[بازگشت 401]  [بازگشت 200 OK + هدرهای هویت کاربر]\n  ↓             ↓\n[بلاک درخواست] [درگاه درخواست را به همراه هدرهای معتبر هویتی به سرویس بالادست می‌فرستد]\n```"
    },
    {
      "level": 4,
      "heading": "سیاست وابستگی و شکست (Auth Service Dependency Strategy):",
      "content": "سیاست وابستگی درگاه به سرویس احراز هویت به صورت **Fail-Closed** طراحی شده است. بدین معنی که در صورت در دسترس نبودن یا لود سنگین Auth Service، درگاه درخواست‌های محافظت‌شده را مسدود کرده و خطای `503 Service Unavailable` بازمی‌گرداند. بدین منظور تنظیمات ارتباطی درگاه با Auth Service با Timeout برابر **۲ ثانیه** و تعداد تلاش مجدد (Retry) برابر **۰** تنظیم می‌شود تا کارایی درگاه در زمان بروز قطعی دچار افت نگردد."
    },
    {
      "level": 4,
      "heading": "مرز امنیت و تزریق هدرها (Identity Injection & Trust Boundary):",
      "content": "پس از احراز هویت موفق، درگاه هدرهای هویتی معتبر را استخراج و به درخواست اضافه می‌کند:\n- `X-User-Id`: شناسه کاربر در Kratos (Identity UUID).\n- `X-Subject`: آدرس ایمیل کاربر.\n- `X-Trace-Id`: شناسه ردگیری درخواست.\n\n**قانون امنیتی حیاتی (Critical Trust Boundary):** هدرهای هویتی فوق صرفاً در صورتی برای میکروسرویس‌های داخلی معتبر و قابل اعتماد هستند که از محدوده آدرس شبکه خصوصی درگاه (Gateway subnet) ارسال شده باشند. کلیه میکروسرویس‌ها موظف هستند در صورتی که درخواستی حاوی این هدرها را به طور مستقیم از کلاینت‌های خارج شبکه درگاه دریافت کنند، آن‌ها را فیلتر و حذف (Strip) نمایند تا از حملات تظاهر به هویت (Identity Spoofing) جلوگیری شود.\n\n---"
    },
    {
      "level": 2,
      "heading": "۷. مدل امنیتی (Security Model)",
      "content": "**Security Model**"
    },
    {
      "level": 3,
      "heading": "۱. اعتبارسنجی نشست (Session Validation)",
      "content": "بررسی صحت نشست‌ها به صورت مستقیم از طریق Traefik ForwardAuth و با بررسی در سرویس `auth-service` (که نشست را از Ory Kratos استعلام می‌کند) انجام می‌پذیرد. در این مدل، مرورگر کوکی نشست `ory_kratos_session` را ارسال کرده و درگاه آن را اعتبارسنجی می‌نماید.\n\n**سیاست طول عمر نشست‌ها (Session TTL Policy):** مقادیر طول عمر نشست‌ها در Kratos پیکربندی شده و خارج از کدهای درگاه مدیریت می‌شوند. این طول عمرها به صورت کاملاً پویا و از طریق فایل تنظیمات Kratos مشخص می‌گردند.\n\n**سیاست ابطال و خروج (Logout & Revocation):** خروج کاربر (Logout) منجر به ابطال آنی نشست در Kratos و در نتیجه بلاک شدن فوری تمام درخواست‌های بعدی کاربر در سطح درگاه می‌گردد."
    },
    {
      "level": 3,
      "heading": "۲. محدودیت نرخ (Rate Limiting)",
      "content": "برای جلوگیری از حملات Brute Force و سوء‌استفاده از APIها، درگاه میان‌افزار Rate Limit را بر اساس دو استراتژی اعمال می‌کند:\n- **کاربران مهمان (IP-based):** حداکثر ۶۰ درخواست در دقیقه برای هر آدرس IP.\n- **کاربران لاگین‌شده (User-based):** حداکثر ۱۲۰ درخواست در دقیقه برای هر شناسه کاربری (`X-User-Id`).\n- **ذخیره‌سازی شمارنده‌ها (Redis-based):** برای سازگاری با معماری چند نسخه‌ای (Multi-Instance)، تمام شمارنده‌های Rate Limit از روز اول در **Redis** ذخیره و مدیریت می‌شوند. استفاده از حالت درون‌حافظه‌ای (In-memory) طبق تصمیم D5 کاملاً رد شده است."
    },
    {
      "level": 3,
      "heading": "۳. مدیریت CORS",
      "content": "مدیریت CORS به صورت انحصاری و متمرکز در سطح API Gateway پیکربندی می‌شود. هیچ سرویس داخلی بک‌اندی مجاز به داشتن CORS Policy مستقل یا موازی نیست. درگاه پاسخ به تمام درخواست‌های Preflight (با متد OPTIONS) را مدیریت می‌کند:\n- هدرهای مجاز: `Content-Type, Authorization, X-Correlation-ID`\n- متدهای مجاز: `GET, POST, PUT, PATCH, DELETE, OPTIONS`\n- خروجی‌های هدر دسترسی: `Access-Control-Allow-Origin` بر اساس لیست سفید (White List) متغیرهای محیطی لود می‌شود."
    },
    {
      "level": 3,
      "heading": "۴. هدرهای امنیتی (Security Headers)",
      "content": "تزریق هدرهای زیر برای تمامی پاسخ‌ها الزامی است:\n```ini\nStrict-Transport-Security: max-age=31536000; includeSubDomains\nX-Frame-Options: DENY\nX-Content-Type-Options: nosniff\nReferrer-Policy: strict-origin-when-cross-origin\nX-XSS-Protection: 1; mode=block\n```"
    },
    {
      "level": 3,
      "heading": "۵. محدودیت اندازه درخواست (Request Size Limits)",
      "content": "- درخواست‌های عمومی و متنی: حداکثر **۲ مگابایت**.\n- درخواست‌های بارگذاری فایل (مانند تصاویر محصولات در مسیرهای خاص): حداکثر **۱۰ مگابایت** (از طریق میان‌افزار اختصاصی Buffering محدود می‌شود)."
    },
    {
      "level": 3,
      "heading": "۶. کنترل خطای آبشاری (Cascade Failure Prevention)",
      "content": "به منظور جلوگیری از قطعی‌های زنجیره‌ای و سرایت خرابی‌ها در سطح پلتفرم (به‌ویژه برای سرویس‌های حیاتی مانند `auth-service`):\n- **تنظیمات Timeout:** برای تمامی درخواست‌های ارتباطی درگاه با سرویس‌های بالادستی زمان انتظار حداکثر ۳ ثانیه تعریف می‌گردد.\n- **تعداد تلاش مجدد (Retry Limits):** در صورت قطع اتصال موقت، حداکثر ۳ بار تلاش مجدد با فاصله زمانی بازگشتی (Backoff) تنظیم می‌شود.\n- **میان‌افزار Circuit Breaker:** درگاه Traefik مجهز به سیستم Circuit Breaker می‌شود تا در صورت شکست‌های مکرر سرویس واسط احراز هویت (مثلاً بروز خطا در ۵۰ درصد درخواست‌ها در بازه ۱۰ ثانیه‌ای)، مسیر فوروارد موقتاً قطع شده و بلافاصله خطای ۵۰۳ بازگردانده شود تا منابع درگاه اشغال نگردد."
    },
    {
      "level": 3,
      "heading": "۷. استراتژی ارتباطات امن داخلی (Internal mTLS Roadmap)",
      "content": "- ارتباطات شبکه محلی کانتینرها در محیط توسعه و استقرار اولیه به صورت HTTP ساده انجام می‌شود.\n- با این حال، فعال‌سازی mTLS داخلی در فاز **Post-Kubernetes Adoption** و به عنوان بخشی از نقشه راه توسعه پیشرفته پلتفرم پیش‌بینی شده است. کلیه آدرس‌دهی‌ها منطبق بر Service Nameها انجام می‌پذیرد تا فرآیند فعال‌سازی بدون نیاز به بازطراحی معماری میکروسرویس‌ها انجام شود."
    },
    {
      "level": 3,
      "heading": "۸. مدیریت رازها (Secret Management)",
      "content": "هیچ رازی (مانند پسورد دیتابیس‌ها و کلیدهای امنیتی) در مخزن ذخیره نمی‌شود و تماماً از فایل‌های محیطی یا Secret Store تامین می‌شود:\n- **فاز ۱ (استقرار اولیه):** استفاده از Kubernetes Secrets.\n- **فاز ۲ (توسعه پیشرفته):** استفاده اختیاری از HashiCorp Vault.\n\n---"
    },
    {
      "level": 2,
      "heading": "۸. استراتژی قابلیت مشاهده (Observability Strategy)",
      "content": "**Observability Strategy**"
    },
    {
      "level": 3,
      "heading": "۱. Correlation ID & Trace ID",
      "content": "برای ردیابی درخواست‌ها در سرتاسر زنجیره میکروسرویس‌ها، هدر `X-Correlation-ID` به صورت زیر مدیریت می‌شود:\n- درگاه بررسی می‌کند که آیا درخواست کلاینت حاوی هدر `X-Correlation-ID` است یا خیر و در صورت عدم وجود، یک شناسه UUIDv4 یکتا تولید می‌کند.\n- **قانون انتشار (Propagation):** این شناسه Correlation ID بدون استثنا باید به تمام سرویس‌های داخلی و خارجی همکار فرستاده و منتشر (Propagate) شود. انتشار این شناسه حیاتی‌ترین بخش ردیابی توزیع‌شده پلتفرم است."
    },
    {
      "level": 3,
      "heading": "۲. ثبت لاگ درخواست‌ها (Request Logging)",
      "content": "فرمت لاگ‌ها به صورت JSON استاندارد پلتفرم است و شامل فیلدهای زیر می‌باشد:\n```json\n{\n  \"timestamp\": \"2026-06-14T23:45:00Z\",\n  \"level\": \"INFO\",\n  \"service\": \"api-gateway\",\n  \"correlationId\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"method\": \"POST\",\n  \"path\": \"/v1/orders\",\n  \"status\": 201,\n  \"durationMs\": 42,\n  \"clientIp\": \"192.168.1.100\",\n  \"bytesSent\": 1024\n}\n```"
    },
    {
      "level": 3,
      "heading": "۳. مانیتورینگ و متریک‌ها (Metrics)",
      "content": "درگاه Traefik متریک‌های استاندارد پرومتئوس (Prometheus Metrics) را در مسیر داخلی `:8082/metrics` اکسپورت می‌کند که شامل:\n- تعداد کل درخواست‌ها بر اساس وضعیت پاسخ (HTTP Status).\n- مدت زمان پاسخ‌دهی مسیرها (Response Latency Histograms).\n\n---"
    },
    {
      "level": 2,
      "heading": "۹. استراتژی مدیریت خطا (Error Handling Strategy)",
      "content": "**Error Handling Strategy**\n\nزمانی که خطایی در سطح خود درگاه یا در ارتباط با سرویس‌های بالادستی رخ دهد، درگاه نباید صفحات HTML پیش‌فرض وب‌سرور را برگرداند. تمام پاسخ‌های خطا باید دارای فرمت JSON یکپارچه پلتفرم باشند."
    },
    {
      "level": 3,
      "heading": "ساختار خطای درگاه (Gateway Error Payload)",
      "content": "```json\n{\n  \"code\": \"GATEWAY_ERROR\",\n  \"message\": \"توضیح خطا به زبان فارسی\",\n  \"details\": {\n    \"correlationId\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"upstreamStatus\": 502\n  }\n}\n```"
    },
    {
      "level": 3,
      "heading": "نگاشت خطاهای انتقال:",
      "content": "| وضعیت رخ‌داده | کد خطا (JSON Code) | پیغام فارسی |\n| --- | --- | --- |\n| **502 Bad Gateway** | `UPSTREAM_UNAVAILABLE` | سرویس مقصد در حال حاضر در دسترس نیست. |\n| **504 Gateway Timeout** | `UPSTREAM_TIMEOUT` | سرویس مقصد در زمان معین پاسخ نداد. |\n| **404 Not Found (مسیر اشتباه)** | `ROUTE_NOT_FOUND` | مسیر مورد نظر یافت نشد. |\n| **429 Too Many Requests** | `RATE_LIMIT_EXCEEDED` | تعداد درخواست‌های شما بیش از حد مجاز است. لطفاً کمی بعد تلاش کنید. |\n\n---"
    },
    {
      "level": 2,
      "heading": "۱۰. دیاگرام‌های توالی (Sequence Diagrams)",
      "content": "**Sequence Diagrams**"
    },
    {
      "level": 3,
      "heading": "۱. جریان ورود (Login Flow)",
      "content": "جریان ورود کاربر و صدور کوکی نشست در Kratos که توسط درگاه API Gateway مسیریابی می‌شود.\n\n```mermaid\nsequenceDiagram\n    autonumber\n    actor Client as User / Browser\n    participant GW as API Gateway\n    participant Auth as Auth Service\n    participant Kratos as Ory Kratos\n\n    Client->>GW: GET /v1/auth/login (درخواست صفحه لاگین)\n    GW->>Auth: پروکسی درخواست به سرویس احراز هویت\n    Auth-->>Client: رندر و نمایش صفحه ورود ایمیل\n    \n    Client->>GW: POST /v1/auth/entry (ارسال ایمیل)\n    GW->>Auth: پروکسی به سرویس احراز هویت\n    Auth->>Kratos: شروع جریان ورود و بررسی ایمیل\n    alt کاربر موجود است\n        Kratos-->>Auth: انتقال به مرحله ۲ (کد OTP ارسال شد)\n        Auth-->>Client: ریدایرکت به /v1/auth/login?flow=...\n    else کاربر جدید است\n        Auth->>Kratos: شروع جریان ثبت‌نام (کد OTP ارسال شد)\n        Auth-->>Client: ریدایرکت به /v1/auth/register?flow=...\n    end\n\n    Client->>GW: POST /v1/auth/login (یا register - ارسال کد OTP)\n    GW->>Auth: پروکسی به سرویس احراز هویت\n    Auth->>Kratos: ارسال کد تایید جهت احراز هویت\n    Kratos-->>GW: تایید نهایی و ست شدن کوکی ory_kratos_session\n    GW-->>Client: انتقال به /v1/auth/dashboard (ورود موفق)\n```"
    },
    {
      "level": 3,
      "heading": "۲. جریان درخواست احراز هویت‌شده (Authenticated Request Flow)",
      "content": "این جریان نشان می‌دهد که چگونه یک درخواست محافظت‌شده ابتدا توسط Gateway به کمک Auth Service اعتبارسنجی شده و سپس به میکروسرویس مقصد هدایت می‌شود.\n\n```mermaid\nsequenceDiagram\n    autonumber\n    actor Client as User / Browser\n    participant GW as API Gateway (Traefik)\n    participant Auth as Auth Service\n    participant Kratos as Ory Kratos\n    participant Upstream as Upstream Service (e.g. Order)\n\n    Client->>GW: GET /v1/orders/123 (به همراه کوکی نشست)\n    Note over GW: درگاه مسیر را محافظت‌شده تشخیص می‌دهد\n    GW->>Auth: درخواست Forward Auth: GET /v1/auth/validate\n    Auth->>Kratos: استعلام نشست کاربر: GET /sessions/whoami\n    alt نشست نامعتبر یا منقضی شده\n        Kratos-->>Auth: وضعیت خطا (401)\n        Auth-->>GW: بازگرداندن 401 Unauthorized\n        GW-->>Client: پاسخ خطا (401) و ریدایرکت به صفحه ورود\n    else نشست معتبر است\n        Kratos-->>Auth: اطلاعات هویت کاربر (200 OK)\n        Auth-->>GW: پاسخ 200 OK + هدرهای X-User-Id و X-Subject\n        Note over GW: تزریق هدرها و تخصیص X-Correlation-ID\n        GW->>Upstream: هدایت درخواست اصلی با هدرهای تزریق‌شده هویتی\n        Upstream->>Upstream: پردازش درخواست با شناسه کاربر\n        Upstream-->>GW: بازگرداندن پاسخ موفق (200)\n        GW-->>Client: تحویل پاسخ نهایی به کلاینت\n    end\n```\n\n```mermaid\nsequenceDiagram\n    autonumber\n    actor Client as User / Browser\n    participant GW as API Gateway (Traefik)\n    participant Engine as Kubernetes API\n    participant NewSvc as New Upstream Service\n\n    Note over NewSvc: پاد سرویس جدید با تعریف Ingress/IngressRoute بالا می‌آید\n    Engine->>GW: ارسال اعلان تغییر وضعیت یا کشف سرویس جدید\n    Note over GW: Traefik مانیفست‌ها را پارس کرده و پیکربندی را بروزرسانی می‌کند\n    Client->>GW: درخواست مسیر جدید: GET /v1/new-service/data\n    GW->>GW: تطابق مسیر با قوانین جدید بارگذاری شده\n    GW->>NewSvc: هدایت ترافیک به پورت مشخص شده در سرویس جدید\n    NewSvc-->>GW: پاسخ درخواست\n    GW-->>Client: بازگرداندن پاسخ به کلاینت\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "۱۱. نقشه راه پیشرفته پلتفرم (Advanced Platform Roadmap)",
      "content": "توسعه قابلیت‌های زیر به فازهای پیشرفته توسعه موکول گردیده و معماری فعلی طوری پیاده‌سازی شده که به آسانی با آن‌ها ادغام شود:\n- **mTLS داخلی (Internal mTLS):** در فاز **Post-Kubernetes Adoption** به منظور رمزنگاری و امنیت کانال‌های ارتباطی میان‌سرویسی فعال خواهد شد.\n- **کنترل جریان خرابی (Circuit Breaker):** پیاده‌سازی Circuit Breaker در سطح پیشرفته پس از استقرار **Service Mesh** (بر پایه الگوهای Envoy، Istio یا Linkerd) انجام می‌پذیرد.\n- **سیستم همکاران فروش (Affiliate Cookie):** سیاست دامنه کوکی (Cookie Domain Strategy) به **فاز Affiliate** موکول گردید و در آن زمان نهایی خواهد شد.\n- **مدیریت ابطال آنی توکن‌ها (Token Revocation Cache):** ابطال آنی توکن‌ها (خروج فوری از کل سامانه) در فاز MVP تعهد نشده است. در صورت نیاز عملیاتی، یک کش ابطال توکن مبتنی بر Redis یا سیستم استعلام آنلاین (Hydra Introspection) بدون تغییر در ساختار اصلی درگاه اضافه خواهد شد.\n- **مدیریت رازها (Secret Management):** انتقال از مخزن محلی و Kubernetes Secrets به ابزار پیشرفته مدیریت رازها مانند HashiCorp Vault در فازهای پیشرفته استقرار.\n- **پیکربندی کشف سرویس (Service Discovery Configuration):** استفاده از Kubernetes Ingress / CRD Provider به عنوان تنها روش رسمی و بومی استقرار در کل سیستم (شامل کلاستر محلی K3d برای توسعه و کلاستر K3s برای پروداکشن) جهت کشف و ثبت پویای سرویس‌ها.\n\n---\n\n**آخرین بروزرسانی:** 2026-06-18  \n**وضعیت:** ✅ تایید شده (APPROVED)\n\n> **تغییرات احراز هویت:** با توجه به ADR-Backend-005، روش‌های احراز هویت به Magic Code (Primary) و Google Login (Secondary) محدود شده‌اند. روش `password` و `discord` از معماری فعال حذف شده‌اند."
    }
  ]
}