{
  "title": "راهنمای درگاه API Gateway",
  "slug": "team/platform/gateway/README",
  "url": "/docs/team/platform/gateway/README",
  "frontmatter": {
    "layout": "doc",
    "title": "راهنمای درگاه API Gateway",
    "description": "راهنمای اجرا، پیکربندی، متغیرهای محیطی و سناریوهای عیب‌یابی درگاه ورود پلتفرم (API Gateway)",
    "version": "1.0.0",
    "status": "PUBLIC",
    "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 Guide**\n\n> **خلاصه:** این مستند راهنمای کاملی برای نحوه پیکربندی، راه‌اندازی، متغیرهای محیطی، تست محلی و عیب‌یابی درگاه API Gateway پلتفرم NONS ارائه می‌دهد.\n\n---"
    },
    {
      "level": 2,
      "heading": "ارجاعات مرتبط",
      "content": "**Related Documents**\n\n- [تصمیم معماری ۱: انتخاب درگاه](./ADR/ADR-Gateway-001)\n- [بلوپرینت درگاه (Gateway Blueprint)](./blueprint)\n- [راهنمای نام‌گذاری پلتفرم](../standards/naming-conventions)\n\n---"
    },
    {
      "level": 2,
      "heading": "فهرست محتوا",
      "content": "**Table of Contents**\n\n1. [معرفی و هدف سرویس](#۱-معرفی-و-هدف-سرویس)\n2. [نیازمندی‌ها و وابستگی‌ها](#۲-نیازمندی‌ها-و-وابستگی‌ها)\n3. [متغیرهای محیطی (Environment Variables)](#۳-متغیرهای-محیطی-environment-variables)\n4. [نحوه اجرا (How to Run)](#۴-نحوه-اجرا-how-to-run)\n5. [نحوه تست محلی (Local Testing)](#۵-نحوه-تست-محلی-local-testing)\n6. [مثال درخواست‌ها (Request Examples)](#۶-مثال-درخواست‌ها-request-examples)\n7. [عیب‌یابی (Troubleshooting)](#۷-عیب‌یابی-troubleshooting)\n\n---"
    },
    {
      "level": 2,
      "heading": "۱. معرفی و هدف سرویس",
      "content": "**Introduction & Objective**\n\nدرگاه API Gateway (پیاده‌سازی شده بر پایه Traefik v3) لایه ورودی خارجی پلتفرم NONS است. هیچ درخواستی از خارج پلتفرم نباید بدون عبور از این درگاه به میکروسرویس‌ها برسد. این درگاه امنیت لبه، بررسی اولیه احراز هویت کلاینت‌ها، هدایت ترافیک به سرویس مقصد، و تزریق Correlation ID را پوشش می‌دهد.\n\n---"
    },
    {
      "level": 2,
      "heading": "۲. نیازمندی‌ها و وابستگی‌ها",
      "content": "**Prerequisites & Dependencies**\n\nبرای اجرای رسمی درگاه در محیط توسعه محلی به ابزارهای زیر نیاز است:\n- **K3d CLI >= v5.6**\n- **Helm CLI >= v3.12**\n- **Kubectl**\n- **Docker** (صرفاً به عنوان ران‌تایم موتور کانتینر کلاستر)\n\nدرگاه برای اعتبارسنجی توکن‌های مسیرهای محافظت‌شده به اجرای **Auth Service (Bridge)** نیاز دارد.\n\n---"
    },
    {
      "level": 2,
      "heading": "۳. متغیرهای محیطی (Environment Variables)",
      "content": "**Environment Variables**\n\nتنظیمات درگاه از طریق فایل `.env` در روت پروژه بک‌اند `nons-api/` مدیریت می‌شوند. متغیرهای کلیدی درگاه به شرح زیر هستند:\n\n| متغیر محیطی | مقدار پیش‌فرض | توضیح |\n| --- | --- | --- |\n| `GATEWAY_PORT` | `80` | پورتی که درگاه درخواست‌های خارجی را روی آن دریافت می‌کند. |\n| `GATEWAY_DASHBOARD_PORT` | `8085` | پورت دسترسی به داشبورد مدیریتی Traefik. |\n| `GATEWAY_DASHBOARD_USER` | `admin` | نام کاربری پنل داشبورد درگاه. |\n| `GATEWAY_DASHBOARD_PASSWORD_HASH` | `$$2y$$10$$abcdef...` | هش کلمه عبور پنل داشبورد (فرمت bcrypt). |\n| `AUTH_SERVICE_VALIDATE_URL` | `http://auth-service:8080/v1/auth/validate` | آدرس بررسی صحت توکن در سرویس واسط احراز هویت. |\n| `CORS_ALLOWED_ORIGINS` | `http://localhost:3000` | دامنه‌های مجاز فرانت‌اند برای دسترسی به APIها. |\n\n---"
    },
    {
      "level": 2,
      "heading": "۴. نحوه اجرا (How to Run)",
      "content": "**How to Run**\n\nمسیر رسمی و انحصاری برای اجرای درگاه و کل پلتفرم، استقرار روی کلاستر کوبرنتیز محلی (K3d) یا پروداکشن (K3s) به وسیله Helm است:"
    },
    {
      "level": 3,
      "heading": "مسیر رسمی (Helm + K3d)",
      "content": "برای بالا آوردن درگاه در کلاستر محلی K3d، پس از راه‌اندازی کلاستر و نصب سایر چارت‌های زیرساختی (طبق [راهنمای راه‌اندازی](../../devops/setup-guide))، دستور زیر را اجرا کنید:\n```powershell\nhelm install nons-gateway ./deploy/helm/gateway -n nons-system -f ./deploy/environments/local/values.yaml\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "۵. نحوه تست محلی و داشبوردها (Local Testing & Dashboards)",
      "content": "**Local Testing**\n\nپس از اجرای موفق درگاه، می‌توانید کارکرد آن را بررسی کنید:"
    },
    {
      "level": 3,
      "heading": "۱. داشبورد مدیریتی Traefik (Traefik Dashboard)",
      "content": "مرورگر خود را باز کرده و به آدرس زیر مراجعه کنید:\n- **URL داشبورد:** `http://localhost:8085/dashboard/`\n- **احراز هویت:** پس از ورود به آدرس فوق، از شما نام کاربری و کلمه عبور خواسته می‌شود:\n  - **نام کاربری (Username):** `admin`\n  - **کلمه عبور (Password):** `admin` (یا هش تعریف شده در فایل `.env`)\nدر این داشبورد می‌توانید وضعیت روت‌ها (HTTP Routers)، سرویس‌ها (Services) و میان‌افزارهای فعال (Middlewares) را به صورت زنده رصد کنید."
    },
    {
      "level": 3,
      "heading": "۲. بررسی سلامت درگاه (Ping Endpoint)",
      "content": "برای اطمینان از آماده بودن درگاه، درخواست زیر را ارسال کنید:\n```powershell\ncurl.exe -i http://localhost/v1/auth/health\n```\nباید پاسخ `200 OK` به همراه وضعیت سرویس احراز هویت دریافت کنید:\n```json\n{\"status\":\"UP\",\"timestamp\":\"2026-06-15T...\"}\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "۶. دریافت توکن تستی و اعتبارسنجی (Test JWT Generation & Validation)",
      "content": "**Test Authentication Scenario**\n\nبرای تست و شبیه‌سازی درخواست‌های احراز هویت شده بدون نیاز به رابط کاربری کامل، می‌توانید جریان تأیید نشست را با کوکی شبیه‌سازی کنید:"
    },
    {
      "level": 3,
      "heading": "۱. ورود به سیستم و دریافت کوکی نشست (Login & Fetch Cookie)",
      "content": "ابتدا یک درخواست ورود شبیه‌سازی شده به سرویس احراز هویت ارسال کنید یا از طریق مرورگر به آدرس `http://localhost/v1/auth/login` مراجعه کرده و وارد شوید تا کوکی `ory_kratos_session` روی مرورگر شما تنظیم شود."
    },
    {
      "level": 3,
      "heading": "۲. فراخوانی مسیر محافظت شده (Call Protected Route)",
      "content": "کوکی نشست دریافت شده را در درخواست خود به درگاه Gateway اعمال کنید تا لایه Forward Auth آن را تایید کند:\n```powershell"
    },
    {
      "level": 1,
      "heading": "استفاده از curl برای ارسال کوکی نشست",
      "content": "curl.exe -i --cookie \"ory_kratos_session=<SESSION_COOKIE_VALUE>\" http://localhost/v1/protected\n```\nخروجی موفقیت‌آمیز (`200 OK`) شامل هدرهای هویتی تزریق شده توسط درگاه به سرویس بالادستی خواهد بود:\n```http\nHTTP/1.1 200 OK\nX-User-Id: 550e8400-e29b-41d4-a716-446655440000\nX-Subject: user@example.com\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "۷. جریان واقعی احراز هویت کلاینت (Real Login Flow Scenario)",
      "content": "**Real Kratos + Traefik ForwardAuth Flow**\n\nدر سناریوی واقعی، مرورگر کاربر مراحل احراز هویت را به شکل زیر طی می‌کند:"
    },
    {
      "level": 3,
      "heading": "مرحله ۱: ورود ایمیل (Email Submission)",
      "content": "کاربر به آدرس ورود مراجعه کرده و ایمیل خود را وارد می‌کند. درخواست به مسیر زیر ارسال می‌شود:\n```text\nPOST http://localhost/v1/auth/entry\n```\nسرویس `auth-service` به صورت پویا با Kratos ارتباط برقرار کرده و متناسب با وضعیت کاربر، یکی از جریان‌های زیر را آغاز می‌کند:\n- **کاربر موجود:** ریدایرکت به آدرس `/v1/auth/login?flow=<flow_id>` به همراه ارسال کد OTP به ایمیل کاربر.\n- **کاربر جدید:** ریدایرکت به آدرس `/v1/auth/register?flow=<flow_id>` به همراه ارسال کد OTP به ایمیل کاربر."
    },
    {
      "level": 3,
      "heading": "مرحله ۲: تایید کد یکبار مصرف (OTP Code Verification)",
      "content": "کاربر کد ۶ رقمی OTP را وارد کرده و به سرویس ارسال می‌کند. Kratos صحت کد را تایید نموده و کوکی نشست `ory_kratos_session` را روی مرورگر کاربر تنظیم کرده و او را به `/v1/auth/dashboard` هدایت می‌کند."
    },
    {
      "level": 3,
      "heading": "مرحله ۳: فراخوانی سرویس‌های محافظت‌شده",
      "content": "برای درخواست‌های بعدی به سرویس‌های تجاری (مثلاً `/v1/orders/*`):\n1. مرورگر کوکی نشست `ory_kratos_session` را به صورت خودکار به همراه درخواست ارسال می‌کند.\n2. درگاه Traefik درخواست را متوقف کرده و آن را جهت تایید صلاحیت به مسیر `/v1/auth/validate` در سرویس `auth-service` ارسال می‌کند (ForwardAuth).\n3. سرویس `auth-service` کوکی نشست را با Kratos بررسی می‌کند. در صورت معتبر بودن، هدرهای `X-User-Id` و `X-Subject` را تزریق کرده و Traefik درخواست را به سرویس مقصد عبور می‌دهد.\n\n---"
    },
    {
      "level": 2,
      "heading": "۸. عیب‌یابی (Troubleshooting)",
      "content": "**Troubleshooting**"
    },
    {
      "level": 3,
      "heading": "خطای ۵۰۲ Bad Gateway",
      "content": "- **علت ۱:** میکروسرویس مقصد خاموش یا در حال بالا آمدن است.\n  - *رفع مشکل:* وضعیت پاد مقصد را با دستور `kubectl get pods -n nons-platform` بررسی کنید.\n- **علت ۲:** پورت معرفی شده در Service/Ingress کوبرنتیز با پورت اجرای سرویس مطابقت ندارد.\n  - *رفع مشکل:* چارت Helm و فایل values.yaml سرویس مربوطه را بررسی کنید."
    },
    {
      "level": 3,
      "heading": "خطای ۵۰۴ Gateway Timeout",
      "content": "- **علت:** سرویس مقصد درخواست را دریافت کرده اما نتوانسته در زمان مجاز پاسخ دهد.\n  - *رفع مشکل:* لاگ‌های سرویس مقصد را با دستور `kubectl logs -l app={service-name} -n nons-platform --tail=100` بررسی کنید."
    },
    {
      "level": 3,
      "heading": "عدم شناسایی سرویس جدید توسط درگاه",
      "content": "- **علت ۱:** پاد سرویس جدید در Namespace یا شبکه کلاستر به درستی ثبت نشده است.\n  - *رفع مشکل:* سلامت سرویس کوبرنتیز را با `kubectl get svc -n nons-platform` بررسی کنید.\n- **علت ۲:** تنظیمات IngressRoute برای سرویس جدید اعمال نشده است.\n  - *رفع مشکل:* وجود منابع IngressRoute را با `kubectl get ingressroute -n nons-system` بررسی کنید.\n\n---\n\n**آخرین بروزرسانی:** 2026-06-15  \n**وضعیت:** ✅ تایید شده (APPROVED)"
    }
  ]
}