# 🚀 قالب آماده و مدرن داشبورد مدیریتی (Dashboard Starter Kit)

یک استارتر کیت پیشرفته، ماژولار و کاملاً راست‌چین (RTL) بر پایه **React 19**، **Tailwind CSS v4**، **Vite 8** و **Shadcn UI** طراحی‌شده برای ساخت سریع پنل‌های ادمین و داشبوردهای سازمانی.

---

## ✨ ویژگی‌های کلیدی

- **🎨 طراحی مدرن و کاملاً راست‌چین (RTL-First):** همراه با فونت وزیرمتن (Vazirmatn) و متغیرهای مدرن CSS.
- **🏛 شل سه ستونه هوشمند (Triple-Column Layout):**
  - **سایدبار راست (Right Sidebar):** منوی جمع‌شونده (Collapsible Offcanvas) بر اساس کانفیگ متمرکز.
  - **محتوای میانی (Main Content):** هدر ناوبری (Topbar) همراه با Breadcrumb پویا.
  - **پنل کشویی چپ (Left Slide-over Panel):** باز شدن جزئیات هر رکورد از چپ بدون ترک یا فشرده شدن صفحه اصلی.
- **⚡ مدیریت پنل‌ها و مودال‌ها از طریق URL (`usePanelRouting`):**
  - قابلیت اشتراک‌گذاری لینک مودال یا پنل باز (Deep Linking).
  - هماهنگ با دکمه Back/Forward مرورگر و کلید Escape.
- **🔍 ابزار جستجوی سراسری هوشمند (Command Palette):** میانبر `Ctrl + K` یا `Cmd + K` برای دسترسی آنی به تمامی صفحات و اکشن‌های سریع.
- **🔒 سیستم احراز هویت یکپارچه (Auth Flow):**
  - صفحه لاگین با حالت آزمایشی (Demo Mode) برای تست سریع بدون نیاز به بک‌اند.
  - کلاینت HTTP با هدرهای خودکار Bearer Token و مدیریت خطای ۴۰۱ (Auto-Logout).
  - گارد امنیتی مسیرها (`RequireAuth`).
- **🧩 بیش از ۲۵ کامپوننت آماده Shadcn UI + Radix:**
  - Dialog / Modal، Alert Dialog، Table، Tabs، Sheet، Select، MultiSelect، Switch، Dropdown، Accordion، Pagination و...
- **📁 معماری تمیز و فیچرمحور (Feature-Based Architecture):** سازمان‌دهی بر اساس موجودیت‌ها به همراه دو صفحه نمونه کامل CRUD (کاربران و آیتم‌ها).

---

## 🛠 راه‌اندازی و اجرا

```bash
# ۱. نصب پکیج‌ها
npm install

# ۲. اجرای سرور توسعه
npm run dev

# ۳. بررسی خطاهای تایپ‌اسکریپت
npm run typecheck

# ۴. بیلد نهایی پروداکشن
npm run build
```

> **اطلاعات حساب دمو (پیش‌فرض):**
> - **ایمیل:** `admin@example.com`
> - **رمز عبور:** `admin`

---

## 📂 ساختار پوشه‌ها

```text
dashboard-template/
├── src/
│   ├── app/                      # روتینگ، گارد احراز هویت و شل اصلی
│   │   ├── App.tsx               # بدنه اصلی (Sidebar + Topbar + PanelSlot)
│   │   ├── router.tsx            # تعریف مسیرهای پروژه
│   │   └── providers.tsx         # کانتکست‌های عمومی (React Query و ...)
│   │
│   ├── config/                   # تنظیمات متمرکز سیستم
│   │   ├── site.ts               # نام پروژه، لوگو و اطلاعات برند
│   │   └── navigation.ts         # لیست صفحات و منوهای سایدبار
│   │
│   ├── components/
│   │   ├── ui/                   # کامپوننت‌های پایه Shadcn (Button, Dialog, Table, ...)
│   │   ├── layout/               # اجزای قالب (AppSidebar, Topbar, PanelSlot)
│   │   └── shared/               # کامپوننت‌های پرتکرار (TablePagination, DeleteConfirmDialog, ...)
│   │
│   ├── features/                 # ماژول‌های بیزینسی (Feature-based)
│   │   ├── auth/                 # ورود، خروج و گارد دسترسی
│   │   ├── dashboard/            # صفحه داشبورد و آمار
│   │   ├── users/                # مدیریت کاربران (جدول، مودال ایجاد/ویرایش)
│   │   ├── items/                # مدیریت نمونه آیتم‌ها (CRUD الگو)
│   │   ├── panels/               # پنل‌های کشویی جزئیات رکوردها
│   │   ├── filters/              # دراور فیلترهای پیشرفته
│   │   └── settings/             # صفحه تنظیمات پنل
│   │
│   ├── services/                 # ارتباط با سرور و API
│   │   ├── http.ts               # کلاینت مرکزی Fetch با اینترسپتور توکن
│   │   ├── auth.ts               # سرویس لاگین و پروفایل
│   │   ├── users-api.ts          # سرویس کاربران (همراه با Mock fallback)
│   │   └── sample-api.ts         # سرویس نمونه CRUD
│   │
│   ├── stores/                   # استیت‌های کلاینت با Zustand (Auth, Search, ...)
│   ├── hooks/                    # هوک‌های سفارشی (usePanelRouting, useMobile, ...)
│   ├── types.ts                  # تایپ‌های عمومی، Pagination و دامنه‌ها
│   └── index.css                 # توکن‌های طراحی، متغیرهای CSS و رنگ‌های قالب
```

---

## 📖 راهنمای استفاده در پروژه‌های جدید

### ۱. چگونه نام و برند داشبورد را تغییر دهم؟
فایل `src/config/site.ts` را باز کرده و عنوان و توضیحات را ویرایش کنید:
```ts
export const siteConfig = {
  name: 'پنل مدیریت من',
  shortName: 'داشبورد',
  description: 'سیستم یکپارچه مدیریت سازمانی',
}
```

### ۲. چگونه منوی جدید به سایدبار اضافه کنم؟
فایل `src/config/navigation.ts` را ویرایش کنید. منو به‌صورت خودکار در سایدبار و در پنجره `Ctrl+K` نمایش داده می‌شود:
```ts
{
  title: 'محصولات و انبار',
  items: [
    { title: 'لیست کالاها', to: '/products', icon: 'grid' },
    { title: 'سفارش‌ها', to: '/orders', icon: 'folder', badge: '۳ جدید' },
  ],
}
```

### ۳. چگونه یک مودال (Modal) ایجاد و باز کنم؟
از هوک `usePanelRouting` استفاده کنید:
```tsx
import { usePanelRouting } from '@/hooks/use-panel-routing'

function MyComponent() {
  const { openModal } = usePanelRouting()

  return (
    <Button onClick={() => openModal('user', 'new')}>
      افزودن کاربر
    </Button>
  )
}
```
این کار پارامتر `?edit=user:new` را در URL ست می‌کند که باعث باز شدن مودال مربوطه می‌شود. برای ویرایش، شناسه رکورد را بفرستید: `openModal('user', '123')`.

### ۴. چگونه پنل کشویی جزئیات (Detail Drawer) را از سمت چپ باز کنم؟
به سادگی شناسه و نوع را با `openPanel` صدا بزنید:
```tsx
const { openPanel } = usePanelRouting()

// در رویداد کلیک روی سطر جدول:
<TableRow onClick={() => openPanel('user', user.id)}>
```
سپس در `src/components/layout/PanelSlot.tsx` کامپوننت پنل جدیدتان را به `switch-case` اضافه نمایید.

### ۵. چگونه رنگ اصلی برند (Primary Color) را تغییر دهم؟
در فایل `src/index.css`، مقدار متغیر `--primary` را با کد رنگ دلخواهتان جایگزین کنید:
```css
:root {
  --primary: #3b82f6; /* آبی کاربنی */
  /* یا #10b981 (زمردی) یا #8b5cf6 (بنفش) */
}
```

---

## 💻 کپی برای پروژه جدید

برای ساخت یک پروژه جدید بر اساس این تمپلیت، کافیست محتویات این پوشه را کپی کرده و شروع به توسعه فیچرهای جدید کنید:

```bash
cp -r /path/to/dashboard-template /path/to/my-new-app
cd /path/to/my-new-app
npm install
npm run dev
```