{
  "title": "شروع سریع بک‌اند",
  "slug": "team/backend/get-started",
  "url": "/docs/team/backend/get-started",
  "frontmatter": {
    "layout": "doc",
    "title": "شروع سریع بک‌اند",
    "description": "راهنمای شروع کار با سرویس‌های بک‌اند — ساختار، ایجاد سرویس جدید، مجوزها، APIها، رویدادها و چک‌لیست PR",
    "version": "1.0.0",
    "status": "ACTIVE",
    "author": "Platform Team",
    "owner": "Backend Team",
    "created_at": "2026-07-24",
    "updated_at": "2026-07-24",
    "tags": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "شروع سریع بک‌اند",
      "content": "**Backend Get Started**\n\n> این سند برای یک توسعه‌دهنده جدید کافی است تا بدون پرسیدن از تیم، سرویس بک‌اند خود را ایجاد، پیکربندی و با استانداردهای پلتفرم هماهنگ کند.\n\n---"
    },
    {
      "level": 2,
      "heading": "۱. نمای کلی",
      "content": ""
    },
    {
      "level": 3,
      "heading": "معماری",
      "content": "پلتفرم NONS بر پایه معماری **Microservice + Monorepo** (Nx + pnpm workspace) ساخته شده است:\n\n```\nnons-api/\n├── contracts/       Proto source of truth\n├── packages/        TS packages (types, contracts, events, logging, client)\n├── core/            Go control plane (NATS, Postgres, OTel)\n├── services/        24 سرویس (۶ پیاده‌سازی‌شده، ۱۸ blueprint)\n├── infra/           Gateway، Kratos، Hydra، k8s\n├── deploy/          Helm charts\n└── scripts/         Codegen و ابزارهای اتوماسیون\n```"
    },
    {
      "level": 3,
      "heading": "سه لایه حیاتی",
      "content": "```\nAuth Service  → «این شخص کیست؟» (هویت) — Ory Kratos\nUser Service  → «این شخص چگونه نمایش داده شود؟» (پروفایل)\nIAM Service   → «این شخص چه کاری اجازه دارد انجام دهد؟» (دسترسی)\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "۲. راه‌اندازی محیط",
      "content": ""
    },
    {
      "level": 3,
      "heading": "پیش‌نیازها",
      "content": "| ابزار | نسخه | توضیح |\n|-------|------|-------|\n| Go | >= 1.26 | کامپایل سرویس‌ها |\n| Node.js | >= 20 | برای pnpm و codegen |\n| pnpm | >= 9 | مدیریت وابستگی‌ها |\n| Docker | جدید | برای Redis، Kratos، Hydra، Postgres |\n| NATS | >= 2.x | صف پیام (اختیاری در توسعه) |"
    },
    {
      "level": 3,
      "heading": "دستورات اصلی",
      "content": "```bash"
    },
    {
      "level": 1,
      "heading": "از ریشه nons-api/ اجرا کنید",
      "content": "pnpm install"
    },
    {
      "level": 1,
      "heading": "تولید کد از Proto",
      "content": "pnpm codegen"
    },
    {
      "level": 1,
      "heading": "تست همه سرویس‌ها",
      "content": "pnpm test"
    },
    {
      "level": 1,
      "heading": "lint همه سرویس‌ها",
      "content": "pnpm lint"
    },
    {
      "level": 1,
      "heading": "build همه سرویس‌ها",
      "content": "pnpm build\n```"
    },
    {
      "level": 3,
      "heading": "اجرای سرویس",
      "content": "```bash"
    },
    {
      "level": 1,
      "heading": "یک سرویس خاص",
      "content": "cd services/iam-service\ngo run ./cmd"
    },
    {
      "level": 1,
      "heading": "یا از root با --filter",
      "content": "pnpm --filter @nons/iam-service dev\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "۳. ساختار یک سرویس",
      "content": ""
    },
    {
      "level": 3,
      "heading": "الگوی استاندارد",
      "content": "هر سرویس باید از این ساختار پیروی کند:\n\n```\nservices/<service-name>/\n├── cmd/\n│   └── main.go              # نقطه ورود\n├── internal/\n│   ├── config/\n│   │   └── config.go        # بارگذاری env vars\n│   ├── handler/\n│   │   └── handler.go       # هندلرهای HTTP\n│   ├── service/\n│   │   └── service.go       # منطق کسب‌وکار\n│   ├── repository/\n│   │   └── repository.go    # دسترسی به داده\n│   ├── model/\n│   │   └── model.go         # ساختارهای داده\n│   ├── middleware/\n│   │   └── auth.go          # میان‌افزار احراز هویت\n│   └── event/\n│       └── event.go         # NATS publisher/subscriber\n├── migrations/\n│   ├── migration.go\n│   └── 001_init.sql\n├── permissions.meta.yaml    # ← مجوزهای این سرویس\n├── go.mod\n├── Dockerfile\n└── README.md\n```\n\n> توجه: سرویس‌های `auth-service` و `login-consent-app` از الگوی قدیمی `main.go` در ریشه و `package internal` تخت استفاده می‌کنند. سرویس‌های جدید باید از الگوی `cmd/main.go` + زیرپکیج‌ها پیروی کنند.\n\n---"
    },
    {
      "level": 2,
      "heading": "۴. قوانین مجوزها (Permission Rules)",
      "content": ""
    },
    {
      "level": 3,
      "heading": "۴.۱ — هر سرویس مالک مجوزهای خود است",
      "content": "فایل `permissions.meta.yaml` در ریشه سرویس، مالکیت مجوزها را مشخص می‌کند:\n\n```yaml"
    },
    {
      "level": 1,
      "heading": "Owner: <your-service>",
      "content": "- key: yourresource.youraction\n  name: Human Readable Name\n  description: One-sentence explanation\n  group: yourresource\n```"
    },
    {
      "level": 3,
      "heading": "۴.۲ — زنجیره تعریف مجوز جدید",
      "content": "| مرحله | اقدام | مسئول |\n|-------|-------|-------|\n| ۱ | افزودن enum به `contracts/permissions.proto` | تیم پلتفرم |\n| ۲ | اجرای `pnpm codegen` | اتوماتیک |\n| ۳ | افزودن metadata به `permissions.meta.yaml` **در سرویس مالک** | تیم سرویس |\n| ۴ | اجرای `pnpm codegen` (aggregation + بررسی orphan/collision) | اتوماتیک |\n| ۵ | ثبت در IAM DB seed (`002_seed_defaults.sql`) | تیم سرویس |\n| ۶ | افزودن برچسب فارسی/انگلیسی در `admin-panel/locales/` | تیم فرانت |\n\n> **مالکیت توزیع‌شده:** هر سرویس فایل `permissions.meta.yaml` خود را در ریشهٔ خود دارد (مثلاً `services/order-service/permissions.meta.yaml`). IAM فقط aggregator است. aggregation در build-time توسط `pnpm codegen` انجام می‌شود. برای جزئیات بیشتر به `permissions-source-of-truth.md` مراجعه کنید."
    },
    {
      "level": 3,
      "heading": "۴.۳ — منبع حقیقت دوگانه",
      "content": "- **Proto** (`contracts/permissions.proto`) منبع حقیقت برای **تعریف کلیدها** است (key names, enum values)\n- **IAM** منبع حقیقت برای **وضعیت runtime** است (کدام کاربر کدام مجوز را دارد، نقش‌ها، خط‌مشی‌ها)\n\nهیچ سرویسی نباید مجوزی تعریف کند که در Proto نباشد (گیر افتادن در CI توسط orphan check). همچنین هیچ کلید Protoای نباید بدون owner بماند (orphan) یا بیش از یک owner داشته باشد (collision).\n\n---"
    },
    {
      "level": 2,
      "heading": "۵. قوانین API",
      "content": ""
    },
    {
      "level": 3,
      "heading": "مسیردهی",
      "content": "- همه routeها از الگوی `METHOD /v1/<resource>/...` پیروی می‌کنند\n- از `POST /v1/path` (بدون پیشوند متد) استفاده نکنید\n- مثال: `GET /v1/iam/roles`، `POST /v1/users/{id}/roles`\n\n```go\nmux.HandleFunc(\"GET /v1/iam/roles\", handler.ListRoles)\nmux.HandleFunc(\"POST /v1/iam/roles\", handler.CreateRole)\n```"
    },
    {
      "level": 3,
      "heading": "OpenAPI Annotation",
      "content": "هر endpoint جدید باید annotation `google.api.http` در proto داشته باشد:\n\n```proto\nrpc ListRoles (ListRolesRequest) returns (ListRolesResponse) {\n  option (google.api.http) = {\n    get: \"/v1/iam/roles\"\n  };\n}\n```"
    },
    {
      "level": 3,
      "heading": "فرمت پاسخ",
      "content": "```json\n{\n  \"success\": true,\n  \"data\": { ... },\n  \"meta\": { ... }\n}\n// یا\n{\n  \"success\": false,\n  \"error\": { \"code\": \"...\", \"message\": \"...\" }\n}\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "۶. قوانین NATS و رویدادها",
      "content": ""
    },
    {
      "level": 3,
      "heading": "EventEnvelope — همه سرویس‌ها باید از یک قالب پیروی کنند",
      "content": "```json\n{\n  \"id\": \"evt_uuid\",            // <- این فیلد الزامی است\n  \"subject\": \"nons.domain.entity.action\",\n  \"version\": 1,\n  \"timestamp\": \"2026-01-01T00:00:00Z\",\n  \"source\": \"service-name\",\n  \"trace_id\": \"...\" ,\n  \"payload\": { ... }\n}\n```\n\n> همه سرویس‌ها باید فیلد `id` را در EventEnvelope داشته باشند. سرویس‌های قدیمی که `id` ندارند باید به‌روز شوند.\n\n###命名 NATS subjects\n\nالگوی اجباری: `nons.<domain>.<entity>.<action>`\nمثال: `nons.auth.user.registered`، `nons.user.profile.updated`\n\n---"
    },
    {
      "level": 2,
      "heading": "۷. قوانین پیکربندی",
      "content": ""
    },
    {
      "level": 3,
      "heading": "بارگذاری env vars",
      "content": "از `godotenv` برای بارگذاری `.env` استفاده کنید (نه parser دستی):\n\n```go\nimport \"github.com/joho/godotenv\"\n\nfunc LoadConfig() Config {\n    godotenv.Load()\n    // ...\n}\n```"
    },
    {
      "level": 3,
      "heading": "نام‌گذاری env vars",
      "content": "- همه سرویس‌ها از `LOG_LEVEL=info` استفاده کنند (نه `AUTH_LOG_LEVEL`)\n- همه سرویس‌ها از `KRATOS_ADMIN_URL=...` استفاده کنند (نه `KRATOS_ADMIN`)\n- همه سرویس‌ها از `IAM_SERVICE_URL=...` استفاده کنند (نه `IAM_URL`)\n- مقادیر اجباری: `DATABASE_URL` (اگر سرویس دیتابیس دارد)\n- همه سرویس‌ها `PORT` برای پورت HTTP\n\n---"
    },
    {
      "level": 2,
      "heading": "۸. قوانین Middleware",
      "content": ""
    },
    {
      "level": 3,
      "heading": "الگوی احراز هویت",
      "content": "سرویس‌های جدید باید از **middleware-based auth** مشابه `iam-service` استفاده کنند:\n\n```go\n// internal/middleware/auth.go\nfunc AuthMiddleware(next http.Handler) http.Handler {\n    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {\n        userID := r.Header.Get(\"X-User-ID\")\n        if r.Header.Get(\"X-User-ID\") == \"\" {\n            http.Error(w, \"missing user identity\", http.StatusUnauthorized)\n            return\n        }\n        ctx := context.WithValue(r.Context(), \"user_id\", userID)\n        next.ServeHTTP(w, r.WithContext(ctx))\n    })\n}\n```\n\n> الگوی ad-hoc (خواندن هدر در هر هندلر به صورت مجزا) منسوخ شده است.\n\n---"
    },
    {
      "level": 2,
      "heading": "۹. چک‌لیست قبل از PR",
      "content": "- [ ] `go build ./...` — بدون خطا\n- [ ] `go vet ./...` — بدون خطا\n- [ ] تست‌ها پاس می‌شوند\n- [ ] فایل `permissions.meta.yaml` وجود دارد (اگر سرویس مجوز دارد)\n- [ ] همه کلیدهای مجوز در Proto تعریف شده‌اند\n- [ ] `pnpm codegen` اجرا شده و `git diff --exit-code` پاس می‌شود\n- [ ] event envelope دارای فیلد `id` است\n- [ ] routeها از الگوی `METHOD /v1/...` پیروی می‌کنند\n- [ ] env vars با naming convention هماهنگ هستند\n- [ ] auth middleware استفاده شده (نه ad-hoc)\n- [ ] خطاها fail-closed هستند (در صورت خطا، دسترسی رد شود)\n- [ ] `go mod tidy` اجرا شده\n\n---"
    },
    {
      "level": 2,
      "heading": "مستندات مرتبط",
      "content": "- [خدمات بک‌اند (index)](index)\n- [مدل مجوزها در پلتفرم](/docs/team/platform/permission-model)\n- [استاندارد قرارداد مجوز](/docs/team/platform/standards/permission-contract-standard)\n- [استاندارد همگام‌سازی SDK](/docs/team/platform/standards/permission-and-sdk-sync-standard)\n- [Blueprint سرویس IAM](services/iam-service)\n- [عیب‌یابی](troubleshooting)\n- [معماری پلتفرم](/docs/team/platform/Architecture)"
    }
  ]
}