79 lines
6.6 KiB
Markdown
79 lines
6.6 KiB
Markdown
# راهنمای توسعهدهندگان (Developer Guide)
|
||
|
||
این مستند مختص دولوپرها است و استانداردهای کدنویسی، نحوه مدیریت Stateها و معماری پوشهها را شرح میدهد. این پروژه از معماری Monorepo (ولی در پوشههای مجزا) برای جداسازی Frontend و Backend استفاده میکند.
|
||
|
||
## ۱. ساختار پوشهها (Folder Structure)
|
||
پروژه از دو پوشه اصلی تشکیل شده است:
|
||
|
||
### فولدر `frontend/application` (Next.js)
|
||
```text
|
||
frontend/application/
|
||
├── app/ # صفحات (Pages) و Layout ها بر اساس Next.js App Router
|
||
│ ├── api/ # مسیرهای (Route Handlers) سمت بکاند Next.js (در صورت نیاز)
|
||
│ ├── shop/ # صفحات مربوط به فروشگاه
|
||
│ ├── blog/ # صفحات وبلاگ
|
||
│ └── ...
|
||
├── components/ # کامپوننتهای React (دکمهها، فرمها، هدر، مودالها)
|
||
├── lib/ # منطق تجاری سمت فرانتاند
|
||
│ ├── services/ # توابع ارتباط با API بکاند (استفاده از Axios)
|
||
│ ├── store/ # استورهای Zustand (Cart, User, Pet و...)
|
||
│ └── utils/ # توابع کمکی (فرمتدهی تاریخ، اعداد، ترکیب کلاسهای tailwind)
|
||
└── public/ # فایلهای استاتیک، تصاویر خام، فونتها
|
||
```
|
||
|
||
### فولدر `backend` (NestJS)
|
||
```text
|
||
backend/
|
||
├── prisma/ # شمای دیتابیس (schema.prisma) و مایگریشنها
|
||
├── src/
|
||
│ ├── modules/ # ماژولهای مستقل (Users, Products, Orders و...)
|
||
│ ├── common/ # گاردهای امنیتی (Guards)، دکوراتورها، اینترسپتورها
|
||
│ └── main.ts # نقطه ورود بکاند
|
||
```
|
||
|
||
## ۲. استانداردهای توسعه در Frontend
|
||
|
||
### کامپوننتها (Components)
|
||
- تمامی فایلهای کامپوننت باید در پوشه `components` قرار گیرند و با حرف بزرگ شروع شوند (`PascalCase`).
|
||
- کامپوننتها باید در صورت امکان **Server Component** باشند. تنها زمانی که به هوکهای React (مثل `useState`, `useEffect`) یا رویدادهای کاربری (`onClick`) نیاز است، از دایرکتیو `"use client"` در بالاترین خط فایل استفاده کنید.
|
||
- از Prop-drilling (ارسال پروپها به صورت آبشاری در لایههای زیاد) خودداری کنید. اگر دیتایی گلوبال است، از Zustand استفاده کنید.
|
||
|
||
### مدیریت State با Zustand
|
||
- فایلهای State منحصراً در پوشه `lib/store/` ذخیره میشوند.
|
||
- نام فایلها باید شامل کلمه `store` باشد (مثلاً `cartStore.ts`).
|
||
- هنگام نیاز به ذخیره ماندگار اطلاعات (مثل سبد خرید یا توکن)، از میدلویر `persist` در Zustand استفاده کنید. این کار به صورت خودکار اطلاعات را در LocalStorage ذخیره و بازیابی میکند.
|
||
|
||
### ارتباط با شبکه (API & Fetching)
|
||
- ارتباطات سمت کلاینت با بکاند در فایلهای پوشه `lib/services/` نوشته میشوند.
|
||
- در فایل `lib/services/api.ts` یک نمونه از Axios (`axios.create`) با کانفیگهای پایه و آدرس Base URL ساخته شده است.
|
||
- تمام Requestها باید تایپکشی (Type-safe) شده باشند. رابطها (Interfaces) مربوط به ریسپانس را صراحتاً مشخص کنید.
|
||
|
||
### سبک استایلدهی (TailwindCSS)
|
||
- استایلدهی باید فقط و فقط از طریق کلاسهای Tailwind انجام شود.
|
||
- از کلاس کمکی `cn` (موجود در `lib/utils`) برای ترکیب کلاسهای شرطی (Conditional Classes) استفاده کنید.
|
||
- رنگهای اختصاصی پروژه (مثل `canino-blue`, `medical-gray`) در فایل `tailwind.config.ts` تعریف شدهاند و باید استفاده شوند، نه مقادیر هگزادسیمال خام.
|
||
|
||
## ۳. استانداردهای توسعه در Backend (NestJS)
|
||
|
||
### مدیریت دیتابیس
|
||
- شمای منبع حقیقت (Source of Truth) فایل `schema.prisma` است. برای افزودن یک جدول یا فیلد جدید، فقط این فایل را تغییر دهید.
|
||
- بعد از هر تغییر در `schema.prisma` دستور `npx prisma migrate dev --name <description>` را اجرا کنید تا تغییرات در دیتابیس اعمال شود و تایپهای Prisma کلاینت آپدیت شوند.
|
||
|
||
### کنترلرها و سرویسها
|
||
- هیچگونه لاجیک پیچیدهای نباید داخل فایلهای `.controller.ts` نوشته شود. کنترلرها فقط وظیفه دریافت درخواست، اعتبارسنجی اولیه پارامترها و ارسال آن به سرویس را دارند.
|
||
- لاجیک اصلی تجاری را داخل فایلهای `.service.ts` پیادهسازی کنید.
|
||
|
||
### امنیت و احراز هویت
|
||
- تمامی روتهایی که به کاربر لاگین شده نیاز دارند، باید با `@UseGuards(JwtAuthGuard)` محافظت شوند.
|
||
- روتهای ادمین باید از گارد اختصاصی ترکیب شده با بررسی نقش کاربری استفاده کنند.
|
||
- رمزهای عبور کاربران پیش از ذخیره در دیتابیس **حتماً** باید با کتابخانه `bcrypt` هش شوند.
|
||
|
||
## ۴. چرخه توسعه ویژگی جدید (Feature Workflow)
|
||
هنگامی که یک توسعهدهنده میخواهد ویژگی جدیدی اضافه کند، این مراحل را طی میکند:
|
||
1. تعریف ساختار دیتابیس جدید در Prisma و مایگریشن.
|
||
2. ساخت ماژول در NestJS (شامل Entity, DTO, Service, Controller).
|
||
3. نوشتن توابع API فراخوانی در پوشه `lib/services` در فرانتاند.
|
||
4. پیادهسازی Store مربوطه در Zustand (اگر نیاز به State گلوبال دارد).
|
||
5. نوشتن و استایلدهی کامپوننتهای UI در فرانتاند.
|
||
6. اتصال UI به اکشنهای Store یا APIها.
|