{
  "title": "یافته‌های احراز معماری",
  "slug": "team/devops/architecture-verification-findings",
  "url": "/docs/team/devops/architecture-verification-findings",
  "frontmatter": {
    "layout": "doc",
    "title": "یافته‌های احراز معماری",
    "description": "بررسی انطباق پروژه nons-api با معماری Kubernetes-Native استقرار — تغییرات الزامی، توصیه‌شده و اختیاری",
    "version": "1.0.0",
    "status": "PRIVATE",
    "author": "Antigravity",
    "owner": "Devops Team",
    "created_at": "2026-06-16",
    "updated_at": "2026-06-16",
    "tags": "",
    "reviewers": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "یافته‌های احراز معماری",
      "content": "**Architecture Verification Findings — Nons-api vs. Kubernetes-Native Architecture**\n\n---"
    },
    {
      "level": 2,
      "heading": "مقدمه",
      "content": "این سند نتیجه بررسی پروژه `nons-api` در برابر معماری Kubernetes-Native استقرار تعریف‌شده در مستندات devops است. **هیچ تغییری در کد اعمال نشده** — فقط یافته‌ها ثبت شده‌اند تا در تسک‌های بعدی پیاده‌سازی شوند.\n\n---"
    },
    {
      "level": 2,
      "heading": "۱. تغییرات الزامی (Required Changes)",
      "content": "تغییراتی که بدون آن‌ها استقرار روی سرور عملیاتی امکان‌پذیر نیست.\n\n| # | عنوان | مؤلفه | اولویت | توضیح |\n|---|-------|--------|--------|-------|\n| R1 | **ghcr.io Authentication** | CI/CD | HIGH | ایجاد PAT برای push تصاویر + `imagePullSecrets` در K8s |\n| R2 | **K3s Cluster Provisioning** | Infrastructure | HIGH | راه‌اندازی سرور K3s با containerd و Helm |\n| R3 | **Production Secrets واقعی** | Deploy | HIGH | جایگزینی placeholderهای `.env.example` با رازهای امن |\n| R4 | **DNS Records + TLS** | Network | HIGH | تنظیم A/CNAME برای `nons.ir` + نصب cert-manager |\n| R5 | **Helm Chart برای Core Service** | Deploy | HIGH | `core/` فاقد چارت Helm است — بدون آن قابل استقرار نیست |\n| R6 | **تکمیل production/values.yaml** | Deploy | HIGH | مقادیر واقعی replica، resources، storage برای Production تنظیم نشده |\n| R7 | **NATS Subjects با پیشوند `nons.`** | Core | HIGH | Core از subjects بدون `nons.` استفاده می‌کند — با سرویس‌ها ناسازگار است |\n| R8 | **پارامتری‌سازی تصویر در auth-service** | Deploy | HIGH | تصویر و pullPolicy در دپلویمنت auth-service هاردکد شده‌اند — باید از values استفاده کنند |\n\n---"
    },
    {
      "level": 2,
      "heading": "۲. تغییرات توصیه‌شده (Recommended Changes)",
      "content": "تغییراتی که استقرار را ایمن‌تر، پایدارتر و قابل نگهداری‌تر می‌کند.\n\n| # | عنوان | مؤلفه | اولویت | توضیح |\n|---|-------|--------|--------|-------|\n| S1 | **CI/CD Pipeline برای انتشار** | CI/CD | MEDIUM | Build + Push + Deploy خودکار — GitHub Actions workflow جدید |\n| S2 | **NetworkPolicy** | Deploy | MEDIUM | محدود کردن ترافیک بین Namespaceها با Kubernetes NetworkPolicy |\n| S3 | **Pod Disruption Budget** | Deploy | MEDIUM | تضمین حداقل ۱ پاد برای سرویس‌های Stateless |\n| S4 | **Health Check برای همه سرویس‌ها** | Services | MEDIUM | اطمینان از readinessProbe/livenessProbe در همه Helm charts |\n| S5 | **HPA فعال** | Deploy | MEDIUM | Horizontal Pod Autoscaler بر اساس CPU/Memory |\n| S6 | **.env.example پاک‌سازی** | Repo | MEDIUM | جایگزینی مقادیر واقعی با placeholders |\n| S7 | **چرخش کلیدها و رمزها** | Devops | MEDIUM | Password/Token قوی برای PostgreSQL, Redis, NATS |\n| S8 | **Image Tag در auth-service** | Auth Service | MEDIUM | `version: '1.0.0'` → `'1.0'` (۲ بخشی به جای ۳ بخشی) |\n| S9 | **مسیرهای تکراری Auth** | Auth Service | MEDIUM | حذف مسیرهای بدون prefix — فقط `/v1/auth/*` بماند |\n\n---"
    },
    {
      "level": 2,
      "heading": "۳. بهبودهای اختیاری (Optional Improvements)",
      "content": "بهبودهایی که برای آینده مفید هستند اما برای MVP ضروری نیستند.\n\n| # | عنوان | مؤلفه | اولویت | توضیح |\n|---|-------|--------|--------|-------|\n| O1 | **External Secrets Operator** | Infrastructure | LOW | Sync خودکار Secrets از Vault/ AWS Secrets Manager |\n| O2 | **Monitoring Stack** | Infrastructure | LOW | Prometheus + Grafana + Jaeger |\n| O3 | **Service Mesh (Istio/Linkerd)** | Infrastructure | LOW | mTLS داخلی، traffic splitting، observability |\n| O4 | **ArgoCD / Flux (GitOps)** | CI/CD | LOW | استقرار Declarative با Git به عنوان منبع حقیقت |\n| O5 | **Grafana Faro (Real User Monitoring)** | Frontend | LOW | نظارت بر عملکرد فرانت‌اند |\n| O6 | **Vault Integration** | Secrets | LOW | مرکزیت مدیریت تمام رازها |\n| O7 | **HashiCorp Waypoint** | CI/CD | LOW | استقرار یکپارچه Platform-as-Product |\n| O8 | **Multi-Arch Images (arm64)** | CI | LOW | پشتیبانی از Apple Silicon و ARM servers |\n| O9 | **Container Image Signing (Cosign)** | CI/CD | LOW | امضای تصاویر برای زنجیره تأمین امن |\n| O10 | **Backup & Restore Automation** | Infrastructure | LOW | CronJob برای pg_dump + S3 upload |\n| O11 | **K8s Event Audit به NATS** | Core | LOW | Core می‌تواند رویدادهای K8s را به NATS پخش کند |\n| O12 | **Canary / Blue-Green Deploy** | CI/CD | LOW | استقرار تدریجی با کنترل ترافیک |\n\n---"
    },
    {
      "level": 2,
      "heading": "۴. یافته‌های خاص معماری (Specific Architecture Findings)",
      "content": ""
    },
    {
      "level": 3,
      "heading": "۴.۱ Core NATS Subjects (H1 از developer-violations.md)",
      "content": "**مشکل:** `core/internal/shared/shared.go` از subjects بدون پیشوند `nons.` استفاده می‌کند:\n\n```go\n// اشتباه — فاقد پیشوند nons.\nSubjectServiceRegistered = \"platform.service.registered\"\nSubjectServiceHeartbeat  = \"platform.service.heartbeat\"\n```\n\n**تأثیر:** Core روی `platform.service.>` subscribe می‌کند در حالی که سرویس‌ها با `nons.platform.service.*` publish می‌کنند. هیچ رویدادی به Core نمی‌رسد.\n\n**راهکار:** اصلاح subjects در `shared.go` و `router.go` به `nons.platform.service.*`."
    },
    {
      "level": 3,
      "heading": "۴.۲ publishStatusChanged هرگز publish نمی‌کند (H2 از developer-violations.md)",
      "content": "**مشکل:** در `core/internal/health/health.go`، تابع `publishStatusChanged` رویداد را می‌سازد و log می‌کند اما هیچوقت روی NATS publish نمی‌کند.\n\n**تأثیر:** رویداد `nons.platform.service.status_changed` ثبت شده در `events.ts` هرگز در NATS منتشر نمی‌شود.\n\n**راهکار:** پیاده‌سازی NATS publish در `publishStatusChanged`."
    },
    {
      "level": 3,
      "heading": "۴.۳ نقش پیش‌فرض `buyer` هاردکد شده (M7 از developer-violations.md)",
      "content": "**مشکل:** `services/auth-service/src/server.ts:240` نقش `buyer` را به عنوان پیش‌فرض هاردکد کرده است:\n\n```typescript\nroles: traits.role ? [traits.role] : ['buyer'],\n```\n\n**تأثیر:** همه کاربران جدید بدون مراجعه به IAM، نقش `buyer` می‌گیرند.\n\n**راهکار:** حذف پیش‌فرض — IAM Service باید از طریق رویداد `nons.iam.role.assigned` نقش را تعیین کند."
    },
    {
      "level": 3,
      "heading": "۴.۴ سرویس‌ها Startup/Shutdown خود را publish نمی‌کنند (M8 از developer-violations.md)",
      "content": "**مشکل:** `core/cmd/main.go` و auth-service startup/shutdown خود را به NATS اعلام نمی‌کنند.\n\n**تأثیر:** Service Registry Core خالی می‌ماند — هیچ سرویسی ثبت‌نام نمی‌کند.\n\n**راهکار:** publish `SubjectServiceRegistered` پس از اتصال NATS، publish `SubjectServiceShutdown` در graceful shutdown."
    },
    {
      "level": 3,
      "heading": "۴.۵ Docker Compose Legacy",
      "content": "**وضعیت:** `docker-compose.yml` در مخزن وجود ندارد — همواره شده به K3d/Helm طبق ADR-DevOps-001. ✅\n**تأیید:** هیچ Docker Compose در مسیر رسمی استقرار وجود ندارد."
    },
    {
      "level": 3,
      "heading": "۴.۶ Package Build-Time Only",
      "content": "**وضعیت:** `packages/types`, `packages/contracts`, `packages/events`, `packages/logging` build-time only هستند و در تصویر نهایی حضور ندارند. ✅\n**تأیید:** `packages/client` در معماری جدید وجود ندارد — مصنوعات فرانت‌اند توسط `nons generate` در `.nons/generated/` تولید می‌شوند. ✅\n\n---"
    },
    {
      "level": 2,
      "heading": "۵. پیشنهادات فنی برای استقرار",
      "content": ""
    },
    {
      "level": 3,
      "heading": "۵.۱ ترتیب استقرار در Production (Recommended Sequence)",
      "content": "```\n۱. PostgreSQL (پایگاه داده مرکزی)\n۲. Redis (کش و Rate Limiting)\n۳. NATS JetStream (گذرگاه رویدادها)\n─── پس از تأیید زیرساخت ───\n۴. Ory Kratos (مدیریت هویت) — migration خودکار\n۵. Ory Hydra (سرور OAuth2) — migration خودکار\n─── پس از تأیید Kratos + Hydra ───\n۶. Auth Service (سرویس واسط)\n─── پس از تأیید احراز هویت ───\n۷. Core (کنترل پلن)\n─── پس از تأیید همه سرویس‌ها ───\n۸. Gateway (Traefik Ingress) — آخرین لایه\n```"
    },
    {
      "level": 3,
      "heading": "۵.۲ استراتژی Image Tag برای Production",
      "content": "| مرحله | Tag | توضیح |\n|-------|-----|-------|\n| اولین استقرار | `1.0.0` | اولین Release |\n| Patch | `1.0.1`, `1.0.2` | رفع باگ |\n| Minor | `1.1.0`, `1.2.0` | قابلیت جدید (عقب‌گر compatible) |\n| Major | `2.0.0`, `3.0.0` | تغییرات بزرگ |"
    },
    {
      "level": 3,
      "heading": "۵.۳ Rollback Strategy",
      "content": "```bash\nhelm history nons-auth-service -n nons-platform\nhelm rollback nons-auth-service <PREVIOUS_REVISION> -n nons-platform\n```\n\n**شرط Rollback:** Failure در readinessProbe تا ۵ دقیقه پس از upgrade.\n\n---"
    },
    {
      "level": 2,
      "heading": "۶. خلاصه",
      "content": "| دسته | تعداد | بحرانی‌ترین |\n|------|-------|------------|\n| 🔴 Required | ۸ | ghcr.io Auth, K3s Cluster, Core Helm Chart |\n| 🟡 Recommended | ۹ | CI/CD Pipeline, NetworkPolicy, HPA |\n| 🟢 Optional | ۱۲ | Monitoring, GitOps, Vault |\n| **Total** | **۲۹** | — |\n\n**نتیجه:** پروژه با ۸ تغییر الزامی برای استقرار آماده می‌شود. این تغییرات در سه حوزه متمرکز هستند: CI/CD (ghcr.io + Pipeline)، زیرساخت (K3s + DNS + TLS)، و اصلاح ناسازگاری‌های معماری (NATS subjects + Core Helm Chart)."
    }
  ]
}