docs: add comprehensive developer documentation

docs/01-introduction.md

@@ -0,0 +1,39 @@
+# معرفی پروژه کانینا ایران (Canina Iran)
+
+## این پروژه چیست؟
+سامانه «کانینا ایران» پلتفرم تخصصی معرفی، فروش و مدیریت مکمل‌های درمانی حیوانات خانگی با گرید دارویی است. این سامانه به عنوان درگاه آنلاین نماینده انحصاری کانینا آلمان در ایران فعالیت می‌کند. هدف اصلی پروژه، ارائه یک تجربه کاربری (UX) بسیار غنی، سریع و در کلاس جهانی برای خریداران، کلینیک‌های دامپزشکی (مشتریان B2B) و همچنین فراهم‌کردن ابزارهای هوشمند (مانند مشاوره هوشمند و دانشنامه ترکیبات دارویی) است.
+
+## قابلیت‌های کلیدی سامانه
+سامانه به گونه‌ای طراحی شده تا تمام نیازهای یک کسب‌وکار مدرن e-commerce را در کنار قابلیت‌های تخصصی حوزه سلامت حیوانات برآورده کند:
+- **فروشگاه آنلاین پیشرفته:** نمایش و فروش محصولات با قابلیت جستجوی هوشمند، دسته‌بندی دقیق و ارائه اطلاعات تخصصی دارویی.
+- **مشاور هوشمند سلامت:** ابزار هوش مصنوعی یا سیستم مبتنی بر قوانین برای پیشنهاد مکمل بر اساس نوع، سن و نیازهای حیوان خانگی.
+- **دانشنامه ترکیبات (Ingredient Wiki):** مرجع کامل برای معرفی ترکیبات موثره، ویتامین‌ها و فرمولاسیون مکمل‌ها.
+- **پروفایل حیوان خانگی (Pet Profile):** ثبت اطلاعات حیوانات خانگی توسط کاربر برای دریافت پیشنهادات شخصی‌سازی شده.
+- **پورتال اختصاصی فروش عمده (B2B Portal):** سیستم قیمت‌گذاری و سفارش‌دهی ویژه برای کلینیک‌های دامپزشکی و داروخانه‌ها.
+- **سیستم مدیریت سفارش و سبد خرید:** شامل پیگیری لحظه‌ای سفارش، استفاده از کدهای تخفیف و کیف پول مجازی.
+- **سئوی بسیار پیشرفته:** تولید متادیتا داینامیک، JSON-LD و سایت‌مپ زنده برای دیده شدن در موتورهای جستجو.
+
+## تکنولوژی‌های استفاده شده و دلیل انتخاب آن‌ها (Tech Stack)
+
+### بخش فرانت‌اند (Frontend)
+- **فریم‌ورک Next.js 15 (App Router):**
+  - **چرا؟** برای بهره‌مندی از رندرینگ سمت سرور (SSR) و تولید صفحات استاتیک (SSG) که سرعت بارگذاری بسیار بالا و سئوی (SEO) خارق‌العاده‌ای را فراهم می‌کند. همچنین سیستم Routing جدید آن توسعه را ساختاریافته‌تر می‌کند.
+- **مدیریت State با Zustand:**
+  - **چرا؟** جایگزینی سبک، سریع و بدون boilerplate برای Redux. برای مدیریت سبد خرید، اطلاعات کاربر و تنظیمات UI در سمت کلاینت عالی است.
+- **استایل‌دهی با TailwindCSS:**
+  - **چرا؟** توسعه سریع رابط کاربری بدون نیاز به فایل‌های CSS جداگانه. امکان پیاده‌سازی سریع دیزاین‌سیستم‌ها و Responsive Design.
+- **انیمیشن‌ها با Framer Motion:**
+  - **چرا؟** ایجاد انیمیشن‌ها و ترانزیشن‌های روان و حرفه‌ای (Micro-interactions) که حس یک وب‌اپلیکیشن بسیار لوکس (Premium) را به کاربر منتقل می‌کند.
+- **ارتباط با API از طریق Axios:**
+  - **چرا؟** مدیریت راحت‌تر اینترسپتورها (Interceptors) برای توکن‌های احراز هویت و مدیریت خطاها در ارتباط با بک‌اند.
+
+### بخش بک‌اند (Backend)
+- **فریم‌ورک NestJS:**
+  - **چرا؟** ایجاد یک معماری ماژولار، مقیاس‌پذیر و مبتنی بر کلاس (Enterprise-level) در محیط Node.js که با TypeScript به صورت Native سازگار است و نگهداری کدهای بزرگ را آسان می‌کند.
+- **پایگاه‌داده PostgreSQL:**
+  - **چرا؟** یک دیتابیس رابطه‌ای بسیار قدرتمند، امن و استاندارد که یکپارچگی داده‌ها (Data Integrity) در سیستم‌های فروشگاهی (مانند سفارشات و تراکنش‌های مالی) را تضمین می‌کند.
+- **مدیریت دیتابیس با Prisma ORM:**
+  - **چرا؟** ارائه Type-safety کامل بین دیتابیس و کدهای TypeScript. مایگریشن‌های ساده و جلوگیری از خطاهای رایج در نوشتن کوئری‌های SQL.
+
+### نتیجه‌گیری معماری
+ترکیب `Next.js` و `NestJS` معماری مدرن و کاملاً جداشده (Decoupled) ایجاد کرده است. فرانت‌اند وظیفه ارائه تجربه کاربری سریع و سئو شده را دارد و بک‌اند مانند یک سرویس قدرتمند (API) امنیت، لاجیک‌های تجاری و پایداری داده‌ها را تضمین می‌کند.

docs/02-user-guide.md

@@ -0,0 +1,33 @@
+# راهنمای کاربری سیستم (User Guide)
+
+سیستم کانینا از نظر نوع مخاطب به دو دسته کلی B2C (مشتریان عادی) و B2B (کلینیک‌ها و فروشگاه‌ها) تقسیم می‌شود. علاوه بر این، نقش «ادمین» برای مدیریت سیستم وجود دارد.
+
+## ۱. مشتریان عادی (B2C Users)
+مشتری عادی کسی است که وارد سایت می‌شود تا برای حیوان خانگی خود مکمل خریداری کند یا اطلاعات کسب کند.
+
+### کاربر چه کارهایی می‌تواند انجام دهد؟
+- **جستجو و کشف محصول:** می‌تواند محصولات را بر اساس دسته‌بندی‌ها (سگ، گربه، نوع بیماری، ویتامین‌ها) فیلتر کرده و جستجو کند.
+- **مشاهده جزئیات دقیق محصول:** مطالعه مشخصات دارویی، ترکیبات، نحوه مصرف، نظرات و همچنین قیمت و وضعیت موجودی.
+- **استفاده از دانشنامه (Wiki):** مطالعه درباره مواد موثره به کار رفته در محصولات (مانند بیوتین، گلوکزآمین) و دیدن محصولات مرتبط با هر ماده.
+- **ثبت پروفایل حیوان خانگی (Pet Profile):** کاربر می‌تواند اطلاعات حیوانات خود (نام، نژاد، سن، وضعیت عقیم‌سازی، بیماری‌های زمینه‌ای) را ثبت کند. سیستم از این اطلاعات برای شخصی‌سازی محصولات استفاده می‌کند.
+- **مشاوره هوشمند (Smart Advisor):** با وارد کردن مشخصات حیوان و مشکلی که دارد (مثلاً ریزش مو یا مشکل مفاصل)، سیستم بهترین مکمل‌های موجود را به صورت هوشمند پیشنهاد می‌دهد.
+- **مدیریت سبد خرید و سفارش:** افزودن محصولات به سبد، استفاده از کدهای تخفیف، استفاده از موجودی کیف پول و در نهایت پرداخت از طریق درگاه بانکی.
+- **پیگیری سفارش:** مشاهده وضعیت سفارشات (در حال بررسی، ارسال شده، تحویل داده شده).
+
+## ۲. مشتریان تجاری (B2B Users / کلینیک‌ها و داروخانه‌ها)
+این دسته از کاربران پس از ثبت‌نام و تایید هویت توسط ادمین، به پورتال B2B دسترسی پیدا می‌کنند.
+
+### کاربر B2B چه کارهایی می‌تواند انجام دهد؟
+- **مشاهده قیمت‌های همکاری:** محصولات را با قیمت عمده یا درصد تخفیف ویژه همکاری مشاهده می‌کنند.
+- **ثبت سفارشات عمده (Bulk Order):** رابط کاربری ویژه‌ای برای سفارش سریع محصولات در تعداد بالا دارند، بدون اینکه نیازی باشد وارد صفحه تک‌تک محصولات شوند.
+- **پرداخت اعتباری/چکی:** در صورت تایید مدیریت، قابلیت پرداخت غیرنقدی یا ثبت اسناد در سیستم برای آن‌ها فعال می‌شود.
+
+## ۳. مدیران سیستم (Admins)
+مدیران از طریق پنل مدیریت (که جدا از رابط کاربری اصلی است) سیستم را کنترل می‌کنند.
+
+### مدیر چه کارهایی می‌تواند انجام دهد؟
+- **مدیریت محصولات:** تعریف محصول جدید، مدیریت موجودی انبار، تغییر قیمت‌ها و تنظیم متادیتای سئو.
+- **مدیریت کاربران و نقش‌ها:** تایید حساب‌های B2B، مدیریت سطوح دسترسی.
+- **مدیریت سفارشات:** تغییر وضعیت سفارشات (به ارسال شده و...) و ثبت کدهای پیگیری پستی.
+- **گزارش‌گیری:** مشاهده گزارش فروش، محصولات پرطرفدار و وضعیت مالی کیف پول‌ها.
+- **مدیریت محتوا:** نوشتن مقالات بلاگ و اطلاعات دانشنامه دارویی.

docs/03-developer-guide.md

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

docs/04-setup-and-deployment.md

@@ -0,0 +1,98 @@
+# راه‌اندازی و انتشار سیستم (Setup & Deployment)
+
+این بخش نحوه اجرای سامانه در محیط توسعه (Local) و فرآیند پابلیش کردن آن روی سرورهای Production را توضیح می‌دهد.
+
+## ۱. محیط توسعه (Development Mode)
+
+برای توسعه بر روی کامپیوتر شخصی، مراحل زیر را طی کنید:
+
+### پیش‌نیازها
+- **Node.js** (نسخه ۲۰ به بالا)
+- **PostgreSQL** نصب شده و در حال اجرا بر روی سیستم شما.
+
+### اجرای بک‌اند
+1. وارد پوشه بک‌اند شوید: `cd backend`
+2. پکیج‌ها را نصب کنید: `npm install`
+3. فایل `.env` را ایجاد کنید و متغیر دیتابیس را به شکل زیر تنظیم کنید:
+   `DATABASE_URL="postgresql://user:password@localhost:5432/caninadb?schema=public"`
+4. جداول را ایجاد کنید: `npx prisma db push` و سپس `npx prisma generate`
+5. پروژه را در حالت توسعه اجرا کنید: `npm run start:dev`
+6. بک‌اند شما اکنون روی پورت پیش‌فرض (معمولاً `3001` یا `3005`) در حال اجراست.
+
+### اجرای فرانت‌اند
+1. یک تب جدید در ترمینال باز کنید و وارد پوشه اپلیکیشن شوید: `cd frontend/application`
+2. نصب پیش‌نیازها: `npm install`
+3. ایجاد متغیرهای محیطی در فایل `.env.local`:
+   `NEXT_PUBLIC_API_URL=http://localhost:3001/api`
+4. اجرای پروژه در حالت دولوپ: `npm run dev`
+5. وب‌سایت در آدرس `http://localhost:3000` در دسترس است.
+
+---
+
+## ۲. محیط پروداکشن و انتشار (Production Deployment)
+
+نحوه استقرار سامانه بر روی سرورهای اصلی به شرح زیر است. معمولاً این فرآیند بر روی سیستم‌عامل لینوکس (Ubuntu) انجام می‌گیرد.
+
+### بیلد کردن پروژه (Building)
+برای بک‌اند:
+```bash
+cd backend
+npm run build
+```
+برای فرانت‌اند (تولید خروجی بسیار بهینه برای سرعت بالا و سئو):
+```bash
+cd frontend/application
+npm run build
+```
+
+### اجرای پروژه در سرور با PM2
+از ابزار [PM2](https://pm2.keymetrics.io/) برای اجرای مداوم (Daemon) و لودبالانسینگ پروسه‌ها استفاده می‌کنیم.
+پس از نصب سراسری `npm install -g pm2`، دستورات زیر را در سرور اجرا کنید:
+
+#### برای راه‌اندازی بک‌اند:
+```bash
+cd backend
+pm2 start dist/main.js --name "canina-api"
+```
+
+#### برای راه‌اندازی فرانت‌اند Next.js:
+```bash
+cd frontend/application
+pm2 start npm --name "canina-web" -- start
+```
+
+### ذخیره پروسه‌ها تا پس از ری‌استارت سرور قطع نشوند:
+```bash
+pm2 save
+pm2 startup
+```
+
+---
+
+## ۳. تنظیمات Nginx (Reverse Proxy)
+سرور Nginx مسئول دریافت ترافیک عمومی و هدایت آن‌ها به پورت‌های صحیح لوکال است.
+
+- ترافیک‌های دامنه `canina-iran.com` به پورت فرانت‌اند (`3000`) هدایت می‌شوند.
+- ترافیک‌هایی که دارای آدرس `/api/` در مسیر خود هستند مستقیماً به پورت بک‌اند (`3001`) هدایت می‌شوند.
+
+### نمونه فایل کانفیگ Nginx
+```nginx
+server {
+    listen 80;
+    server_name canina-iran.com www.canina-iran.com;
+
+    # ارسال ترافیک /api به Backend
+    location /api/ {
+        proxy_pass http://localhost:3001;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+
+    # ارسال مابقی ترافیک به Frontend
+    location / {
+        proxy_pass http://localhost:3000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+}
+```

docs/05-devops-and-monitoring.md

@@ -0,0 +1,41 @@
+# دواپس و مانیتورینگ سیستم (DevOps & Monitoring)
+
+این مستند توضیحاتی در مورد پایش مستمر سامانه و اتوماسیون (CI/CD) پس از انتشار ارائه می‌دهد. هدف این است که اطمینان حاصل شود سرورها همیشه با بالاترین بهره‌وری در حال اجرا هستند و کدهای جدید با کمترین خطا دیپلوی می‌شوند.
+
+## ۱. فرآیند استقرار خودکار (CI/CD)
+در تیم‌های بزرگ برای جلوگیری از بروز خطای انسانی در سرور، از فرآیند استقرار خودکار استفاده می‌شود.
+
+- کدهای جدید ابتدا در برنچ‌های مختلف توسعه داده شده و پس از تست (توسط GitHub Actions یا ابزارهای مشابه) به شاخه `main` یا `production` مرج می‌شوند.
+- یک اکشن در گیت‌هاب پس از Push شدن کدهای جدید به صورت خودکار تغییرات را بیلد کرده و بر روی سرور کپی می‌کند.
+- برای انجام دستی این کار یک اسکریپت در سرور وجود دارد که آخرین کدها را `git pull` کرده، دستورات نصب وابستگی و `npm run build` را اجرا و در نهایت سرویس‌های PM2 را ری‌استارت می‌کند.
+
+## ۲. مانیتورینگ عملکرد (PM2 Dashboard)
+با توجه به اینکه سامانه روی پلتفرم Node.js و از طریق مدیریت فرآیند `pm2` اجرا می‌شود، بهترین راه برای نظارت محلی (Local Server Monitoring) استفاده از دستورات زیر است:
+
+- **مشاهده داشبورد منابع:**
+  ```bash
+  pm2 monit
+  ```
+  این دستور در ترمینال یک محیط گرافیکی را نشان می‌دهد که میزان مصرف CPU و RAM برای سرویس‌های فرانت‌اند و بک‌اند را نمایش می‌دهد.
+
+- **مشاهده لیست وضعیت برنامه‌ها:**
+  ```bash
+  pm2 list
+  ```
+  نمایش Uptime (میزان زمان روشن ماندن) و وضعیت اجرا. اگر سرویسی Crash کرده باشد، در این لیست مشخص خواهد بود.
+
+## ۳. بررسی لاگ‌های سیستم (Logs Management)
+سیستم لاگین بک‌اند (NestJS) ارورهای پایگاه داده و ریکوئست‌های ناموفق را ثبت می‌کند. خطاهای رندرینگ فرانت‌اند نیز در لاگ‌های اجرای اپلیکیشن قابل ردیابی است.
+
+- برای مشاهده لاگ‌های زنده سیستم از این دستور استفاده کنید:
+  ```bash
+  pm2 logs
+  ```
+- برای فیلتر کردن لاگ‌های مشخص، مثلاً فقط بک‌اند:
+  ```bash
+  pm2 logs canina-api --lines 100
+  ```
+
+## ۴. مانیتورینگ دیتابیس (PostgreSQL)
+از آنجا که پایگاه داده یکی از گلوگاه‌های اصلی (Bottlenecks) سرعت در سیستم‌های فروشگاهی است، می‌توانید در صورت بروز کندی سیستم از ابزار `pg_stat_statements` برای ردیابی کوئری‌های کُند (Slow Queries) در دیتابیس استفاده کنید.
+همچنین پیشنهاد می‌شود از دیتابیس به صورت دوره‌ای بک‌آپ گرفته و لاگ‌های بک‌آپ را در سرور مانیتورینگ نظارت کنید.

docs/06-testing.md

@@ -0,0 +1,44 @@
+# راهنمای تست سیستم (Software Testing)
+
+تست نرم‌افزار برای اطمینان از کیفیت (QA) کدهای نوشته شده، عدم وجود باگ و تضمین کارکرد صحیح سامانه قبل از انتشار بسیار حیاتی است. در این سامانه استراتژی‌های تست زیر به کار گرفته می‌شود.
+
+## ۱. تست‌های واحد در Backend (Unit Testing)
+از آنجا که سیستم بک‌اند ما با `NestJS` نوشته شده است، فریم‌ورک استاندارد تست آن یعنی `Jest` از پیش بر روی سیستم تنظیم شده است.
+
+- **هدف:** در این لایه، تک‌تک Service ها و ماژول‌ها بدون نیاز به راه‌اندازی واقعی دیتابیس تست می‌شوند تا مطمئن شویم منطق محاسبه‌ها (مثل محاسبه تخفیف‌ها یا اتصال به درگاه) درست است.
+- **نحوه نوشتن تست:** برای هر سرویس یک فایل در کنار آن با پسوند `.spec.ts` ایجاد می‌شود (مثلاً `product.service.spec.ts`).
+- **اجرای تست‌ها:**
+  برای اجرای تست‌های واحد بک‌اند دستور زیر را اجرا کنید:
+  ```bash
+  cd backend
+  npm run test
+  ```
+
+## ۲. تست‌های End-to-End در Backend (E2E Testing)
+تست e2e کل چرخه را از درخواست کاربر تا ذخیره در دیتابیس بررسی می‌کند.
+
+- **نحوه نوشتن تست:** تست‌های e2e در پوشه `backend/test/` قرار دارند و معمولاً به صورت ریکوئست‌های شبیه‌سازی شده HTTP از طریق ابزار `Supertest` ایجاد می‌شوند.
+- **اجرای تست‌ها:**
+  ```bash
+  cd backend
+  npm run test:e2e
+  ```
+
+## ۳. تست‌های UI در Frontend (Component Testing)
+برای اینکه مطمئن شویم کامپوننت‌های رابط کاربری به درستی رندر می‌شوند و با کلیک کردن به استورها واکنش نشان می‌دهند، از سیستم تستی مثل `Jest` و `React Testing Library` استفاده می‌کنیم. (توجه: در صورت پیاده‌سازی این ابزار در سیستم).
+
+- **مواردی که باید در فرانت‌اند تست شوند:**
+  - فرآیند افزودن محصول به سبد خرید (`cartStore`).
+  - رندرینگ صحیح اطلاعات دریافتی از `API`.
+  - اجرای صحیح و عدم بروز خطا در فرم‌های لاگین و اعتبارسنجی‌ها.
+
+## ۴. تست‌های یکپارچگی سیستمی در Frontend (E2E Frontend - Playwright / Cypress)
+برای شبیه‌سازی رفتار واقعی کاربر (کارهایی مثل باز کردن صفحه، کلیک روی یک دکمه و پرداخت سبد خرید) می‌توان از ابزارهایی مثل `Cypress` یا `Playwright` استفاده کرد. این ابزارها یک مرورگر واقعی را باز کرده و مراحل را طی می‌کنند. این نوع تست قبل از فرآیند Deployment روی سیستم اعمال می‌شود تا از اینکه یک بروزرسانی کل سیستم ثبت سفارش را از کار انداخته جلوگیری شود.
+
+## ۵. چک لیست تست‌های دستی (Manual QA Checklist)
+هیچ کدی بدون پاس کردن چک لیست زیر نباید روی سرور Production پابلیش شود:
+1. قابلیت ثبت‌نام کاربر جدید و لاگین صحیح تست شده است؟
+2. آیا محصول می‌تواند به سبد خرید اضافه شده و فرآیند Checkout بدون خطا نمایش داده شود؟
+3. در موبایل (Responsive) آیا هدر، دکمه‌های ناوبری و گرید محصولات خوانا و قابل دسترس هستند؟
+4. آیا درخواستی به بک‌اند وجود دارد که باعث بازگشت ارور 500 سرور شود؟
+5. آیا عملکرد سئو (تولید تگ‌های Title و JSON-LD) در سورس پیج صحیح است؟

docs/README.md

@@ -0,0 +1,30 @@
+# مستندات توسعه‌دهندگان (Developer Documentation)
+
+به مستندات رسمی سامانه «کانینا ایران» خوش آمدید. این مستندات به منظور راهنمایی توسعه‌دهندگان، مهندسین دواپس و تیم فنی شرکت نوشته شده است و نباید در دسترس کاربران عمومی قرار گیرد.
+
+در این دایرکتوری تمامی ساختارها، معماری‌ها، قوانین کدنویسی و مراحل انتشار (Deployment) به دقت تدوین شده‌اند تا سرعت 온‌بوردینگ (Onboarding) توسعه‌دهندگان جدید افزایش یافته و نگهداری کدهای قدیمی با کمترین ریسک انجام شود.
+
+## فهرست مطالب (Table of Contents)
+
+لطفاً بر اساس نیاز خود به هر یک از بخش‌های زیر مراجعه کنید:
+
+1. [معرفی پروژه و معماری (Introduction)](01-introduction.md)
+   - پروژه چیست، قابلیت‌های آن کدامند و چرا از این ابزارها (Next.js & NestJS) استفاده شده است.
+
+2. [راهنمای کاربری و نقش‌ها (User Guide)](02-user-guide.md)
+   - انواع کاربران سیستم (کاربران عادی، تجاری و مدیران) و اینکه هر کدام قادر به انجام چه کارهایی هستند.
+
+3. [راهنمای توسعه‌دهندگان (Developer Guide)](03-developer-guide.md)
+   - **(مهم‌ترین بخش برای دولوپرها)** ساختار پوشه‌ها، استانداردهای کدنویسی، مدیریت State و قوانین توسعه بک‌اند و فرانت‌اند.
+
+4. [راه‌اندازی و انتشار سیستم (Setup & Deployment)](04-setup-and-deployment.md)
+   - نحوه اجرای محیط دولوپ روی سیستم شخصی، روند خروجی گرفتن (Build) و دستورات سرور پروداکشن با استفاده از PM2 و Nginx.
+
+5. [دواپس و مانیتورینگ سیستم (DevOps & Monitoring)](05-devops-and-monitoring.md)
+   - مدیریت و بررسی سلامت سرور، لاگ‌گیری و خودکارسازی دیپلوی (CI/CD).
+
+6. [راهنمای تست سیستم (Software Testing)](06-testing.md)
+   - انواع تست‌هایی که روی فرانت‌اند و بک‌اند انجام می‌گیرد و نحوه اجرای آن‌ها برای تضمین کیفیت کدها.
+
+---
+**توجه:** در صورت اضافه شدن ماژول‌ها و ابزارهای جدید به پروژه، لطفاً مستندات مربوطه را در همین پوشه بروزرسانی نمایید.