358 lines
12 KiB
Plaintext
358 lines
12 KiB
Plaintext
---
|
|
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` - دادههای منو
|
|
|
|
---
|
|
|
|
**نکته مهم**: این معماری باید در تمام توسعههای آینده رعایت شود. هر تغییری باید با این ساختار سازگار باشد.
|