Files
canina/docs/03-developer-guide.md
T

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) استفاده کنید.
- رنگ‌های اختصاصی پروژه (مثل `canina-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ها.