canina/docs/03-developer-guide.md

راهنمای توسعه‌دهندگان (Developer Guide)

این مستند مختص دولوپرها است و استانداردهای کدنویسی، نحوه مدیریت Stateها و معماری پوشه‌ها را شرح می‌دهد. این پروژه از معماری Monorepo (ولی در پوشه‌های مجزا) برای جداسازی Frontend و Backend استفاده می‌کند.

۱. ساختار پوشه‌ها (Folder Structure)

پروژه از دو پوشه اصلی تشکیل شده است:

فولدر frontend/application (Next.js)

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)

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ها.