First commit
This commit is contained in:
@@ -0,0 +1,357 @@
|
||||
---
|
||||
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` - دادههای منو
|
||||
|
||||
---
|
||||
|
||||
**نکته مهم**: این معماری باید در تمام توسعههای آینده رعایت شود. هر تغییری باید با این ساختار سازگار باشد.
|
||||
Reference in New Issue
Block a user