{
  "title": "شروع سریع فرانت‌اند",
  "slug": "team/frontend/get-started",
  "url": "/docs/team/frontend/get-started",
  "frontmatter": {
    "layout": "doc",
    "title": "شروع سریع فرانت‌اند",
    "description": "راهنمای شروع کار با پنل ادمین — نصب، ساختار، قوانین مجوزها، ترجمه و چک‌لیست PR",
    "version": "1.0.0",
    "status": "ACTIVE",
    "author": "Platform Team",
    "owner": "Frontend Team",
    "created_at": "2026-07-24",
    "updated_at": "2026-07-24",
    "tags": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "شروع سریع فرانت‌اند",
      "content": "**Frontend Get Started**\n\n> این سند برای یک توسعه‌دهنده جدید کافی است تا بدون پرسیدن از تیم، محیط خود را راه‌اندازی کند، با ساختار پروژه آشنا شود و قوانین توسعه را رعایت کند.\n\n---"
    },
    {
      "level": 2,
      "heading": "📌 قانون معماری و تصمیم فریم‌ورک (Architecture Standard & ADR-0001)",
      "content": "> 🚨 **دستورالعمل اجباری فرانت‌اند:**\n> طبق سند تصمیم معماری [ADR-0001 / ADR-Platform-006](https://dotdive.ir/docs/team/platform/ADR/ADR-Platform-006-renderer-framework-vue)، تمام پکیج‌های فرانت‌اند شامل `@nons-dev/uikit`، `@nons-dev/renderer` و `admin-panel` **منحصراً مبتنی بر Vue 3** توسعه می‌یابند.\n>\n> **چرخهٔ لایه‌های Schema-Driven UI:**\n>\n> ```\n> @nons-dev/ui-schema (قرارداد داده خالص TS)\n>        ↓\n> @nons-dev/renderer (موتور رندر Vue 3)\n>        ↓\n> @nons-dev/uikit (کامپوننت‌های UI پایه Vue 3)\n>        ↓\n> admin-panel / UI Builder (مصرف‌کننده نهایی)\n> ```\n>\n> توسعه‌دهندگان جدید پیش از شروع کدنویسی باید الزامات این معماری را مطالعه و رعایت نمایند.\n\n---"
    },
    {
      "level": 2,
      "heading": "۱. راه‌اندازی محیط",
      "content": ""
    },
    {
      "level": 3,
      "heading": "پیش‌نیازها",
      "content": "| ابزار   | نسخه       | توضیح                                |\n| ------- | ---------- | ------------------------------------ |\n| Node.js | >= 20      | runtime                              |\n| npm     | همراه Node | package manager (pnpm نیست، npm است) |"
    },
    {
      "level": 3,
      "heading": "دستورات اصلی",
      "content": "```bash"
    },
    {
      "level": 1,
      "heading": "نصب وابستگی‌ها",
      "content": "npm install"
    },
    {
      "level": 1,
      "heading": "شروع توسعه (پورت 3000، auto-open)",
      "content": "npm run dev"
    },
    {
      "level": 1,
      "heading": "build + typecheck",
      "content": "npm run build"
    },
    {
      "level": 1,
      "heading": "فقط typecheck",
      "content": "npx vue-tsc -b --noEmit\n```\n\n> نکته: `admin-panel` از npm استفاده می‌کند، **نه pnpm**. فایل `package-lock.json` را با npm مدیریت کنید."
    },
    {
      "level": 3,
      "heading": "متغیرهای محیطی",
      "content": "| متغیر          | پیش‌فرض                 | اجباری؟ | توضیح                               |\n| -------------- | ----------------------- | ------- | ----------------------------------- |\n| `VITE_API_URL` | `''` (خالی = proxy)     | خیر     | آدرس API بک‌اند (توسعه: proxy Vite) |\n| `VITE_AUTH_UI` | `http://localhost:3000` | خیر     | آدرس auth-ui برای ریدایرکت لاگین    |\n\nفایل `.env` را از `.env.example` کپی کنید (در مخزن موجود است).\n\n---"
    },
    {
      "level": 2,
      "heading": "۲. معماری پروژه",
      "content": ""
    },
    {
      "level": 3,
      "heading": "ساختار پوشه‌ها",
      "content": "```\nsrc/\n├── main.ts              # نقطه ورود — bootstrap، SDK، mount\n├── App.vue               # فقط <RouterView /> + استایل سراسری\n├── app/\n│   └── router.ts         # Vue Router — تک مسیر / → AdminLayout\n├── auth/                 # احراز هویت — store, api, types, plugin\n├── components/           # کامپوننت‌های اپلیکیشن\n│   └── GenericPage.vue   # بارگذاری پویای schema بر اساس route param\n├── engine/               # PageRenderer — رندر پویای قالب‌ها\n├── templates/            # قالب‌های صفحه: table, form, detail, settings\n├── layouts/              # AdminLayout — سایدبار، هدر، ناحیه محتوا + i18n\n├── navigation/           # منوی استاتیک + فیلتر دسترسی\n├── permissions/          # ثابت‌های مجوزها (PERMISSIONS.*)\n├── i18n/                 # دیکشنری ترجمه + تست پوشش\n├── sdk/                  # HTTP client (fetch-based) + سرویس‌های SDK\n├── registry/             # پل بین UI و SDK\n├── schemas/              # صفحه‌های JSON (users, permissions, settings, ...)\n├── providers/            # کامپوزابل‌های اشتراکی\n├── services/             # (قدیمی — ترجیحاً از SDK استفاده کنید)\n└── styles/               # استایل‌های سراسری\n```"
    },
    {
      "level": 3,
      "heading": "جریان داده",
      "content": "```\nPage Schema (JSON) → PageRenderer → Template → @nons-dev/uikit → Registry → SDK\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "۳. قوانین مصرف مجوزها (Permission Rules)",
      "content": ""
    },
    {
      "level": 3,
      "heading": "قانون اول — هرگز رشته هاردکد نکنید",
      "content": "همه مجوزها باید از ثابت‌های `PERMISSIONS.*` در `src/permissions/constants.ts` استفاده کنند:\n\n```ts\n// ✅ درست\nimport { PERMISSIONS } from '../permissions/constants'\nif (hasPermission(PERMISSIONS.ADMIN.ACCESS)) { ... }\n\n// ❌ نادرست\nif (hasPermission('admin.access')) { ... }\n```"
    },
    {
      "level": 3,
      "heading": "قانون دوم — مجوزها در JSON schema",
      "content": "در فایل‌های JSON، از آرایه `permissions` با کلید کامل استفاده کنید:\n\n```json\n{\n  \"permissions\": [\"admin.access\"]\n}\n```\n\nاین فایل‌ها JSON هستند و نمی‌توانند از `PERMISSIONS.*` استفاده کنند، پس باید **دستی** با Proto هماهنگ بمانند."
    },
    {
      "level": 3,
      "heading": "قانون سوم — فقط ۲۱ کلید معتبر",
      "content": "تنها ۲۱ کلید مجوز در پلتفرم وجود دارد (تعریف‌شده در `contracts/permissions.proto`). هیچ کلید دیگری نباید در کد ظاهر شود. لیست کامل:\n\n| گروه     | کلیدها                                                                                                                                                                       |\n| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| admin    | `admin.access`, `roles.read`, `permissions.read`, `capabilities.read`, `restrictions.read`, `policies.read`, `workspaces.read`, `audit.read`, `events.read`, `settings.read` |\n| products | `products.create`, `products.update`, `products.delete`, `products.publish`                                                                                                  |\n| orders   | `orders.create`, `orders.cancel`                                                                                                                                             |\n| wallets  | `wallets.read`, `wallets.withdraw`                                                                                                                                           |\n| users    | `users.read`                                                                                                                                                                 |\n| tickets  | `tickets.read`, `tickets.resolve`                                                                                                                                            |"
    },
    {
      "level": 3,
      "heading": "قانون چهارم — IAM منبع runtime است، نه توسعه",
      "content": "Frontend هرگز Permission جدید نمی‌سازد. همه کلیدها از IAM از طریق `GET /v1/iam/permissions/meta` دریافت می‌شوند. برای افزودن کلید جدید:\n\n1. به Proto اضافه شود (تیم پلتفرم)\n2. `pnpm codegen` اجرا شود\n3. به `permissions.meta.yaml` سرویس مربوطه اضافه شود\n4. به IAM DB seed اضافه شود\n5. آنگاه در فرانت‌اند `constants.ts` و localeها بروز شوند\n\n---"
    },
    {
      "level": 2,
      "heading": "۴. قوانین ترجمه (i18n)",
      "content": ""
    },
    {
      "level": 3,
      "heading": "ساختار",
      "content": "ترجمه‌ها در دو فایل `locales/fa.json` و `locales/en.json` زیر namespace `permissions` ذخیره می‌شوند:\n\n```json\n{\n  \"permissions\": {\n    \"admin.access\": \"دسترسی به پنل مدیریت\",\n    \"products.create\": \"ایجاد محصول\"\n  }\n}\n```"
    },
    {
      "level": 3,
      "heading": "قوانین",
      "content": "- هر کلید مجوز در Proto باید **دقیقاً یک** entry در هر دو فایل locale داشته باشد\n- کلیدهای اضافی (که در Proto نیستند) در localeها **ممنوع** هستند — تست `permission-catalog.spec.ts` این را بررسی می‌کند\n- کلیدهای گمشده توسط تست `permission-catalog.spec.ts` گزارش می‌شوند (fail روی missing)\n- اگر کلیدی از Proto حذف شد، باید از localeها نیز حذف شود (warn روی stale)\n\n---"
    },
    {
      "level": 2,
      "heading": "۵. قوانین SDK",
      "content": ""
    },
    {
      "level": 3,
      "heading": "SDK مرورگر هرگز Bearer token ندارد",
      "content": "SDK مرورگر (`src/sdk/`) از `Authorization: Bearer` استفاده **نمی‌کند**. احراز هویت از طریق:\n\n- کوکی نشست Kratos (`credentials: 'include'`)\n- هدر `X-User-ID` (تنظیم توسط `setDefaultHeaders`)\n\n```ts\n// ✅ SDK فعلی — فقط baseURL + locale\nconst sdk = initSDK({\n  baseURL: (import.meta.env.VITE_API_URL as string) || \"\",\n  locale: \"fa\",\n});\n\n// تزریق header پس از احراز هویت (در src/auth/store.ts)\nsdk.setDefaultHeaders({ \"X-User-ID\": userId });\n```"
    },
    {
      "level": 3,
      "heading": "فراخوانی مستقیم IAM (در auth/store.ts)",
      "content": "```ts\nconst response = await fetch(`/v1/iam/me/context`, {\n  headers: { \"X-User-ID\": userId, Accept: \"application/json\" },\n  credentials: \"include\",\n});\n```"
    },
    {
      "level": 3,
      "heading": "Permission از طریق UIKit runtime",
      "content": "`hasPermission()` از `runtimeContext.permissions` UIKit می‌خواند (تنظیم در `src/auth/store.ts` پس از دریافت context از IAM):\n\n```ts\n// UIKit فقط هوک setPermissions را ارائه می‌دهد\nimport { runtimeContext } from '@nons-dev/uikit'\nruntimeContext.setPermissions(userPermissions)\n\n// مصرف در کامپوننت‌ها\nimport { hasPermission } from '../permissions/helpers'\nif (hasPermission(PERMISSIONS.ADMIN.ACCESS)) { ... }\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "۶. چک‌لیست قبل از PR",
      "content": "- [ ] `npm run build` — بدون خطا (typecheck + build)\n- [ ] همه مجوزهای جدید در `PERMISSIONS.*` تعریف شده‌اند\n- [ ] همه مجوزهای جدید در `locales/fa.json` و `en.json` اضافه شده‌اند\n- [ ] هیچ رشته مجوزی به‌صورت هاردکد در کد جدید وجود ندارد (تست `no-hardcoded-permissions.spec.ts` پاس می‌شود)\n- [ ] `permission-catalog.spec.ts` پاس می‌شود (هیچ کلید missing/stale نیست)\n- [ ] از `any` استفاده نشده — به‌خصوص در مسیر auth/permission\n- [ ] خطاها fail-closed هستند (در صورت خطا، دسترسی محدود شود نه افزایش)\n\n---"
    },
    {
      "level": 2,
      "heading": "مستندات مرتبط",
      "content": "- [معماری فرانت‌اند (Overview)](architecture/overview)\n- [قرارداد Auth Header در پنل ادمین](architecture/admin-panel-auth-headers)\n- [مدل مجوزها در پلتفرم](/docs/team/platform/permission-model)\n- [استاندارد قرارداد مجوز](/docs/team/platform/standards/permission-contract-standard)"
    }
  ]
}