---
alwaysApply: true
---

# مستندسازی معماری پروژه Ai-School Frontend

## بررسی و مستندسازی معماری کامل پروژه

این پروژه یک ادمین پنل Next.js 15 با معماری پیشرفته است که بر پایه Vuexy Template ساخته شده است.

### ساختار کلی پروژه

```
frontend/
├── src/
│   ├── @core/          # کامپوننت‌ها و ابزارهای اصلی
│   ├── @layouts/       # لایه‌بندی‌های مختلف (Vertical/Horizontal)
│   ├── @menu/          # سیستم منو (عمودی/افقی)
│   ├── app/            # Next.js App Router
│   ├── components/     # کامپوننت‌های قابل استفاده مجدد
│   ├── contexts/       # Context API برای state management
│   ├── libs/           # کتابخانه‌های شخصی‌سازی شده
│   ├── redux-store/    # Redux store و slices
│   ├── views/          # View components برای صفحات
│   └── utils/          # توابع کمکی
```

### 1. ساختار Routing (Next.js App Router)

#### مسیرهای اصلی:

- `/layout.tsx` - Root layout
- `/(dashboard)/(private)/` - صفحات احراز هویت شده
- `/(blank-layout-pages)/(guest-only)/` - صفحات مهمان (Login, Register)
- `/(blank-layout-pages)/pages/` - صفحات عمومی

#### نحوه Fetch کردن Routes:

- Routes به صورت فایل‌های `page.tsx` در دایرکتوری‌های `app/(dashboard)/(private)/` تعریف می‌شوند
- هر صفحه می‌تواند Server Component باشد و داده‌ها را از API fetch کند
- مثال: `src/app/(dashboard)/(private)/dashboards/crm/page.tsx`

#### Redirects:

- در `next.config.ts` تعریف شده‌اند
- `/` به `/dashboards/crm` redirect می‌شود

### 2. کامپوننت‌ها

#### کامپوننت‌های آماده (Core Components):

- **@core/components/mui/** - کامپوننت‌های MUI شخصی‌سازی شده:
  - `Autocomplete.tsx`
  - `Avatar.tsx`
  - `Badge.tsx`
  - `Chip.tsx`
  - `IconButton.tsx`
  - `TabList.tsx`
  - `TextField.tsx`

- **@core/components/custom-inputs/** - Input های سفارشی:
  - `Horizontal.tsx` - Input با label افقی
  - `Vertical.tsx` - Input با label عمودی
  - `Image.tsx` - Input برای آپلود تصویر

- **@core/components/customizer/** - تنظیمات تم و layout
- **@core/components/scroll-to-top/** - دکمه بازگشت به بالا
- **@core/components/option-menu/** - منوی انتخاب

#### کامپوننت‌های Layout:

- **components/layout/vertical/** - کامپوننت‌های layout عمودی:
  - `Navigation.tsx` - منوی کناری
  - `Navbar.tsx` - نوار بالایی
  - `Footer.tsx` - فوتر

- **components/layout/horizontal/** - کامپوننت‌های layout افقی:
  - `Header.tsx` - هدر افقی
  - `Navigation.tsx` - منوی افقی
  - `Footer.tsx` - فوتر

- **components/layout/shared/** - کامپوننت‌های مشترک:
  - `UserDropdown.tsx` - منوی کاربر
  - `NotificationsDropdown.tsx` - اعلان‌ها
  - `ModeDropdown.tsx` - تغییر تم (Dark/Light)
  - `search/` - جستجو

#### کامپوننت‌های آماده استفاده:

- **components/card-statistics/** - کارت‌های آمار:
  - `Vertical.tsx` - کارت عمودی
  - `Horizontal.tsx` - کارت افقی
  - `StatsWithAreaChart.tsx` - کارت با نمودار

- **components/dialogs/** - دیالوگ‌های آماده:
  - `confirmation-dialog/` - تایید عملیات
  - `edit-user-info/` - ویرایش اطلاعات کاربر
  - `role-dialog/` - مدیریت نقش‌ها
  - `permission-dialog/` - مدیریت دسترسی‌ها

- **components/pricing/** - کامپوننت‌های قیمت‌گذاری
- **components/stepper-dot/** - Stepper با نقطه

### 3. سیستم منو (Menu System)

#### ساختار منو:

- **@menu/vertical-menu/** - منوی عمودی:
  - `Menu.tsx` - منوی اصلی
  - `MenuItem.tsx` - آیتم منو
  - `SubMenu.tsx` - زیرمنو
  - `MenuSection.tsx` - بخش منو

- **@menu/horizontal-menu/** - منوی افقی:
  - `Menu.tsx`
  - `MenuItem.tsx`
  - `SubMenu.tsx`

#### داده‌های منو:

- **src/data/navigation/verticalMenuData.tsx** - داده‌های منوی عمودی
- **src/components/GenerateMenu.tsx** - تابع تولید منو از داده‌ها

#### Contexts:

- `@menu/contexts/verticalNavContext.tsx` - Context منوی عمودی
- `@menu/contexts/horizontalNavContext.tsx` - Context منوی افقی

#### Hooks:

- `@menu/hooks/useVerticalMenu.tsx` - Hook منوی عمودی
- `@menu/hooks/useHorizontalMenu.tsx` - Hook منوی افقی
- `@menu/hooks/useVerticalNav.tsx` - Hook navigation عمودی
- `@menu/hooks/useHorizontalNav.tsx` - Hook navigation افقی

### 4. ساختار API

#### API Client:

- **src/libs/api/client.ts** - کلاس `ApiClient`:
  - مدیریت base URL
  - مدیریت authentication token (از localStorage)
  - متدهای `get`, `post`, `put`, `delete`
  - مدیریت خطاها و 401 (unauthorized)

#### API Services:

- **src/libs/api/services/**:
  - `authService.ts` - احراز هویت:
    - `requestOTP(phoneNumber)` - درخواست OTP
    - `verifyOTP(token, otpCode)` - تایید OTP
    - `logout()` - خروج
  - `taskService.ts` - مدیریت تسک‌ها
  - `eventService.ts` - مدیریت رویدادها
  - `simulatorService.ts` - شبیه‌ساز

#### نحوه استفاده:

```typescript
import { authService } from '@/libs/api'

// درخواست OTP
const tempToken = await authService.requestOTP(phoneNumber)

// تایید OTP
await authService.verifyOTP(tempToken, otpCode)
```

### 5. Hooks

#### Core Hooks (@core/hooks):

- `useSettings.tsx` - دسترسی به تنظیمات تم و layout
- `useLayoutInit.ts` - مقداردهی اولیه layout
- `useImageVariant.ts` - مدیریت variant تصاویر
- `useObjectCookie.ts` - مدیریت cookie به صورت object

#### Custom Hooks (hooks):

- `useIntersection.ts` - Intersection Observer برای lazy loading

#### Menu Hooks (@menu/hooks):

- `useVerticalMenu.tsx` - مدیریت state منوی عمودی
- `useHorizontalMenu.tsx` - مدیریت state منوی افقی
- `useVerticalNav.tsx` - مدیریت navigation عمودی
- `useHorizontalNav.tsx` - مدیریت navigation افقی
- `useMediaQuery.tsx` - Responsive breakpoints

### 6. مدیریت State

#### Redux Store:

- **src/redux-store/index.ts** - تنظیمات store:
  - `chatReducer` - state چت
  - `calendarReducer` - state تقویم
  - `kanbanReducer` - state کانبان
  - `emailReducer` - state ایمیل

#### Context API:

- **src/contexts/authContext.tsx** - مدیریت احراز هویت:
  - `user` - اطلاعات کاربر
  - `isAuthenticated` - وضعیت احراز هویت
  - `isLoading` - وضعیت بارگذاری
  - `login()` - ورود
  - `logout()` - خروج
  - `requestOTP()` - درخواست OTP

- **@core/contexts/settingsContext.tsx** - تنظیمات تم و layout
- **@menu/contexts/** - Contexts منو
- **src/contexts/intersectionContext.tsx** - Intersection Observer

### 7. Layouts

#### Vertical Layout:

- **@layouts/VerticalLayout.tsx** - Layout عمودی:
  - Navigation (منوی کناری)
  - Navbar (نوار بالایی)
  - Content (محتوای اصلی)
  - Footer (فوتر)

#### Horizontal Layout:

- **@layouts/HorizontalLayout.tsx** - Layout افقی:
  - Header (هدر)
  - Content (محتوای اصلی)
  - Footer (فوتر)

#### Layout Wrapper:

- **@layouts/LayoutWrapper.tsx** - Wrapper برای switch بین layouts

### 8. احراز هویت (Authentication)

#### AuthGuard:

- **src/hocs/AuthGuard.tsx** - محافظت از صفحات:
  - بررسی `isAuthenticated`
  - Redirect به صفحه login در صورت عدم احراز هویت

#### GuestOnlyRoute:

- **src/hocs/GuestOnlyRoute.tsx** - فقط برای مهمانان:
  - Redirect به dashboard در صورت احراز هویت

#### AuthProvider:

- **src/contexts/authProvider.tsx** - Provider احراز هویت
- **src/contexts/authContext.tsx** - Context و Hook `useAuth()`

### 9. زبان و جهت متن

#### پیکربندی:

- **کل پروژه به فارسی است** - تمام متون، کامنت‌ها و مستندات به فارسی
- جهت متن: `rtl` (راست به چپ) برای تمام صفحات
- فونت: استفاده از فونت‌های فارسی (ایران سنس و غیره)

### 10. سیستم تم (Theme)

#### پیکربندی:

- **src/configs/themeConfig.ts** - تنظیمات:
  - `mode`: 'system' | 'light' | 'dark'
  - `skin`: 'default' | 'bordered'
  - `layout`: 'vertical' | 'collapsed' | 'horizontal'
  - `navbar`, `contentWidth`, `footer` settings

#### Theme Provider:

- **src/components/theme/** - مدیریت تم:
  - `index.tsx` - ThemeProvider
  - `mergedTheme.ts` - ادغام تم‌ها
  - `userTheme.ts` - تم کاربر

#### Customizer:

- **@core/components/customizer/** - تنظیمات زنده تم و layout

### 11. Views

#### ساختار:

- **src/views/** - کامپوننت‌های view برای صفحات:
  - `dashboards/` - داشبوردها
  - `apps/` - اپلیکیشن‌ها
  - `pages/` - صفحات
  - `forms/` - فرم‌ها
  - `charts/` - نمودارها

#### الگوی استفاده:

```tsx
// در page.tsx
import DashboardView from '@views/dashboards/crm'

const DashboardPage = async () => {
  const data = await fetchData() // Optional
  return <DashboardView data={data} />
}
```

### 12. Providers

#### Providers Chain:

- **src/components/Providers.tsx** - زنجیره Providers:

  1. `AuthProvider` - احراز هویت
  2. `VerticalNavProvider` - منوی عمودی
  3. `SettingsProvider` - تنظیمات
  4. `ThemeProvider` - تم
  5. `ReduxProvider` - Redux

### 13. Path Aliases

#### تعریف شده در tsconfig.json:

- `@/*` → `./src/*`
- `@core/*` → `./src/@core/*`
- `@layouts/*` → `./src/@layouts/*`
- `@menu/*` → `./src/@menu/*`
- `@assets/*` → `./src/assets/*`
- `@components/*` → `./src/components/*`
- `@configs/*` → `./src/configs/*`
- `@views/*` → `./src/views/*`

### 14. قوانین مهم معماری

1. **زبان پروژه**: **کل پروژه باید به فارسی باشد** - تمام کامنت‌ها، متون، نام متغیرها (در صورت امکان)، و مستندات باید به فارسی نوشته شوند. پروژه تک‌زبانه است و فقط فارسی پشتیبانی می‌شود.
2. **Routing**: همه routes در `app/` بدون `[lang]` تعریف می‌شوند. مسیرها مستقیماً در `app/(dashboard)/(private)/` یا `app/(blank-layout-pages)/` قرار دارند.
3. **Components**: 
   - کامپوننت‌های قابل استفاده مجدد در `components/`
   - View components در `views/`
   - Core components در `@core/components/`
4. **API**: همه API calls از طریق `libs/api/` و services
5. **State**: 
   - State محلی با Context API
   - State پیچیده با Redux (chat, calendar, kanban, email)
6. **Authentication**: استفاده از `AuthGuard` برای صفحات protected
7. **Theme**: استفاده از `useSettings()` برای دسترسی به تنظیمات
8. **Layout**: استفاده از `LayoutWrapper` برای switch بین layouts
9. **جهت متن**: تمام صفحات با جهت `rtl` (راست به چپ) هستند

### 15. فایل‌های مهم

- `next.config.ts` - تنظیمات Next.js و redirects
- `tailwind.config.ts` - تنظیمات Tailwind CSS
- `tsconfig.json` - تنظیمات TypeScript و path aliases
- `src/configs/themeConfig.ts` - تنظیمات تم
- `src/data/navigation/verticalMenuData.tsx` - داده‌های منو

---

**نکته مهم**: این معماری باید در تمام توسعه‌های آینده رعایت شود. هر تغییری باید با این ساختار سازگار باشد.