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 انجام می‌شود. پس از دریافت توکن در زمان ورود، باید هدر زیر در سایر درخواست‌ها الصاق شود:

  Authorization: Bearer <your_jwt_token>
  

• Error Structure: ساختار برگشت‌گر خطاها در شرایط کدهای وضعیت (HTTP Status Codes) غیر ۲۰۰ باید به فرم زیر باشد:

  {
    "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):

  interface LoginRequest {
    role: "User_Guest" | "User_PetOwner" | "User_Partner";
    mobile?: string;
  }
  

• تایپ خروجی (Success Response):

  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 در هدر)
• تایپ خروجی:

  interface LogoutResponse {
    success: boolean;
  }
  

۳. ویرایش و بروزرسانی اطلاعات پروفایل (Update Profile)

• مسیر: PATCH /api/user/profile
• موقعیت در کد: src/store/userStore.ts (متد updateProfile)
• تایپ ورودی:

  type UpdateProfileRequest = Partial<{
    firstName: string;
    lastName: string;
    email: string;
  }>;
  

• تایپ خروجی: UserProfile (پروفایل با داده‌های جدید)

۴. ثبت آدرس جدید برای کاربر (Add New Address)

• مسیر: POST /api/user/addresses
• موقعیت در کد: src/store/userStore.ts (متد addAddress)
• تایپ ورودی:

  interface AddAddressRequest {
    title: string;
    receptorName: string;
    phone: string;
    province: string;
    city: string;
    detail: string;
    zipCode: string;
    isDefault: boolean;
  }
  

• تایپ خروجی:

  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
• تایپ خروجی:

  interface DeleteAddressResponse {
    success: boolean;
  }
  

۷. انتخاب آدرس به عنوان پیش‌فرض (Set Address as Default)

• مسیر: POST /api/user/addresses/{id}/set-default
• موقعیت در کد: src/store/userStore.ts (متد setDefaultAddress)
• تایپ ورودی: پارامتر متغیر در آدرس URL
• تایپ خروجی:

  interface SetDefaultAddressResponse {
    success: boolean;
  }
  

۸. افزایش اعتبار و شارژ کیف پول (Wallet Top-Up)

• مسیر: POST /api/user/wallet/top-up
• موقعیت در کد: src/store/userStore.ts (متد topUpWallet)
• تایپ ورودی:

  interface TopUpRequest {
    amount: number;
  }
  

• تایپ خروجی:

  interface TopUpResponse {
    transactionId: string;
    newBalance: number;
  }
  

---

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

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

۹. دریافت کاتالوگ محصولات با فیلترینگ چندجانبه (Get Products)

• مسیر: GET /api/products
• موقعیت در کد: src/services/productService.ts (متد fetchProducts)
• پارامترهای کوئری ورودی (Query params):

  interface ProductsQueryFilters {
    category?: string;    // مانند joints, immune, energy, special-care
    petType?: string;     // مقادیر: سگ, گربه, or all
    query?: string;       // کلمه کلیدی برای جستجو در متن درمان یا نام
  }
  

• تایپ خروجی (Success Response):

  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)
• تایپ ورودی:

  interface AddPetRequest {
    name: string;
    type: "سگ" | "گربه";
    breed: string;
    age: number;
    weight: number;
    activityLevel: "کم" | "متوسط" | "زیاد";
    medicalConditions: string[];
    image?: string;
  }
  

• تایپ خروجی:

  interface PetResponse extends AddPetRequest {
    id: string; // شناسه تولید شده سمت سرور
    reminders: Reminder[];
    logs: HealthLog[];
    consumptions: PetConsumption[];
  }
  

۱۱. حذف پرونده سلامت حیوان خانگی (Delete Pet)

• مسیر: DELETE /api/pets/{id}
• موقعیت در کد: src/store/usePetStore.ts (متد removePet)
• تایپ ورودی: پارامتر متغیر در آدرس URL
• تایپ خروجی:

  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)
• تایپ ورودی:

  interface AddReminderRequest {
    title: string;
    time: string;
    frequency: "روزانه" | "هفتگی";
    productId?: string; // آیدی مکمل بخصوص برای اتصال به انبار مصرفی
  }
  

• تایپ خروجی:

  interface ReminderResponse extends AddReminderRequest {
    id: string;
    completedDates: string[];
  }
  

۱۴. ثبت مصرف دوز یادآوری شده (تغییر وضعیت و همگام‌سازی انبار) (Toggle & Consume Reminder)

• مسیر: POST /api/pets/{petId}/reminders/{reminderId}/toggle
• موقعیت در کد: src/store/usePetStore.ts (متد toggleReminder)
• تایپ ورودی:

  interface ToggleReminderRequest {
    date: string; // تاریخ روز به فرمت ISO (YYYY-MM-DD)
  }
  

• تایپ خروجی:

  interface ToggleReminderResponse {
    success: boolean;
    newRemaining?: number; // مقدار باقیمانده بسته پس از مصرف دوز (کم شده از پک پت)
  }
  

۱۵. ثبت لاگ‌های ارزیابی وضعیت گوارش و انرژی پت (Add Daily Health Log)

• مسیر: POST /api/pets/{petId}/health-logs
• موقعیت در کد: src/store/usePetStore.ts (متد addHealthLog)
• تایپ ورودی:

  interface AddHealthLogRequest {
    appetite: "عالی" | "متوسط" | "کم";
    energy: "زیاد" | "نرمال" | "بی‌حال";
    digestion: "نرمال" | "حساس" | "مشکل‌دار";
    note?: string;
  }
  

• تایپ خروجی:

  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)
• تایپ ورودی:

  interface ApplyCouponRequest {
    code: string;
  }
  

• تایپ خروجی:

  interface ApplyCouponResponse {
    discount: number; // قیمت آفر کاهش دهنده یا پله درصد (نسب کسر)
  }
  

• کدهای خطا: 404 Not Found (چنین کدی تعریف نشده)، 400 Bad Request (منقضی یا نامعتبر).

۱۷. ثبت قطعی سفارش و ایجاد پیش‌فاکتور (Place Final Order)

• مسیر: POST /api/orders
• موقعیت در کد: src/store/cartStore.ts (متد addOrder)
• تایپ ورودی:

  interface PlaceOrderRequest {
    items: Array<{
      product: { id: string; name: string };
      quantity: number;
      calculatedDose?: { quantity: number; unit: string };
    }>;
    total: number;
    charityDonation?: number;
    petId?: string;
  }
  

• تایپ خروجی:

  interface OrderResponse extends PlaceOrderRequest {
    id: string;
    date: string;
    status: "processing" | "shipped" | "delivered";
    trackingNumber: string; // کد رهگیری پستی ملی فیزیکی تولید شده
  }
  

۱۸. آماده‌سازی توکن پرداخت شبکه بانکی زیتون/شتاب (Initialize Gateway)

• مسیر: POST /api/payment/init
• موقعیت در کد: src/components/CheckoutPage.tsx
• تایپ ورودی:

  interface PaymentInitRequest {
    method: string; // روش مانند "wallet" یا "online"
    amount: number; // کل مبلغ قابل پرداخت به ریال یا تومان
  }
  

• تایپ خروجی:

  interface PaymentInitResponse {
    gatewayUrl: string; // آدرس ریدایرکت کلاینت به درگاه شاپرک/شتاب بانکی
  }
  

---

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

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

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;
  }
};

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