{
  "title": "شروع سریع CLI و Codegen",
  "slug": "team/platform/get-started/cli-codegen",
  "url": "/docs/team/platform/get-started/cli-codegen",
  "frontmatter": {
    "layout": "doc",
    "title": "شروع سریع CLI و Codegen",
    "description": "راهنمای شروع کار با ابزارهای خط فرمان و pipeline تولید خودکار کد از Proto — Buf، OpenAPI، SDK",
    "version": "1.0.0",
    "status": "ACTIVE",
    "author": "Platform Team",
    "owner": "Platform Team",
    "created_at": "2026-07-24",
    "updated_at": "2026-07-24",
    "tags": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "شروع سریع CLI و Codegen",
      "content": "**CLI & Codegen Get Started**\n\n> این سند برای یک توسعه‌دهنده جدید کافی است تا pipeline تولید خودکار کد از Proto را بفهمد، اجرا کند و خطاهای رایج را رفع کند.\n\n---"
    },
    {
      "level": 2,
      "heading": "۱. پیش‌نیازها",
      "content": "| ابزار | نسخه | توضیح |\n|-------|------|-------|\n| Node.js | >= 20 | برای pnpm + اسکریپت‌ها |\n| pnpm | >= 9 | مدیریت وابستگی‌ها |\n| Go | >= 1.26 | برای protoc-gen-go و کامپایل سرویس‌ها |\n| Buf CLI | ^1.70.0 | از طریق devDependencies نصب می‌شود (`npx buf`) |\n\n---"
    },
    {
      "level": 2,
      "heading": "۲. دستورات اصلی",
      "content": "```bash"
    },
    {
      "level": 1,
      "heading": "از ریشه nons-api/ اجرا شود",
      "content": "pnpm codegen\n```\n\nاین دستور ۸ مرحله را به ترتیب اجرا می‌کند:\n\n```\n1. buf generate (types)       → packages/types/src/\n2. buf generate (contracts)   → packages/contracts/src/\n3. buf generate (events)      → packages/events/src/\n4. buf generate (go)          → core/platform/        (Go pb bindings)\n5. buf generate (openapi)     → gen/                  (gitignored .swagger.json)\n6. generate-iam-keys          → iam-service Go constants\n7. aggregate-permission-meta  → iam-service aggregated metadata\n8. openapi-typescript         → iam-sdk.ts            (TS from OpenAPI)\n   └── prettier --write       → فرمت‌دهی تمام خروجی‌ها\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "۳. تمایز FINAL vs INTERMEDIATE",
      "content": "| Artifact | مسیر | وضعیت | توضیح |\n|----------|------|-------|-------|\n| تایپ‌های TS | `packages/types/src/` | ✅ FINAL | commit شده، CI-enforced |\n| کانترکت‌های TS | `packages/contracts/src/` | ✅ FINAL | commit شده |\n| رویدادها | `packages/events/src/` | ✅ FINAL | commit شده |\n| Go pb bindings | `core/platform/*.pb.go` | ✅ FINAL | commit شده |\n| Go aggregated meta | `iam-service/.../permission_meta_aggregated.go` | ✅ FINAL | commit شده |\n| OpenAPI JSON | `gen/openapi/` | 🔄 INTERMEDIATE | gitignored |\n| iam-sdk.ts | `packages/contracts/src/iam-sdk.ts` | ✅ FINAL | commit شده |\n\n> **قاعده:** INTERMEDIATEها (`gen/`) gitignore هستند چون در همان run مصرف می‌شوند. FINALها commit می‌شوند و CI با `git diff --exit-code` بررسی می‌کند که همیشه با Proto هماهنگ باشند.\n\n---"
    },
    {
      "level": 2,
      "heading": "۴. افزودن Permission جدید",
      "content": "زنجیره کامل (رجوع کنید به `permissions-source-of-truth.md` برای جزئیات):\n\n1. افزودن enum value به `contracts/permissions.proto`\n2. `pnpm codegen` (تایپ‌های Go/TS به‌روز می‌شوند)\n3. افزودن metadata به `services/<your-service>/permissions.meta.yaml` (مالکیت توزیع‌شده)\n4. `pnpm codegen` (aggregation + بررسی orphan/collision)\n5. ثبت در IAM DB seed (`002_seed_defaults.sql`)\n6. افزودن برچسب فارسی/انگلیسی در `admin-panel/locales/`\n\n---"
    },
    {
      "level": 2,
      "heading": "۵. عیب‌یابی خطاهای رایج CI",
      "content": ""
    },
    {
      "level": 3,
      "heading": "`git diff --exit-code` fail",
      "content": "علت: فایل‌های FINAL با Proto هماهنگ نیستند. یا Proto تغییر کرده و codegen اجرا نشده، یا خروجی دستی تغییر کرده.\n\n**رفع:** `pnpm codegen` را اجرا کنید و فایل‌های تغییر یافته را commit کنید."
    },
    {
      "level": 3,
      "heading": "`buf breaking` fail",
      "content": "علت: تغییری در Proto ایجاد شده که با نسخهٔ قبلی سازگار نیست (حذف فیلد، تغییر شماره enum).\n\n**رفع:** فیلدهای حذف‌شده را با `reserved` علامت‌گذاری کنید یا enum values را با `reserved` نگه دارید."
    },
    {
      "level": 3,
      "heading": "Orphan key (CI rejects)",
      "content": "علت: کلیدی در Proto تعریف شده که هیچ `permissions.meta.yaml`ای مالکیت آن را اعلام نکرده.\n\n**رفع:** به سرویس مربوطه `permissions.meta.yaml` اضافه کنید."
    },
    {
      "level": 3,
      "heading": "Collision key (CI rejects)",
      "content": "علت: یک کلید در دو فایل `permissions.meta.yaml` متفاوت تعریف شده.\n\n**رفع:** مشخص کنید کدام سرویس مالک واقعی است و از دیگری حذف کنید.\n\n---"
    },
    {
      "level": 2,
      "heading": "مستندات مرتبط",
      "content": "- [شروع سریع فرانت‌اند](/docs/team/frontend/get-started)\n- [شروع سریع بک‌اند](/docs/team/backend/get-started)\n- [منبع حقیقت مجوزها](https://github.com/nons/nons-api/blob/main/services/iam-service/docs/permissions-source-of-truth.md)\n- [استاندارد قرارداد مجوز](/docs/team/platform/standards/permission-contract-standard)\n- [معماری پلتفرم](/docs/team/platform/Architecture)"
    }
  ]
}