{
  "title": "بلوپرینت هسته اصلی",
  "slug": "team/platform/core/blueprint",
  "url": "/docs/team/platform/core/blueprint",
  "frontmatter": {
    "layout": "doc",
    "title": "بلوپرینت هسته اصلی",
    "description": "راهنمای طراحی، اصول، مسئولیت‌ها و ساختار کلان سرویس Core",
    "version": "1.0.0",
    "status": "PUBLIC",
    "author": "xoxxel",
    "owner": "xoxxel",
    "created_at": "2026-06-11",
    "updated_at": "2026-06-13",
    "tags": "",
    "reviewers": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "بلوپرینت هسته اصلی",
      "content": "**Core Platform Blueprint**\n\n> **خلاصه:** این سند نمای کلی، اصول طراحی، مسئولیت‌ها و الگوهای تعاملی لایه کنترل پلتفرم (Core) رو در پروژه NONS تشریح می‌کنه.\n\n---"
    },
    {
      "level": 2,
      "heading": "ارجاعات مرتبط",
      "content": "**Related Documents**\n\n- [معماری هسته اصلی](./Architecture)\n- [تصمیم معماری ۱: انتخاب Go](./ADR/ADR-Core-001)\n- [تصمیم معماری ۲: Core به عنوان Platform Control Plane](./ADR/ADR-Core-002)\n\n---"
    },
    {
      "level": 2,
      "heading": "فهرست محتوا",
      "content": "**Table of Contents**\n\n1. [هدف](#هدف)\n2. [اصول طراحی](#اصول-طراحی)\n3. [جایگاه در معماری](#جایگاه-در-معماری)\n4. [مسئولیت‌های Core](#مسئولیت‌های-core)\n5. [مسئولیت‌های ممنوع](#مسئولیت‌های-ممنوع)\n6. [ساختار پروژه](#ساختار-پروژه)\n7. [معرفی تفصیلی ماژول‌ها](#معرفی-تفصیلی-ماژول‌ها)\n8. [ذخیره‌سازی و وابستگی‌ها](#ذخیره‌سازی-و-وابستگی‌ها)\n9. [رویدادهای مورد انتظار](#رویدادهای-مورد-انتظار)\n10. [الزامات غیرعملیاتی و معیار موفقیت](#الزامات-غیرعملیاتی-و-معیار-موفقیت)\n\n---"
    },
    {
      "level": 2,
      "heading": "هدف",
      "content": "**Objective**\n\nCore لایه کنترل پلتفرم (Platform Control Plane) در پروژه NONS هستش.\nاین سرویس مسئول مدیریت قابلیت‌های فنی مشترک در سطح پلتفرمه و اصلاً نباید وارد حوزه‌های کسب‌وکاری و بیزنس بشه.\n\nهدف از طراحی Core، ایجاد یک نقطه متمرکز واسه کارهای زیر هست:\n\n- Audit Logging\n- Technical Event Validation\n- Service Registry\n- Health Monitoring\n- Platform Governance\n\n> [!IMPORTANT]\n> سرویس Core نباید به هیچ عنوان به دامنه‌های کسب‌وکاری پلتفرم وابسته باشه.\n\n---"
    },
    {
      "level": 2,
      "heading": "اصول طراحی",
      "content": "**Design Principles**"
    },
    {
      "level": 3,
      "heading": "استقلال از دامنه کسب‌وکار",
      "content": "**Domain Agnostic**\n\nسرویس Core نسبت به دامنه‌های کسب‌وکاری کاملاً ناآگاه هستش و نباید هیچ اطلاعاتی درباره سفارش‌ها، پرداخت‌ها، کیف پول، محصولات، کاربرا، چت و جستجو داشته باشه. وجود هر مدل دامنه‌ای توی Core یه نقض معماری جدی به حساب میاد."
    },
    {
      "level": 3,
      "heading": "اولویت زیرساخت",
      "content": "**Infrastructure First**\n\nCore یه سرویس زیرساختیه که واسه پشتیبانی از اکوسیستم سرویس‌ها طراحی شده، نه برای اجرای منطق محصول و کارهای تجاری."
    },
    {
      "level": 3,
      "heading": "رویدادمحور بودن",
      "content": "**Event Driven**\n\nتمام تعاملات Core مبتنی بر رویداد (Event) هستن. Core هیچ وقت سرویس‌های دیگه رو مستقیم صدا نمی‌زنه و کل ارتباطاتش از طریق NATS انجام می‌شه."
    },
    {
      "level": 3,
      "heading": "استقلال از فناوری",
      "content": "**Technology Independent**\n\nواسه‌ Core فرقی نداره سرویس‌های دیگه با چی نوشته شدن (Go، Node.js، Python یا غیره). Core نباید هیچ وابستگی به تکنولوژی سرویس‌ها داشته باشه."
    },
    {
      "level": 3,
      "heading": "پایداری بلندمدت",
      "content": "**Long-Term Stability**\n\nاضافه شدن سرویس یا رویداد جدید، یا تغییر تکنولوژی سرویس‌ها نباید تغییری روی Core اعمال کنه.\n\n---"
    },
    {
      "level": 2,
      "heading": "جایگاه در معماری",
      "content": "**Position in Architecture**\n\n```text\nFrontend\n    │\n    ▼\nAPI Gateway\n    │\n    ▼\nBusiness Services\n    │\n    ▼\nNATS\n    │\n    ├───────────────► Core\n    │\n    ▼\nOther Consumers\n```\n\nCore خارج از فرآیند مستقیم درخواست‌های کاربرا قرار داره و هیچ Endpoint عمومی برای کاربرا نداره.\n\n---"
    },
    {
      "level": 2,
      "heading": "مسئولیت‌های Core",
      "content": "**Core Responsibilities**"
    },
    {
      "level": 3,
      "heading": "ثبت لاگ‌های حسابرسی",
      "content": "**Audit Logging**\n\nثبت غیرقابل تغییر وقایع سیستم جهت پیگیری رخدادها، انطباق با قوانین، عیب‌یابی و بررسی حوادث. Core تاریخچه کامل رویدادها رو نگه می‌داره."
    },
    {
      "level": 3,
      "heading": "اعتبارسنجی فنی رویدادها",
      "content": "**Technical Event Validation**\n\nاعتبارسنجی فراداده‌های فنی رویدادها بر اساس ساختار مشترک در فایل [envelope.proto](file:///C:/Users/ASUS/Documents/GitHub/nons/nons-api/contracts/envelope.proto). فیلدهای فنی مثل `id`، `subject`، `version`، `timestamp`، `source` و `trace_id` اعتبارسنجی می‌شن. Core حق نداره محتوای دامنه‌ای (Payload) رو بررسی کنه."
    },
    {
      "level": 3,
      "heading": "ثبت سرویس‌ها",
      "content": "**Service Registry**\n\nنگهداری لیست و اطلاعات سرویس‌های فعال شامل نام سرویس، نسخه، محیط اجرا (Environment)، زمان اولین مشاهده و آخرین مشاهده."
    },
    {
      "level": 3,
      "heading": "پایش وضعیت سلامت",
      "content": "**Health Monitoring**\n\nبررسی و تعیین وضعیت سلامت سرویس‌ها از طریق سیگنال‌های Heartbeat. وضعیت‌ها شامل **UP**، **DEGRADED** و **DOWN** می‌شه."
    },
    {
      "level": 3,
      "heading": "حاکمیت پلتفرم",
      "content": "**Platform Governance**\n\nکنترل و نظارت روی انطباق فنی سرویس‌ها با قوانین و استانداردهای پلتفرم (مثل قرارداد رویدادها، متادیتا و لاگ‌نویسی).\n\n---"
    },
    {
      "level": 2,
      "heading": "مسئولیت‌های ممنوع",
      "content": "**Forbidden Responsibilities**\n\nسرویس Core به هیچ عنوان نباید کارهای زیر رو انجام بده:\n\n- احراز هویت (Authentication) و مجوزها (Authorization)\n- مدیریت پرداخت‌ها، کیف پول و تسویه حساب\n- پردازش سفارش‌ها و مدیریت محصولات\n- چت، جستجو و اجرای گردش کارهای دامنه‌ای (Workflow / Saga)\n\n---"
    },
    {
      "level": 2,
      "heading": "ساختار پروژه",
      "content": "**Project Structure**\n\n```text\ncore/\n├── cmd/\n│   └── main.go\n├── internal/\n│   ├── audit/\n│   ├── validation/\n│   ├── registry/\n│   ├── health/\n│   ├── lifecycle/\n│   ├── eventrouter/\n│   ├── storage/\n│   ├── telemetry/\n│   └── shared/\n├── configs/\n├── migrations/\n├── deployments/\n├── go.mod\n└── Dockerfile\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "معرفی تفصیلی ماژول‌ها",
      "content": "**Modules In-Depth**"
    },
    {
      "level": 3,
      "heading": "ماژول Event Router",
      "content": "**Event Router Module**\n\nوظیفه این ماژول دریافت رویدادها از NATS و تحویل اون‌ها به بخش‌های Validator و Audit هستش. این ماژول نباید هیچ تصمیم تجاری یا هماهنگی فرآیندی انجام بده."
    },
    {
      "level": 3,
      "heading": "ماژول Validation",
      "content": "**Validation Module**\n\nوظیفه بررسی Envelope رویدادها رو بر اساس بایندینگ‌های Go تولیدشده داره. در صورت نامعتبر بودن رویداد، موضوع رو ثبت کرده و متریک‌های مربوطه رو بالا می‌بره."
    },
    {
      "level": 3,
      "heading": "ماژول Audit",
      "content": "**Audit Module**\n\nمسئول ذخیره‌سازی ایمن و غیرقابل تغییر رویدادها و تاریخچه‌ نویسی هست."
    },
    {
      "level": 3,
      "heading": "ماژول Registry",
      "content": "**Registry Module**\n\nثبت و به‌روزرسانی مشخصات و نسخه‌های تمام سرویس‌های فعال پلتفرم رو انجام می‌ده."
    },
    {
      "level": 3,
      "heading": "ماژول Health",
      "content": "**Health Module**\n\nدریافت Heartbeatها و تحلیل تاخیرها برای اعلام وضعیت سلامت سرویس‌ها رو انجام می‌ده.\n\n> [!NOTE]\n> **محدودیت فاز فعلی (MVP):** سرویس Core در این فاز مسئولیتی بابت فرستادن اعلان یا اجرای خودکار فرآیندهای بازیابی در زمان خرابی سرویس‌ها نداره. رویداد `platform.service.status_changed` به عنوان نقطه توسعه آتی (Extension Point) واسه این کار در نظر گرفته شده."
    },
    {
      "level": 3,
      "heading": "ماژول Lifecycle",
      "content": "**Lifecycle Module**\n\nمدیریت بالا آمدن و خاموش شدن امن و منظم (Graceful Shutdown) سرویس Core و وابستگی‌هاش رو بر عهده داره.\n\n---"
    },
    {
      "level": 2,
      "heading": "ذخیره‌سازی و وابستگی‌ها",
      "content": "**Storage & Dependencies**"
    },
    {
      "level": 3,
      "heading": "پایگاه داده PostgreSQL",
      "content": "**PostgreSQL Database**\n\nسرویس Core برای ذخیره اطلاعات فقط به PostgreSQL وابسته هست و از جداول `services`، `heartbeats` و `audit_logs` استفاده می‌کنه."
    },
    {
      "level": 3,
      "heading": "وابستگی‌های مجاز و غیرمجاز",
      "content": "**Allowed & Forbidden Dependencies**\n\n- **مجاز:** NATS، PostgreSQL، OpenTelemetry و Prometheus.\n- **غیرمجاز:** وابستگی به کدهای اختصاصی هر سرویس تجاری در `nons-api/services/*` و کلیه پکیج‌های TypeScript در `nons-api/packages/*`.\n- **مجاز پس از ADR-Platform-001:** استفاده از فایل‌های Proto در `contracts/` و بایندینگ‌های Go تولید شده از اون‌ها در مرحله CI.\n\n---"
    },
    {
      "level": 2,
      "heading": "رویدادهای مورد انتظار",
      "content": "**Expected Events**\n\nCore رویدادهای اختصاصی خودش رو نداره و فقط رویدادهای عمومی پلتفرم رو که ساختارشون توی `envelope.proto` مشخص شده، مصرف می‌کنه. مثل:\n\n```text\nplatform.service.registered\nplatform.service.heartbeat\nplatform.service.shutdown\n```\n\nCore نباید با اضافه شدن رویداد جدید تغییر کنه.\n\n---"
    },
    {
      "level": 2,
      "heading": "الزامات غیرعملیاتی و معیار موفقیت",
      "content": "**Performance Requirements & Success Criteria**"
    },
    {
      "level": 3,
      "heading": "الزامات عملکردی",
      "content": "**Performance Requirements**\n\n- **بی‌حالت بودن (Stateless):** Core باید Stateless بمونه تا بشه چندتا نسخه ازش رو به طور همزمان اجرا کرد.\n- **مقیاس‌پذیری افقی:** پشتیبانی کامل از Horizontal Scaling.\n- **متریک‌ها:** ثبت متریک‌های پردازش رویدادها، وضعیت سلامت و تعداد سرویس‌ها."
    },
    {
      "level": 3,
      "heading": "معیار موفقیت",
      "content": "**Success Criteria**\n\nاگه با حذف، اضافه یا تغییر زبان هر کدوم از سرویس‌های محصول (مثل پرداخت یا سفارش)، سرویس Core بدون هیچ تغییری به کار خودش ادامه بده، معماری طراحی شده موفق بوده."
    }
  ]
}