canina/BACKEND_INTEGRATION.md

# نقشه جامع اتصال به بک‌بند (Comprehensive Backend Integration Map) 🏗️

این سند حاوی معماری دقیق، فهرست کامل نقاط اتصال (API Endpoints)، کامنت‌های مکان‌نما در کد (TODO Markers)، و تعاریف رسمی تمامی تایپ‌های ورودی (Inputs) و خروجی (Outputs) پلتفرم درمانی و فروشگاهی کنینا ایران است.

---

## ۱. اصول عمومی و ساختار تبادل داده (General Protocols)

-   **Base URL:** تمام درخواست‌ها به روت اصلی آدرس ریلیتیو `/api` یا آدرس دامین اصلی متصل می‌شوند.
-   **Content-Type:** کلیه ورودی‌ها و خروجی‌ها در قالب `application/json` با استاندارد انکودینگ UTF-8 تبادل می‌شوند.
-   **Authentication:** احراز هویت با استفاده از استاندارد JWT انجام می‌شود. پس از دریافت توکن در زمان ورود، باید هدر زیر در سایر درخواست‌ها الصاق شود:
    ```http
    Authorization: Bearer <your_jwt_token>
    ```
-   **Error Structure:** ساختار برگشت‌گر خطاها در شرایط کدهای وضعیت (HTTP Status Codes) غیر ۲۰۰ باید به فرم زیر باشد:
    ```json
    {
      "success": false,
      "message": "کد تخفیف وارد شده منقضی شده است",
      "code": "COUPON_EXPIRED",
      "details": {} // اختیاری
    }
    ```

---

## ۲. مستندات جزء به جزء تایپ‌ها و نقاط اتصال (API Directory & Types)

در زیر، تمام ۱۸ نقطه اتصال مشخص شده همراه با کارهایی که در فروشگاه‌های حالت (Zustand Stores) و کامپوننت‌های فرانت‌اند باید جایگزین منطق موالاتی کلاینت شوند آورده شده است:

### ۲.۱. مدیریت احراز هویت و اطلاعات کاربر (Authentication & Profiling)

موقعیت فایل‌ها:
-   درون کامپوننت `src/components/AuthModal.tsx` دکمه ورود.
-   درون استور حالت پرتابل `src/store/userStore.ts`.

#### ۱. ورود کاربر به سیستم (User Login)
-   **مسیر:** `POST /api/auth/login`
-   **موقعیت در کد:** `src/components/AuthModal.tsx`
-   **تایپ ورودی (Payload):**
    ```typescript
    interface LoginRequest {
      role: "User_Guest" | "User_PetOwner" | "User_Partner";
      mobile?: string;
    }
    ```
-   **تایپ خروجی (Success Response):**
    ```typescript
    interface LoginResponse {
      token: string;
      user: {
        firstName: string;
        lastName: string;
        email: string;
        walletBalance: number;
        charityDonationTotal: number;
        addresses: Address[];
        transactions: Transaction[];
      };
    }
    ```
-   **کدهای خطا:** `400 Bad Request` (فرمت موبایل نامعتبر)، `401 Unauthorized` (رد ورود).

#### ۲. خروج از سیستم (User Logout)
-   **مسیر:** `POST /api/auth/logout`
-   **موقعیت در کد:** `src/store/userStore.ts` (متد `logout`)
-   **تایپ ورودی:** فاقد بدنه (استفاده از Bearer Token در هدر)
-   **تایپ خروجی:**
    ```typescript
    interface LogoutResponse {
      success: boolean;
    }
    ```

#### ۳. ویرایش و بروزرسانی اطلاعات پروفایل (Update Profile)
-   **مسیر:** `PATCH /api/user/profile`
-   **موقعیت در کد:** `src/store/userStore.ts` (متد `updateProfile`)
-   **تایپ ورودی:**
    ```typescript
    type UpdateProfileRequest = Partial<{
      firstName: string;
      lastName: string;
      email: string;
    }>;
    ```
-   **تایپ خروجی:** `UserProfile` (پروفایل با داده‌های جدید)

#### ۴. ثبت آدرس جدید برای کاربر (Add New Address)
-   **مسیر:** `POST /api/user/addresses`
-   **موقعیت در کد:** `src/store/userStore.ts` (متد `addAddress`)
-   **تایپ ورودی:**
    ```typescript
    interface AddAddressRequest {
      title: string;
      receptorName: string;
      phone: string;
      province: string;
      city: string;
      detail: string;
      zipCode: string;
      isDefault: boolean;
    }
    ```
-   **تایپ خروجی:**
    ```typescript
    interface AddressResponse extends AddAddressRequest {
      id: string; // شناسه یکتا تولید شده توسط دیتابیس
    }
    ```

#### ۵. ویرایش آدرس موجود (Update Address)
-   **مسیر:** `PATCH /api/user/addresses/{id}`
-   **موقعیت در کد:** `src/store/userStore.ts` (متد `updateAddress`)
-   **تایپ ورودی:** `Address` (شامل فیلد `id`)
-   **تایپ خروجی:** `Address` (آدرس با آخرین تغییرات)

#### ۶. حذف آدرس (Delete Address)
-   **مسیر:** `DELETE /api/user/addresses/{id}`
-   **موقعیت در کد:** `src/store/userStore.ts` (متد `deleteAddress`)
-   **تایپ ورودی:** پارامتر متغیر در آدرس URL
-   **تایپ خروجی:**
    ```typescript
    interface DeleteAddressResponse {
      success: boolean;
    }
    ```

#### ۷. انتخاب آدرس به عنوان پیش‌فرض (Set Address as Default)
-   **مسیر:** `POST /api/user/addresses/{id}/set-default`
-   **موقعیت در کد:** `src/store/userStore.ts` (متد `setDefaultAddress`)
-   **تایپ ورودی:** پارامتر متغیر در آدرس URL
-   **تایپ خروجی:**
    ```typescript
    interface SetDefaultAddressResponse {
      success: boolean;
    }
    ```

#### ۸. افزایش اعتبار و شارژ کیف پول (Wallet Top-Up)
-   **مسیر:** `POST /api/user/wallet/top-up`
-   **موقعیت در کد:** `src/store/userStore.ts` (متد `topUpWallet`)
-   **تایپ ورودی:**
    ```typescript
    interface TopUpRequest {
      amount: number;
    }
    ```
-   **تایپ خروجی:**
    ```typescript
    interface TopUpResponse {
      transactionId: string;
      newBalance: number;
    }
    ```

---

### ۲.۲. جستجو و پایگاه داده محصولات (Product Catalog)

موقعیت فایل: `src/services/productService.ts`.

#### ۹. دریافت کاتالوگ محصولات با فیلترینگ چندجانبه (Get Products)
-   **مسیر:** `GET /api/products`
-   **موقعیت در کد:** `src/services/productService.ts` (متد `fetchProducts`)
-   **پارامترهای کوئری ورودی (Query params):**
    ```typescript
    interface ProductsQueryFilters {
      category?: string;    // مانند joints, immune, energy, special-care
      petType?: string;     // مقادیر: سگ, گربه, or all
      query?: string;       // کلمه کلیدی برای جستجو در متن درمان یا نام
    }
    ```
-   **تایپ خروجی (Success Response):**
    ```typescript
    interface Product {
      id: string;
      artNo: string;
      name: string;
      scientificTagline?: string;
      description: string;
      shortDescription: string;
      keyBenefits: Array<{ icon: string; title: string; description: string }>;
      category: string;
      categorySlug?: string;
      price: string;
      priceValue: number;
      unit: string;
      packageSize: number;
      main_ingredients: string[];
      dosage_logic?: string;
      benefits: string | string[];
      symptoms: string[];
      suitableFor: "سگ" | "گربه" | "هر دو";
      calculateDosage?: (weight: number) => string;
      image: string;
    }
    
    type GetProductsResponse = Product[];
    ```

---

### ۲.۳. پرونده سلامت و شناسنامه سلامت پت (Pet Profile & Medical Records)

موقعیت فایل: `src/store/usePetStore.ts`.

#### ۱۰. ثبت و ایجاد شناسنامه دیجیتال برای پت جدید (Add Pet)
-   **مسیر:** `POST /api/pets`
-   **موقعیت در کد:** `src/store/usePetStore.ts` (متد `addPet`)
-   **تایپ ورودی:**
    ```typescript
    interface AddPetRequest {
      name: string;
      type: "سگ" | "گربه";
      breed: string;
      age: number;
      weight: number;
      activityLevel: "کم" | "متوسط" | "زیاد";
      medicalConditions: string[];
      image?: string;
    }
    ```
-   **تایپ خروجی:**
    ```typescript
    interface PetResponse extends AddPetRequest {
      id: string; // شناسه تولید شده سمت سرور
      reminders: Reminder[];
      logs: HealthLog[];
      consumptions: PetConsumption[];
    }
    ```

#### ۱۱. حذف پرونده سلامت حیوان خانگی (Delete Pet)
-   **مسیر:** `DELETE /api/pets/{id}`
-   **موقعیت در کد:** `src/store/usePetStore.ts` (متد `removePet`)
-   **تایپ ورودی:** پارامتر متغیر در آدرس URL
-   **تایپ خروجی:**
    ```typescript
    interface DeletePetResponse {
      success: boolean;
    }
    ```

#### ۱۲. ویرایش اطلاعات بیومتریک پت (Update Pet Details)
-   **مسیر:** `PATCH /api/pets/{id}`
-   **موقعیت در کد:** `src/store/usePetStore.ts` (متد `updatePet`)
-   **تایپ ورودی:** `Partial<AddPetRequest>`
-   **تایپ خروجی:** `PetProfile` (مشخصات بروزرسانی شده)

#### ۱۳. ثبت برنامه دارویی و یادآور جدید (Add Medicine Reminder)
-   **مسیر:** `POST /api/pets/{petId}/reminders`
-   **موقعیت در کد:** `src/store/usePetStore.ts` (متد `addReminder`)
-   **تایپ ورودی:**
    ```typescript
    interface AddReminderRequest {
      title: string;
      time: string;
      frequency: "روزانه" | "هفتگی";
      productId?: string; // آیدی مکمل بخصوص برای اتصال به انبار مصرفی
    }
    ```
-   **تایپ خروجی:**
    ```typescript
    interface ReminderResponse extends AddReminderRequest {
      id: string;
      completedDates: string[];
    }
    ```

#### ۱۴. ثبت مصرف دوز یادآوری شده (تغییر وضعیت و همگام‌سازی انبار) (Toggle & Consume Reminder)
-   **مسیر:** `POST /api/pets/{petId}/reminders/{reminderId}/toggle`
-   **موقعیت در کد:** `src/store/usePetStore.ts` (متد `toggleReminder`)
-   **تایپ ورودی:**
    ```typescript
    interface ToggleReminderRequest {
      date: string; // تاریخ روز به فرمت ISO (YYYY-MM-DD)
    }
    ```
-   **تایپ خروجی:**
    ```typescript
    interface ToggleReminderResponse {
      success: boolean;
      newRemaining?: number; // مقدار باقیمانده بسته پس از مصرف دوز (کم شده از پک پت)
    }
    ```

#### ۱۵. ثبت لاگ‌های ارزیابی وضعیت گوارش و انرژی پت (Add Daily Health Log)
-   **مسیر:** `POST /api/pets/{petId}/health-logs`
-   **موقعیت در کد:** `src/store/usePetStore.ts` (متد `addHealthLog`)
-   **تایپ ورودی:**
    ```typescript
    interface AddHealthLogRequest {
      appetite: "عالی" | "متوسط" | "کم";
      energy: "زیاد" | "نرمال" | "بی‌حال";
      digestion: "نرمال" | "حساس" | "مشکل‌دار";
      note?: string;
    }
    ```
-   **تایپ خروجی:**
    ```typescript
    interface HealthLogResponse extends AddHealthLogRequest {
      id: string;
      date: string; // تاریخ ثبت شده سمت سرور
    }
    ```

---

### ۲.۴. سبد خرید، کدهای آفر و خروجی فاکتور نهایی (Cart & Order Transactions)

موقعیت فایل‌ها:
-   درون استور حالت کاربری سبد `src/store/cartStore.ts`.
-   درون کامپوننت پرداخت فیزیکی `src/components/CheckoutPage.tsx`.

#### ۱۶. ارزیابی و بررسی اعتبار کوپن‌های آفر (Apply Discount Coupon)
-   **مسیر:** `POST /api/cart/apply-coupon`
-   **موقعیت در کد:** `src/store/cartStore.ts` (متد `applyCoupon`)
-   **تایپ ورودی:**
    ```typescript
    interface ApplyCouponRequest {
      code: string;
    }
    ```
-   **تایپ خروجی:**
    ```typescript
    interface ApplyCouponResponse {
      discount: number; // قیمت آفر کاهش دهنده یا پله درصد (نسب کسر)
    }
    ```
-   **کدهای خطا:** `404 Not Found` (چنین کدی تعریف نشده)، `400 Bad Request` (منقضی یا نامعتبر).

#### ۱۷. ثبت قطعی سفارش و ایجاد پیش‌فاکتور (Place Final Order)
-   **مسیر:** `POST /api/orders`
-   **موقعیت در کد:** `src/store/cartStore.ts` (متد `addOrder`)
-   **تایپ ورودی:**
    ```typescript
    interface PlaceOrderRequest {
      items: Array<{
        product: { id: string; name: string };
        quantity: number;
        calculatedDose?: { quantity: number; unit: string };
      }>;
      total: number;
      charityDonation?: number;
      petId?: string;
    }
    ```
-   **تایپ خروجی:**
    ```typescript
    interface OrderResponse extends PlaceOrderRequest {
      id: string;
      date: string;
      status: "processing" | "shipped" | "delivered";
      trackingNumber: string; // کد رهگیری پستی ملی فیزیکی تولید شده
    }
    ```

#### ۱۸. آماده‌سازی توکن پرداخت شبکه بانکی زیتون/شتاب (Initialize Gateway)
-   **مسیر:** `POST /api/payment/init`
-   **موقعیت در کد:** `src/components/CheckoutPage.tsx`
-   **تایپ ورودی:**
    ```typescript
    interface PaymentInitRequest {
      method: string; // روش مانند "wallet" یا "online"
      amount: number; // کل مبلغ قابل پرداخت به ریال یا تومان
    }
    ```
-   **تایپ خروجی:**
    ```typescript
    interface PaymentInitResponse {
      gatewayUrl: string; // آدرس ریدایرکت کلاینت به درگاه شاپرک/شتاب بانکی
    }
    ```

---

## ۳. الگوی نمونه پیاده‌سازی متد اتصال (Zustand Axios Integration Blueprint)

برای اتصال فرانت‌اند Zustand با دیتابیس زنده، توسعه‌دهندگان می‌توانند از الگوی زیر برای متدهای استور استفاده کنند. قبل از الصاق، حتما کتابخانه `axios` را نصب نمایید:

```typescript
import axios from "axios";

// نمونه فراخوانی جهت ثبت پت جدید در فایل src/store/usePetStore.ts
const addPet = async (petData: Omit<PetProfile, "id">) => {
  try {
    const token = localStorage.getItem("auth_token");
    const response = await axios.post<PetProfile>("/api/pets", petData, {
      headers: {
        Authorization: `Bearer ${token}`
      }
    });
    
    // بروزرسانی استور محلی پس از موفقیت پاسخ بک‌بند
    set((state) => ({
      pets: [...state.pets, response.data],
      activePetId: response.data.id
    }));
  } catch (error) {
    console.error("خطا در ایجاد شناسنامه پت روی سرور:", error);
    throw error;
  }
};
```

*این سند فاکتور تحویل نهایی بخش توسعه فرانت‌اند به تیم بک‌بند جهت هماهنگی معماری میکروسرویس تلقی می‌گردد.*