# راهنمای توسعه‌دهندگان (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ها.