{
  "title": "مسیر توسعه",
  "slug": "team/backend/roadmap",
  "url": "/docs/team/backend/roadmap",
  "frontmatter": {
    "layout": "doc",
    "title": "مسیر توسعه",
    "description": "نقشه راه توسعه سرویس‌ها و برنامه فازی پروژه",
    "version": "2.1.0",
    "status": "PRIVATE",
    "author": "xoxxel",
    "owner": "xoxxel",
    "created_at": "2026-06-09",
    "updated_at": "2026-06-18",
    "tags": "",
    "reviewers": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "مسیر توسعه",
      "content": "**Development Roadmap**\n\nاین سند نقشه راه رسمی توسعه پروژه است و جایگزین تمام فازبندی‌های قبلی (از جمله فازبندی داخل `docs/blueprint.md`) می‌شود.  \nنکته کلیدی: **توسعه به صورت افزایشی و سرویس‌به‌سرویس** انجام می‌شود.  \nما ابتدا برای همه سرویس‌ها فقط یک README پیشنهادی و پایه می‌نویسیم.  \nسپس قدم به قدم، هر سرویس را کامل می‌کنیم (بلوپرینت ← دمو ← مستندات تکمیلی ← خروجی قابل تحویل).  \nهیچ‌کس برای ۱۸ سرویس با هم دمو نمی‌سازد. تمرکز روی یک سرویس در هر مرحله است.\n\n---"
    },
    {
      "level": 2,
      "heading": "اصول کلیدی توسعه",
      "content": "1. **اول مستندات پیشنهادی، نه دمو**  \n   در فاز آماده‌سازی، فقط یک README ساده برای هر سرویس نوشته می‌شود شامل:\n   - معماری پیشنهادی پایه\n   - مسئولیت و وظایف آن سرویس\n   - وابستگی‌ها\n   - نکته: «این مستند پیشنهادی است و در حین توسعه سرویس‌های قبلی ممکن است تغییر کند»\n\n2. **پایه‌گذاری قبل از سرویس‌ها**  \n   ابتدا لایه قراردادها (`nons-api/contracts/` Proto)، پکیج‌های مشترک (`nons-api/core`, `nons-api/packages/types`, `nons-api/packages/contracts`)، زیرساخت محلی و CI/CD ساده راه‌اندازی می‌شود.\n\n3. **توسعه سرویس‌به‌سرویس**  \n   بعد از پایه‌گذاری، یک سرویس را انتخاب می‌کنیم و تا انتها کامل می‌کنیم:\n   - بازبینی و تکمیل بلوپرینت آن سرویس\n   - ساخت دمو (نمایشی از کارکرد اصلی)\n   - تکمیل مستندات آن سرویس (API، رویدادها، خطاها)\n   - تست و تحویل خروجی\n   - سپس رفتن به سرویس بعدی\n\n4. **مستندات زنده هستند**  \n   مستندات معماری اولیه (فاز 1-) «پیشنهادی» هستند و ممکن است بعد از توسعه سرویس‌های قبلی تغییر کنند.  \n   مستندات نهایی و قابل اعتماد بعد از اتمام هر سرویس به‌روز می‌شوند.\n\n5. **قرارداد ثبت وقایع (Logging Contract) مستقل از پیاده‌سازی**  \n   سرویس‌ها در انتخاب کتابخانه و پیاده‌سازی ثبت وقایع (Logger Implementation) آزاد هستند، اما تمام وقایع ثبت‌شده باید با **قرارداد ثبت وقایع پلتفرم** مطابقت داشته باشند.  \n   - **قرارداد (Logging Standard):** فرمت JSON، فیلدهای اجباری (`correlationId`, `service`, `timestamp`, `level`, `message`)، سطوح `DEBUG/INFO/WARN/ERROR`\n   - **پیاده‌سازی (Logger Implementation):** آزاد — پیشنهاد: Go ← `slog`، Node.js ← `pino`، Python ← `structlog`\n   - این تفکیک در `nons-api/packages/logging` به صورت قرارداد (types, interfaces, validators) تعریف می‌شود، نه پیاده‌سازی نهایی.\n\n---"
    },
    {
      "level": 2,
      "heading": "فاز ۱- — آماده‌سازی مستندات پیشنهادی `(Readiness)`",
      "content": "> هدف: نوشتن یک README ساده و پیشنهادی برای **همه** سرویس‌ها، بدون هیچ دمو یا کد اجرایی"
    },
    {
      "level": 3,
      "heading": "نقاط عطف این فاز (Milestones):",
      "content": "- [X] **M-1.0:** ساخت اسکلت پروژه مطابق زیرساخت و مستندات با پوشه‌های کاملاً خالی\n- [X] **M-1.1:** نوشتن README پیشنهادی برای `auth-service` و `IAM + keto`\n- [X] **M-1.2:** نوشتن README پیشنهادی برای `marketplace-service`\n- [X] **M-1.3:** نوشتن README پیشنهادی برای `order-service`\n- [X] **M-1.4:** نوشتن README پیشنهادی برای `payment-service`\n- [X] **M-1.5:** نوشتن README پیشنهادی برای `chat-service`\n- [X] **M-1.6:** نوشتن README پیشنهادی برای `kyc-service`\n- [X] **M-1.7:** نوشتن README پیشنهادی برای `dispute-service`, `review-service`, `zone-service`, `moderation-service`, `storage-service`\n- [X] **M-1.8:** نوشتن README پیشنهادی برای `boost-service`, `search-service`, `notification-service`, `analytics-service`\n- [X] **M-1.9:** بازبینی همه READMEها و اضافه کردن عبارت هشدار:  \n- [X] **M-1.10:** نوشتن حد اقل یک فایل readme  از معماری پیشنهادی  همه - سرویس ها و پوشه های قبلا ساهته شده - با مختوای دکر شده در همین فاز \n  *«این مستند پیشنهادی اولیه است و در حین توسعه سرویس‌های قبلی ممکن است تغییر کند. تا زمانی که سرویس واقعاً پیاده‌سازی نشده، برای تصمیم‌گیری نهایی قابل اعتماد نیست.»*"
    },
    {
      "level": 3,
      "heading": "✅ خروجی فاز ۱-",
      "content": "یک پوشه `docs/services/` شامل ۱۸ فایل README (پیشنهادی)  و سایر پوشه ها برای همه سرویس‌ها.  \nهیچ کدی نوشته نشده، هیچ دموی ساخته نشده، فقط معماری پایه و مسئولیت‌ها مشخص شده.\n\n---"
    },
    {
      "level": 2,
      "heading": "فاز ۰ — پایه‌گذاری `(Foundation)`",
      "content": "> هدف: پروژه آماده کدنویسی بشه — هنوز هیچ سرویس تخصصی نوشته نشده"
    },
    {
      "level": 3,
      "heading": "نقاط عطف این فاز (Milestones):",
      "content": "- [x] **M0.1:** راه‌اندازی مونوریپو با `pnpm workspaces` + ساختار پوشه‌ها (`nons-api/services/`, `nons-api/packages/`, `nons-api/infra/`) + تنظیم `nx.json`\n- [x] **M0.2:** پیاده‌سازی ساختار قراردادها و پکیج‌های مشترک:\n  - [x] اسکلت‌بندی و راه‌اندازی اولیه‌ی پکیج‌های TypeScript در `nons-api/packages/*` به صورت ساختار خام و کامپایل‌شونده (`types`, `contracts`, `events`, `logging`, `client`)\n  - [x] تعریف ساختار قراردادها با فایل‌های `.proto` در مسیر `nons-api/contracts/` (شامل `envelope.proto`، `registry.proto`، `errors.proto` و `permissions.proto`) به عنوان منبع واحد حقیقت (Source of Truth) پلتفرم\n  - [x] پیکربندی و راه‌اندازی ابزار **Buf** (`buf.yaml` و `buf.gen.yaml`) جهت تولید خودکار (Code Generation) تایپ‌های TypeScript و سورس کدهای Go از فایل‌های Proto\n  - [x] جایگزینی پکیج‌های موقت TypeScript با خروجی بیلد خودکار قراردادها (شامل `nons-api/packages/types`، `nons-api/packages/contracts` و `nons-api/packages/events`)\n  - [x] نهایی‌سازی ساختار `nons-api/packages/logging` جهت مدیریت قرارداد لاگینگ پلتفرم (خارج از ساختار Proto)\n- [x] **M0.3:** پیاده‌سازی سرویس هسته Go (موتور رویداد، ثبت خدمات، لاگ حسابرسی، اعتبارسنجی فنی رویدادها)\n  - *نکته معماری*: سرویس Core کاملاً فاقد دانش نسبت به دامنه‌های کسب‌وکار (Domain Agnostic) است. بر این اساس، **ماشین حالت سفارش** در Core پیاده‌سازی نخواهد شد و پیاده‌سازی آن در سرویس سفارش (`order-service` - Milestone M1.4) انجام می‌گردد.\n  - سرویس Core با استفاده از Go Bindings تولید شده از روی قراردادهای `.proto` پیاده‌سازی می‌شود.\n- [x] **M0.4:** راه‌اندازی زیرساخت محلی با K3d و Helm (PostgreSQL، MongoDB، Redis، NATS، API Gateway، Go core)\n- [x] **M0.5:** راه‌اندازی CI/CD پایه (GitHub Actions: lint، build، test ساده برای پکیج‌های مشترک + Code Generation با Buf)"
    },
    {
      "level": 3,
      "heading": "✅ خروجی فاز ۰",
      "content": "مونوریپو آماده، لایه Proto تعریف شده، پکیج‌های مشترک بروزرسانی شده، هسته Go قابل اجرا، زیرساخت محلی K3d و Helm راه‌اندازی شده.  \nهیچ سرویس تخصصی (auth, marketplace, ...) هنوز نوشته نشده.\n\n---"
    },
    {
      "level": 2,
      "heading": "فاز ۱ — چرخه خرید و فروش (یک سرویس در هر مرحله)",
      "content": "> هدف: هر سرویس را کامل کنیم و بعد برویم سراغ بعدی — خروجی هر مرحله یک سرویس کامل با دمو و مستندات نهایی است"
    },
    {
      "level": 3,
      "heading": "ترتیب توسعه سرویس‌ها (تک‌تک و کامل):",
      "content": ""
    },
    {
      "level": 4,
      "heading": "**M1.1** - `auth-service` (کامل) — مبتنی بر **Ory Kratos** (سرویس آماده خارجی)",
      "content": "- [] بازبینی README پیشنهادی فاز ۱-\n- [] آشنایی با مستندات و APIهای Ory Kratos\n- [] پیکربندی Kratos برای نیازهای پلتفرم (فعال‌سازی `code` و `oidc`، غیرفعال‌سازی `password`)\n- [] پیکربندی Google OIDC provider در Kratos\n- [] پیکربندی SMTP برای ارسال Magic Code\n- [] ساخت دمو (ورود با Magic Code، ورود با Google، Auto Sign-Up، تشخیص کاربر جدید)\n- [] تکمیل مستندات (API، رویدادها، خطاها، معماری نهایی)\n- [] تست و خروجی تأیید شده\n\n> این سرویس از صفر توسعه داده نمی‌شود — از قابلیت‌های آماده Ory Kratos استفاده می‌کند.\n>\n> **روش‌های احراز هویت:**\n> - **Primary:** Magic Code (ورود با ایمیل + کد یکبار مصرف)\n> - **Secondary:** Google Login (ورود با حساب Google + تطبیق خودکار ایمیل)\n> - روش‌های `password` و `discord` از معماری فعال حذف شده‌اند."
    },
    {
      "level": 4,
      "heading": "**M1.1.5** - `token-service` (کامل) — **NEW**",
      "content": "- بازبینی Blueprint (`services/token-service/blueprint.md`)\n- راه‌اندازی Ory Hydra به عنوان سرور OAuth2/OIDC (دیتابیس جدا از Kratos)\n- پیاده‌سازی `login-consent-app` جهت تبدیل نشست Kratos به توکن OAuth2\n- افشای JWKS endpoint (`/.well-known/jwks.json`) و OIDC discovery\n- صدور access/refresh/id token + فعال‌سازی Refresh Token Rotation\n- پیاده‌سازی middleware اعتبارسنجی stateless JWT در یک میکروسرویس pilot\n- انتشار رویدادها: `nons.token.issued`, `nons.token.revoked`\n- تکمیل مستندات (API، Events، Architecture)\n- تست و خروجی\n\n> token-service از قابلیت‌های آماده Ory Hydra استفاده می‌کند. صدور و اعتبارسنجی توکن از auth-service جدا شده است."
    },
    {
      "level": 4,
      "heading": "**M1.2** - `IAM Service` (کامل)",
      "content": "- بازبینی README پیشنهادی\n- تکمیل بلوپرینت (Roles, Permissions, Capabilities, Policy Engine)\n- پیاده‌سازی مدل داده (PostgreSQL): users, roles, capabilities, permissions, plans, entitlements, policies\n- پیاده‌سازی APIهای: Authorization Check, Role Management, Permission Registration, Policy Engine\n- پیاده‌سازی Authorization Context و کش Redis\n- پیاده‌سازی Policy Engine با شرط‌های تک‌متریک\n- پیاده‌سازی Audit Logging\n- انتشار رویدادها: `nons.iam.user.status_changed`, `nons.iam.user.role_assigned`, `nons.iam.policy.executed` و ...\n- ساخت دمو (ثبت Permission, تعریف نقش, اختصاص دسترسی, بررسی مجوز, اجرای Policy)\n\n> IAM با Go + PostgreSQL + Redis پیاده‌سازی می‌شود. Policy Engine داخلی، بدون وابستگی به Ory Keto.\n- تکمیل مستندات (API, Events, Errors, Architecture)\n- تست و خروجی"
    },
    {
      "level": 4,
      "heading": "**M1.3** - `marketplace-service` (کامل)",
      "content": "- بازبینی README پیشنهادی\n- تکمیل بلوپرینت (CRUD محصول، versioning، مدیریت موجودی، فروشگاه)\n- ساخت دمو (ایجاد محصول، ویرایش، کاهش موجودی)\n- تکمیل مستندات\n- تست و خروجی"
    },
    {
      "level": 4,
      "heading": "**M1.4** - `order-service` (کامل)",
      "content": "- بازبینی README پیشنهادی\n- تکمیل بلوپرینت (state machine ۸ حالته، تایمر ضمانت ۲۴ ساعته)\n- ساخت دمو (ایجاد سفارش، تغییر وضعیت، تایمر)\n- تکمیل مستندات\n- تست و خروجی"
    },
    {
      "level": 4,
      "heading": "**M1.5** - `payment-service` (کامل)",
      "content": "- بازبینی README پیشنهادی\n- تکمیل بلوپرینت (قفل Escrow، آزادسازی وجه، درگاه ریالی)\n- ساخت دمو (قفل وجه، آزادسازی، لغو)\n- تکمیل مستندات\n- تست و خروجی"
    },
    {
      "level": 4,
      "heading": "**M1.5.5** - `wallet-service` (کامل)",
      "content": "- بازبینی README پیشنهادی\n- تکمیل بلوپرینت (مدیریت موجودی، برداشت، واریز، پرداخت خودکار به فروشنده)\n- ساخت دمو (افزایش/کاهش موجودی، برداشت، ثبت تراکنش)\n- تکمیل مستندات\n- تست و خروجی"
    },
    {
      "level": 4,
      "heading": "**M1.5.6** - `currency-service` (کامل) — **NEW**",
      "content": "- بازبینی README پیشنهادی\n- تکمیل بلوپرینت (نرخ ارز، تبدیل مبلغ، cache در Redis، منابع خارجی Nobitex/fixer.io)\n- ساخت دمو (GET /rates, POST /convert, fallback به cache)\n- تکمیل مستندات\n- تست و خروجی"
    },
    {
      "level": 4,
      "heading": "**M1.5.7** - `settlement-service` (کامل) — **NEW**",
      "content": "- بازبینی README پیشنهادی\n- تکمیل بلوپرینت (کمیسیون بر اساس seller_tier، تسویه خودکار/دستی، refund، TigerBeetle ledger)\n- ساخت دمو (محاسبه کمیسیون، تسویه فروشنده، انتشار رویداد settlement.completed)\n- تکمیل مستندات\n- تست و خروجی"
    },
    {
      "level": 4,
      "heading": "**M1.6** - `chat-service` (کامل)",
      "content": "- بازبینی README پیشنهادی\n- تکمیل بلوپرینت (گفتگوی متنی، پیام سیستمی، ذخیره immutable)\n- ساخت دمو (ارسال پیام، دریافت، پیام سیستمی سفارش)\n- تکمیل مستندات\n- تست و خروجی"
    },
    {
      "level": 4,
      "heading": "**M1.7** - `kyc-service` (سطح پایه - کامل)",
      "content": "- بازبینی README پیشنهادی\n- تکمیل بلوپرینت (تأیید تلفن و ایمیل، الزام برای معامله)\n- ساخت دمو (ارسال کد، تأیید، سطوح دسترسی)\n- تکمیل مستندات\n- تست و خروجی"
    },
    {
      "level": 3,
      "heading": "✅ خروجی فاز ۱",
      "content": "۸ سرویس کامل با دمو، مستندات نهایی و تست شده.  \nیک کاربر می‌تواند ثبت‌نام کند، محصول ببیند، بخرد، به ارز محلی پرداخت کند، موجودی کیف پول داشته باشد، تسویه فروشنده انجام شود، چت کند و احراز هویت پایه انجام دهد.  \nکل فرآیند خرید، فروش، پرداخت و تسویه MVP کامل است.\n\n---"
    },
    {
      "level": 2,
      "heading": "فاز ۲ — اعتماد و داوری (یک سرویس در هر مرحله)",
      "content": "> هدف: اضافه کردن لایه اعتماد"
    },
    {
      "level": 4,
      "heading": "**M2.1** - `dispute-service` (کامل)",
      "content": ""
    },
    {
      "level": 4,
      "heading": "**M2.2** - `review-service` (کامل)",
      "content": ""
    },
    {
      "level": 4,
      "heading": "**M2.3** - `zone-service` (کامل)",
      "content": ""
    },
    {
      "level": 4,
      "heading": "**M2.4** - `moderation-service` (کامل)",
      "content": ""
    },
    {
      "level": 4,
      "heading": "**M2.5** - `kyc-service` (ارتقا به سطح پیشرفته - مدارک هویتی)",
      "content": ""
    },
    {
      "level": 4,
      "heading": "**M2.6** - `storage-service` (کامل)",
      "content": ""
    },
    {
      "level": 3,
      "heading": "✅ خروجی فاز ۲",
      "content": "فروشنده اعتبار کسب می‌کند. خریدار می‌تواند داوری بخواهد. تخلف‌های ساده شناسایی می‌شوند.  \nاحراز هویت کامل با مدارک انجام می‌شود. آپلود فایل در چت فعال است.\n\n---"
    },
    {
      "level": 2,
      "heading": "فاز ۳ — رشد و کشف (یک سرویس در هر مرحله)",
      "content": "> هدف: اقتصاد فعال و کشف محصول"
    },
    {
      "level": 4,
      "heading": "**M3.1** - `boost-service` (کامل)",
      "content": "- سیستم انرژی و حراج نمایش، TTL، کسر از کیف پول"
    },
    {
      "level": 4,
      "heading": "**M3.2** - `search-service` (کامل)",
      "content": "- سرویس مستقل جستجو با Elasticsearch، full-text، فیلترها، رتبه‌بندی ترکیبی"
    },
    {
      "level": 4,
      "heading": "**M3.3** - `notification-service` (کامل)",
      "content": "- اعلان داخلی، بات تلگرام، ایمیل تراکنشی"
    },
    {
      "level": 4,
      "heading": "**M3.4** - `analytics-service` (کامل)",
      "content": "- گزارش فروشندگان، داشبورد مدیریتی، تحلیل رفتار خریدار"
    },
    {
      "level": 3,
      "heading": "✅ خروجی فاز ۳",
      "content": "فروشنده می‌تواند محصولش را boost کند. خریدار می‌تواند جستجو و فیلتر کند. اعلان‌ها و تحلیل‌ها فعال هستند.\n\n---"
    },
    {
      "level": 2,
      "heading": "فاز ۳.۵ — امنیت و احراز هویت پیشرفته (Authentication & Security Enhancement)",
      "content": "> هدف: افزودن لایه‌های امنیتی تکمیلی به احراز هویت"
    },
    {
      "level": 4,
      "heading": "**M3.5.1** — Passkey / WebAuthn",
      "content": "- فعال‌سازی WebAuthn method در Kratos\n- پشتیبانی از Passkey به عنوان credential ثانویه\n- ورود بدون نیاز به ایمیل یا Google (در دستگاه‌های دارای Passkey)"
    },
    {
      "level": 4,
      "heading": "**M3.5.2** — TOTP / Authenticator Apps",
      "content": "- فعال‌سازی TOTP method در Kratos\n- امکان اسکن QR code و اتصال اپلیکیشن Authenticator\n- MFA اختیاری برای کاربران"
    },
    {
      "level": 4,
      "heading": "**M3.5.3** — Transaction Verification",
      "content": "- فعال‌سازی MFA برای عملیات حساس (برداشت، تسویه، انتقال مالکیت)\n- تأیید تراکنش‌های پرخطر با TOTP یا Passkey\n- مدیریت دستگاه‌های اطمینان (Trusted Devices)\n\n---"
    },
    {
      "level": 2,
      "heading": "فاز ۴ — پیشرفته و اتوماسیون (یک سرویس در هر مرحله)",
      "content": "> هدف: ویژگی‌های تکمیلی"
    },
    {
      "level": 4,
      "heading": "**M4.1** - محصولات خودکار (تحویل خودکار کالاهای دیجیتال در marketplace + storage)",
      "content": ""
    },
    {
      "level": 4,
      "heading": "**M4.2** - پلن پریمیوم (طرح‌های اشتراک در IAM)",
      "content": ""
    },
    {
      "level": 4,
      "heading": "**M4.3** - موتور پیشنهاد (Interest Tags، پیشنهاد هوشمند)",
      "content": ""
    },
    {
      "level": 4,
      "heading": "**M4.4** - لایه اتوماسیون با n8n",
      "content": "- وب‌هوک، محرک‌های گردش کار برای سفارش، تقلب، اطلاع‌رسانی، تحلیل"
    },
    {
      "level": 4,
      "heading": "**M4.5** - برداشت رمزارز",
      "content": "- برداشت از کیف پول داخلی، یکپارچه‌سازی با درگاه‌های رمزارز"
    },
    {
      "level": 4,
      "heading": "**M4.6** - سیستم همکاران فروش (Affiliate Marketing)",
      "content": "- طراحی و پیاده‌سازی سیستم رهگیری، پارامترهای UTM و نهایی‌سازی سیاست دامنه کوکی (Cookie Domain Strategy) برای درگاه و وب‌سایت فرانت‌اند."
    },
    {
      "level": 3,
      "heading": "✅ خروجی فاز ۴",
      "content": "پلتفرم کاملاً قابل اتوماسیون با n8n. محصولات خودکار فعال. پلن پریمیوم، پیشنهاد هوشمند و سیستم همکاران فروش (Affiliate) به همراه سیاست کوکی آن فعال است.\n\n---\n\n---"
    },
    {
      "level": 2,
      "heading": "فاز ۰.۵ — زیرساخت تحویل کانتینر (Container Delivery Infrastructure)",
      "content": "> هدف: مستندسازی و تصویب معماری ساخت، ثبت، انتشار و استقرار کانتینر قبل از پیاده‌سازی"
    },
    {
      "level": 3,
      "heading": "Milestoneهای این فاز:",
      "content": ""
    },
    {
      "level": 4,
      "heading": "**M0.5.1** — Container Registry Integration",
      "content": "- **Purpose:** ایجاد مخزن رسمی کانتینر برای پلتفرم NONS در ghcr.io\n- **Dependencies:** حساب سازمانی GitHub، دسترسی Devops به تنظیمات Packages\n- **Expected phase:** فاز ۰.۵\n- **Architectural impact:** تعیین منبع حقیقت تصاویر — تمام CI/CD workflows به این registry متصل می‌شوند"
    },
    {
      "level": 4,
      "heading": "**M0.5.2** — Automated Image Builds",
      "content": "- **Purpose:** ساخت خودکار تصویر کانتینر برای هر commit به main + هر PR\n- **Dependencies:** Container Registry Integration (M0.5.1)\n- **Expected phase:** فاز ۰.۵\n- **Architectural impact:** حذف Build دستی — هر commit دارای SHA Tag در registry است"
    },
    {
      "level": 4,
      "heading": "**M0.5.3** — CI/CD Pipeline Implementation",
      "content": "- **Purpose:** پیاده‌سازی pipeline کامل: PR validation → Build → Push → Staging Deploy → E2E → Production Gate\n- **Dependencies:** Automated Image Builds (M0.5.2), Helm Charts موجود\n- **Expected phase:** فاز ۰.۵\n- **Architectural impact:** استقرار خودکار Staging، Production با گیت دستی"
    },
    {
      "level": 4,
      "heading": "**M0.5.4** — Deployment Automation",
      "content": "- **Purpose:** خودکارسازی Helm upgrade به Staging پس از build موفق\n- **Dependencies:** CI/CD Pipeline (M0.5.3)\n- **Expected phase:** فاز ۰.۵\n- **Architectural impact:** حذف دستورات دستی `helm upgrade` برای Staging"
    },
    {
      "level": 4,
      "heading": "**M0.5.5** — GitOps Evaluation",
      "content": "- **Purpose:** بررسی ArgoCD/Flux برای استقرار declarative\n- **Dependencies:** CI/CD Pipeline (M0.5.3), maturity فاز ۵\n- **Expected phase:** فاز ۵\n- **Architectural impact:** تغییر مدل استقرار از imperative (helm upgrade) به declarative (GitRepo sync)"
    },
    {
      "level": 4,
      "heading": "**M0.5.6** — Supply Chain Security Enhancements",
      "content": "- **Purpose:** امضای تصاویر (Cosign)، اسکن vulnerability (Trivy)، تولید SBOM (Syft)\n- **Dependencies:** CI/CD Pipeline (M0.5.3)\n- **Expected phase:** فاز ۵\n- **Architectural impact:** اعمال policy enforcement برای تصاویر اسکن‌نشده"
    },
    {
      "level": 4,
      "heading": "**M0.5.7** — Multi-Architecture Image Support",
      "content": "- **Purpose:** پشتیبانی از linux/amd64 + linux/arm64\n- **Dependencies:** BuildKit, CI/CD Pipeline\n- **Expected phase:** فاز ۵\n- **Architectural impact:** افزایش زمان build, نیاز به QEMU در CI"
    },
    {
      "level": 4,
      "heading": "**M0.5.8** — Progressive Delivery Capabilities",
      "content": "- **Purpose:** Canary deployment, feature flags, traffic splitting\n- **Dependencies:** GitOps (M0.5.5), Service Mesh\n- **Expected phase:** پس از فاز ۵\n- **Architectural impact:** نیاز به Service Mesh (Istio/Linkerd) + Flagger/Argo Rollouts\n\n---"
    },
    {
      "level": 2,
      "heading": "فاز ۵ — مقیاس و بهینه‌سازی",
      "content": "> هدف: آماده برای تولید در مقیاس بالا"
    },
    {
      "level": 4,
      "heading": "**M5.1** - Load Balancing و کش Redis",
      "content": ""
    },
    {
      "level": 4,
      "heading": "**M5.2** - بهینه‌سازی NATS و Distributed Tracing",
      "content": ""
    },
    {
      "level": 4,
      "heading": "**M5.3** - پارتیشن‌بندی پایگاه داده و Performance Tuning",
      "content": ""
    },
    {
      "level": 4,
      "heading": "**M5.4** - تست بار، Benchmark، مستندات Runbook و Recovery",
      "content": ""
    },
    {
      "level": 4,
      "heading": "**M5.5** - فعال‌سازی پروتکل امن داخلی (Internal mTLS)",
      "content": "- پیاده‌سازی و استقرار پروتکل mTLS میان درگاه و میکروسرویس‌ها و همچنین کل شبکه‌ی ارتباطات داخلی کلاستر (فاز Post-Kubernetes Adoption)."
    },
    {
      "level": 4,
      "heading": "**M5.6** - کنترل پیشرفته جریان خرابی (Circuit Breaker via Service Mesh)",
      "content": "- پیاده‌سازی و استقرار Circuit Breaker پیشرفته در سطح پلتفرم با استفاده از الگوهای Service Mesh (مانند Envoy / Istio / Linkerd)."
    },
    {
      "level": 4,
      "heading": "**M5.7** - انتقال به سیستم مدیریت رازهای پیشرفته (Migration to HashiCorp Vault)",
      "content": "- انتقال سیستم مدیریت رازهای پلتفرم از Kubernetes Secrets به ابزار پیشرفته **HashiCorp Vault** جهت مدیریت پویا و متمرکز کلیدها، رمزها و اطلاعات حساس (D18)."
    },
    {
      "level": 3,
      "heading": "✅ خروجی فاز ۵",
      "content": "سیستم آماده برای تولید در مقیاس بالا به همراه امنیت ارتباطی mTLS و Circuit Breakerهای توزیع‌شده.\n\n---"
    },
    {
      "level": 2,
      "heading": "فاز ۶ — فرانت‌اند",
      "content": "> هدف: رابط کاربری"
    },
    {
      "level": 4,
      "heading": "**M6.1** - اپلیکیشن وب خریداران",
      "content": ""
    },
    {
      "level": 4,
      "heading": "**M6.2** - اپلیکیشن وب فروشندگان",
      "content": ""
    },
    {
      "level": 4,
      "heading": "**M6.3** - داشبورد مدیریتی + پنل داوری",
      "content": ""
    },
    {
      "level": 3,
      "heading": "✅ خروجی فاز ۶",
      "content": "رابط کاربری کامل برای همه نقش‌ها.\n\n---"
    },
    {
      "level": 2,
      "heading": "خلاصه ترتیب توسعه (فازها و Milestoneها)",
      "content": "```\nفاز ۱-   M-1.1 → M-1.2 → ... → M-1.9 (فقط README پیشنهادی)\nفاز ۰    M0.1 → M0.2 → M0.3 → M0.4 → M0.5 (پایه مشترک)\nفاز ۰.۵  M0.5.1 → M0.5.2 → M0.5.3 → M0.5.4 (زیرساخت تحویل کانتینر)\nفاز ۱    M1.1 → M1.2 → M1.3 → M1.4 → M1.5 → M1.5.5 → M1.5.6 → M1.5.7 → M1.6 → M1.7 (یک‌به‌یک کامل)\nفاز ۲    M2.1 → M2.2 → M2.3 → M2.4 → M2.5 → M2.6 (یک‌به‌یک کامل)\nفاز ۳    M3.1 → M3.2 → M3.3 → M3.4 (یک‌به‌یک کامل)\nفاز ۳.۵  M3.5.1 → M3.5.2 → M3.5.3 (امنیت و احراز هویت پیشرفته)\nفاز ۴    M4.1 → M4.2 → M4.3 → M4.4 → M4.5 → M4.6 (یک‌به‌یک کامل)\nفاز ۵    M5.1 → M5.2 → M5.3 → M5.4 → M5.5 → M5.6 → M5.7\nفاز ۶    M6.1 → M6.2 → M6.3\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "جدول زمانی و نقاط عطف (کلان)",
      "content": "| نقطه عطف | شرح | فاز |\n| --------- | ---- | --- |\n| **M0** | همه مستندات، بلوپرینت‌ها و قراردادها آماده و تأیید شده | فاز ۱- |\n| **M1** | زیرساخت آماده، هسته Go کار می‌کند، مونوریپو راه افتاده | فاز ۰ |\n| **M1.5** | زیرساخت تحویل کانتینر: Registry, CI/CD, Deployment Automation | فاز ۰.۵ |\n| **M2** | بازارچه + سفارش + پرداخت + چت + KYC — اولین تراکنش واقعی | فاز ۱ |\n| **M3** | داوری + بازخورد + زون + نظارت + ذخیره‌سازی — اعتماد کامل | فاز ۲ |\n| **M3.5** | Passkey + TOTP + Transaction Verification — امنیت پیشرفته | فاز ۳.۵ |\n| **M4** | بوست + جستجو + اعلان + تحلیل — اقتصاد فعال | فاز ۳ |\n| **M5** | اتوماسیون + n8n + پریمیوم — پلتفرم کامل | فاز ۴ |\n| **M6** | مقیاس‌پذیری و بهینه‌سازی — آماده تولید | فاز ۵ |\n| **M7** | فرانت‌اند کامل — قابل استفاده برای کاربران نهایی | فاز ۶ |\n\n---"
    },
    {
      "level": 2,
      "heading": "نکات مهم",
      "content": "- **هیچ سرویسی به صورت موازی کامل نمی‌شود** — تمرکز روی یک سرویس تا خروجی نهایی.\n- **دموها فقط بعد از پایه‌گذاری و برای همان سرویسی که در حال توسعه است ساخته می‌شوند**.\n- **مستندات README فاز ۱- صرفاً پیشنهادی است** و ممکن است بعد از توسعه سرویس‌های قبلی تغییر کند.  \n  مستندات نهایی و قابل اعتماد پس از اتمام هر سرویس در همان Milestone به‌روز می‌شوند.\n- هر Milestone خروجی مشخصی دارد: یک سرویس کاملاً کارا با دمو، مستندات و تست.\n\n---"
    },
    {
      "level": 2,
      "heading": "موارد خارج از MVP منتقل‌شده به نقشه راه (Roadmap Relocation - D4)",
      "content": "به منظور بهینه‌سازی دامنه MVP و تمرکز بر راه‌اندازی فرآیندهای حیاتی کسب‌وکار، موارد زیر از معماری فعال MVP خارج شده و به نقشه راه (Roadmap) منتقل شده‌اند:"
    },
    {
      "level": 3,
      "heading": "۱. چارت مستقر در کوبرنتیز مونگودی‌بی (MongoDB Helm Chart)",
      "content": "- **دلیل عدم نیاز در MVP:** در فاز MVP، چت گفتگوی کاربران حجم بسیار کمی داشته و نیازی به یک کلاستر توزیع‌شده با قابلیت دسترسی بالا برای MongoDB نیست. اجرای تک‌نمونه‌ای پایگاه‌داده موقت محلی برای اعتبارسنجی اولیه گفتگوها کافی است.\n- **زمان تقریبی ورود:** فاز ۲ (اعتماد و داوری)، همزمان با توسعه کامل `storage-service` (Milestone M2.6).\n- **وابستگی‌ها:** پیکربندی صحیح Persistent Volumes (PV/PVC) و StorageClassها روی کلاستر هدف.\n- **اثر بر معماری:** انتقال Chat Service از ذخیره‌ساز محلی به StatefulSetهای مقیاس‌پذیر MongoDB در کوبرنتیز به همراه تضمین ماندگاری داده‌ها برای داوری اختلافات."
    },
    {
      "level": 3,
      "heading": "۲. چارت مستقر در کوبرنتیز تایگربیتل (TigerBeetle Helm Chart)",
      "content": "- **دلیل عدم نیاز در MVP:** دفترکل تراکنش‌های مالی در فاز MVP می‌تواند به صورت یک پایگاه‌داده تک‌نسخه‌ای محلی موقت اجرا شود. عدم استفاده از چارت توزیع‌شده تایگربیتل در ابتدا، پیچیدگی استقرار اولیه را کاهش می‌دهد.\n- **زمان تقریبی ورود:** فاز ۵ (مقیاس و بهینه‌سازی)، Milestone M5.4.\n- **وابستگی‌ها:** پایداری ارکستراسیون حافظه ماندگار Stateful و مکانیزم‌های بازیابی شبکه در کلاستر.\n- **اثر بر معماری:** تغییر مدل استقرار لجر مالی از تک‌کانتینر توسعه محلی به کلاستر توزیع‌شده و خطاتحمل‌پذیر (بر پایه Raft) در کوبرنتیز پروداکشن."
    },
    {
      "level": 3,
      "heading": "۳. پشته مانیتورینگ (Monitoring Stack — Prometheus, Grafana, Jaeger)",
      "content": "- **دلیل عدم نیاز در MVP:** پایش پیشرفته سناریوهای توزیع‌شده و رهگیری درخواست‌ها برای تایید منطق تجاری اولیه ضروری نیست. عیب‌یابی اولیه از طریق بررسی لاگ پادها (`kubectl logs`) کفایت می‌کند.\n- **زمان تقریبی ورود:** فاز ۵ (مقیاس و بهینه‌سازی)، Milestone M5.2.\n- **وابستگی‌ها:** پیاده‌سازی کامل ابزاردقیق OpenTelemetry روی تمامی میکروسرویس‌ها و پایداری لایه رویداد.\n- **اثر بر معماری:** معرفی یک Namespace اختصاصی برای ابزارهای مانیتورینگ، اجرای DaemonSetها برای جمع‌آوری متریک‌ها و لاگ‌ها، و تعریف Sidecarهای مانیتورینگ در کنار پادها."
    },
    {
      "level": 3,
      "heading": "۴. اعتبارسنجی بازیابی پس از بحران (Disaster Recovery Validation)",
      "content": "- **دلیل عدم نیاز در MVP:** هدف اصلی MVP، صحت عملکرد فرآیند خرید و فروش است. فرآیندهای تست خرابی کامل کلاستر و بازیابی چندمنطقه‌ای به فازهای بلوغ عملیاتی موکول می‌شود.\n- **زمان تقریبی ورود:** فاز ۵ (مقیاس و بهینه‌سازی)، Milestone M5.4 (Recovery).\n- **وابستگی‌ها:** سیستم‌های ذخیره‌سازی ابری ماندگار، اسنپ‌شات‌های خودکار دیتابیس‌ها و سیاست‌های توزیع DNS.\n- **اثر بر معماری:** پیاده‌سازی بک‌آپ‌های خودکار و انتقال آن‌ها به ذخیره‌ساز خارجی S3 و ایجاد سناریوهای Failover خودکار برای ترافیک درگاه."
    },
    {
      "level": 3,
      "heading": "۵. توسعه ذخیره‌سازی ماندگار (Persistent Storage Expansion)",
      "content": "- **دلیل عدم نیاز در MVP:** برای توسعه محلی و سناریوهای تست اولیه، استفاده از hostPath یا حجم‌های پیش‌فرض محلی K3d کافی است و نیازی به راه‌اندازی و توسعه درایورهای ذخیره‌سازی ابری پیچیده نیست.\n- **زمان تقریبی ورود:** فاز ۵ (مقیاس و بهینه‌سازی)، Milestone M5.7.\n- **وابستگی‌ها:** ارائه‌دهندگان ذخیره‌سازی کلاستر هدف (مانند Rook-Ceph، AWS EBS یا ارتقای local-path-provisioner).\n- **اثر بر معماری:** افزودن درایورهای CSI پیشرفته، اعمال سیاست‌های افزایش حجم پویای دیسک پادها و تفکیک دیسک‌های با کارایی بالا برای دیتابیس‌ها."
    }
  ]
}